Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 38 ยท Scanner and Extensions

Extensions, the BApp Store and the Montoya API

Learn how Burp extensions work, how to install them from the BApp Store, how to review one for safety, and how the Montoya API lets you write your own passive check.

Burp Suite is useful straight out of the box, but its real strength is that you can add to it. Extensions are add-ons that can hook into the proxy, add scanner checks, decode special formats, colour-code traffic, or add whole new tabs. Thousands have been written by the community, and you can write your own. This lesson shows how to find and install extensions safely and how a simple extension is structured.

As elsewhere in this track, Burp itself is a desktop application that cannot run in your browser. The Java and screen examples are read-only and labelled; the runnable block is a Python stand-in that models an extension's logic.

What an extension can do

Extensions plug into Burp at defined extension points. The most common ones:

Extension point What your code can do
HTTP handler See and change every request and response from any tool
Proxy handler Intercept, edit, drop or highlight proxy traffic
Scanner checks Add passive or active checks that the scanner runs
Editor tabs Add a custom view, for example a decoded form of a binary format
Context menu Add right-click items such as "Send to my tool"
Session handling Provide custom token or signature logic
Collaborator Use out-of-band interaction results in your own checks

The BApp Store

The BApp Store (Extensions tab, BApp Store) is a catalogue of reviewed extensions you can install with one click. Each entry shows a description, rating, last update, and the languages it needs. Examples of widely used ones, described by purpose rather than detail:

  • Logger-style extensions that keep a searchable record of all traffic.
  • Decoders for formats such as JWT, protocol buffers or Java serialised objects.
  • Authorisation testers that replay requests with another user's session to check access control.
  • Scanner add-ons that look for specific issue classes.

Extensions are written in Java (using the Montoya API), Python (via Jython, older API) or Ruby (via JRuby). Python and Ruby extensions need you to point Burp at the interpreter JAR in the Extensions settings.

Install, then review

An extension runs inside Burp with access to all your traffic, including the cookies and passwords of any system you test. Treat it like any software you run on a work machine.

Install extensions from the BApp Store or from sources you trust and can read. A malicious extension could send your captured traffic anywhere. Never install an extension just because a forum post tells you to.

A short review checklist before you add one:

  1. Is it in the BApp Store, or is the source public?
  2. When was it last updated? Is it compatible with your Burp version?
  3. Does it make network requests of its own? Why?
  4. What permissions does it need, for example reading all traffic?
  5. Try it first in a separate Burp project with no client data.

The Montoya API

The current Java API is called Montoya. An extension is a class that implements BurpExtension and registers handlers when Burp loads it. Here is a read-only example (labelled example code): a passive check that flags responses sending a cookie without the HttpOnly flag.

Java
import burp.api.montoya.BurpExtension;
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.http.handler.*;

public class CookieFlagWatcher implements BurpExtension {
    private MontoyaApi api;

    @Override
    public void initialize(MontoyaApi api) {
        this.api = api;
        api.extension().setName("Cookie Flag Watcher");
        api.http().registerHttpHandler(new HttpHandler() {
            @Override
            public RequestToBeSentAction handleHttpRequestToBeSent(HttpRequestToBeSent request) {
                return RequestToBeSentAction.continueWith(request);
            }

            @Override
            public ResponseReceivedAction handleHttpResponseReceived(HttpResponseReceived response) {
                response.headers().stream()
                    .filter(h -> h.name().equalsIgnoreCase("Set-Cookie"))
                    .filter(h -> !h.value().toLowerCase().contains("httponly"))
                    .forEach(h -> api.logging().logToOutput(
                        "No HttpOnly: " + h.value()));
                return ResponseReceivedAction.continueWith(response);
            }
        });
    }
}

The pattern is always the same: implement initialize, register a handler, and inside the handler read the message and optionally return a changed one. You package the class as a JAR, then load it in Extensions, Add. Output appears in the extension's Output tab and errors in Errors.

The same logic as a runnable stand-in

You cannot run the Java here, but the core of the extension is a few lines of text handling. This stand-in feeds fake responses through the same decision.

Python Cookie flag watcher logic (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that the handler returns the response unchanged, because this extension only observes. A modifying extension would return an edited copy.

Passive versus active extension checks

A scanner-check extension can be passive (examines responses already seen) or active (sends payloads). Prefer passive whenever you can: it adds no traffic and no risk. Active checks must use Burp's request API so they respect scope, throttling and the project's logging, rather than opening their own sockets.

Managing extensions

In the Extensions tab you can:

  • Toggle an extension on and off without removing it.
  • See Output and Errors per extension. A crashing extension may slow Burp, so check here first when something misbehaves.
  • Set Java and Python environment paths under Extension settings.
  • Reload an extension after changing its code, which is handy while developing.

Keep your set small. Ten extensions that each touch every request make Burp sluggish, and each one is more code you have to trust.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the BApp Store?

    The BApp Store hosts extensions that can be installed with one click.
  2. 2. Why should you be careful when installing an extension?

    Extensions have broad access to captured traffic, so only trusted code should be installed.
  3. 3. Which class do you implement in the Montoya API to write an extension?

    A Montoya extension implements BurpExtension and its initialize method.
  4. 4. Why prefer passive checks in extensions where possible?

    Passive checks analyse existing traffic and do not send anything new.

Summary

  • Extensions add handlers, scanner checks, editor tabs and menu items to Burp.
  • Use the BApp Store, review before installing, and test new extensions in a throwaway project.
  • Montoya extensions implement BurpExtension.initialize and register handlers.
  • Prefer passive checks and keep the installed set small.
  • The Java and screens shown are labelled read-only examples; the Python block models the logic.

Next: Session token analysis with Sequencer