ProfessionalCommunity Edition

Creating Burp extensions

Last updated: October 29, 2024
Read time: 2 Minutes

If you're proficient in Java, you can create your own extensions for Burp Suite using our Montoya API. Note that Burp Suite only supports extensions written in Java 21 or lower.

To get started, create a new Maven or Gradle project and add a dependency for the Montoya API as follows.

Maven

<dependency>
    <groupId>net.portswigger.burp.extensions</groupId>
    <artifactId>montoya-api</artifactId>
    <version>LATEST</version>
</dependency>

Gradle

implementation 'net.portswigger.burp.extensions:montoya-api:+'

Next, create a class that implements the BurpExtension interface. The initialize() method gives you an implementation of the MontoyaApi, which you can use to modify and interact with Burp Suite.

When your extension is complete, you can submit it to the BApp Store to share it with other Burp users. Please refer to Submitting extensions to the BApp Store and BApp Store acceptance criteria.

Note

Many of the extensions on the BApp Store were written using our legacy Extender API. Burp Suite will continue to support the Extender API for the time being, but we strongly recommend writing any new extensions using the Montoya API instead.

Useful resources for extension developers

Although we can't provide detailed instructions on how to write your own extensions, you can refer to the following useful resources:

The Montoya API GitHub repository, which contains some example implementations of common tasks, such as registering an HTTP handler or Proxy listener.
The Montoya API JavaDoc.
A test extension that uses the Montoya API to implement most of the functions from the legacy Extender API. This provides a useful reference, especially if you're attempting to port an old extension. We've given each method the same name as its equivalent in the Extender API, so you can easily find what you're looking for.
The main PortSwigger GitHub repository contains a forked version of each extension that is available on the BApp Store, as well as some simple example extensions. However, note that most of these were written using the legacy Extender API.

Note

When you write extensions, make sure that any ExtensionHttpRequestEditor returned does not use an HttpRequestEditor as the UI component when it registers an HttpRequestEditorProvider. This avoids a scenario where the HttpRequestEditor is created within another HttpRequestEditor, potentially creating an infinite loop of HttpRequestEditor components and causing Burp to crash.

For the same reason, avoid returning an HttpResponseEditor when registering an HttpResponseEditorProvider.

Handling kettled HTTP/2 requests in extensions

When issuing new requests from your extension, you're free to send kettled requests using HTTP/2 formatting. This enables you to develop extensions to test for HTTP/2-exclusive vulnerabilities.

However, it is not currently possible for extensions to modify kettled requests that were issued by Burp. This is because they can only access the normalized, HTTP/1-style representation of them via the API.