Burp Suite Python Extensions

July 18, 2022
Zandt Lavish
10 min read

Beyond the Tool

PortSwigger’s Burp Suite is a must have tool in the repertoire of any web application pentester. Master its default services and you have a highly respected skill set. Master its API and you’re overpowered.


Burp Suite Extender

Burp Suite offers an API that allows you to tailor it’s already present tool set to specific application. Documentation of the API can be found in the Burp Suite app itself under Extender > APIs. For a slightly more readable version of the info, you can checkout PortSwigger’s website. Keep in mind, the examples and description they give is in Java. 

You can also navigate to Extender > BApp Store to see examples of extensions that have been validated by PortSwigger. The code for all of these can be found on the PortSwigger GitHub page. Let’s practice making our own.



While we hypothetically want to write our extension in Python,BurpSuite is written in Java. In compromise, we’ll actually be writing in Jython – the Java variant of Python. Keep in mind for syntax that it’s based onPython2 rather than Python3. A little disheartening that it’s not purely python,yes, but this will get the fun stuff done.

Because this is Jython, we’ll need the Jython standalone JAR file to use Jython without having to install it. We can get this ­­– as described on PortSwigger’s site – at jython.org and clicking the Jython Standalone hypertext. Once downloaded, you can place this file wherever you’d like, just make sure you know how to navigate to it because now we need to point to it.

Navigate to Burp Suite > Extender > Python Environment> Options and point the “Location of Jython standalone JAR file” to the Jython JAR file, wherever you placed it. Now we have the Jython interpreter available to us.


Adding our extension

First let’s make a frighteningly basic extension and see how we connect it to Burp Suite. You can call it anything you’d like as long as it ends with the python ‘.py’ extension.

Make an import and start the main class (Quick note – make sure you pip install burp first).


Give your extension a name,


And give a message to be seen when we link it to Burp Suite.


Our first Burp Suite extension script! Now go to Extender> Extensions, click Add, choose “Python” as the Extension type,set Extension file to the python file you’ve been working on (wherever you saved it), and click Next. This will load the file in and check that it compiles correctly. The Output page should look like this,

And there should be no errors under the Errors tab.

Now, navigate to your Dashboard and check the Event Log ­(bottom left of the window by default) – you should see the info from the Extender that looks something like this


We have a running Burp Suite extension!


The Fun Stuff

For a more functional extension, we can do a simple example of using the HttpListener method. This will listen for any web requests and responses passing through the proxy setup with our Burp Suite so we can grab them and modify them. If you need to setup a proxy, take a look at our insight here.

Using the template we already scripted, import IHttpListener from burp and include it as a parameter into the BurpExtender class we made earlier. We’ll also register the listener within the method we’ve already made.


Next we’ll define the method to grab the headers and body of the webpage request. This will pull out the info we need to get the headers info and the body from the response. Then we’ll be able to work with them.


Then we’ll grab the headers and body and turn them into a list and string respectively to be able to work with them in python. Then we’ll return both.


Finally create the process HttpMessage required by the IHttpListener interface (as explained in the documentation).


Pull in the headers and body variables we returned from our getResponseHeadersAndBody method. As our example interaction with the web request, we’ll simply modify the body by making it display twice.


Then return the message


That’s it for the script! Go to the Burp Suite window, navigate to Proxy > Intercept, and select Intercept. Next select Open Browser and go to example.com.


Now let’s apply our code. Navigate back to Extender >Extensions and uncheck the Loaded option for the extension and recheck it. This will prompt Burp Suite to reload the code, updating it from its earlier state. Navigate back to the browser we opened through Burp Suite and refresh the page. You should see double!


For a little more fun, add this to the processHttpMessage method and see what it does


We have a working Burp Suite extension waiting to be taken to the next level!



Scripting extensions for Burp Suite is different than any other Python you’re most likely going to write. This said, between Burp Suite’s APIs tab, PortSwigger’s website and GitHub page, and the leverage this gives for an already powerful tool, making an extension is hard to pass up. For more insights like this, check out our other posts and find new ones weekly!

Let's Get Started

Book a time to chat about your security needs.
* Indicates a required field.
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.