Programming concepts
The programming ideas the exercises lean on, in one place, so you can look one up while you work.
Most exercises ask you to write a Bambda: a short snippet of Java that Burp Suite runs for you. You work out an answer and hand it back with return. A few exercises build a full extension, a complete program. Both are plain Java, so everything here applies to either.
Table of contents
- The vocabulary
- How to read the examples
- Java building blocks
- Java you’ll use in Bambdas
- Java for extensions
Note: The examples are generic, chosen to show the idea rather than solve any exercise. Each exercise asks you to apply these concepts to its own task.
The vocabulary
The words you’ll hear throughout the workshop, each anchored to something you already know well: an HTTP request.
Variable
A variable is a named box that holds a value. You give it a name and put something in it. var timeout = 30; names a box timeout and stores 30 in it. See var and local variables.
Class
A class is a blueprint. HttpRequest is the blueprint for “a request”: it describes what every request has and what you can do with one, but it isn’t any particular request itself. See Classes and the one-file rule.
Object
An object is one real thing built from a blueprint: an actual request in your proxy history, with a real URL and real headers. One class, as many objects as you like. See Objects and methods.
Field
A field is a variable that lives inside an object, a piece of data it holds. A request’s URL is a field, and its headers are a field. See Constructors and fields.
Method
A method is an action you ask an object to perform, or a question you ask it. request.bodyToString() asks that request to hand back its body as text. See Objects and methods.
Interface
An interface is a contract: a checklist of methods that something promises to provide, without saying how it provides them. Burp says “give me something that can handle a request”, the interface is that checklist, and your code fills in the how. See Interfaces and @Override.
How to read the examples
The code below uses a few pieces of Java notation throughout:
- A comment is anything after
//: a note for you that Java ignores. - Every statement ends with a semicolon (
;). The;marks where a statement ends, so one statement can spread across several lines. - You act on a value by calling a method on it with a dot, and you pass any inputs inside the parentheses.
request.method()calls the methodmethod()onrequest. See Objects and methods.
Java building blocks
The pieces you build every Bambda and extension from: the kinds of value your code works with, the symbols that combine them, and the way you branch on the result.
Types
A type is the kind of a value. Every value has one, and it decides what the value can hold and what you can do with it. Java’s basic types include String (text), int (a whole number), double (a decimal), and boolean (true or false).
String method = request.method(); // a String
int code = response.statusCode(); // an int
boolean ok = code == 200; // a boolean
- The type decides which methods you can call. A
StringhastoLowerCase(); anHttpResponsehasstatusCode(). - Objects have types too: an object’s type is its class.
HttpRequest,HttpResponse, andByteArrayare Montoya types you’ll meet. Objectis the most general type. Any value is anObject, which is why a custom column may return one.- When you declare a variable, you either name its type or let
varinfer it from the value. See var and local variables.
Strings
A string is text: a run of characters, written in double quotes. "GET", "admin", and "application/json" are all strings. Most Bambda logic is string work. The header names, values, and paths you read from a request or response all arrive as strings.
String label = "example"; // a string literal: text written directly in the code
var method = request.method(); // a String read from the request, like "GET"
You test and transform a string by calling its methods, such as startsWith(...) or toLowerCase(). See Working with String for the ones you’ll use most.
Objects and methods
An object bundles data together with the methods that act on it. requestResponse, request, and response are all objects Burp hands you. You reach a method on an object with a dot: object.method(...).
var request = requestResponse.request(); // request() is a method on requestResponse
request.method(); // method() is a method on the request
- A method may take arguments in the parentheses, like
hasHeader("Content-Type"), or none, likemethod(). - A method usually returns a value. When that value is another object, you can call a method on it straight away. Chaining reads left to right:
requestResponse.request().url().toLowerCase(). nullmeans “no object here”. Calling a method onnullfails, so you check a value exists before you use it. See Guard before you read.
Operators
An operator is a symbol that combines or compares values. The ones you’ll use across the exercises:
=assigns a value to a variable:var total = 5;.==and!=test whether two values are equal or not:response.statusCode() != 200.!reverses a boolean:!requestResponse.hasResponse()istruewhen there’s no response.&&and||combine booleans as “and” and “or”. See Short-circuit evaluation.+adds numbers, or joins strings end to end:"count: " + total.<,>,<=, and>=compare numbers.
Note: Compare strings with
.equals(...), not==."POST".equals(method)tests the text;==tests whether two values are the same object, which is not what you want for strings.
if and else
An if runs a block of code only when its condition is true. The condition is a boolean, usually built from the operators above.
On its own, an if either does something or does nothing. There is no else, so when the condition is false, Java skips the block and continues:
if (statusCode == 200) {
// runs only when the status is 200; otherwise nothing happens here
}
Add an else for the opposite case:
if (statusCode == 200) {
// the 200 case
} else {
// every other status
}
Chain else if to test several conditions in turn. Java checks them top to bottom and runs the first block whose condition is true, skipping the rest:
if (statusCode == 200) {
// OK
} else if (statusCode == 404) {
// not found
} else {
// any other status
}
In a Bambda you often return early from inside an if with no else, to stop before the main logic. That is the guard pattern: check for a problem, return the “no match” value, and continue only when it’s safe.
if (statusCode != 200) return ""; // stop here for a non-200 response
// reached only when the status is 200
When both branches just produce a value, a ternary says the same thing in one expression.
Java you’ll use in Bambdas
Burp supplies the objects a Bambda works with and calls your code when needed. You write the logic and hand your answer back with return.
- Which objects you get depends on the Bambda type. A filter or column gets
requestResponse; a scan check getsrequestResponseandapi, and an active check addshttpandinsertionPoint. - Bambdas take no
importlines. Burp preimports the Montoya types and commonjava.utilclasses, soPatternandHttpParameterTypeare already available to use. - What you return depends on the Bambda type.
| Bambda type | Return type | Value that means “no match” |
|---|---|---|
| Table filter | boolean |
false hides the row |
| Custom column | Object (often a String) |
"" renders a blank cell |
| Scan check | AuditResult |
AuditResult.auditResult() with no issue |
Guard before you read
Reading a method off a value that is null throws a NullPointerException (see try/catch, which explains throwing): the Bambda hits an error and stops. A request may have no response yet, and a header or parameter may be absent. Check presence first, then read.
if (!requestResponse.hasResponse()) return "";
var response = requestResponse.response();
if (!response.hasHeader("Content-Type")) return "";
return response.headerValue("Content-Type");
hasResponse(), hasHeader(...), and hasParameter(...) are your guards. Return the “no match” value for the Bambda type when a guard fails.
Note: The guard-then-read pattern appears in every Bambda exercise. See Exercise A: Proxy History Intelligence.
Short-circuit && and ||
Java stops evaluating a && chain the moment one part is false, and a || chain the moment one part is true. So a guard on the left protects a read on the right: the read runs only once the guard passes. This lets you collapse a guard-then-read into one expression.
Start with the shape, ignoring the detail. It’s a single return with three checks joined by &&:
return checkA && checkB && checkC;
return hands back whatever you write to its right. Here that right-hand side is checkA && checkB && checkC, which works out to one true or false. So the whole line returns a single value. Java reads a statement up to its semicolon (;), not to the end of a line. This lets you spread one long expression over several lines without changing it. That’s all the real Bambda does: the same one statement, with each check on its own indented line so the chain is easy to read.
return requestResponse.hasResponse() // checkA
&& requestResponse.response().hasHeader("Content-Type") // checkB
&& requestResponse.response().headerValue("Content-Type").contains("json"); // checkC
There’s still only one return and one ;. The line breaks and indentation are for your eyes; Java sees the three lines as a single expression.
This works like a math expression. Just as * binds tighter than +, && binds tighter than ||. So Java reads a || b && c as a || (b && c). That is the same way 2 + 3 * 4 multiplies before it adds. Parentheses reorder a boolean expression just as they reorder a sum. (a || b) && c forces the || first, exactly as (2 + 3) * 4 forces the addition first.
That precedence is exactly why the next example needs parentheses. You want “a response, whose status is 401 or 403, from a POST request”. To keep the grouping visible, read the three checks into variables first:
var hasResponse = requestResponse.hasResponse();
var statusCode = requestResponse.response().statusCode();
var isPostRequest = requestResponse.request().method().equals("POST");
Without parentheses, Java applies the tighter && first, so the || ends up splitting the whole line in two:
return hasResponse && statusCode == 401 || statusCode == 403 && isPostRequest;
// Java groups it as: (hasResponse && statusCode == 401) || (statusCode == 403 && isPostRequest)
That is the wrong meaning. It returns true for any 401 response, even a GET, and for any 403 POST. Add parentheses around the || and the two status checks become one unit, which the && chain then treats as a single condition:
return hasResponse && (statusCode == 401 || statusCode == 403) && isPostRequest;
// grouped as: hasResponse AND (statusCode is 401 or 403) AND isPostRequest
Now it returns true only when there is a response, its status is 401 or 403, and the method is POST.
The ternary ?:
A ternary is an if/else that produces a value: condition ? valueIfTrue : valueIfFalse. A custom column returns a value, so a ternary lets you pick one in a single expression.
return requestResponse.hasResponse() ? "answered" : "pending";
Read it as: if there’s a response, the value is "answered"; otherwise it’s "pending".
var and local variables
A local variable is one you declare inside a Bambda. You can write its type in full, or let var infer it from the value on the right. These two lines behave identically:
HttpResponse response = requestResponse.response(); // explicit type
var response = requestResponse.response(); // var infers the same type
Use var when the value already makes the type obvious, so you don’t repeat a long type name. It also lets you read a value once into a variable and reuse it, rather than calling the same method again.
Write the type in full when naming it makes the code clearer, such as when the right-hand side doesn’t make the type plain.
Working with String
Most Bambda logic is string work: test a value, transform it, split it. The methods you use most:
startsWith(...)andcontains(...)test for a prefix or a substring.toLowerCase()normalizes case before you compare, so text matches regardless of capitalization.split(...)breaks a string into aString[](an array, a numbered list of strings) on a separator. See Arrays and indexing.+joins strings, so you can build a message from pieces.
String csv = "alice,bob,carol";
String[] names = csv.split(","); // names[0] is "alice"
Regular expressions: Pattern and Matcher
A regex matches text against a pattern. Java’s regex is a two-step API: Pattern.compile(...) builds the pattern, and .matcher(text) binds it to the string you’re scanning. Burp preimports both classes in Bambdas.
Note: Inside a Java string, you double every regex backslash. You write
"\\d"for the regex\d(a single digit) and"\\."for a literal dot. So the pattern"id=(\\d+)"is typed with the backslash doubled, but as a regex it readsid=(\d+).
String text = "user id=42 logged in"; // the string you're scanning
var matcher = Pattern.compile("id=(\\d+)").matcher(text);
if (matcher.find()) {
String id = matcher.group(1); // "42", the digits captured by (\d+)
}
.find()returnstrueif the pattern occurs anywhere in the string. (.matches()is stricter: it demands the whole string match.)- Parentheses
(...)are a capturing group. After a successful.find(),.group(1)returns what the first group matched, and.group(0)returns the whole match.
Note: You need regex to pull one field out of a decoded JWT header in Exercise B: JWT Triage.
try/catch
When code hits a problem it can’t handle, it throws an exception and stops at that point. An uncaught exception makes the whole Bambda fail. Some operations throw on bad input, such as parsing a number from text that isn’t numeric, or reading an array index that isn’t there. Wrap them in try/catch so a failure returns a safe default instead of breaking the Bambda.
try {
int port = Integer.parseInt(value); // throws if value isn't a number
return port > 1024;
} catch (NumberFormatException e) {
return false; // not a number, so treat it as no match
}
The catch block runs only if the try block throws. Return the Bambda’s “no match” value from it.
Arrays and indexing
split(...) gives you a String[]. You read an element by its index, counting from zero: parts[0] is the first element, parts[1] the second.
String[] parts = "alice,bob,carol".split(",");
// parts[0] = "alice", parts[1] = "bob", parts[2] = "carol"
Reading an index that doesn’t exist throws, which is one more reason to keep the read inside a try/catch when the input might be malformed.
Java for extensions
A Bambda is a snippet; an extension is a program. The Extension Workshop builds one from PortSwigger’s starter template. You work with full Java: several classes of your own, methods you write, imported libraries, and the Montoya API. The snippets below use a made-up RequestLogger to show the shape; the exercises implement different interfaces for their own jobs.
Tip: The Extension Workshop overview covers the IntelliJ workflow for these concepts, including how to add a class and let the IDE stub interface methods for you.
Classes and the one-file rule
A class groups related data and behavior under one name. Java requires each public class to live in a file named after it, so RequestLogger goes in RequestLogger.java. When an exercise adds 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.
Imports and libraries
A Bambda needs no imports, because Burp preimports the common types for you. An extension is different: each source file starts with import lines naming the types it uses. You write one per type, or let IntelliJ add them for you.
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.http.handler.HttpHandler;
Because an extension is a normal Gradle project, you can also pull in third-party libraries from Maven Central. Add the dependency to build.gradle.kts with implementation(...), and the starter template bundles it into your JAR (the single packaged file Burp loads) when you build. Burp loads one JAR, so the library has to travel inside it:
dependencies {
compileOnly("net.portswigger.burp.extensions:montoya-api:2026.4")
implementation("com.google.code.gson:gson:2.11.0") // bundled into your JAR
}
Once it’s on the classpath (available for your code to use), import it and use it like any other type. A maintained library often beats writing the same logic yourself.
Interfaces and @Override
An interface is a contract: it lists the methods Burp will call, without their bodies. Your class declares implements and supplies a body for every method the interface names. This is how Burp runs your code without knowing your class ahead of time. Burp defines interfaces for response editors, scan checks, session handling actions, and more; your class implements whichever one fits its job.
public class RequestLogger implements HttpHandler {
@Override
public RequestToBeSentAction handleHttpRequestToBeSent(HttpRequestToBeSent request) {
return RequestToBeSentAction.continueWith(request); // your logic goes here
}
// HttpHandler also declares handleHttpResponseReceived(...); implement that too
}
Mark each implemented method with @Override, an annotation (a marker for the compiler). It tells the compiler to check your method against the interface, so a misspelled name becomes an error rather than a method Burp never calls. Your class must implement every method the interface declares, or it won’t compile.
Writing your own methods
Interface methods are the ones Burp calls. You can also write your own methods to organize your code: give a piece of logic a name, then call it wherever you need it. A method declares an access level, a return type, a name, and the parameters it takes:
private boolean isLargeRequest(HttpRequest request) {
return request.body().length() > 100_000; // more than 100,000 bytes; the _ just groups digits
}
privatemeans only this class calls the method;publicwould let other classes call it too.booleanis the return type, the kind of value the method hands back. Usevoidwhen it returns nothing.isLargeRequestis the name, and(HttpRequest request)is the single parameter it takes.
Call it by name from another method in the same class:
if (isLargeRequest(request)) {
// handle the large-request case
}
Splitting logic into small, named methods keeps each one short and lets you reuse it.
Constructors and fields
A field holds a value for the life of an object. A constructor runs once, when you create the object with new, and sets those fields up. The pattern you’ll repeat is taking the api in the constructor, storing it in a field, and using it from the other methods:
public class RequestLogger implements HttpHandler {
private final MontoyaApi api;
public RequestLogger(MontoyaApi api) {
this.api = api; // store the passed-in object
}
@Override
public RequestToBeSentAction handleHttpRequestToBeSent(HttpRequestToBeSent request) {
api.logging().logToOutput(request.url()); // a different method, using the field
return RequestToBeSentAction.continueWith(request);
}
}
this.api is the field; api is the constructor argument. this. distinguishes the two when they share a name. final means you set the field once and never reassign it.
The constructor is also how you pass objects from one class to another. new RequestLogger(montoyaApi) hands the api in, and the object keeps it. You pass your own objects the same way: build a helper first, then pass it into the constructor of the class that needs it. That is how you connect the pieces of an extension.
var reporter = new IssueReporter(montoyaApi); // one object...
var check = new MyScanCheck(montoyaApi, reporter); // ...passed into another
The MontoyaApi entry point
Every extension implements BurpExtension and receives a MontoyaApi object through its initialize(...) method, called once on load. That single object is the door to everything: api.userInterface(), api.http(), api.scanner(), api.logging(), and more.
public class Extension implements BurpExtension {
@Override
public void initialize(MontoyaApi montoyaApi) {
montoyaApi.extension().setName("My Extension");
montoyaApi.logging().logToOutput("Extension loaded.");
montoyaApi.http().registerHttpHandler(new RequestLogger(montoyaApi));
}
}
Keep initialize(...) thin: it creates your classes, passes each the objects it needs, and registers them with Burp. The behavior lives in those classes. For the full surface, see the Montoya API JavaDoc.