Advanced Bambda concepts
Most Bambdas are a few lines: a guard, a check, a return. Two techniques extend what a Bambda can do once you’re past that. The first lets you declare your own fields and helper methods inside a Bambda, so logic that outgrows one expression stays organized. The second lets a Bambda read live data from one of your compiled extensions, with no HTTP API or file on disk between them.
Both techniques rely on how Burp compiles a Bambda rather than on documented API. Read the caveats before you rely on either.
Table of contents
Escaping the method body
When you write a Bambda, Burp wraps your snippet as the body of a single method inside a generated class, roughly like this:
public class GeneratedBambda /* implements the right interface */ {
public Object getValue(HttpRequestResponse requestResponse, MontoyaApi api) {
// your Bambda code goes here
}
}
Everything you type lands inside that one method. Java has no local functions, and a field can’t live inside a method body: only local variables can. To get past that, close the method early, declare your own class-scope members, then open a dummy method. The closing brace Burp appends after your snippet then has something to match.
Fields for values that outlive a single run
A custom column runs its Bambda once per row, and a filter runs once per row too. Burp rebuilds anything you construct inside the method on every run. A field is different: Burp builds it once and reuses it, which matters for anything expensive to create, such as a compiled regular expression:
return PATH_PATTERN.matcher(requestResponse.request().path()).find() ? "api" : "";
}
// Compiled once, when the Bambda's class loads, not once per row
private static final java.util.regex.Pattern PATH_PATTERN =
java.util.regex.Pattern.compile("/api/v\\d+/");
// A dummy method. Burp appends one closing brace after your snippet,
// and that brace closes this method, keeping the class valid.
void unused() {
Read it top to bottom as Burp assembles it: your code returns, then the } you typed closes getValue. PATH_PATTERN sits alongside getValue at class scope. Finally, void unused() { stays open for Burp’s trailing brace to close. The result compiles cleanly.
The field is static final, so Burp builds it once when it loads the generated class, then every row reuses it. Burp rebuilds it only when the class regenerates, such as when you edit the Bambda or restart Burp. The same holds for anything costly you build once and then only read: a DateTimeFormatter, or a lookup Set populated from a list. Keep such a field immutable, for the thread-safety reason in the caveats below.
Note: The dummy method has to be valid once its body is empty. That’s why it’s
void:void unused() {}compiles, whereasObject unused() {}would fail with a missing return.
Tip: On
PatternandMatcher, see Programming Concepts: Regular expressions.
Helper logic
For most helper logic you don’t need to escape the method body at all. A lambda held in a local variable stays inside the snippet and does the job:
if (!requestResponse.hasResponse()) return "";
java.util.function.IntFunction<String> classify = status -> {
if (status >= 500) return "server-error";
if (status >= 400) return "client-error";
if (status >= 300) return "redirect";
return "ok";
};
return classify.apply(requestResponse.response().statusCode());
The same escape trick from above declares a real method at class scope, in the spot PATH_PATTERN took. Reach for one only where a lambda is awkward. A lambda can’t call itself, so recursion needs a named method. Mutually-calling helpers also read better as methods than as nested lambdas. A class-scope method can’t see requestResponse or api, so pass anything it needs as arguments. Past a helper or two, the logic wants a compiled extension instead.
Tip: On declaring and calling your own methods, see Programming Concepts: Writing your own methods.
Caveats
Warning: This relies on how Burp generates the wrapper class, which is not documented API. Re-test your Bambdas after a Burp upgrade in case the code generation changes.
- The fields and methods you add sit at class scope, so they cannot see the method’s parameters (
requestResponse,api, and the like). Pass whatever they need in as arguments. - Keep the dummy method
voidso its empty body stays valid. - Burp may run a Bambda from more than one thread at once. An immutable field like the compiled
Patternabove is safe to share; a mutablestaticfield (a counter, a cache you write to) is not, and Burp gives you no synchronization for free. Keep shared state immutable, or guard it yourself. - A column or filter Bambda runs once per row, on a thread that feeds the UI. Fields help (compile once, reuse), but anything slow or blocking in the body stalls the table.
- Bambdas, and the columns and filters you save, live in the Burp project file. Large, elaborate ones add up, so prune the ones you no longer use.
- Use this for readability, not to build a full program in a filter box. If a Bambda grows past a couple of helper methods, it probably belongs in a compiled extension instead.
Sharing values between an extension and a Bambda
A Bambda and a compiled extension both run inside the same Burp process, yet neither holds a reference to the other. Burp compiles a Bambda into its own short-lived class and never hands it your extension’s objects. Your extension, in turn, has no handle on the anonymous Bambda Burp just built. There is no direct method call from one to the other, even though they share a JVM. Say a custom column needs to show something only your extension can work out. The usual workarounds (a small HTTP endpoint, a file both sides read) are heavier than the problem needs.
The two do share one thing: the JVM’s own system properties. System.getProperties() returns a single map that every class in the process can see: Burp’s core, every extension, and every Bambda alike. Most code uses it for strings like os.name. But the map’s type is Map<Object, Object>, so you can store any object in it, not just text.
This is what makes the approach work. Rather than publishing a static value, publish a Function: a small object that carries behavior you can invoke later. Your extension puts the function into the map under a name it owns. A Bambda looks it up by that name, hands it an input, and gets a result back. The Bambda never needs to know how the extension produces the answer, only where to find the function. This keeps the two sides loosely coupled: change the extension’s logic and every Bambda that calls it picks up the new behavior with no edits.
In your extension
Put a function into the properties map on load, and take it back out on unload:
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 that any Bambda can call
Function<String, String> lookup = (url) -> {
// Whatever your extension knows how to compute for a URL.
// Return a plain JDK type (here, a String).
return "some value for " + url;
};
System.getProperties().put("myextension.lookup", lookup);
// Take it back out when the extension unloads
montoyaApi.extension().registerUnloadingHandler(
() -> System.getProperties().remove("myextension.lookup"));
}
}
In the Bambda
A custom column reads the function back out and calls it:
var lookup = (java.util.function.Function) System.getProperties().get("myextension.lookup");
if (lookup == null) return "N/A";
return (String) lookup.apply(requestResponse.request().url());
The cast is a raw Function because the Bambda has no shared generic type with the extension; the (String) on the result covers the return. Guarding against null matters here: the extension might not be loaded, so return a placeholder rather than throwing when the property is absent. The Bambda reads the function fresh on every run. Reload the extension and the column picks up the new function on its own.
Example: Hackvertor
You don’t have to build both halves to benefit from this. Hackvertor is a widely used extension that encodes, decodes, hashes, and transforms data through a small tag language: wrap text in a tag such as <@base64>...</@base64> and it converts whatever sits inside. Recent versions expose that whole engine to Bambdas using the exact pattern above.
On load, Hackvertor registers a Function<String, String> under the key hackvertor.convert, and removes it on unload. The function takes a string containing Hackvertor tags and returns the converted result. Any Bambda can pull it out of the properties map and run a conversion without a line of extension code of your own:
var convert = (java.util.function.Function) System.getProperties().get("hackvertor.convert");
if (convert == null) return "N/A";
// Run any Hackvertor conversion straight from a Bambda
return (String) convert.apply("<@base64>" + requestResponse.request().url() + "</@base64>");
Drop that into a custom column and every row shows its URL Base64-encoded. Swap in any other tag Hackvertor supports, or nest tags to chain conversions. Hackvertor does the work while your Bambda stays a one-liner. To find the exact call for your installed version, use the Hackvertor menu option that generates a ready-to-paste Bambda snippet like this one.
Bear in mind this isn’t an official extension-to-Bambda API, in Hackvertor or anywhere else. A few extensions have adopted it as a convention. Treat any key you didn’t set yourself as something that could change or disappear between versions.
Caveats
Warning:
System.getProperties()is one global map shared by Burp’s own code, every extension, and every Bambda. Namespace your key (myextension.lookup, notlookup) so nothing collides.
- The values you move across the boundary should be plain JDK types:
String,Map,List, and so on. Montoya types such asHttpRequestResponseare loaded by a different classloader on each side and may not be assignable, whereas JDK types are shared. If you need to pass an HTTP message, serialize it to aStringon one side and rebuild anHttpRequestResponsefrom thatStringon the other. - Always remove your key in an unloading handler, so a stale function doesn’t linger after the extension is gone.
- Make the function fast and thread-safe. It runs inside the Bambda, which fires once per row on a UI-facing thread and may be called from several threads at once. Slow or blocking work stalls the table, and shared mutable state inside the function needs guarding.
- This couples the Bambda to an extension. A Bambda that reads a key it didn’t set (Hackvertor’s
hackvertor.convert, say) is no longer self-contained: it only works when that extension is installed, loaded, and still publishing the key. Hand the Bambda to someone without the extension and it falls back to yournullcase. The guard stops it throwing. Note the requirement wherever you share the Bambda, and prefer this only when the extra reach is worth giving up a standalone script. - This works from any Bambda type (custom column, filter, match and replace), and from more than one extension at once. That is what makes it a general way to share values across Burp.