Exercise B: Custom scan check
Burp’s scanner covers common vulnerabilities, but it can’t know about your target’s specifics. Examples include a custom error format, a header that leaks internals, or an insertion point Burp wouldn’t normally probe. A custom scan check lets you teach the scanner new checks that run alongside the built-in ones and file proper audit issues.
In this exercise you’ll write two small checks, each in its own class. A PassiveScanCheck flags an information leak, and an ActiveScanCheck injects a payload and confirms a reflected-input vulnerability. You’ll also add deduplication so the same finding isn’t reported repeatedly.
This exercise is the compiled-extension counterpart to Bambda Exercise C. The checks are the same (a passive stack-trace check and an active reflected-input check against the same labs); here you build them as a packaged extension with the Montoya scanner APIs rather than as inline Bambdas.
You register passive and active checks separately, with registerPassiveScanCheck() and registerActiveScanCheck(). The customscanchecks example implements them as two classes (MyPassiveScanCheck + MyActiveScanCheck), the structure we follow here.
Reference: customscanchecks in the Montoya API examples repo.
JavaDoc: Scanner · PassiveScanCheck · ActiveScanCheck · AuditIssue
Table of contents
- The goal
- Before you start
- How to approach it
- Check your work
- The complete extension
- Taking it further
The goal
Two classes:
- Write
MyPassiveScanCheck implements PassiveScanCheckwith adoCheck(...)that flags responses leaking a Java stack trace. - Write
MyActiveScanCheck implements ActiveScanCheckwith adoCheck(...)that injects a probe and raises an issue on unencoded reflection. - Give each a
checkName()and aconsolidateIssues(...)to collapse duplicate findings. - Register both with
registerPassiveScanCheckandregisterActiveScanCheckso they run under Dashboard > Issue activity.
Before you start
This exercise starts from the extension starter project, the same one every exercise uses. If you haven’t already downloaded it and opened it in IntelliJ, follow Set up your development environment on the overview page (Exercise A also walks through it inline). Have the jar task building and the extension loading in Extensions without errors before you start.
Passive versus active: these are two separate interfaces, and you can implement either or both:
PassiveScanCheck.doCheck(HttpRequestResponse): runs against a request/response Burp already captured. No new requests; you inspect what’s there. Use it for leaked information, missing headers, and risky content.ActiveScanCheck.doCheck(HttpRequestResponse, AuditInsertionPoint, Http): Burp hands you an insertion point and anHttpobject. You build a request with your payload, send it with thathttp, and decide from the response whether there’s a vulnerability.
Both return an AuditResult holding zero or more AuditIssue objects. An empty result means “nothing found”.
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.
How to approach it
Step 1: Sketch the two classes
Create two classes: MyPassiveScanCheck implements PassiveScanCheck and MyActiveScanCheck implements ActiveScanCheck. Each implements checkName(), its own doCheck(...), and consolidateIssues(...). Each also takes the api in its constructor so it can log. Build them up one method at a time; the steps below each fill in one.
They are separate classes because passive and active scanning are two different Montoya interfaces, PassiveScanCheck and ActiveScanCheck: two roles, two classes. Each class is a new file in src/main/java/, named to match: MyPassiveScanCheck.java and MyActiveScanCheck.java. Add each by selecting the folder and pressing Alt+Insert (⌘N on macOS) > Java Class. See Working with classes for why you split code this way, and IntelliJ shortcuts.
Tip: On implementing a Burp interface, see Programming Concepts: Interfaces and @Override.
Step 2: The passive check
In the passive doCheck(HttpRequestResponse), inspect the captured response body for a Java stack trace and raise a LOW issue if one is present. A stack trace leaks an exception class plus framework source references (SomeClass.java:123), so matching both "Exception" and ".java:" is a reliable signal a normal page rarely trips. Guard against a null response, and return an empty auditResult() when there’s nothing to report.
Hint: argument order
AuditIssue.auditIssue(name, detail, remediation, baseUrl, severity, confidence, background, remediationBackground, typicalSeverity, evidence). Pass null for fields you’re not using and the HttpRequestResponse as the final evidence argument.
Step 3: The active check
In the active doCheck(HttpRequestResponse, AuditInsertionPoint, Http), build a request with a distinctive probe placed at the insertion point. Send it via the supplied http object, and raise a MEDIUM issue if the probe comes back unencoded. Burp calls this once per insertion point it identifies.
Hint: placing the payload
insertionPoint.buildHttpRequestWithPayload(ByteArray.byteArray(payload)) builds the probe request; call .withService(baseRequestResponse.httpService()) on it so Burp knows where to send it. Make the probe a rare marker (such as bbYscan9173) plus characters that would be encoded if sanitized ('"<>), so a match is unambiguous.
Step 4: Deduplication
Give each check a consolidateIssues(...) so Burp collapses duplicate findings: treat issues with the same name as the same issue. Both interfaces declare it with the parameter order (existingIssue, newIssue).
Solution: `MyPassiveScanCheck.java`
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.http.message.HttpRequestResponse;
import burp.api.montoya.http.message.responses.HttpResponse;
import burp.api.montoya.scanner.AuditResult;
import burp.api.montoya.scanner.ConsolidationAction;
import burp.api.montoya.scanner.audit.issues.AuditIssue;
import burp.api.montoya.scanner.audit.issues.AuditIssueConfidence;
import burp.api.montoya.scanner.audit.issues.AuditIssueSeverity;
import burp.api.montoya.scanner.scancheck.PassiveScanCheck;
import static burp.api.montoya.scanner.AuditResult.auditResult;
public class MyPassiveScanCheck implements PassiveScanCheck {
private final MontoyaApi api;
public MyPassiveScanCheck(MontoyaApi api) {
this.api = api;
}
@Override
public String checkName() {
return "Stack trace disclosure";
}
@Override
public AuditResult doCheck(HttpRequestResponse baseRequestResponse) {
HttpResponse response = baseRequestResponse.response();
if (response == null) {
return auditResult();
}
String body = response.bodyToString();
if (!(body.contains("Exception") && body.contains(".java:"))) {
return auditResult();
}
AuditIssue issue = AuditIssue.auditIssue(
"Stack trace disclosed in response",
"The response returns a verbose error containing a Java stack trace, " +
"revealing the framework and its version.",
null, // remediation
baseRequestResponse.request().url(),
AuditIssueSeverity.LOW,
AuditIssueConfidence.FIRM,
null, // background
null, // remediation background
AuditIssueSeverity.LOW,
baseRequestResponse // evidence
);
return auditResult(issue);
}
@Override
public ConsolidationAction consolidateIssues(AuditIssue existingIssue, AuditIssue newIssue) {
// Treat issues with the same name as duplicates
return existingIssue.name().equals(newIssue.name())
? ConsolidationAction.KEEP_EXISTING
: ConsolidationAction.KEEP_BOTH;
}
}
Solution: `MyActiveScanCheck.java`
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.http.Http;
import burp.api.montoya.http.message.HttpRequestResponse;
import burp.api.montoya.http.message.requests.HttpRequest;
import burp.api.montoya.http.message.responses.HttpResponse;
import burp.api.montoya.scanner.AuditResult;
import burp.api.montoya.scanner.ConsolidationAction;
import burp.api.montoya.scanner.audit.insertionpoint.AuditInsertionPoint;
import burp.api.montoya.scanner.audit.issues.AuditIssue;
import burp.api.montoya.scanner.audit.issues.AuditIssueConfidence;
import burp.api.montoya.scanner.audit.issues.AuditIssueSeverity;
import burp.api.montoya.scanner.scancheck.ActiveScanCheck;
import static burp.api.montoya.core.ByteArray.byteArray;
import static burp.api.montoya.scanner.AuditResult.auditResult;
public class MyActiveScanCheck implements ActiveScanCheck {
private final MontoyaApi api;
public MyActiveScanCheck(MontoyaApi api) {
this.api = api;
}
@Override
public String checkName() {
return "Reflected input probe";
}
// Note the extra params: the insertion point to probe, and an Http to send with.
@Override
public AuditResult doCheck(HttpRequestResponse baseRequestResponse,
AuditInsertionPoint insertionPoint,
Http http) {
// A rare marker plus characters that would be encoded if the input were sanitized
String payload = "bbYscan9173'\"<>";
// Place the payload at the insertion point, and set the service so Burp knows where to send it
HttpRequest checkRequest = insertionPoint
.buildHttpRequestWithPayload(byteArray(payload))
.withService(baseRequestResponse.httpService());
HttpRequestResponse checkResult = http.sendRequest(checkRequest);
HttpResponse checkResponse = checkResult.response();
if (checkResponse == null) {
return auditResult();
}
if (checkResponse.bodyToString().contains(payload)) {
AuditIssue 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,
checkResult
);
return auditResult(issue);
}
return auditResult();
}
@Override
public ConsolidationAction consolidateIssues(AuditIssue existingIssue, AuditIssue newIssue) {
return existingIssue.name().equals(newIssue.name())
? ConsolidationAction.KEEP_EXISTING
: ConsolidationAction.KEEP_BOTH;
}
}
MyPassiveScanCheck.doCheck(): inspects the response body for a stack trace (Exceptionplus.java:), raises aLOWissue if present, guards againstnull.MyActiveScanCheck.doCheck(): injects the probe at the insertion point (setting the service on the built request), sends it via the suppliedhttp, raises aMEDIUMissue on unencoded reflection.consolidateIssues(): each class collapses its own duplicate findings; the parameter order is(existingIssue, newIssue).
Tip: When IntelliJ flags a line in red, put the caret on it and press Alt+Enter for the context-action menu: it offers the relevant fix, whether that’s importing a missing class, stubbing an interface method, or creating a symbol. To fix every import at once, run Add or optimize imports. See IntelliJ shortcuts.
Step 5: Register the checks
In initialize(), register each check. Each register call takes a ScanCheckType telling Burp how often to invoke it: PER_REQUEST for the passive check, PER_INSERTION_POINT for the active one.
Tip: On
initialize()and themontoyaApiobject, see Programming Concepts: The MontoyaApi entry point.
Solution
import burp.api.montoya.scanner.scancheck.ScanCheckType;
// ...
@Override
public void initialize(MontoyaApi montoyaApi) {
montoyaApi.extension().setName("Custom Scan Check");
montoyaApi.logging().logToOutput("Custom Scan Check loaded.");
montoyaApi.scanner().registerPassiveScanCheck(new MyPassiveScanCheck(montoyaApi), ScanCheckType.PER_REQUEST);
montoyaApi.scanner().registerActiveScanCheck(new MyActiveScanCheck(montoyaApi), ScanCheckType.PER_INSERTION_POINT);
}
Step 6: Build, reload, and test the passive check
Run ./gradlew jar. With auto-reload enabled, Burp reloads the extension for you. Confirm Custom Scan Check loaded. in Extensions > Output.
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.
- 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 provoke an error so the response carries a stack trace: send
GET /product?productId="example"(a non-integer) and the lab returns a full Java stack trace disclosing the framework version. - Right-click that request in proxy history (or the site map) and click Scan > Passive scan, or run a full audit.
- Go to Dashboard > Issue activity. Your
Stack trace disclosed in responseissue should appear with the request/response attached.
Nothing appears?
Confirm the response contains the stack trace (click the row, look at Response > Body). Add api.logging().logToOutput(...) inside the passive doCheck() to confirm it’s being called.
Step 7: Test the active check
- Open the Reflected XSS into HTML context with nothing encoded lab and run a search so you capture a
GET /?search=...request. - Right-click it and click Scan > Active scan (or run an audit). Burp exercises your check against each insertion point it identifies.
- A hit appears under Dashboard > Issue activity with both the probe request and its response as evidence.
Warning: Active checks send live requests. Run them against lab targets only, and keep the payload set small while iterating.
Step 8: Make the issue actionable
The auditIssue(...) calls take the descriptive fields the issue viewer displays. Fill them in deliberately:
- Set a short, specific name that says what was found, not the category.
- Put the evidence that triggered the issue in the detail, 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 and confirm the name, severity, detail, and evidence render as you intended.
Check your work
- The passive check raises its issue only when the header is present, with evidence attached.
- The active check fires per insertion point and reports only on a genuine hit.
- Re-running a scan doesn’t create duplicate copies of the same issue.
The complete extension
Every file in its finished state. These files go in src/main/java/ in the starter project: Extension.java (replacing the template’s), plus the two scan checks.
`Extension.java`
import burp.api.montoya.BurpExtension;
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.scanner.scancheck.ScanCheckType;
public class Extension implements BurpExtension {
@Override
public void initialize(MontoyaApi montoyaApi) {
montoyaApi.extension().setName("Custom Scan Check");
montoyaApi.logging().logToOutput("Custom Scan Check loaded.");
montoyaApi.scanner().registerPassiveScanCheck(new MyPassiveScanCheck(montoyaApi), ScanCheckType.PER_REQUEST);
montoyaApi.scanner().registerActiveScanCheck(new MyActiveScanCheck(montoyaApi), ScanCheckType.PER_INSERTION_POINT);
}
}
`MyPassiveScanCheck.java`
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.http.message.HttpRequestResponse;
import burp.api.montoya.http.message.responses.HttpResponse;
import burp.api.montoya.scanner.AuditResult;
import burp.api.montoya.scanner.ConsolidationAction;
import burp.api.montoya.scanner.audit.issues.AuditIssue;
import burp.api.montoya.scanner.audit.issues.AuditIssueConfidence;
import burp.api.montoya.scanner.audit.issues.AuditIssueSeverity;
import burp.api.montoya.scanner.scancheck.PassiveScanCheck;
import static burp.api.montoya.scanner.AuditResult.auditResult;
public class MyPassiveScanCheck implements PassiveScanCheck {
private final MontoyaApi api;
public MyPassiveScanCheck(MontoyaApi api) {
this.api = api;
}
@Override
public String checkName() {
return "Stack trace disclosure";
}
@Override
public AuditResult doCheck(HttpRequestResponse baseRequestResponse) {
HttpResponse response = baseRequestResponse.response();
if (response == null) {
return auditResult();
}
String body = response.bodyToString();
if (!(body.contains("Exception") && body.contains(".java:"))) {
return auditResult();
}
AuditIssue issue = AuditIssue.auditIssue(
"Stack trace disclosed in response",
"The response returns a verbose error containing a Java stack trace, " +
"revealing the framework and its version.",
null, // remediation
baseRequestResponse.request().url(),
AuditIssueSeverity.LOW,
AuditIssueConfidence.FIRM,
null, // background
null, // remediation background
AuditIssueSeverity.LOW,
baseRequestResponse // evidence
);
return auditResult(issue);
}
@Override
public ConsolidationAction consolidateIssues(AuditIssue existingIssue, AuditIssue newIssue) {
// Treat issues with the same name as duplicates
return existingIssue.name().equals(newIssue.name())
? ConsolidationAction.KEEP_EXISTING
: ConsolidationAction.KEEP_BOTH;
}
}
`MyActiveScanCheck.java`
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.http.Http;
import burp.api.montoya.http.message.HttpRequestResponse;
import burp.api.montoya.http.message.requests.HttpRequest;
import burp.api.montoya.http.message.responses.HttpResponse;
import burp.api.montoya.scanner.AuditResult;
import burp.api.montoya.scanner.ConsolidationAction;
import burp.api.montoya.scanner.audit.insertionpoint.AuditInsertionPoint;
import burp.api.montoya.scanner.audit.issues.AuditIssue;
import burp.api.montoya.scanner.audit.issues.AuditIssueConfidence;
import burp.api.montoya.scanner.audit.issues.AuditIssueSeverity;
import burp.api.montoya.scanner.scancheck.ActiveScanCheck;
import static burp.api.montoya.core.ByteArray.byteArray;
import static burp.api.montoya.scanner.AuditResult.auditResult;
public class MyActiveScanCheck implements ActiveScanCheck {
private final MontoyaApi api;
public MyActiveScanCheck(MontoyaApi api) {
this.api = api;
}
@Override
public String checkName() {
return "Reflected input probe";
}
// Note the extra params: the insertion point to probe, and an Http to send with.
@Override
public AuditResult doCheck(HttpRequestResponse baseRequestResponse,
AuditInsertionPoint insertionPoint,
Http http) {
// A rare marker plus characters that would be encoded if the input were sanitized
String payload = "bbYscan9173'\"<>";
// Place the payload at the insertion point, and set the service so Burp knows where to send it
HttpRequest checkRequest = insertionPoint
.buildHttpRequestWithPayload(byteArray(payload))
.withService(baseRequestResponse.httpService());
HttpRequestResponse checkResult = http.sendRequest(checkRequest);
HttpResponse checkResponse = checkResult.response();
if (checkResponse == null) {
return auditResult();
}
if (checkResponse.bodyToString().contains(payload)) {
AuditIssue 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,
checkResult
);
return auditResult(issue);
}
return auditResult();
}
@Override
public ConsolidationAction consolidateIssues(AuditIssue existingIssue, AuditIssue newIssue) {
return existingIssue.name().equals(newIssue.name())
? ConsolidationAction.KEEP_EXISTING
: ConsolidationAction.KEEP_BOTH;
}
}
Taking it further
Highlight the matched bytes
Attach a Marker to the evidence HttpRequestResponse so the viewer highlights exactly where the match occurred. Marker offsets are into the whole message, so add bodyOffset() to the position you found within the body.
Solution
import burp.api.montoya.core.Marker;
// ... inside the active doCheck(), once you've confirmed the reflection:
String responseBody = checkResponse.bodyToString();
int matchStart = checkResponse.bodyOffset() + responseBody.indexOf(payload);
Marker marker = Marker.marker(matchStart, matchStart + payload.length());
HttpRequestResponse evidence = checkResult.withResponseMarkers(marker);
AuditIssue 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,
evidence // marked-up evidence: the viewer highlights the match
);
return auditResult(issue);
Make the active condition robust
A single reflected string may be a false positive: a search box echoing your input isn’t a vulnerability. Require the special characters to survive unencoded, not just the alphanumeric marker.
Solution
String reflected = checkResponse.bodyToString();
boolean markerPresent = reflected.contains("bbYscan9173"); // our input reached the response
boolean rawSpecials = reflected.contains("'\"<>"); // and was NOT HTML-encoded
if (markerPresent && rawSpecials) {
// raise the MEDIUM issue: the characters that matter came back intact
}
Stronger still: send a baseline request with the marker but without the special characters first. Only raise the issue if the specials appear unencoded with the probe but not in the baseline. That rules out a page that happens to contain < or > already.
Add an insertion point provider
Register an AuditInsertionPointProvider via api.scanner() to scan locations Burp wouldn’t normally treat as insertion points. Examples are a custom header, a value inside a JSON body, or a serialized blob. provideInsertionPoints() returns one AuditInsertionPoint per location you want probed. The factory auditInsertionPoint(name, request, start, end) marks the byte range to replace.
Reference: customscaninsertionpoints in the Montoya API examples repo.
Solution
import burp.api.montoya.http.message.HttpRequestResponse;
import burp.api.montoya.scanner.audit.insertionpoint.AuditInsertionPoint;
import burp.api.montoya.scanner.audit.insertionpoint.AuditInsertionPointProvider;
import java.util.List;
import static burp.api.montoya.scanner.audit.insertionpoint.AuditInsertionPoint.auditInsertionPoint;
public class HeaderInsertionPointProvider implements AuditInsertionPointProvider {
private static final String HEADER = "X-Api-Version";
@Override
public List<AuditInsertionPoint> provideInsertionPoints(HttpRequestResponse base) {
String value = base.request().headerValue(HEADER);
if (value == null) {
return List.of(); // header absent, nothing to scan here
}
// Locate the header's value within the request bytes so Burp knows what to replace
String raw = base.request().toString();
int start = raw.indexOf(value, raw.indexOf(HEADER));
int end = start + value.length();
return List.of(auditInsertionPoint(HEADER, base.request(), start, end));
}
}
Register it in initialize():
montoyaApi.scanner().registerInsertionPointProvider(new HeaderInsertionPointProvider());
Configure it from the UI
Register a settings panel with SettingsPanelBuilder so you can retune the stack-trace marker without recompiling. The default .java: matches Java stacks; swap it for .py, .rb, or another source-file marker to spot other frameworks’ traces. Burp handles the layout, the Settings entry, and persistence for you.
Solution
import burp.api.montoya.ui.settings.SettingsPanelPersistence;
import burp.api.montoya.ui.settings.SettingsPanelWithData;
import static burp.api.montoya.ui.settings.SettingsPanelBuilder.settingsPanel;
import static burp.api.montoya.ui.settings.SettingsPanelSetting.stringSetting;
// In initialize():
SettingsPanelWithData settings = settingsPanel()
.withPersistence(SettingsPanelPersistence.PROJECT_SETTINGS)
.withTitle("Custom Scan Check")
.withSettings(stringSetting("Stack trace marker", ".java:"))
.build();
montoyaApi.userInterface().registerSettingsPanel(settings);
// Hand the settings object to the check so it reads the current value
montoyaApi.scanner().registerPassiveScanCheck(
new MyPassiveScanCheck(montoyaApi, settings), ScanCheckType.PER_REQUEST);
MyPassiveScanCheck now takes the panel in its constructor and reads the current value at scan time. Update the constructor from Step 1 accordingly:
import burp.api.montoya.ui.settings.SettingsPanelWithData;
private final MontoyaApi api;
private final SettingsPanelWithData settings;
public MyPassiveScanCheck(MontoyaApi api, SettingsPanelWithData settings) {
this.api = api;
this.settings = settings;
}
// In doCheck(), replace the hardcoded source-file marker:
if (!(body.contains("Exception") && body.contains(settings.getString("Stack trace marker")))) {
return auditResult();
}