Extension Workshop
Hands-on exercises for the Burp, But Yours workshop, where you build a working extension using the Montoya API.
Table of contents
- Prerequisites
- The Montoya API
- Set up your development environment
- Working with classes
- The development loop
- Select your exercise
- Using a large language model (LLM) to generate your extension
- Going further
Prerequisites
- Burp Suite Professional
- IntelliJ IDEA Community Edition (free)
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):
- Go to Extensions > APIs.
- Click Download starter project.
- Save the
ExtensionTemplateProjectfolder.
- 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:
- Click the Code dropdown.
- Click Download ZIP.
- 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:
- In Burp, go to Extensions > Installed and click Add.
- Under Extension details, click Select file, select the JAR you built, then click Open.
- Click Next, review the Output and Errors tabs, then click Close.
- 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:
- Right-click the
src/main/javafolder. - Go to New > Java Class.
- Enter the class name. IntelliJ creates the matching file for you.
Tip: With the
src/main/javafolder 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:
- Type the class declaration with
implements. IntelliJ underlines the class name in red, because the required methods are missing. - 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.
- 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:
- In Burp, go to Extensions > Installed and select the checkbox in the Auto-reload column for your extension.
- 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.
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.
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).
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:
- Open a terminal in the
ExtensionTemplateProjectfolder. - Run
claude. - Prompt it to build your extension.
It reads
CLAUDE.mdanddocs/automatically; if it doesn’t seem to have, tell it to read them before continuing. - Open a terminal in the
- Other LLMs: prompt the model to read
CLAUDE.mdand thedocs/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
- Starter project reference: Set up your starter project
- Publish to the BApp Store: BApp submission criteria and review process
- More examples: burp-extensions-montoya-api-examples
- Community: PortSwigger Discord, the #extensions channel