Scalpel: A Burp Suite extension to edit HTTP traffic, in Python 3

Scalpel is a Burp extension for intercepting and rewriting HTTP traffic, either on the fly or in the Repeater, using Python 3 scripts.

It is common to see additional obfuscation or encryption layers that make the audit process tedious, such as encrypted POST data or signed HTTP headers.

Although existing tools can modify requests on the fly (Burp Macros, Piper) or in the Repeater (Hackvertor), some cases are more complex and require external tools like mitmproxy. For instance, decrypting an encrypted HTTP parameter to view it in cleartext in Burp typically requires a cumbersome mitmproxy-Burp-mitmproxy setup.

A use-case example

To demonstrate how Scalpel can assist you, let us walk you through a practical example:

Suppose a web application sends POST data encrypted using the AES algorithm, and the encryption key is conveniently stored in the X-Key HTTP header. With Scalpel, you can configure your Repeater to display a new tab that automatically decrypts this data.

Scalpel adds its own interface to Burp, allowing you to create scripts, edit them directly in Burp, or use your own text editor:

The function req_edit_in can be implemented in a Python script to decrypt the content and display the plaintext in the Repeater:

def req_edit_in(req: Request) -> bytes | None:
    secret = req.headers["X-Key"]
    encrypted = req.form[b"encrypted"]
    if not encrypted:
        return b""

    return decrypt(secret, encrypted)

Additionally, the tab can be used to modify the plaintext, which will be encrypted again automatically. The function req_edit_out can be implemented to re-encrypt the plaintext:

def req_edit_out(req: Request, text: bytes) -> Request:
    secret = req.headers["X-Key"]
    req.form[b"encrypted"] = encrypt(secret, text)
    return req

Scalpel even allows you to apply a change to the whole traffic by implementing the request function:

def request(req: Request) -> Request:
    secret = req.headers["X-Key"]
    req.form[b"encrypted"] = encrypt(secret, "<script>alert(1)</script>")
    return req

Here are a few cases we used Scalpel for:

• Encrypting/decrypting traffic
• Extracting values to a log file
• Signing HTTP requests
• Decompressing responses
• Implementing a custom protocol encapsulated in HTTP

Main features

• Write Python 3 scripts: Since Burp only supports Python 2.7, Scalpel has implemented its own framework to support Python versions greater than 3.8.
• Python library: Easy to use and well-suited for penetration testing.
• Manipulate HTTP traffic: Scalpel provides a set of predefined function names that can be implemented to intercept and modify HTTP requests and responses.
• Create custom Burp editors: Program your own Burp editors in Python to handle encoded/encrypted content as plaintext.

See our GitHub repository.

💡 Find example use cases here.

⚠️ Because Scalpel is in Alpha version, it is not stable yet.
If you encounter any bug, feel free to open a GitHub issue.

Scalpel is designed to be easy to use, but some issues may still occur. In the next section, we'll discuss the limitations we encountered during its development.

Scalpel’s implementation and limitations

We faced many challenges during the development process.

1. Implementing Python 3 support

Developing Python Burp extensions using Jython was not an option because Python 2.7 is the last supported version and it reached end-of-life in 2020. Additionally, Burp published a new API this year. Since it is compatible with Java only, the former one is now deprecated.

That’s why we chose Jep (Java Embedded Python) to implement a custom Java/Python interface.

Jep relies on the libpython library to seamlessly manipulate Java objects in Python and vice versa. Thus, advanced Scalpel users can directly access the Burp API if needed.

Scalpel aims to be very simple to use. It embeds a Python framework designed for penetration testing, strongly inspired by tools widely used by pentesters, such as mitmproxy.

2. Handling dependencies

In the early stages of development, Scalpel used the global Python environment to install its requirements, which led to package conflicts. To avoid these conflicts, a fresh environment (venv) is now created during Scalpel’s installation.

However, for Jep to function properly, specific libraries, a JDK, and a C compiler must be installed beforehand.

Despite striving to offer the best user experience possible, Scalpel can malfunction or stop working due to dependency issues, making the installation process complex and leading to unexpected problems.

3. Handling Burp API limitations

The Burp API presents many limitations and challenges for developers. It doesn’t provide access to every feature, and there is limited control over the graphical interface. The documentation (basically a Javadoc) sometimes lacks detailed explanations of object behaviors and usage. Moreover, unexpected behaviors can occur, such as null pointers being returned randomly or unplanned object rewrites. Its architecture is also unsafe for parallel operations (not thread-safe), which can lead to deadlocks in asynchronous tasks.

Another challenge was handling Burp API extensions. When an extension is uninstalled or disabled, some native libraries it loaded may remain. This causes the application to crash whenever the extension is installed or enabled again. As a result, the developer has to restart Burp every time the extension’s Java code is modified, which can be very time-consuming.

Lastly, since Burp Suite is proprietary, all its symbols and interfaces are obfuscated, making bug-solving very difficult.

Conclusion

Scalpel simplifies auditing applications that need to automatically modify HTTP traffic, especially when additional encryption layers are used.

As Scalpel is in its Alpha version, you may encounter bugs. Since the project is constantly being improved, your feedback is very valuable to us. Don’t hesitate to contribute in the GitHub repository.

For further explanations, read the documentation.

We're hiring!

Ambionics is an entity of Lexfo, and we're hiring! To learn more about job opportunities, do not hesitate to contact us at rh@lexfo.fr. We're a French-speaking company, so we expect candidates to be fluent in our beautiful language.