Overview
In this blog post series, we’ll guide you through the process of creating Burp extensions. First, we will set up your development environment. Then, we will create a basic extension to add a custom feature to Burp Suite. Over the course of the series, we will slowly add new functionality and improve our extension.
Whether you’re a web app pentester seeking to optimize your Burp Suite experience or an enthusiastic developer eager to explore the realm of cybersecurity, this guide is for you.
Setting Up Your Development Environment
Let’s get started by setting up your development environment. We’ll use the Montoya API, which is compatible with Burp 2022.9.5 and later. Unlike the legacy API, Montoya is all Java-based, so it’s essential to be familiar with Java programming. If you’re new to Java, Codecademy offers a free Java course that can help you get started.
Installing Java 17 Development Kit
To develop Burp extensions, you’ll need the Java 17 Development Kit (higher Java versions are not currently supported). If you’re using Kali Linux or a similar distro, open your terminal and run the following commands to ensure your software repositories are up to date and install the OpenJDK 17 Development Kit:
sudo apt update
sudo apt install openjdk-17-jdkInstalling an Integrated Development Environment (IDE)
For the development of Burp extensions, we recommend using an IDE. There are many Java IDEs available, however IntelliJ IDEA is one of the easiest to set up. You can download the free community edition from the JetBrains website.
Create a new project in IntelliJ IDEA and give it a name, making sure you use the following options:
- Language: Java
- Build system: Maven
- JDK: 17
- Deselect “Add sample code”
Adding the Montoya API to Your Project
To incorporate the Montoya API into your project, you’ll need to add the dependencies to the pom.xml file within IntelliJ IDEA. Enter the following code before the closing </project> tag:
<dependencies>
<dependency>
<groupId>net.portswigger.burp.extensions</groupId>
<artifactId>montoya-api</artifactId>
<version>LATEST</version>
</dependency>
</dependencies>Creating a JAR File
You need to set up your project to create a JAR file when you compile your code. This JAR file will be used to install or share your Burp extension. To do this, follow these steps:
- Open the top left hamburger menu and choose “Project Structure”.
- Click on “Artifacts” and add a new JAR artifact, choosing the “From modules with dependencies” option.
- Leave everything else as default, but ensure you select “Include in project build.”
With these preparations in place, you’re ready to start coding your first Burp extension!
Developing Your Burp Extension
In your project pane, navigate to src → main, right-click on the java folder, and create a new Java Class for your extension. Give it a name like “MyFirstExtension”.
Inside your class, you will need to import the BurpExtension interface and the MontoyaApi:
import burp.api.montoya.BurpExtension;
import burp.api.montoya.MontoyaApi;
public class MyFirstExtension {
}BurpExtension interface using the implements keyword in the class definition, as well as creating an initialize method:public class MyFirstExtension implements BurpExtension {
@Override
public void initialize(MontoyaApi api) {
}
}Customizing Your Extension
In your initialize method, you can customize your extension. For example, to set the name of your extension using the Montoya API:
api.extension().setName("My First Extension");api.logging().logToOutput("Your message here");import burp.api.montoya.BurpExtension;
import burp.api.montoya.MontoyaApi;
public class MyFirstExtension implements BurpExtension {
@Override
public void initialize(MontoyaApi api) {
api.extension().setName("My First Extension");
api.logging().logToOutput("Your message here");
}
}Remember to save your file and build your extension. In IntelliJ, you can build the project by clicking “Build” in the hamburger menu or pressing Control + F9.
To see the build output, click the hammer icon in the bottom left. A green checkmark tells us that the build finished with no issues. In your project pane, navigate to out → artifacts and drill down. You should find that IntelliJ has compiled a JAR file.
Loading Your Extension in Burp Suite
To load your extension in Burp Suite, go to the “Extensions” tab, click “Add” in the “Installed” sub-tab, and select the JAR file you’ve just compiled. You can typically find all project related files in the IdeaProjects folder in your home directory. Once added, your extension will appear in the list of extensions, and you can access its output messages in the “Output” tab.
Adding Features to Your Extension
You can enhance your Burp extension by adding more features. In this example, we’ll show you how to tweak the requests that Burp sends by adding a custom header. To do this, you’ll need to import the HttpHandler classes:
import burp.api.montoya.http.handler.*;
import burp.api.montoya.http.message.requests.HttpRequest;We can implement the HttpHandler interface by adding it to the implements keyword section in the class definition:
public class MyFirstExtension implements BurpExtension, HttpHandler {In the initialize method, we must register the HttpHandler with Burp:
api.http().registerHttpHandler(this);handleHttpRequestToBeSent and handleHttpResponseReceived methods, even if we only need to use one. The full code for our extension should now look like this:import burp.api.montoya.BurpExtension;
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.http.handler.*;
public class MyFirstExtension implements BurpExtension, HttpHandler {
@Override
public void initialize(MontoyaApi api) {
api.extension().setName("My First Extension");
api.logging().logToOutput("Your message here");
api.http().registerHttpHandler(this);
}
@Override
public RequestToBeSentAction handleHttpRequestToBeSent(HttpRequestToBeSent httpRequestToBeSent) {
return null;
}
@Override
public ResponseReceivedAction handleHttpResponseReceived(HttpResponseReceived httpResponseReceived) {
return null;
}
}handleHttpRequestToBeSent method. Here’s an example of how you can add a custom header:@Override
public RequestToBeSentAction handleHttpRequestToBeSent(HttpRequestToBeSent httpRequestToBeSent) {
HttpRequest request = httpRequestToBeSent.withAddedHeader("New-Header", "Tib3rius");
return RequestToBeSentAction.continueWith(request);
}Remember to save and rebuild your project, and then reload the updated extension in Burp Suite.
To see the added header, send a request through Burp (e.g. using a proxied browser) and look at the request in the Logger tab. Note that any modifications you make to requests won’t be shown in other tools (e.g. Proxy HIstory, Repeater, etc.) using this method.
Conclusion
Congratulations! You’ve learned the basics of Burp extension development using the Montoya API. With the help of IntelliJ, you can create custom extensions to enhance your Burp Suite experience. In the next part of this series, we will explore more advanced features and coding practices. You can also find the code from this series on GitHub.
Penetration Testing – PCI Compliance – Auditing
See How We Can Secure Your Assets
Let’s talk about how TCM Security can solve your cybersecurity needs. Give us a call, send us an e-mail, or fill out the contact form below to get started.