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

  1. The goal
  2. Before you start
    1. Labs to launch
  3. How to approach it
    1. Step 1: Sketch the two classes
    2. Step 2: The passive check
    3. Step 3: The active check
    4. Step 4: Deduplication
    5. Step 5: Register the checks
    6. Step 6: Build, reload, and test the passive check
    7. Step 7: Test the active check
    8. Step 8: Make the issue actionable
  4. Check your work
  5. The complete extension
  6. Taking it further

The goal

Two classes:

  • Write MyPassiveScanCheck implements PassiveScanCheck with a doCheck(...) that flags responses leaking a Java stack trace.
  • Write MyActiveScanCheck implements ActiveScanCheck with a doCheck(...) that injects a probe and raises an issue on unencoded reflection.
  • Give each a checkName() and a consolidateIssues(...) to collapse duplicate findings.
  • Register both with registerPassiveScanCheck and registerActiveScanCheck so 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 an Http object. You build a request with your payload, send it with that http, 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:

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 (Exception plus .java:), raises a LOW issue if present, guards against null.
  • MyActiveScanCheck.doCheck(): injects the probe at the insertion point (setting the service on the built request), sends it via the supplied http, raises a MEDIUM issue 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 the montoyaApi object, 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.

  1. 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.
  2. Right-click that request in proxy history (or the site map) and click Scan > Passive scan, or run a full audit.
  3. Go to Dashboard > Issue activity. Your Stack trace disclosed in response issue 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

  1. Open the Reflected XSS into HTML context with nothing encoded lab and run a search so you capture a GET /?search=... request.
  2. Right-click it and click Scan > Active scan (or run an audit). Burp exercises your check against each insertion point it identifies.
  3. 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, or INFORMATION to match real impact.
  • Set the confidence to CERTAIN, FIRM, or TENTATIVE, and be honest about false positives.
  • Pass the HttpRequestResponse as 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();
}