Advanced extension concepts
A first extension registers one handler and returns. Past that, a few concerns show up that the workshop exercises don’t reach. None are hard, but each has a pitfall worth knowing before you meet it.
These build on the extension fundamentals in Programming concepts and the Extension Workshop. Read those first if the Extension class and the MontoyaApi object aren’t yet familiar.
Table of contents
- Threading: don’t block Burp
- Settings and persistence
- Calling Burp AI
- Exposing your extension to Bambdas
Threading: don’t block Burp
Burp calls your extension on its own threads, and it expects them back quickly. An HttpHandler runs on the thread carrying that request through the proxy. A UI action runs on Swing’s event dispatch thread (the EDT), the single thread that paints every Burp window. Do slow work on either and you pay for it directly: block a proxy thread and that request stalls, block the EDT and the whole interface freezes until you return.
The rule is simple: do slow work (a network call, parsing a large body, an AI prompt) on your own threads, not Burp’s. Return to the EDT for any UI update. A single ExecutorService, created on load and shut down on unload, is all you need.
import burp.api.montoya.BurpExtension;
import burp.api.montoya.MontoyaApi;
import javax.swing.SwingUtilities;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.function.Consumer;
public class Extension implements BurpExtension {
private final ExecutorService workers = Executors.newFixedThreadPool(4);
@Override
public void initialize(MontoyaApi montoyaApi) {
montoyaApi.extension().setName("Background Worker");
// Shut the pool down on unload, so its threads don't outlive the
// extension across reload cycles
montoyaApi.extension().registerUnloadingHandler(() -> workers.shutdownNow());
}
// Call this instead of doing the work inline on Burp's thread
private void analyseInBackground(String input, Consumer<String> onDone) {
workers.submit(() -> {
String result = expensiveWork(input); // off Burp's threads
SwingUtilities.invokeLater(() -> onDone.accept(result)); // back on the EDT for UI
});
}
private String expensiveWork(String input) {
// a network call, heavy parsing, an AI prompt: anything slow
return input.toUpperCase();
}
}
Caveats
Warning:
api.http().sendRequest(...)blocks until the response arrives. Calling it from inside anHttpHandlerfor the message you’re handling can stall the proxy. Send follow-up requests from a background thread instead.
- Never call Swing from a background thread. Read and update UI components on the EDT only, and return to it with
SwingUtilities.invokeLater(...). Swing is not thread-safe, and violations show up as intermittent, hard-to-reproduce glitches. - Always shut your pool down in an unloading handler. Without it, every reload during the development loop leaks a pool, and threads pile up until you restart Burp.
- Keep handlers lean. Return the handler’s action promptly and let the slow part happen elsewhere. A handler is not the place for a long job.
Settings and persistence
Two separate questions come up as soon as an extension does more than one fixed thing: where does the user change its settings, and where does state live when Burp closes.
A native settings panel
Burp can render your settings for you. SettingsPanelBuilder produces a panel that appears under Burp’s own Settings, with typed controls and persistence handled for you. Prefer it to hand-built Swing: it matches Burp’s look, and it saves and reloads values with no extra code.
import burp.api.montoya.BurpExtension;
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.ui.settings.SettingsPanelBuilder;
import burp.api.montoya.ui.settings.SettingsPanelPersistence;
import burp.api.montoya.ui.settings.SettingsPanelSetting;
import burp.api.montoya.ui.settings.SettingsPanelWithData;
public class Extension implements BurpExtension {
@Override
public void initialize(MontoyaApi montoyaApi) {
montoyaApi.extension().setName("Configurable Extension");
SettingsPanelWithData settings = SettingsPanelBuilder.settingsPanel()
.withTitle("Configurable Extension")
.withPersistence(SettingsPanelPersistence.USER_SETTINGS)
.withSettings(
SettingsPanelSetting.booleanSetting("Enabled"),
SettingsPanelSetting.stringSetting("Target host", "example.com"),
SettingsPanelSetting.integerSetting("Max requests", 100))
.build();
montoyaApi.userInterface().registerSettingsPanel(settings);
// Read values back wherever you need them, by the same names
boolean enabled = settings.getBoolean("Enabled");
String host = settings.getString("Target host");
int max = settings.getInteger("Max requests");
}
}
withPersistence(...) decides where Burp stores those values: USER_SETTINGS keeps them across every project on this machine, PROJECT_SETTINGS ties them to the current project file, and NONE forgets them when Burp closes.
Open the settings window from your own UI
Once your panel is registered, you don’t have to make the user hunt for it. api.userInterface().openSettingsWindow() opens Burp’s Settings dialog, and because you registered a panel it lands the user straight on yours. That means a suite tab of your own can carry a Settings button that jumps to the native settings window. You don’t have to duplicate a settings form inside your tab.
import javax.swing.JButton;
JButton settingsButton = new JButton("Settings");
settingsButton.addActionListener(
e -> montoyaApi.userInterface().openSettingsWindow());
A button listener already runs on the EDT, so opening the window from it is safe to call directly. The upside is one place for configuration, rendered by Burp and looking like the rest of the suite. You can reach it from wherever makes sense in your own UI.
Persisting your own state
Settings are values the user sets. For state your own code produces (a cache, a counter, the last token you saw), reach for api.persistence() directly. It offers two stores, and the choice between them matters:
extensionData()returns aPersistedObjectsaved in the current Burp project file. Use it for anything tied to this engagement: per-target data, results you’ve gathered.preferences()is a user-level store that survives across every project and every reload. Use it for machine-wide config: an API key, a default the user set once.
Both are typed. A PersistedObject has setString / getString, setInteger, setBoolean, setByteArray, and even setHttpRequest and setChildObject for nested structure. preferences() exposes the same style of typed getters and setters.
The pattern to follow is read-on-load, write-on-unload: pull each value into a field once in initialize(), work against that field through the session, and write it back once in an unloading handler. A getter returns null for a key that was never set, so guard it as you would a possibly-absent response (see Programming concepts: Guard before you read).
import burp.api.montoya.BurpExtension;
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.persistence.PersistedObject;
public class Extension implements BurpExtension {
private int requestsSeen; // live state, held in memory for the session
@Override
public void initialize(MontoyaApi montoyaApi) {
montoyaApi.extension().setName("Stateful Extension");
PersistedObject data = montoyaApi.persistence().extensionData();
// Read once, on load
Integer saved = data.getInteger("requestsSeen"); // null if never set
requestsSeen = (saved == null ? 0 : saved);
// Write once, on unload
montoyaApi.extension().registerUnloadingHandler(
() -> data.setInteger("requestsSeen", requestsSeen));
// ... your handlers just do requestsSeen++ during the session
}
}
Tip: Read every persisted value in
initialize()and write them all back from the unloading handler. This is how Burp persists its own settings: it keeps disk access off the request path (no read-modify-write on every request) and gives you one clear place for each direction. Bear in mind an unloading handler won’t run if Burp is killed outright, so checkpoint anything you can’t afford to lose.
Caveats
Warning: Pick the store by scope.
preferences()is machine-wide, so a value you write there is visible in every project (right for an API key, wrong for per-target data).extensionData()is bound to the open project, and lives only in memory when no project is loaded.
- Prefer the settings panel to hand-rolled Swing for anything a user configures. It persists for free and looks native.
- The project file and the preferences store are not a secret vault. Don’t write anything there you wouldn’t want sitting on disk in plain form.
Calling Burp AI
Burp ships its own AI, and the Montoya API lets your extension use it. Calls run on the user’s Burp AI credits rather than a key you manage. You send messages and get text back.
First, opt in. An extension only gets AI access if it declares the capability; without this, api.ai() stays disabled.
import burp.api.montoya.BurpExtension;
import burp.api.montoya.EnhancedCapability;
import burp.api.montoya.MontoyaApi;
import java.util.Set;
public class Extension implements BurpExtension {
@Override
public Set<EnhancedCapability> enhancedCapabilities() {
return Set.of(EnhancedCapability.AI_FEATURES);
}
@Override
public void initialize(MontoyaApi montoyaApi) {
montoyaApi.extension().setName("AI Assistant");
}
}
Then run a prompt. Send a system message to set the AI’s role, and a user message with the actual input. Read the reply off the response.
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.ai.chat.Message;
import burp.api.montoya.ai.chat.PromptException;
import burp.api.montoya.ai.chat.PromptResponse;
private void explainFinding(MontoyaApi api, String finding) {
if (!api.ai().isEnabled()) {
api.logging().logToOutput("AI is not enabled for this extension.");
return;
}
try {
PromptResponse response = api.ai().prompt().execute(
Message.systemMessage("You are a concise web security assistant."),
Message.userMessage("Explain this finding in two sentences: " + finding));
api.logging().logToOutput(response.content());
} catch (PromptException e) {
api.logging().logToError("Prompt failed: " + e.getMessage());
}
}
Caveats
Warning:
prompt().execute(...)makes a network call and blocks until it returns. Run it on a background thread, never on a proxy thread or the EDT. See Threading above.
- Guard with
isEnabled(). The user controls whether AI is available and holds the credits, so assume it can be off. - Handle
PromptException. It covers empty or malformed messages, communication failures, and exhausted credits. Don’t let it propagate into Burp. - Mind what you send. Prompt contents leave the user’s machine for Burp’s AI service. Treat them as you would any other outbound data, and don’t put secrets into a prompt.
Exposing your extension to Bambdas
The Bambdas page shows a custom column pulling a function out of System.getProperties() and calling it. This is the other side of that bridge: publishing the function from your extension, so any Bambda, or another extension, can reach your logic without a shared reference between them.
import burp.api.montoya.BurpExtension;
import burp.api.montoya.MontoyaApi;
import java.util.function.Function;
public class Extension implements BurpExtension {
@Override
public void initialize(MontoyaApi montoyaApi) {
montoyaApi.extension().setName("Lookup Provider");
// Publish a function keyed under a name you own
Function<String, String> lookup = (url) -> {
// whatever only your extension can work out
return "value for " + url;
};
System.getProperties().put("myextension.lookup", lookup);
// Remove it on unload so nothing stale lingers
montoyaApi.extension().registerUnloadingHandler(
() -> System.getProperties().remove("myextension.lookup"));
}
}
This is exactly the pattern Hackvertor uses to expose its conversion engine under hackvertor.convert.
Caveats
Warning: The function may be called from several threads at once (a custom column renders many rows in parallel), so keep it thread-safe and quick. See Threading above.
- Namespace the key (
myextension.lookup, notlookup) so it can’t collide with another extension’s. - Pass and return plain JDK types (
String,Map,List), not Montoya types, which won’t cross the classloader boundary cleanly. - Remove the key in an unloading handler.
The Bambdas page covers the consuming side and the full set of caveats.