PortSwigger’s Burp Suite is one of the best-known tools for web application penetration testing. Burp Suite’s strength lies not only in its integrated modules such as proxy, scanner and repeater, but above all in its extensibility. There are various ways to extend Burp Suite with functionality, including BChecks, Bambdas and what is probably the oldest method, extensions. This article will briefly discuss the different types and then dive deeper into the development of an extension with Kotlin. Alongside this article, we are also publishing the first version of HeaderMate, our own Burp Suite extension for logging and evaluating server response headers.

Bambdas

Bambdas were already introduced in the article Burp Bambdas & BCheck. These are Java code snippets that enable filtering in several places in Burp. Since the publication of the last article, Bambdas can also be used in the logger capture filter to specify the traffic that is to be analysed later in more detail. In addition, the site map can also be filtered more finely with the help of Bambdas. Bambdas have been given limited access to the MontoyaApi in order to create more advanced match and replace rules. There is now also a separate output console for improved debugging of Bambdas.

BChecks

BChecks are another way to easily extend Burp Suite with minimal coding. BChecks are scan checks that can be written or added by the user. An introduction and example can be found in the article Burp Bambdas & BCheck.

Extensions

Burp Suite can be tailored to your specific needs with Burp Extensions. Whether you want to automate a special security check, prepare data or expand the user interface, an extension can save you a lot of time and manual work. Extensions are much more complex to create than BChecks and Bambdas, but they are also much more powerful. Burp Extensions can be created in various programming languages.

Supported Programming Languages

PortSwigger offers developers several interfaces to extend Burp Suite. There are basically two APIs: The old Extender API and the new MontoyaApi. Burp extensions can be written in various programming languages:

• Java – The “primary language” for Burp development, as Burp Suite itself is also written in Java
• Kotlin – Also runs on the Java Virtual Machine (JVM) and extension developing with Kotlin was presented last year in a webcast by Virtue Security
• Python or Jython – Easy to get started for script developers or people with a Python background, ideal for rapid prototyping
• Ruby or JRuby – Suitable for Ruby developers, rarely used nowadays

In combination with Jython and JRuby, the legacy Extender API is used which is no longer actively maintained. Therefore, it is recommended to use Kotlin or Java in combination with the MontoyaApi for new developments. With very old versions of Burp Suite (e.g. 1.5.02), it was still possible to use a combination of Java and JavaScript e.g. Rhino for extensions.

BApp Store

Burp Suite includes a BApp Store, which can be used to install published extensions that have been added to the store by PortSwigger. Depending on the test setup, however, it may also be helpful to download and install the extensions via the BApp Store in the browser or directly via GitHub.

Burp Extender API (Legacy)

This API was the standard for a long time and is still widely used. Here, the extension registers itself via the IBurpExtender interface and can then implement various listeners:

• IHttpListener for HTTP requests and responses
• IScannerCheck for custom scans
• IMessageEditorTab for custom display tabs on the user interface

A major advantage is the large community and the many examples on the internet, especially on GitHub. However, the API is outdated, is no longer being developed and is partially confusing.

New features with the MontoyaApi

Since 2022, there has been the new MontoyaApi, which is more modern, clearly structured and easier to use. It relies on a clean object model and replaces the old Extender API. The MontoyaApi comes with a clear object model with consistent naming conventions instead of scattered interfaces. The Javadoc documentation linked above is understandable, comprehensive and contains various examples. It is considered future-proof, as the Extender API is no longer being developed and the new functions are being integrated into the MontoyaApi.

Basic Structure of an Extension with the MontoyaApi

An extension with MontoyaApi implements the interface burp.api.montoya.BurpExtension and overwrites the initialise method with the desired values and functionalities of the extension.

class MyFirstExtension : BurpExtension {
  private lateinit var montoyaApi: MontoyaApi
  override fun initialize(api: MontoyaApi?) {
    montoyaApi = requireNotNull(api) { "api : MontoyaApi is not allowed to be null" }
    montoyaApi.logging().logToOutput("Started loading the extension...")
    montoyaApi.extension().setName("MyFirstExtension")

    //register active or passive ScanChecks
    montoyaApi.scanner().registerPassiveScanCheck(MyOwnPassiveScanCheck(montoyaApi), ScanCheckType.PER_REQUEST)

    //register a ContextMenuItemsProvider
    montoyaApi.userInterface().registerContextMenuItemsProvider(MyOwnContextMenu(montoyaApi))
    montoyaApi.logging().logToOutput("...Finished loading the extension")
  }
}

The log outputs in this section are useful for easily determining whether the extension has been loaded successfully.

The MontoyaApi object provides access to:

• HTTP interception and manipulation
• Scanner integration (active and passive)
• UI extensions
• Logging and settings
• Burp’s AI integration
• And other Burp modules and functions

The desired interface can be extended using a separate class and registered in the MyFirstExtension class, thereby extending Burp Suite with the desired functionality. The GitHub repository KotlinBurpExtensionBase is a great place to start when developing extensions using Kotlin. It also describes how to create a jar using Gradle and shadowJar and how to connect a debugger to your extension.

HeaderMate

As part of this article, we began developing the HeaderMate extension. This is intended to replace our internal Burp Suite extension for evaluating server response headers, which was developed in Python and uses the old Extender API. In the new development, we have tried to make the extension less resource-intensive. To this end, only requests from previously configured host names are checked, and the extension offers the option of enabling or disabling issue creation within Burp Suite. In the background, the evaluated server response headers are written to the persistent memory of the Burp Suite project. Caution for temporary projects, the persistent memory is only available as long as Burp Suite is open.

Finally, the logged server response headers can be exported as a CSV file via the context menu, for example in the proxy history. The export is well suited for evaluation with an internal script and conversion to the required format for the desired reporting tool. The evaluated server response headers are exported in CSV format, using the ASCII unit separator 0×1F as the separator. This is because it is machine-friendly and unique, and is not permitted in HTTP header values or URLs.

The HeaderMate extension also has a configuration file that specifies which headers are checked, what their optimal values are, and what the values are for different severity levels. There is a default configuration file that is also included with the extension. You can also load your own configuration file with different headers. As long as new server response headers are not special cases, such as content security policy, the idea is that it will work without any adjustments to the extension code. However, new special cases require certain adjustments to the extension itself. Kotlin was chosen over Java for development because Kotlin offers a more modern syntax, null safety, and many convenience features.

The content of the default configuration file complies with OWASP recommendations and the articles Inglorious Headers, Response Header Hardening and HTTP Strict Transport Security – Five Common Mistakes and How to Fix Them.

How it works

The main functionality of the HeaderMate extension takes place in the HeaderScanCheck class, more specifically in the passiveAudit method.

First, it checks whether there has been a change to the configuration. Then it checks the initial termination criteria, whether a response is existing, and whether responses from this host should be checked. Next, it goes through the active header configuration line by line or header by header, performing the following steps:

1. The header and its value are marked in the current response for issue creation.
2. If the header is not found in the response, a log entry is created and, if issue creation is active, an issue is generated. The severity of the issue depends on the configuration for an unset header.
3. If the header is set, a check is performed to determine whether it is the optimal value, which leads to a passed issue.
4. If it is not the optimal value, the remaining values from the configuration are checked, as well as the special cases that are not yet included in the first published version. If no match can be made with the configuration, the severity level false positive is set in the code in the first published version and no issue is created. This is a conscious development decision.

Future Enhancements

In the latest versions of Burp Suite, there was another change to the scan checks in MontoyaApi, whereby the interface burp.api.montoya.scanner.ScanCheck was declared deprecated and PassiveScanCheck or ActiveScanCheck should now be used depending on the scan check. The change to PassiceScanCheck in HeaderMate led to some curious side effects that have not yet been resolved. The changeover to the PassiveScanCheck interface will therefore take place in a future version. In the first published version, only the optimal configuration and a few special cases such as the CacheControl header are checked and the severity level is set accordingly. This will also be further expanded in the next releases.

Conclusion

Developing Burp extensions is a powerful way to automate your own security tests and customise Burp Suite. Whether in Java, Python or Kotlin, the flexibility of Burp Suite makes it possible to turn your own ideas directly into productive tools. With MontoyaApi, PortSwigger has created a modern approach that makes development easier, cleaner and future-proof. Using Kotlin and the extension base mentioned above, you can quickly set up a new extension. The large number of Burp extensions available in the BApp Store and on GitHub demonstrates the demand and possibilities for extending and personalising Burp Suite.

About the Author

Ralph Meier completed an apprenticeship as an application developer, with a focus on web development with Java, at a major Swiss bank and then completed a Bachelor of Science in Computer Science UAS Zurich at the ZHAW School of Engineering. His primary task is doing security-related analysis of web applications and services. (ORCID 0000-0002-3997-8482)

Links

• https://github.com/ncoblentz/KotlinBurpExtensionBase
• https://github.com/scipag/HeaderMate
• https://portswigger.github.io/burp-extensions-montoya-api/javadoc/burp/api/montoya/MontoyaApi.html
• https://portswigger.net/bappstore
• https://portswigger.net/burp
• https://portswigger.net/burp/documentation/desktop/extend-burp/extensions/creating/extender-api-examples-legacy
• https://www.scip.ch/?labs.20160121
• https://www.scip.ch/?labs.20180308
• https://www.scip.ch/?labs.20190214
• https://www.scip.ch/?labs.20240111
• https://www.youtube.com/watch?v=C8r6uSem93A