Edit on GitHub

#  Event Hooks

Scalpel scripts hook into Burps’s internal mechanisms through event hooks.

These are implemented as methods with a set of well-known names. Events receive Request, Response, Flow and bytes objects as arguments. By modifying these objects, scripts can change traffic on the fly and program custom request/response editors.

For instance, here is an script that adds a response header with the number of seen responses:

from pyscalpel import Response

count = 0

def response(res: Response) -> Response:
    global count

    count += 1
    res.headers["count"] = count
    return res

#  Intercept and Rewrite HTTP Traffic

#  Request / Response

To intercept requests/responses, implement the request() and response() functions in your script:

E.g: Hooks that add an arbitrary header to every request and response:

from pyscalpel import Request, Response

# Intercept the request
def request(req: Request) -> Request:
    # Add an header
    req.headers["X-Python-Intercept-Request"] = "request"
    # Return the modified request
    return req

# Same for response
def response(res: Response) -> Response:
    res.headers["X-Python-Intercept-Response"] = "response"
    return res

#  Match

Decide whether to intercept an HTTP message with the match() function:

E.g: A match intercepting requests to localhost and 127.0.0.1 only:

from pyscalpel import Flow

# If match() returns true, request(), response(), req_edit_in(), [...] callbacks will be used.
def match(flow: Flow) -> bool:
    # True if host is localhost or 127.0.0.1
    return flow.host_is("localhost", "127.0.0.1")

#  Further reading