Extension Workshop

Hands-on exercises for the Burp, But Yours workshop, where you build a working extension using the Montoya API.

Table of contents

  1. Prerequisites
  2. The Montoya API
  3. Set up your development environment
    1. 1. Get the starter project
    2. 2. Open it in IntelliJ
    3. 3. Build the JAR
    4. 4. Load it into Burp
  4. Working with classes
    1. One public class, one file
    2. Implementing an interface
    3. Why split the work across classes
    4. IntelliJ shortcuts
  5. The development loop
  6. Select your exercise
    1. Exercise A: Custom Editor Tab Beginner
    2. Exercise B: Custom Scan Check Intermediate
    3. Exercise C: Session Handling Advanced
  7. Using a large language model (LLM) to generate your extension
  8. Going further

Prerequisites

You don’t need a separate JDK or Git install. IntelliJ downloads a JDK for you: go to Project Structure > SDK > Download JDK and select Temurin 21. You can get the starter project directly from Burp or as a GitHub ZIP. Only if you’d rather build from a terminal or clone the template yourself, install a standalone JDK 21 or Git.


The Montoya API

Every extension implements BurpExtension and receives a MontoyaApi instance via the initialize() method. From that single object you can access everything:

Method What it gives you
api.proxy() Intercept and modify proxy traffic
api.http() Make requests, build HTTP models, register handlers
api.scanner() Add custom scan checks and insertion points (Burp Suite Professional only)
api.userInterface() Register tabs, editor panels, context menu items
api.logging() Write to the extension output console
api.extension() Set extension name, register unload handler

Full API reference: Montoya API JavaDoc
Worked examples: github.com/PortSwigger/burp-extensions-montoya-api-examples


Set up your development environment

Every exercise starts from PortSwigger’s official extension starter project. Set it up once, before you select an exercise, and confirm your environment works. These steps follow the official guide. Keep it open as you go:

Set up your starter project: portswigger.net/burp/documentation/…/set-up/starter-project

1. Get the starter project

To get the starter project you can:

  • Download it from Burp (recommended):
    1. Go to Extensions > APIs.
    2. Click Download starter project.
    3. Save the ExtensionTemplateProject folder.
  • Get it from GitHub: open the extension-template-project repo, a public GitHub template. Either click Use this template to create your own copy, or download it as a ZIP:
    1. Click the Code dropdown.
    2. Click Download ZIP.
    3. Unzip it.

2. Open it in IntelliJ

Go to File > Open and select the project folder. Let IntelliJ auto-detect and configure the Gradle settings when prompted.

Set the project JDK to version 21. Burp only runs extensions built for Java 21 or lower, and the template targets 21. In File > Project Structure > SDK, either select an installed JDK 21 or click Download JDK and select Temurin 21. You don’t need a separate JDK install if you let IntelliJ download it here.

3. Build the JAR

Open the Gradle tool window (the elephant icon on the right edge) and run the jar task under Tasks > build. If you’d rather use a terminal in the project root:

./gradlew jar        # macOS / Linux
gradlew jar          # Windows

Gradle writes the JAR to build/libs/extension-template-project.jar (the name comes from settings.gradle.kts).

4. Load it into Burp

Following the docs:

  1. In Burp, go to Extensions > Installed and click Add.
  2. Under Extension details, click Select file, select the JAR you built, then click Open.
  3. Click Next, review the Output and Errors tabs, then click Close.
  4. Turn on auto-reload now. Back in Extensions > Installed, select the checkbox in the Auto-reload column for your extension. Burp then reloads it automatically every time you rebuild the JAR, so you don’t reload it manually while iterating. See The development loop below.

If the extension name appears in the Extensions list without errors, then your environment is ready. The main source file is src/main/java/Extension.java. Its initialize(MontoyaApi montoyaApi) method is where every exercise begins.

Common setup issues:

Symptom Fix
Gradle fails to sync Check your project JDK. The template requires JDK 21. In IntelliJ: File > Project Structure > SDK
UnsupportedClassVersionError on load You built with a newer JDK than Burp’s runtime. Set the project JDK to 21 and rebuild
Extension loads but Output tab is empty Add montoyaApi.logging().logToOutput("Extension loaded"); to initialize() to confirm it’s running

Working with classes

The starter template gives you one class, Extension, in src/main/java/Extension.java. Every exercise adds more classes next to it: a provider and an editor, a pair of scan checks, or a generator and an action. Two rules decide where the code goes. Each class then implements one of Burp’s interfaces. One principle decides how you divide the work.

One public class, one file

Java requires each public class to live in a file named after it. JsonEditorProvider goes in JsonEditorProvider.java, and MyActiveScanCheck goes in MyActiveScanCheck.java. When an exercise tells you to add a class, you create a new file.

Put every source file in src/main/java/, next to Extension.java. The template uses Java’s default package, so you write no package line and create no subfolders. Gradle compiles every .java file in that directory into the JAR.

To add a class in IntelliJ:

  1. Right-click the src/main/java folder.
  2. Go to New > Java Class.
  3. Enter the class name. IntelliJ creates the matching file for you.

Tip: With the src/main/java folder selected, Alt+Insert (⌘N on macOS) opens the same New menu from the keyboard.

Implementing an interface

Burp defines the interfaces, and your classes implement them. An interface is a contract: it lists the methods Burp will call, without providing their bodies. PassiveScanCheck declares checkName(), doCheck(...), and consolidateIssues(...), and your class supplies what each one does. This is how Burp runs your code without knowing your class ahead of time.

Declare the contract with implements:

public class MyPassiveScanCheck implements PassiveScanCheck {

Your class must implement every method the interface declares, or it won’t compile. Mark each one with @Override. The annotation tells the compiler to check your method against the interface, so a misspelled name or a wrong parameter type becomes an error rather than a method Burp never calls.

Let IntelliJ write the stubs:

  1. Type the class declaration with implements. IntelliJ underlines the class name in red, because the required methods are missing.
  2. Put the caret on the class name and press Alt+Enter, then select Implement methods. The shortcut is Ctrl+I (the Control key, on macOS too), and the menu is Code > Implement Methods.
  3. Select the methods in the dialog and click OK. IntelliJ inserts a stub for each, already annotated with @Override.

Fill in each stub. To see what a method is for, hold Cmd (Ctrl on Windows and Linux) and click the interface name to open its source, or read its JavaDoc from View > Quick Documentation.

Tip: Ctrl+O does the same for overriding methods. You override when your class builds on another class (it extends that class, taking on its methods) rather than implementing an interface, such as when you subclass a Swing component to customize it.

Why split the work across classes

Give each class one job. A class with a single responsibility is shorter, easier to read, and safe to change without disturbing the rest.

The Montoya API leads you this way. Everything you register implements a specific interface, and each interface is one role: a provider is a factory, an editor is a tab, a scan check is a check. Implement each role in its own class and the roles stay separate. In Exercise A, the provider creates editors and the editor renders a message, so they are two classes. In Exercise B, the passive check and the active check are two interfaces, so they are two classes.

Split your own logic too, not only where an interface forces it. Exercise C puts its TOTP calculation in a TotpGenerator class, separate from the session handling action that calls it. The generator is plain Java with no Burp dependency, so you can read it, test it, and reuse it on its own.

Keep Extension thin. Its initialize() method wires the extension together: it creates your classes and registers them with Burp. The behavior lives in those classes.

IntelliJ shortcuts

The handful of actions you repeat across every exercise, from the keyboard. On macOS, Alt maps to the ⌥ (Option) key, and Ctrl stays as the Control key unless noted.

Action Windows / Linux macOS
Show intention actions / quick-fix Alt+Enter ⌥ Enter
Implement interface methods Ctrl+I Ctrl+I
Add or optimize imports Ctrl+Alt+O Ctrl+⌥ O
Reformat code Ctrl+Alt+L ⌘⌥ L
New class (from the Project tool window) Alt+Insert ⌘N

Tip: When IntelliJ underlines something in red, put the caret on it and press Alt+Enter. The context-action menu offers the relevant fix: importing a missing class, stubbing the interface methods you still owe, creating a symbol that doesn’t exist yet, and so on. It’s the one shortcut to reach for whenever the editor flags a problem. To resolve a whole file’s imports at once, run Add or optimize imports; Reformat code then tidies the indentation.


The development loop

Every exercise follows the same edit-build-reload cycle. Turn on auto-reload once and Burp reloads for you each time you rebuild:

  1. In Burp, go to Extensions > Installed and select the checkbox in the Auto-reload column for your extension.
  2. From then on, whenever you rebuild the JAR (./gradlew jar), Burp detects the file change and reloads the extension automatically.
Edit code → ./gradlew jar → (Burp auto-reloads) → Check Extensions > Output → Iterate

Tip: If auto-reload isn’t available, or you want to force a reload, hold Ctrl (Cmd on macOS) and click the Loaded checkbox next to your extension in Extensions > Installed. Removing and re-adding the extension also works, but it’s slower.

The Extensions > Output tab is your primary debugging tool. Any exception your extension throws appears there. Any api.logging().logToOutput() call appears there. Look there first when something isn’t working.


Select your exercise

Each walkthrough is a self-contained brief with a step-by-step approach and hints you can reveal as needed. Start with any exercise and work through as many as you like.

Exercise A: Custom Editor Tab Beginner

Register an extra tab in Burp’s HTTP message editor that extracts and reformats data from a message. The worked example adds a JSON tab that pretty-prints minified response bodies. The same pattern fits any custom decoder or field extractor you need for your workflow.

Open the walkthrough →

Exercise B: Custom Scan Check Intermediate

Register custom scan checks that raise audit issues Burp’s built-in scanner doesn’t cover. You’ll write a passive check (analyzes traffic you already have) and an active check (injects a payload and confirms the result) as two classes, plus deduplication, reporting findings under Dashboard > Issue activity.

Open the walkthrough →

Exercise C: Session Handling Advanced

Register a session handling action that solves a complex authentication requirement. The worked example generates a fresh TOTP code and injects it into requests as Burp sends them, so Repeater, Scanner, and Intruder all authenticate: a pattern that fits any short-lived credential (HMAC-signed timestamps, rotating keys, nonces).

Open the walkthrough →


Using a large language model (LLM) to generate your extension

The starter project ships with a CLAUDE.md file and a docs/ folder at its root. PortSwigger built these to give an AI coding assistant the Montoya API structure and project layout it needs. The starter project guide covers this under Vibe Coding Your Extension with AI.

  • Claude Code:
    1. Open a terminal in the ExtensionTemplateProject folder.
    2. Run claude.
    3. Prompt it to build your extension.

    It reads CLAUDE.md and docs/ automatically; if it doesn’t seem to have, tell it to read them before continuing.

  • Other LLMs: prompt the model to read CLAUDE.md and the docs/ folder, or paste their contents into your context window.

Sample prompt structure:

I want to write a Burp extension that:
- [what it intercepts or observes]
- [what it computes or transforms]
- [what it displays or produces]

Please implement the initialize() method and any required handler classes.

Before loading generated code, read through it. Check what API methods it calls, whether it makes any outbound network requests, and whether the logic matches your intent. The extension output console shows any runtime errors.


Going further