fbpx
TCM Security is offering free Active Directory Health Checks to any company with 10 or more employees. To inquire, please contact us here.

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-jdk

Installing 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>
You can ensure that the Montoya API library was downloaded successfully by checking the “External Libraries” in your project.

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:

  1. Open the top left hamburger menu and choose “Project Structure”.
  2. Click on “Artifacts” and add a new JAR artifact, choosing the “From modules with dependencies” option.
  3. 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 srcmain, 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 {
}
Next, you must implement the 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");
In addition, you can also log messages using the Montoya API:
api.logging().logToOutput("Your message here");
The full code for our extension so far should look like this:
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 outartifacts and drill down. You should find that IntelliJ has compiled a JAR file.

A successful build log from IntelliJ.

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.

Loading a Burp Extension using a JAR file.

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);
Consequently, we must implement both the 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;
	}
}
Finally, to modify requests before Burp sends them, we’ll need to write code in the 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.

An HTTP request modified by our Burp Extension.

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.

 

tel: (877) 771-8911 | email: info@tcm-sec.com