Burp Extender

Burp Extender lets you use Burp extensions, to extend Burp's functionality using your own or third-party code. You can load and manage extensions, view details about installed extensions, install extensions from the BApp Store, view the current Burp Extender API, and configure options for how extensions are handled.

Burp extensions can customize Burp's behavior in numerous ways, such as modifying HTTP requests and responses, customizing the UI, adding custom Scanner checks, and accessing key runtime information, including the Proxy history, Target site map and Scanner issues.

For help on creating your own Burp extensions, see the main extensibility documentation.

Loading and managing extensions

The table shows a list of any installed extensions. You can add, remove and reorder extensions using the buttons by the extensions table. Please note:

• The order that extensions are shown is the order in which any registered listeners and other extension resources will be invoked.
• Extensions can be unloaded but retained in the table to enable easy reloading at a later time.To toggle an extension's loaded state without removing it from the list, click on the checkbox in the "Loaded" column or in the extension details panel. Note: You can fast-reload an extension by Ctrl+clicking the "Loaded" checkbox. This will unload and reload the extension without showing a confirmation dialog.
• To run extensions written in Python, you will first need to configure the location of the Jython standalone JAR, in the Python environment options.

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 name. Extensions can programmatically set their preferred name which appears in the UI. You can manually edit this name if required.
• The type of the extension (Java or Python).
• The file from which the extension was loaded.
• Details of methods, listeners, and other resources in use by the extension.

The Output tab contains details of the extension's standard output stream, and 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, or 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.

BApp store

The BApp Store contains Burp extensions that have been written by users of Burp Suite, to extend Burp's capabilities.

You can view the list of available BApps, install specific BApps, and submit user ratings for those you have installed.

If you do not have Internet access from the machine that is running Burp, you can download BApp files from the BApp Store web site, and manually install them into Burp.

Some BApps are written in Python or Ruby, and require you to download Jython or JRuby, and configure Burp with the location of the relevant language interpreters. Some BApps may require a more recent version of Burp, or a different edition of Burp.

Burp Extender API

This 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.

Extender options

This 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. Note: 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.