Awesome

PyBurp

中文版

PyBurp is a powerful Burp Suite extension that enables you to write simple Python code to dynamically modify HTTP requests and responses. It is especially useful for handling scenarios where HTTP requests and responses are encrypted, as it supports remote invocation of encryption and decryption methods in Chrome or mobile applications.

In addition, PyBurp supports:

• Complex nested JSON, Query String, and XML Content-Type conversions
• Dynamic registration of custom context menus
• Saving relevant information from HTTP history to an SQLite database
• Chrome DevTools Protocol
• gRPC
• ...

Video

Interaction with Chrome： https://youtu.be/FRCnZ8a7UGI
Interaction with Frida： https://youtu.be/zfvNqd5VmY0?t=45

For method calls in mobile applications, PyBurp relies on Frida for remote interaction.

Please note that the above features have been thoroughly tested on Burp Suite v2024.5.4. It is recommended to use this version or a later one for optimal compatibility and stability.

Installation

Download from the Release page or install directly from the BApp Store. You can open PyBurp from the top level menu bar.

To use gRPC or invoke methods in mobile applications, you also need to install pyburp.

pip install pyburp

Usage Guide

Predefined Functions

PyBurp includes several predefined functions. When you define these functions in your script, they are automatically registered in Burp Suite with the corresponding functionality. The detailed predefined functions are listed in the table below:

After running the script, you can view the registration details in the Details tab of the Extensions in Burp Suite.

Examples

To help you get familiar with using predefined functions, PyBurp includes several common scripts, as listed in the table below:

Please note that modifications to the built-in example script files will not be saved. <span id="jump"></span>

Registering Context Menu

To register context menu items in your code, you first need to define a function named registerContextMenu that accepts a menus as a parameter.
Then, call the register method of the menus object to register specific menu items. The register method takes three parameters: the name of the menu, the name of the function associated with the menu item (which is called when the menu item is clicked), and the MenuType. The table below shows the MenuType options and the requirements for associated functions:

The following code demonstrates how to register a purify headers context menu item that removes extraneous request headers from an HTTP message editor request:

def removeBoringHeaders(editor):
    request = editor.requestResponse().request()
    editor.setRequest(request.withRemovedHeader("Sec-Ch-Ua")\
                             .withRemovedHeader("Sec-Ch-Ua-Mobile")\
                             .withRemovedHeader("Sec-Ch-Ua-Platform")\
                             .withRemovedHeader("Sec-Fetch-Site")\
                             .withRemovedHeader("Sec-Fetch-Mode")\
                             .withRemovedHeader("Sec-Fetch-Dest")\
                             .withRemovedHeader("Priority")
                             )

def registerContextMenu(menus):
    menus.register("purify headers", removeBoringHeaders, MenuType.MESSAGE_EDITOR)

When using MESSAGE_EDITOR as the menu type, the following two utility methods are also available:

• getSelectedText(editor), Retrieves the selected text, returning a ByteArray object.
• replaceSelectedText(editor, "new string")，Replaces the selected text in editor, returning an HttpRequest object.

For more examples, please refer to customise_context_menu.py.

RPC

PyBurp allows calling methods provided by other programs via gRPC. You need to implement the service interfaces defined in burpextender.proto for these calls.。

For Python users, the related service interfaces are already implemented in pyburp. You can install and use this library via pip install pyburp.
For other programming languages, generate code from the burpextender.proto file and implement the corresponding service interfaces.

Here’s a Python demonstration:

1. Run the RPC server with the following code, which provides test1 and test2 functions:

   import pyburp
   from base64 import b64encode
   
   def test1(s):
       return b64encode(s)
   
   def test2(i, j):
       return i + j
   
   pyburp.expose(test1)
   pyburp.expose(test2)
   pyburp.run("127.0.0.1:30051")
   

2. Run the client code in PyBurp as follows:

   server = rpc("localhost", 30051)
   result1 = server.callFunc('test1', bytearray("123"))
   result2 = server.callFunc('test2', 3, 4)
   print(result1)
   print(result1.tostring()) # or print(bytearray(result1))
   print(result2)
   server.shutdown()
   

For examples of interactions with Frida, please check server_frida.py

Note:

1. PyBurp supports only the following parameter types: str,bool,int,float,bytes,None.
2. If the server-side exposed method has only one parameter and it is of type bytes，in PyBurp, you need to wrap the parameter using bytearray or place it in []; otherwise, byte[] will be treated as a variable-length argument array, with each byte being treated as an individual argument.
3. The bytes type returned by the server is of type array.array('b',initializer) in PyBurp，you can consider it as byte[], except that you need to use tostring() to convert it to a string instead of toString().

Contributions

We’re excited about the future of this project and have a roadmap of upcoming work. We welcome contributions from the community to help us achieve our goals. Whether you’re fixing bugs, adding features, or improving documentation, your help is greatly appreciated!. Here’s what we’re focusing on next:

1. Simplify the HttpRequestEditorProvider and HttpResponseEditorProvider registration process
2. Code Completion, here is an example.
3. Perhaps a lightweight search box is needed.
4. HyperLink clickable.

Thank you for your support and involvement!

Questions

1. Why are some Python libraries or methods not available in PyBurp？
   PyBurp uses the Jython interpreter rather than standard CPython, so not all third-party Python libraries are compatible. However, it can seamlessly access Java libraries.

2. How do you create a byte array compatible with byte[] in Jython?
   Here are three methods to create it. Note that you need to use tostring() to convert it to a string instead of toString().

   • bytestring("asdf")

   • bytearray("asdf").getBytes()

   • import array; print(array.array('b', [97, 115, 100, 102]))

Acknowledgements

Much of PyBurp’s inspiration comes from Turbo Intruder