PROFESSIONALCOMMUNITY

Burp Extender

  • Last updated: August 25, 2022

  • Read time: 7 Minutes

Burp Extender lets you enhance Burp's functionality by installing extensions created by the community, or even writing your own.

Burp extensions can customize and extend Burp Suite's behavior in numerous ways. These can include:

  • Modifying HTTP requests and responses.

  • Sending additional HTTP requests.

  • Customizing Burp Suite's interface.

  • Adding extra checks to Burp Scanner.

  • Accessing information from Burp Suite.

Note

From the 2022.5 release, Burp Suite requires Java 11 or later to run. This change should not impact you unless you run Burp Suite as a JAR file. However, any extensions written in a version of Java earlier than 11 may not run correctly from Burp Suite 2022.5 onward.

About the BApp Store

The BApp Store contains community-created extensions, or BApps, that we have reviewed for security and quality.

You can access the BApp Store from the Extender > BApp Store tab. Here, you can view and install available BApps. You can also rate BApps that you have already installed.

Installing extensions from the BApp Store

To install an extension from the Extender > BApp Store tab, select it from the list and then click the Install button in the description panel.

Installing a BApp from the BApp Store

Some BApps are written in Python or Ruby. To use these, you need to download Jython or JRuby, and configure the Python environment or Ruby environment settings on the Extender > Options tab.

You might need to update Burp Suite or upgrade to Burp Suite Professional to install some BApps.

If you install an extension from the BApp Store, Burp Suite keeps it up to date automatically.

Managing extensions

You can see a table of installed extensions on the Extender > Extensions tab.

Requests and responses pass through extensions in the same order that they appear in the table, from top to bottom. Therefore, if you have multiple extensions loaded that modify requests, it is important that these are listed in the order that you want each modification to occur. You can change this order using the Up and Down buttons.

To disable an extension without removing it from the list, clear its checkbox in the Loaded column.

To uninstall an extension and remove it from the list, click the Remove button.

Note

The type and the number of extensions that you use may impact your system performance. The System impact column shows the estimated impact that each BApp could have. The Estimated system impact bar shows how much the combination of loaded BApps is likely to impact performance.

Installing an extension from a file

To install extensions from outside the BApp Store, use the Add button next to the Burp Extensions table.

You can also install a BApp downloaded as a file from the BApp Store website in the same way. This is useful if you are running Burp Suite on a machine without internet access.

To install extensions written in Python or Ruby, you need to download Jython or JRuby, and configure the Python environment or Ruby environment settings on the Extender > Options tab.

If you update the file of an extension installed like this, you then need to reload it in Burp Suite using the Loaded checkbox. You can fast-reload an extension without showing a confirmation dialogue by Ctrl/⌘+clicking the Loaded checkbox.

Extension details

Selecting an item in the extensions table shows information about that extension in the lower panel.

The Details tab shows the following information:

  • Whether the extension is currently loaded. You can click on the checkbox to load or unload the selected extension.
  • The extension's name. You can manually edit this name if required.
  • The type of the extension (Java, Python, or Ruby).
  • The file name of the extension.
  • Details of methods, listeners, and other resources that the extension uses.

The Output tab contains details of the extension's standard output stream. The Error tab contains the same information about the standard error stream. For each stream, you can configure whether the application's output should be directed to the system console, saved to file, or displayed in the UI. Please note:

  • The UI-based output window is limited in size and is not intended for heavy duty logging.
  • Extensions are responsible for directing their output and error messages to the correct streams which Burp has assigned to them, and which are programmatically available via the extensibility API. Extensions that do not honor this may direct output directly to the system console regardless of the settings specified here.

How extensions impact system performance

An extension can make Burp Suite carry out a wide range of additional tasks. If these tasks are resource-intensive or time-consuming, this can impact how Burp Suite performs.

Using multiple extensions at the same time has a cumulative effect on performance. If Burp Suite is performing slowly, try unloading some extensions.

Estimated system impact

In the BApp store, the Estimated system impact section shows the impact that a BApp might have on your system performance.

We list system impact as Low, Medium, or High.

The Estimated system impact is divided into the following categories:

  • Time shows the overall impact on the speed of Burp Suite. This includes the responsiveness of the interface and how long tools take to complete tasks.

  • CPU shows how much additional load the BApp places on the CPU.

  • Memory shows what impact the BApp is likely to have on Burp Suite's memory usage.

  • Scanner shows the likely impact on how long a scan takes to complete.

  • Overall shows the highest impact rating across all of these categories.

Our benchmarks are generated automatically using a range of tests, which we have designed to replicate normal usage of Burp Suite.

Note

These ratings are just an approximate guide and may not fully reflect the performance impact of a BApp. We are unable to fully test BApps that add custom tabs or context menu options.

Extender options

The Options tab contains options for extension settings, the Java environment, the Python environment, and the Ruby environment.

Settings

The following settings are available:

  • Whether to automatically reload extensions on startup. If Burp was shut down with this setting selected, and you nonetheless want to restart Burp without automatically reloading any extensions then you can start Burp with the command line flag --disable-extensions . This will prevent Burp from automatically reloading any extensions.
  • Whether to automatically update installed BApps on startup.

Java environment

These settings let you configure the environment for executing extensions that are written in Java. If your extensions use any libraries, you can specify a folder from which libraries will be loaded. Burp will search this folder and any subfolders for JAR files, and will include these in the classpath of the classloader that is used to load Java extensions.

Python environment

These settings let you configure the environment for executing extensions that are written in Python. To use Python extensions, you will need to download Jython, which is a Python interpreter implemented in Java. The following options are available:

  • Location of the Jython standalone JAR file - This is the location where you have downloaded Jython. You must download the standalone version of Jython.
  • Folder for loading modules - This setting is optional and can be used to specify a folder from which the Python interpreter should attempt to load modules that are required for your extensions. If configured, this option causes Burp to update the Python sys.path variable with the specified location. Using this option is useful if you have created your own set of Python libraries for use in multiple separate extensions.

Note

Because of the way in which Jython dynamically generates Java classes, you may encounter memory problems if you load several different Python extensions, or if you unload and reload a Python extension multiple times. If this happens, you will see an error like:

java.lang.OutOfMemoryError: PermGen space

You can avoid this problem by configuring Java to allocate more PermGen storage, by adding a -XX:MaxPermSize option to the command line when starting Burp. For example:

java -XX:MaxPermSize=1G -jar burp.jar

Ruby environment

These settings let you configure the environment for executing extensions that are written in Ruby. To use Ruby extensions, you will need to download JRuby, which is a Ruby interpreter implemented in Java. Note that you can either configure the location of the JRuby JAR file here, or you can load the JAR file on startup via the Java classpath.

Note

If you load several Ruby extensions, the same issue may arise with PermGen storage as is described for the Python environment, and the issue can be resolved in the same way.

Creating your own extensions

For help on creating your own Burp extensions, see the main extensibility documentation and our guide to submitting extensions to the BApp store.

Burp Extender API

The APIs tab contains details of the APIs that are available for creating Burp extensions. The listing shows the APIs that are available in the version of Burp that is running. Select the name of an interface from the list to show the interface code in full.

You can also use the Save interface files and Save Javadoc files buttons to save local copies of these files, for use when developing extensions.

Note for extension developers

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.

Was this article helpful?