Exercise C: Custom Scan Checks
Advanced / Professional only
Filters and columns change what you see. A scan check changes what Burp reports. It teaches the scanner to find something it doesn’t already look for, and files a proper audit issue with evidence attached.
In this exercise you’ll write two scan-check Bambdas. A passive check flags an information leak in a response. An active check injects a payload and confirms a vulnerability from the response. Both appear under Dashboard > Issue activity.
Note: This is a stretch exercise. Tackle it once you have a working Exercise A or B, or if you want a deeper challenge: scan checks have more moving parts than a filter or a column.
For the compiled-extension version of these same checks, see Extension Exercise B. It implements the same passive stack-trace check and active reflected-input check against the same labs, built as a packaged extension with the Montoya scanner APIs rather than as inline Bambdas.
Table of contents
- The goal
- Passive versus active checks
- How to approach it
- Check your work
- The complete Bambdas
- Taking it further
The goal
- A passive scan check that raises an
AuditIssuewhen a response contains a pattern you choose (the example flags a leaked stack trace). - An active scan check that injects a probe at an insertion point, sends it, and raises an issue if the response proves the payload had an effect.
- Populate both issues with a meaningful name, severity, confidence, and detail so the finding is actionable.
Labs to launch
Launch both of these labs, one for each check:
- Passive check: Information disclosure in error messages
- Active check: Reflected XSS into HTML context with nothing encoded, where the search field reflects input with nothing encoded.
Open each in Burp’s browser (click the browser icon in the top-right of Burp, then paste the lab’s URL). The steps below walk you through generating the traffic each check needs.
Passive versus active checks
A scan check answers one of two questions for Burp:
- Passive: “Given a request/response I already captured, is there a problem?” Burp sends no new requests; you inspect what’s already there.
- Active: “If I inject a payload at this insertion point, does the response prove a vulnerability?” Burp drives the scan; you decide what to send and what counts as a hit.
Both return an AuditResult holding zero or more AuditIssue objects. An empty result means “nothing found”.
Note: The editor pre-populates the imports, the method signature, and the objects in scope. A passive check gets
requestResponseandapi. An active check adds aninsertionPointand anhttpobject. Send probes throughhttp, notapi.http(), so each request runs under the scan task.Docs: Bambdas ·
ScanCheck·AuditIssue
How to approach it
Tip: Staring at a blank editor? If you have Burp AI credits, the AI Bambda Generator BApp drafts a Bambda from a plain-English description. Refine its output from there. You can also try using Burp AT, Burp’s agentic AI.
Read and understand what either tool produces first. The aim is to learn the approach, not only to run it.
Part 1: The passive check
Step 1: Generate some traffic
Open the Information disclosure in error messages lab in Burp’s browser (click the browser icon in the top-right of Burp, then paste the lab’s URL) and browse the site. Provoke a few errors if you can: a malformed parameter, or a path that doesn’t exist. The aim is a history full of responses worth flagging.
Note: It doesn’t matter where you’re logged into Web Security Academy. Browse the lab from Burp’s browser and the traffic reaches your history regardless.
Step 2: Open the passive scan-check editor
To open the editor:
- Go to Extensions > Custom scan checks.
- Click New (a blank script or a template).
- Set Type to Passive.
- Set Script runs to Per request.
The editor opens with imports and the method body ready.
Step 3: Detect the pattern and raise an issue
The example flags any response that leaks a stack trace. Provoke one first: send GET /product?productId="example" (a non-integer) and the lab returns a full Java stack trace disclosing the framework version. Your logic:
- Check a response exists with
requestResponse.hasResponse(); if not, return an emptyAuditResult(nothing to check). - Read the body. If it looks like a stack trace, build an
AuditIssue, wrap it in anAuditResult, and return it. - Otherwise fall through to an empty
AuditResultat the end.
Tip: On guarding a possibly-
nullresponse before you read it, see Programming Concepts: Guard before you read.
The AuditIssue.auditIssue(...) call takes many arguments: name, detail, remediation, URL, severity, confidence, and others. Don’t worry about the descriptive fields yet; Part 3 covers improving them. For now, get a finding to appear.
Hint: the argument order
auditIssue(name, detail, remediation, baseUrl, severity, confidence, background, remediationBackground, typicalSeverity, evidence). Pass null for the ones you don’t need yet, and pass requestResponse as the final evidence argument so the finding is verifiable in the viewer.
Solution
if (!requestResponse.hasResponse()) {
return AuditResult.auditResult();
}
var response = requestResponse.response();
var body = response.bodyToString();
// A stack trace leaks an exception class plus framework source references
// (SomeClass.java:123). A normal page rarely contains both.
if (body.contains("Exception") && body.contains(".java:")) {
var issue = AuditIssue.auditIssue(
"Stack trace disclosed in response", // name
"The response returns a verbose error containing a Java stack trace, " +
"revealing the framework and its version.", // detail
null, // remediation
requestResponse.request().url(), // base URL
AuditIssueSeverity.LOW,
AuditIssueConfidence.FIRM,
null, // background
null, // remediation background
AuditIssueSeverity.LOW, // typical severity
requestResponse // evidence
);
return AuditResult.auditResult(issue);
}
return AuditResult.auditResult();
requestResponse.hasResponse(): guard first; a passive check still runs on requests that never got a response, and reading one offnullwould throw.response.bodyToString(): the response body as text, so you can match against it.- The positive match: both markers present → build the finding and return it. Anything else falls through to the empty
AuditResultat the end. AuditIssue.auditIssue(...): builds the finding; the last argument attachesrequestResponseas evidence.
Confidence is FIRM, not CERTAIN: a plain contains check may be a false-positive, so be honest about it. Swap the body check for any other leak in these labs:
- Match
body.contains("SECRET_KEY")on the debug page lab. - Match a hard-coded
jdbc:connection string in a served.bakfile on the backup files lab. - Match a verbose SQL error.
Step 4: Test the check, then run a passive scan
Before launching a full scan, use Burp’s built-in tester to iterate quickly against known requests:
- Right-click one or more requests (include the one with the stack trace) and click Send to Custom scan checks editor.
- In the editor, select your test cases and click Run test.
Results appear in the Audit items, Issues, Event log, and Logger tabs. This drives your check against exactly those messages, so you can confirm it fires before committing to a scan.
Once it behaves, run it for real: click Save & close, then right-click a request in proxy history (or the site map) and click Scan > Passive scan, or run an audit. A full scan runs your check only if it’s enabled in your scan configuration, so select it there when you launch the scan. Go to Dashboard > Issue activity and your issue should appear with the evidence attached.
Note: The Run test tester always runs the selected check; only a full scan needs the check enabled in your scan configuration.
Tip: You can also open the editor from Extensions > Custom scan checks.
Nothing appears?
Confirm the check is enabled in the scan configuration you ran, and that the response contains your pattern (click the row, look at the Response body). If nothing has a stack trace yet, send GET /product?productId="example" to provoke one first. Anything you log with logging.logToOutput(...) in the Bambda goes to the Bambda output console.
Part 2: The active check
Step 5: Open the active scan-check editor
In Extensions > Custom scan checks, click New again, this time setting Type to Active and Script runs to Per insertion point. The editor exposes an insertionPoint (where Burp wants you to inject) and an http object (so you can send requests through the scanner).
Step 6: Inject, send, and confirm
The example sends a unique probe and reports an issue if it comes back reflected unencoded: a reflected-input check. The flow:
- Build a distinctive probe: a marker unlikely to occur naturally, plus a few characters (
'"<>) that would be encoded if the app sanitizes input. - Ask the insertion point to build a request with your payload placed in it.
- Send it via the provided
httpobject and guard the response againstnull. - If the raw payload appears in the response body, it wasn’t encoded. Raise a
MEDIUMissue with the probe request/response as evidence. Otherwise return an empty result.
Hint: building the request and the evidence
insertionPoint.buildHttpRequestWithPayload(ByteArray.byteArray(payload)) gives you the request to send. Burp calls your check once per insertion point it finds. For evidence, bundle the request and response with HttpRequestResponse.httpRequestResponse(checkRequest, checkResponse).
Solution
// A token unlikely to occur naturally in the response
var probe = "bbYscan9173";
var payload = probe + "'\"<>";
var checkRequest = insertionPoint.buildHttpRequestWithPayload(
ByteArray.byteArray(payload));
var checkResponse = http.sendRequest(checkRequest).response();
if (checkResponse == null) {
return AuditResult.auditResult();
}
if (checkResponse.bodyToString().contains(payload)) {
var issue = AuditIssue.auditIssue(
"Reflected input (custom active check)",
"The injected probe <code>" + payload +
"</code> was reflected unencoded in the response.",
null,
checkRequest.url(),
AuditIssueSeverity.MEDIUM,
AuditIssueConfidence.FIRM,
null,
null,
AuditIssueSeverity.MEDIUM,
HttpRequestResponse.httpRequestResponse(checkRequest, checkResponse)
);
return AuditResult.auditResult(issue);
}
return AuditResult.auditResult();
- Build the probe: the marker makes the reflection unambiguous; the special characters reveal whether input is sanitized.
insertionPoint.buildHttpRequestWithPayload(...): Burp hands you the insertion point; this places your payload there.http.sendRequest(...): sends the request through the scanner’s providedhttpobject and returns the response, so the probe runs under the scan task. This is what a passive check can’t do.- Check the condition: if the raw payload appears in the body, it wasn’t encoded; report it with both messages as evidence.
Step 7: Test the check, then run an active scan
Test first, same as the passive check: in the Reflected XSS into HTML context with nothing encoded lab, run a search so you capture a GET /?search=... request. Select that request, right-click it, click Send to Custom scan checks editor, then select the message and click Run test. Burp exercises your check against the search insertion point, so you can confirm the probe and condition before launching a real scan.
Once it behaves, run it for real: click Save & close, then right-click the request and click Scan > Active scan (or run an audit). A full scan runs your check only if it’s enabled in your scan configuration, so select it there when you launch the scan. Burp exercises your check against each insertion point, and a hit appears under Dashboard > Issue activity.
Warning: Active checks send live requests. Run them against lab targets only, and keep the payload set small while iterating.
Part 3: Make the issue actionable
Both auditIssue(...) calls take the same descriptive fields. Now fill them in deliberately, so the finding is actionable:
- Set a short, specific name that says what was found, not the category.
- Write the detail from the evidence that triggered the issue, including the matched value. HTML is allowed (
<code>,<b>). - Set the severity to
HIGH,MEDIUM,LOW, orINFORMATIONto match real impact. - Set the confidence to
CERTAIN,FIRM, orTENTATIVE, and be honest about false positives. - Pass the
HttpRequestResponseas evidence so the finding is verifiable in the viewer.
Open each issue under Dashboard > Issue activity and confirm the name, severity, detail, and evidence all render as you intended.
Check your work
- The passive check raises its issue only when the pattern is present, with evidence attached.
- The active check fires per insertion point and reports only on a genuine hit.
- Every reported issue has a clear name, an honest severity/confidence, and a detail string that names the matched value.
The complete Bambdas
Both scan checks in their finished state. Each goes in its own editor under Extensions > Custom scan checks. Click New and select a blank script or template. Set the first to Type: Passive and Per request, the second to Type: Active and Per insertion point. The editor pre-populates the imports and method signature, so paste the body below into each.
Passive check: stack trace disclosure
if (!requestResponse.hasResponse()) {
return AuditResult.auditResult();
}
var response = requestResponse.response();
var body = response.bodyToString();
// A stack trace leaks an exception class plus framework source references
// (SomeClass.java:123). A normal page rarely contains both.
if (body.contains("Exception") && body.contains(".java:")) {
var issue = AuditIssue.auditIssue(
"Stack trace disclosed in response", // name
"The response returns a verbose error containing a Java stack trace, " +
"revealing the framework and its version.", // detail
null, // remediation
requestResponse.request().url(), // base URL
AuditIssueSeverity.LOW,
AuditIssueConfidence.FIRM,
null, // background
null, // remediation background
AuditIssueSeverity.LOW, // typical severity
requestResponse // evidence
);
return AuditResult.auditResult(issue);
}
return AuditResult.auditResult();
Active check: reflected input probe
// A token unlikely to occur naturally in the response
var probe = "bbYscan9173";
var payload = probe + "'\"<>";
var checkRequest = insertionPoint.buildHttpRequestWithPayload(
ByteArray.byteArray(payload));
var checkResponse = http.sendRequest(checkRequest).response();
if (checkResponse == null) {
return AuditResult.auditResult();
}
if (checkResponse.bodyToString().contains(payload)) {
var issue = AuditIssue.auditIssue(
"Reflected input (custom active check)",
"The injected probe <code>" + payload +
"</code> was reflected unencoded in the response.",
null,
checkRequest.url(),
AuditIssueSeverity.MEDIUM,
AuditIssueConfidence.FIRM,
null,
null,
AuditIssueSeverity.MEDIUM,
HttpRequestResponse.httpRequestResponse(checkRequest, checkResponse)
);
return AuditResult.auditResult(issue);
}
return AuditResult.auditResult();
Taking it further
Highlight the matched bytes
Attach request/response markers so the evidence viewer highlights exactly where the match occurred, rather than showing the whole message.
Make the active condition robust
A single reflected string may be a false-positive. Send a baseline request first and compare, or require the payload to land in an executable context, before raising the issue.
Combine with Exercise A/B: use a filter or custom column to spot candidate requests by eye, then point your active check at exactly those insertion points.
More scan-check examples live in the Montoya customscanchecks example (Java extension form) and the community Bambdas repo.