python3-10.pyscalpel

This is a module providing tools to handle Burp HTTP traffic through the use of the Scalpel extension.

It provides many utilities to manipulate HTTP requests, responses and converting data.

View Source

 1"""
 2This is a module providing tools to handle Burp HTTP traffic through the use of the Scalpel extension.
 3
 4It provides many utilities to manipulate HTTP requests, responses and converting data.
 5"""
 6
 7from pyscalpel.http import Request, Response, Flow
 8from pyscalpel.edit import editor
 9from pyscalpel.burp_utils import ctx as _context
10from pyscalpel.java.scalpel_types import Context
11from pyscalpel.logger import Logger, logger
12from pyscalpel.events import MatchEvent
13from . import http
14from . import java
15from . import encoding
16from . import utils
17from . import burp_utils
18from . import venv
19from . import edit
20
21ctx: Context = _context
22"""The Scalpel Python execution context
23
24Contains the Burp Java API object, the venv directory, the user script path,
25the path to the file loading the user script and a logging object
26"""
27
28
29__all__ = [
30    "http",
31    "java",
32    "encoding",
33    "utils",
34    "burp_utils",
35    "venv",
36    "edit",
37    "Request",
38    "Response",
39    "Flow",
40    "ctx",
41    "Context",
42    "MatchEvent",
43    "editor",
44    "logger",
45    "Logger",
46]

class Response(_internal_mitmproxy.http.Response): View Source

 22class Response(MITMProxyResponse):
 23    """A "Burp oriented" HTTP response class
 24
 25
 26    This class allows to manipulate Burp responses in a Pythonic way.
 27
 28    Fields:
 29        scheme: http or https
 30        host: The initiating request target host
 31        port: The initiating request target port
 32        request: The initiating request.
 33    """
 34
 35    scheme: Literal["http", "https"] = "http"
 36    host: str = ""
 37    port: int = 0
 38    request: Request | None = None
 39
 40    def __init__(
 41        self,
 42        http_version: bytes,
 43        status_code: int,
 44        reason: bytes,
 45        headers: Headers | tuple[tuple[bytes, bytes], ...],
 46        content: bytes | None,
 47        trailers: Headers | tuple[tuple[bytes, bytes], ...] | None,
 48        scheme: Literal["http", "https"] = "http",
 49        host: str = "",
 50        port: int = 0,
 51    ):
 52        # Construct the base/inherited MITMProxy response.
 53        super().__init__(
 54            http_version,
 55            status_code,
 56            reason,
 57            headers,
 58            content,
 59            trailers,
 60            timestamp_start=time.time(),
 61            timestamp_end=time.time(),
 62        )
 63        self.scheme = scheme
 64        self.host = host
 65        self.port = port
 66
 67    @classmethod
 68    # https://docs.mitmproxy.org/stable/api/mitmproxy/http.html#Response
 69    # link to mitmproxy documentation
 70    def from_mitmproxy(cls, response: MITMProxyResponse) -> Response:
 71        """Construct an instance of the Response class from a [mitmproxy.http.HTTPResponse](https://docs.mitmproxy.org/stable/api/mitmproxy/http.html#Response).
 72        :param response: The [mitmproxy.http.HTTPResponse](https://docs.mitmproxy.org/stable/api/mitmproxy/http.html#Response) to convert.
 73        :return: A :class:`Response` with the same data as the [mitmproxy.http.HTTPResponse](https://docs.mitmproxy.org/stable/api/mitmproxy/http.html#Response).
 74        """
 75        return cls(
 76            always_bytes(response.http_version),
 77            response.status_code,
 78            always_bytes(response.reason),
 79            Headers.from_mitmproxy(response.headers),
 80            response.content,
 81            Headers.from_mitmproxy(response.trailers) if response.trailers else None,
 82        )
 83
 84    @classmethod
 85    def from_burp(
 86        cls,
 87        response: IHttpResponse,
 88        service: IHttpService | None = None,
 89        request: IHttpRequest | None = None,
 90    ) -> Response:
 91        """Construct an instance of the Response class from a Burp suite :class:`IHttpResponse`."""
 92        body = get_bytes(cast(IByteArray, response.body())) if response.body() else b""
 93        scalpel_response = cls(
 94            always_bytes(response.httpVersion() or "HTTP/1.1"),
 95            response.statusCode(),
 96            always_bytes(response.reasonPhrase() or b""),
 97            Headers.from_burp(response.headers()),
 98            body,
 99            None,
100        )
101
102        burp_request: IHttpRequest | None = request
103        if burp_request is None:
104            try:
105                # Some responses can have a "initiatingRequest" field.
106                # https://portswigger.github.io/burp-extensions-montoya-api/javadoc/burp/api/montoya/http/handler/HttpResponseReceived.html#initiatingRequest():~:text=HttpRequest-,initiatingRequest(),-Returns%3A
107                burp_request = response.initiatingRequest()  # type: ignore
108            except AttributeError:
109                pass
110
111        if burp_request:
112            scalpel_response.request = Request.from_burp(burp_request, service)
113
114        if not service and burp_request:
115            # The only way to check if the Java method exist without writing Java is catching the error.
116            service = burp_request.httpService()
117
118        if service:
119            scalpel_response.scheme = "https" if service.secure() else "http"
120            scalpel_response.host = service.host()
121            scalpel_response.port = service.port()
122
123        return scalpel_response
124
125    def __bytes__(self) -> bytes:
126        """Convert the response to raw bytes."""
127        # Reserialize the response to bytes.
128
129        # Format the first line of the response. (e.g. "HTTP/1.1 200 OK\r\n")
130        first_line = (
131            b" ".join(
132                always_bytes(s)
133                for s in (self.http_version, str(self.status_code), self.reason)
134            )
135            + b"\r\n"
136        )
137
138        # Format the response's headers part.
139        headers_lines = b"".join(
140            b"%s: %s\r\n" % (key, val) for key, val in self.headers.fields
141        )
142
143        # Set a default value for the response's body. (None -> b"")
144        body = self.content or b""
145
146        # Build the whole response and return it.
147        return first_line + headers_lines + b"\r\n" + body
148
149    def to_burp(self) -> IHttpResponse:  # pragma: no cover (uses Java API)
150        """Convert the response to a Burp suite :class:`IHttpResponse`."""
151        response_byte_array: IByteArray = PythonUtils.toByteArray(bytes(self))
152
153        return HttpResponse.httpResponse(response_byte_array)
154
155    @classmethod
156    def from_raw(
157        cls, data: bytes | str
158    ) -> Response:  # pragma: no cover (uses Java API)
159        """Construct an instance of the Response class from raw bytes.
160        :param data: The raw bytes to convert.
161        :return: A :class:`Response` parsed from the raw bytes.
162        """
163        # Use the Burp API to trivialize the parsing of the response from raw bytes.
164        # Convert the raw bytes to a Burp ByteArray.
165        # Plain strings are OK too.
166        str_or_byte_array: IByteArray | str = (
167            data if isinstance(data, str) else PythonUtils.toByteArray(data)
168        )
169
170        # Instantiate a new Burp HTTP response.
171        burp_response: IHttpResponse = HttpResponse.httpResponse(str_or_byte_array)
172
173        return cls.from_burp(burp_response)
174
175    @classmethod
176    def make(
177        cls,
178        status_code: int = 200,
179        content: bytes | str = b"",
180        headers: Headers | tuple[tuple[bytes, bytes], ...] = (),
181        host: str = "",
182        port: int = 0,
183        scheme: Literal["http", "https"] = "http",
184    ) -> "Response":
185        # Use the base/inherited make method to construct a MITMProxy response.
186        mitmproxy_res = MITMProxyResponse.make(status_code, content, headers)
187
188        res = cls.from_mitmproxy(mitmproxy_res)
189        res.host = host
190        res.scheme = scheme
191        res.port = port
192
193        return res
194
195    def host_is(self, *patterns: str) -> bool:
196        """Matches the host against the provided patterns
197
198        Returns:
199            bool: Whether at least one pattern matched
200        """
201        return host_is(self.host, *patterns)
202
203    @property
204    def body(self) -> bytes | None:
205        """Alias for content()
206
207        Returns:
208            bytes | None: The request body / content
209        """
210        return self.content
211
212    @body.setter
213    def body(self, val: bytes | None):
214        self.content = val

A "Burp oriented" HTTP response class

This class allows to manipulate Burp responses in a Pythonic way.

Fields: scheme: http or https host: The initiating request target host port: The initiating request target port request: The initiating request.

Response( http_version: bytes, status_code: int, reason: bytes, headers: pyscalpel.http.headers.Headers | tuple[tuple[bytes, bytes], ...], content: bytes | None, trailers: pyscalpel.http.headers.Headers | tuple[tuple[bytes, bytes], ...] | None, scheme: Literal['http', 'https'] = 'http', host: str = '', port: int = 0) View Source

40    def __init__(
41        self,
42        http_version: bytes,
43        status_code: int,
44        reason: bytes,
45        headers: Headers | tuple[tuple[bytes, bytes], ...],
46        content: bytes | None,
47        trailers: Headers | tuple[tuple[bytes, bytes], ...] | None,
48        scheme: Literal["http", "https"] = "http",
49        host: str = "",
50        port: int = 0,
51    ):
52        # Construct the base/inherited MITMProxy response.
53        super().__init__(
54            http_version,
55            status_code,
56            reason,
57            headers,
58            content,
59            trailers,
60            timestamp_start=time.time(),
61            timestamp_end=time.time(),
62        )
63        self.scheme = scheme
64        self.host = host
65        self.port = port

scheme: Literal['http', 'https'] = 'http'

host: str = ''

port: int = 0

request: Request | None = None

@classmethod

def from_mitmproxy( cls, response: _internal_mitmproxy.http.Response) -> Response: View Source

67    @classmethod
68    # https://docs.mitmproxy.org/stable/api/mitmproxy/http.html#Response
69    # link to mitmproxy documentation
70    def from_mitmproxy(cls, response: MITMProxyResponse) -> Response:
71        """Construct an instance of the Response class from a [mitmproxy.http.HTTPResponse](https://docs.mitmproxy.org/stable/api/mitmproxy/http.html#Response).
72        :param response: The [mitmproxy.http.HTTPResponse](https://docs.mitmproxy.org/stable/api/mitmproxy/http.html#Response) to convert.
73        :return: A :class:`Response` with the same data as the [mitmproxy.http.HTTPResponse](https://docs.mitmproxy.org/stable/api/mitmproxy/http.html#Response).
74        """
75        return cls(
76            always_bytes(response.http_version),
77            response.status_code,
78            always_bytes(response.reason),
79            Headers.from_mitmproxy(response.headers),
80            response.content,
81            Headers.from_mitmproxy(response.trailers) if response.trailers else None,
82        )

Construct an instance of the Response class from a mitmproxy.http.HTTPResponse.

Parameters

**response: The mitmproxy.http.HTTPResponse to convert.

Returns

A Response with the same data as the mitmproxy.http.HTTPResponse.

@classmethod

def from_burp( cls, response: pyscalpel.java.burp.http_response.IHttpResponse, service: pyscalpel.java.burp.http_service.IHttpService | None = None, request: pyscalpel.java.burp.http_request.IHttpRequest | None = None) -> Response: View Source

 84    @classmethod
 85    def from_burp(
 86        cls,
 87        response: IHttpResponse,
 88        service: IHttpService | None = None,
 89        request: IHttpRequest | None = None,
 90    ) -> Response:
 91        """Construct an instance of the Response class from a Burp suite :class:`IHttpResponse`."""
 92        body = get_bytes(cast(IByteArray, response.body())) if response.body() else b""
 93        scalpel_response = cls(
 94            always_bytes(response.httpVersion() or "HTTP/1.1"),
 95            response.statusCode(),
 96            always_bytes(response.reasonPhrase() or b""),
 97            Headers.from_burp(response.headers()),
 98            body,
 99            None,
100        )
101
102        burp_request: IHttpRequest | None = request
103        if burp_request is None:
104            try:
105                # Some responses can have a "initiatingRequest" field.
106                # https://portswigger.github.io/burp-extensions-montoya-api/javadoc/burp/api/montoya/http/handler/HttpResponseReceived.html#initiatingRequest():~:text=HttpRequest-,initiatingRequest(),-Returns%3A
107                burp_request = response.initiatingRequest()  # type: ignore
108            except AttributeError:
109                pass
110
111        if burp_request:
112            scalpel_response.request = Request.from_burp(burp_request, service)
113
114        if not service and burp_request:
115            # The only way to check if the Java method exist without writing Java is catching the error.
116            service = burp_request.httpService()
117
118        if service:
119            scalpel_response.scheme = "https" if service.secure() else "http"
120            scalpel_response.host = service.host()
121            scalpel_response.port = service.port()
122
123        return scalpel_response

Construct an instance of the Response class from a Burp suite IHttpResponse.

def to_burp(self) -> pyscalpel.java.burp.http_response.IHttpResponse: View Source

149    def to_burp(self) -> IHttpResponse:  # pragma: no cover (uses Java API)
150        """Convert the response to a Burp suite :class:`IHttpResponse`."""
151        response_byte_array: IByteArray = PythonUtils.toByteArray(bytes(self))
152
153        return HttpResponse.httpResponse(response_byte_array)

Convert the response to a Burp suite IHttpResponse.

@classmethod

def from_raw(cls, data: bytes | str) -> Response: View Source

155    @classmethod
156    def from_raw(
157        cls, data: bytes | str
158    ) -> Response:  # pragma: no cover (uses Java API)
159        """Construct an instance of the Response class from raw bytes.
160        :param data: The raw bytes to convert.
161        :return: A :class:`Response` parsed from the raw bytes.
162        """
163        # Use the Burp API to trivialize the parsing of the response from raw bytes.
164        # Convert the raw bytes to a Burp ByteArray.
165        # Plain strings are OK too.
166        str_or_byte_array: IByteArray | str = (
167            data if isinstance(data, str) else PythonUtils.toByteArray(data)
168        )
169
170        # Instantiate a new Burp HTTP response.
171        burp_response: IHttpResponse = HttpResponse.httpResponse(str_or_byte_array)
172
173        return cls.from_burp(burp_response)

Construct an instance of the Response class from raw bytes.

Parameters

data: The raw bytes to convert.

Returns

A Response parsed from the raw bytes.

@classmethod

def make( cls, status_code: int = 200, content: bytes | str = b'', headers: pyscalpel.http.headers.Headers | tuple[tuple[bytes, bytes], ...] = (), host: str = '', port: int = 0, scheme: Literal['http', 'https'] = 'http') -> Response: View Source

175    @classmethod
176    def make(
177        cls,
178        status_code: int = 200,
179        content: bytes | str = b"",
180        headers: Headers | tuple[tuple[bytes, bytes], ...] = (),
181        host: str = "",
182        port: int = 0,
183        scheme: Literal["http", "https"] = "http",
184    ) -> "Response":
185        # Use the base/inherited make method to construct a MITMProxy response.
186        mitmproxy_res = MITMProxyResponse.make(status_code, content, headers)
187
188        res = cls.from_mitmproxy(mitmproxy_res)
189        res.host = host
190        res.scheme = scheme
191        res.port = port
192
193        return res

Simplified API for creating response objects.

def host_is(self, *patterns: str) -> bool: View Source

195    def host_is(self, *patterns: str) -> bool:
196        """Matches the host against the provided patterns
197
198        Returns:
199            bool: Whether at least one pattern matched
200        """
201        return host_is(self.host, *patterns)

Matches the host against the provided patterns

Returns: bool: Whether at least one pattern matched

body: bytes | None View Source

203    @property
204    def body(self) -> bytes | None:
205        """Alias for content()
206
207        Returns:
208            bytes | None: The request body / content
209        """
210        return self.content

Alias for content()

Returns: bytes | None: The request body / content

Inherited Members

_internal_mitmproxy.http.Response: data; status_code; reason; cookies; refresh
_internal_mitmproxy.http.Message: from_state; get_state; set_state; stream; http_version; is_http10; is_http11; is_http2; headers; trailers; raw_content; content; text; set_content; get_content; set_text; get_text; timestamp_start; timestamp_end; decode; encode; json
_internal_mitmproxy.coretypes.serializable.Serializable: copy

class Flow: View Source

10class Flow:
11    """Contains request and response and some utilities for match()"""
12
13    def __init__(
14        self,
15        scheme: Literal["http", "https"] = "http",
16        host: str = "",
17        port: int = 0,
18        request: Request | None = None,
19        response: Response | None = None,
20        text: bytes | None = None,
21    ):
22        self.scheme = scheme
23        self.host = host
24        self.port = port
25        self.request = request
26        self.response = response
27        self.text = text
28
29    def host_is(self, *patterns: str) -> bool:
30        """Matches a wildcard pattern against the target host
31
32        Returns:
33            bool: True if at least one pattern matched
34        """
35        return host_is(self.host, *patterns)
36
37    def path_is(self, *patterns: str) -> bool:
38        """Matches a wildcard pattern against the request path
39
40        Includes query string `?` and fragment `#`
41
42        Returns:
43            bool: True if at least one pattern matched
44        """
45        req = self.request
46        if req is None:
47            return False
48
49        return req.path_is(*patterns)

Contains request and response and some utilities for match()

Flow( scheme: Literal['http', 'https'] = 'http', host: str = '', port: int = 0, request: Request | None = None, response: Response | None = None, text: bytes | None = None) View Source

13    def __init__(
14        self,
15        scheme: Literal["http", "https"] = "http",
16        host: str = "",
17        port: int = 0,
18        request: Request | None = None,
19        response: Response | None = None,
20        text: bytes | None = None,
21    ):
22        self.scheme = scheme
23        self.host = host
24        self.port = port
25        self.request = request
26        self.response = response
27        self.text = text

scheme

host

port

request

response

text

def host_is(self, *patterns: str) -> bool: View Source

29    def host_is(self, *patterns: str) -> bool:
30        """Matches a wildcard pattern against the target host
31
32        Returns:
33            bool: True if at least one pattern matched
34        """
35        return host_is(self.host, *patterns)

Matches a wildcard pattern against the target host

Returns: bool: True if at least one pattern matched

def path_is(self, *patterns: str) -> bool: View Source

37    def path_is(self, *patterns: str) -> bool:
38        """Matches a wildcard pattern against the request path
39
40        Includes query string `?` and fragment `#`
41
42        Returns:
43            bool: True if at least one pattern matched
44        """
45        req = self.request
46        if req is None:
47            return False
48
49        return req.path_is(*patterns)

Matches a wildcard pattern against the request path

Includes query string ? and fragment #

Returns: bool: True if at least one pattern matched

ctx: Context = {}

The Scalpel Python execution context

Contains the Burp Java API object, the venv directory, the user script path, the path to the file loading the user script and a logging object

class Context(typing.TypedDict): View Source

 6class Context(TypedDict):
 7    """Scalpel Python execution context"""
 8
 9    API: Any
10    """
11        The Burp [Montoya API]
12        (https://portswigger.github.io/burp-extensions-montoya-api/javadoc/burp/api/montoya/MontoyaApi.html)
13        root object.
14
15        Allows you to interact with Burp by directly manipulating the Java object.
16    
17    """
18
19    directory: str
20    """The framework directory"""
21
22    user_script: str
23    """The loaded script path"""
24
25    framework: str
26    """The framework (loader script) path"""
27
28    venv: str
29    """The venv the script was loaded in"""

Scalpel Python execution context

API: Any

The Burp [Montoya API] (https://portswigger.github.io/burp-extensions-montoya-api/javadoc/burp/api/montoya/MontoyaApi.html) root object.

Allows you to interact with Burp by directly manipulating the Java object.

directory: str

The framework directory

user_script: str

The loaded script path

framework: str

The framework (loader script) path

venv: str

The venv the script was loaded in

MatchEvent = typing.Literal['request', 'response', 'req_edit_in', 'req_edit_out', 'res_edit_in', 'res_edit_out']

def editor(mode: Literal['raw', 'hex', 'octal', 'binary', 'decimal']): View Source

12def editor(mode: EditorMode):
13    """Decorator to specify the editor type for a given hook
14
15    This can be applied to a req_edit_in / res_edit_in hook declaration to specify the editor that should be displayed in Burp
16
17    Example:
18    ```py
19        @editor("hex")
20        def req_edit_in(req: Request) -> bytes | None:
21            return bytes(req)
22    ```
23    This displays the request in an hex editor.
24
25    Currently, the only modes supported are `"raw"`, `"hex"`, `"octal"`, `"binary"` and `"decimal"`.
26
27
28    Args:
29        mode (EDITOR_MODE): The editor mode (raw, hex,...)
30    """
31
32    if mode not in EDITOR_MODES:
33        raise ValueError(f"Argument must be one of {EDITOR_MODES}")
34
35    def decorator(hook: Callable):
36        hook.__annotations__["scalpel_editor_mode"] = mode
37        return hook
38
39    return decorator

Decorator to specify the editor type for a given hook

This can be applied to a req_edit_in / res_edit_in hook declaration to specify the editor that should be displayed in Burp

Example:

    @editor("hex")
    def req_edit_in(req: Request) -> bytes | None:
        return bytes(req)

This displays the request in an hex editor.

Currently, the only modes supported are "raw", "hex", "octal", "binary" and "decimal".

Args: mode (EDITOR_MODE): The editor mode (raw, hex,...)

class Logger: View Source

 8class Logger:  # pragma: no cover
 9    """Provides methods for logging messages to the Burp Suite output and standard streams."""
10
11    def all(self, msg: str):
12        """Prints the message to the standard output
13
14        Args:
15            msg (str): The message to print
16        """
17        print(f"(default): {msg}")
18
19    def trace(self, msg: str):
20        """Prints the message to the standard output
21
22        Args:
23            msg (str): The message to print
24        """
25        print(f"(default): {msg}")
26
27    def debug(self, msg: str):
28        """Prints the message to the standard output
29
30        Args:
31            msg (str): The message to print
32        """
33        print(f"(default): {msg}")
34
35    def info(self, msg: str):
36        """Prints the message to the standard output
37
38        Args:
39            msg (str): The message to print
40        """
41        print(f"(default): {msg}")
42
43    def warn(self, msg: str):
44        """Prints the message to the standard output
45
46        Args:
47            msg (str): The message to print
48        """
49        print(f"(default): {msg}")
50
51    def fatal(self, msg: str):
52        """Prints the message to the standard output
53
54        Args:
55            msg (str): The message to print
56        """
57        print(f"(default): {msg}")
58
59    def error(self, msg: str):
60        """Prints the message to the standard error
61
62        Args:
63            msg (str): The message to print
64        """
65        print(f"(default): {msg}", file=sys.stderr)

Provides methods for logging messages to the Burp Suite output and standard streams.

def all(self, msg: str): View Source

11    def all(self, msg: str):
12        """Prints the message to the standard output
13
14        Args:
15            msg (str): The message to print
16        """
17        print(f"(default): {msg}")

Prints the message to the standard output