Comprehensive Burp Suite Guide

A practitioner’s reference for Burp Suite — core tools, essential extensions, Bambdas and BChecks, Collaborator, macros and session handling, custom extension development, Burp AI, and real-world testing workflows. Compiled from 69 research sources.

Table of Contents

1. Fundamentals
2. Proxy
3. Repeater
4. Intruder
5. Scanner
6. Comparer, Decoder, Sequencer
7. Collaborator (OAST)
8. Macros & Session Handling
9. Target, Sitemap & Scope
10. Essential BApp Extensions
11. Turbo Intruder
12. Bambdas
13. BChecks
14. Writing Custom Extensions (Montoya API)
15. Burp AI
16. Keyboard Shortcuts
17. Real-World Workflows
18. Troubleshooting & Tuning
19. Learning Resources

1. Fundamentals

Burp Suite, from PortSwigger, is the de-facto web application security testing platform. It is an intercepting proxy with a rich toolbox for manual and semi-automated testing. Three editions ship today:

Pro is a one-user license and is the unambiguous standard for practitioners. The latest feature waves (2025.2 → 2026.1) shipped built-in AI integration, recorded login sequences, improved DOM Invader, Bambdas in more tools, and continued hardening of the Montoya API.

Core concepts

• Dashboard: central view of tasks (live passive crawl, active scans, issue activity, event log). Tasks are how Burp models background work.
• Proxy-first workflow: every HTTP(S) request a browser makes flows through Burp, where it can be observed, modified, recorded, and replayed.
• Tool chaining: right-click → “Send to …” moves a request through Repeater, Intruder, Scanner, Comparer, Decoder, or Sequencer.
• Project files: Pro persists every request, issue, and setting into a single .burp file for resumable engagements.
• Scope: the URL patterns you are allowed to test. Defining scope early keeps passive crawl and logging focused and prevents Intruder from firing at out-of-scope hosts.

Installing and launching

Install from portswigger.net, trust Burp’s CA certificate in your browser (http://burp → CA Certificate), and either use the embedded Chromium browser (no proxy setup required) or FoxyProxy in a real browser pointing to 127.0.0.1:8080. The embedded browser is the right default — it avoids the tedium of per-browser cert trust and gives you a clean session separated from your personal browsing.

2. Proxy

The Proxy is Burp’s heart. Everything else is downstream of what the Proxy captures.

Intercept vs HTTP history

• Intercept: a manual checkpoint. Toggle it on and Burp pauses every request so you can edit headers/body before forwarding. Useful for surgical edits; quickly becomes painful for normal browsing — turn it off by default.
• HTTP history: the full log of everything the browser proxied. This is where 90% of your exploratory work happens. Filter, search, and right-click-send from here.
• WebSockets history: parallel log for WS traffic, with its own intercept and history panes.

Match and Replace

Proxy → Settings → Match and Replace rewrites requests or responses in flight. Classic uses:

• Inject a Burp Collaborator host into the Host: header on every outbound request to catch routing oddities.
• Strip Content-Security-Policy headers to make XSS PoCs easier to demo.
• Force X-Forwarded-For: 127.0.0.1 on all requests to test trust-boundary bugs.
• Rewrite authorization headers to a canary token and hunt for requests that bypass auth.

Response modification and interception rules

Interception rules (Proxy → Options) let you build boolean chains like “intercept only if URL is in scope AND method is POST AND Content-Type contains json”. This keeps Intercept usable without drowning you.

TLS pass-through and invisible proxying

For thick clients, mobile apps, or non-browser HTTP clients, enable “Support invisible proxying” on the listener and add TLS pass-through entries for hosts you don’t want Burp to MITM (e.g. pinned certificate traffic you cannot crack).

3. Repeater

Repeater is where serious testing happens. It is a stateful request editor: take a request, tweak a parameter, resend, diff the response, repeat. Every senior tester lives in Repeater.

Tabs, groups, and notes

• Tabs are cheap — open one per attack variant (SQLi, XSS, path traversal, auth bypass) and name them.
• Tab groups (Pro) organize related tabs visually.
• The notes pane attached to each Repeater tab survives project save/load — use it as a mini-runbook: what you tried, what you observed, the hypothesis you’re testing.

Response rendering modes

Pretty / Raw / Hex / Render — switch fluidly. Render is indispensable for verifying stored-XSS payloads and for seeing how the browser actually renders your modified response.

Message-level features

• Inspector (right-hand panel): decode URL/Base64/JWT inline, view cookie attributes, edit body params as a structured list.
• Change request method: toggles GET↔POST and reformats parameters appropriately.
• Change body encoding: url-encoded ↔ multipart ↔ JSON.
• Go with Bambda (2025+): run a Bambda transform on the request before sending.

Comparing responses

Right-click two history entries → “Compare” opens Comparer on word- or byte-level diff. Use this for authorization tests: request as user A, as user B, compare. Any field that moves is a candidate IDOR signal.

4. Intruder

Intruder is Burp’s request fuzzer. You mark positions in a template request with §…§, pick a payload set, and fire.

Attack types

Payload types

Built-ins cover: simple list, runtime file, custom iterator, character substitution, case modification, recursive grep (extract from previous response — classic for CSRF-token-required login brute force), illegal unicode, numbers, dates, brute forcer, null payloads, character frobber, bit flipper, username generator, ECB block shuffler, extension-generated.

The recursive grep payload type is underused but powerful — it pulls a value out of each previous response via a grep expression and feeds it into the next request. This is how you brute force a login that re-issues an anti-CSRF token every request without a macro.

Grep-match, grep-extract, grep-payloads

Attack results can be scored by whether a response contains a given string, by extracting content between markers (populating a results column), or by matching against the payload itself. Sort by response length or grep column to surface anomalies instantly.

Community edition throttling

Intruder in Community is heavily throttled (time delay between requests). For any serious fuzzing you need Pro — or switch to Turbo Intruder.

5. Scanner

Burp Scanner has both passive and active modes and underpins Burp’s reputation.

Passive scanning

Runs on every response Burp sees. It looks for things that don’t require sending new requests: cookie flags, information disclosure headers, reflected parameters, mixed content, CORS misconfigurations, cacheable HTTPS responses, verbose error messages, form autocomplete, email disclosure. Zero-noise — always on.

Active scanning

Sends crafted payloads. Covers (non-exhaustive): SQLi (error/union/time/boolean), reflected & stored XSS, OS command injection, XXE, SSTI, SSRF, path traversal, LDAP injection, HTTP request smuggling (via the CL.TE/TE.CL/TE.TE probes that made Burp famous), HTTP/2 downgrade smuggling, Host header injection, open redirects, CRLF injection, unrestricted file uploads, XPath injection, and many more.

Active scans are tuned via scan configurations: which insertion points (URL params, body, headers, cookies, JSON keys/values, XML), which issue classes to probe, how aggressive, whether to use Collaborator. Save a config per engagement type — “quick audit”, “deep API scan”, “smuggling-only”.

Insertion points

Scanner identifies insertion points automatically, but you can mark custom ones. For APIs, load an OpenAPI/Swagger/Postman collection via the appropriate extension and scan the whole catalogue.

Issue activity and the dashboard

Every finding lands in the Issue activity panel with severity, confidence, and advisor/evidence detail. Right-click an issue → “Show response in browser” or “Request in Repeater” for quick validation. Export as HTML/XML for reporting.

Recorded login sequences

Burp records you logging into an app (click-by-click in the embedded browser) and replays it during authenticated crawls/scans. As of 2025.2 this is AI-assisted — the AI infers the right form fields even when layouts change.

6. Comparer, Decoder, Sequencer

Comparer

Diff two pieces of data at word or byte level. Main uses:

• Two responses from the same endpoint with different auth contexts (IDOR hunting).
• Expected vs observed response when testing a filter bypass.
• Normal 404 vs injected 404 (blind boolean channels).

Decoder

A Swiss-army knife for encoding: URL, HTML, Base64, ASCII hex, hex, octal, binary, gzip, plus hashing (MD5/SHA-family). Stackable — chain decodes top-to-bottom. Inspector panes in Repeater now cover most use cases, but Decoder is still useful for quick one-off conversions.

Sequencer

Statistical analysis of token randomness. Grab a few thousand session tokens via the automated token capture flow (live capture from a request that issues a new token) and Sequencer runs FIPS randomness tests. Rarely finds modern bugs in mainstream frameworks but still relevant for bespoke auth code, anti-CSRF generators, and password reset tokens.

7. Collaborator (OAST)

Burp Collaborator is PortSwigger-hosted out-of-band interaction capture. Every Pro install gets a unique Collaborator subdomain of oastify.com (or a private server you host).

What it catches

• Blind SSRF (server fetches your Collaborator URL)
• Blind XXE (external entity resolution triggers DNS/HTTP)
• Blind command injection (; curl <payload>)
• Blind SQLi via OOB (xp_dirtree, UTL_HTTP, load_file over SMB)
• Email header injection (SPF lookups)
• Delayed interactions (log processors that deref URLs hours later)

Using it

• Collaborator client (Burp → Collaborator): poll manually, see DNS/HTTP/SMTP hits in real time with full request bodies.
• In Scanner: Burp auto-injects Collaborator hosts into active scan payloads. When the scanner sees an interaction, it raises a high-confidence issue.
• In Repeater: insert a Collaborator payload via the context menu and watch for hits.
• Collaborator Everywhere extension: automatically sprinkles Collaborator hosts into headers (Referer, X-Forwarded-For, True-Client-IP, From, etc.) on every browsed request, surfacing blind SSRF purely through normal browsing.

Private Collaborator servers

For sensitive engagements you can run a self-hosted Collaborator. Wildcard DNS and a public-facing host are required. The ngrok-based community extension provides a quick-and-dirty alternative when a full deploy is overkill.

8. Macros & Session Handling

Session handling is the subsystem that keeps Burp’s automated tools (Scanner, Intruder, Repeater-with-rules) authenticated even when the app rotates tokens or times out sessions.

Macros

A macro is a recorded sequence of requests Burp can replay. Classic scenario: log in, fetch a CSRF token, call an endpoint that re-issues a JWT, then use that JWT in the tested request.

• Record by selecting a chain of requests in the history.
• Edit each item to specify which parameters to re-derive (from prior response) and which to hard-code.
• Test the macro from the macro editor — Burp runs it and shows each response.

Session handling rules

Rules bind macros to scopes of tools and URLs, and apply actions:

• Check session is valid: before each request, run a probe; if the response doesn’t contain an expected string, consider the session dead and re-run the login macro.
• Run a macro: unconditionally execute a macro (e.g. fetch fresh CSRF token) before each matching request.
• Update param/cookie from prior response: grab the new token from the macro response and splice it into the current request.
• Invoke Burp extension action: hand off to a custom extension for complex logic (ATOR, ExtendedMacro, etc.).

ATOR — Authentication Token Obtain and Replace

Popular BApp that replaces the clunky macro UI with a structured “here’s the login request, here’s the response field I need, here’s where it goes” flow. Faster to set up for bearer-token APIs than native session handling rules.

When macros fail

Modern SPAs with multi-step OAuth, PKCE, WebAuthn, or device-bound tokens can break Burp’s macro recorder. Fallbacks: use recorded login sequences (AI-assisted), script the login in an extension, or use AutoRepeater / Reshaper to rewrite tokens on the fly.

9. Target, Sitemap & Scope

Scope

Defined as include/exclude URL patterns. Everything — proxy logging, passive scan, active scan targeting, Intruder throttling — keys off scope. Always set it first.

Sitemap

Tree view of every URL Burp has seen, annotated with method, status, length, MIME type, time, and discovered issues. Right-click a branch to “Actively scan this host”, “Engagement tools → Discover content” (content discovery brute-force), or “Analyze target” (surface stats).

Content discovery

Built-in dirbusting with a default wordlist plus recursive expansion. For anything serious, pipe off-tool (ffuf, feroxbuster) or use the GAP / JSpector extensions to harvest endpoints from JavaScript.

Engagement tools

Under Target → right-click → Engagement tools:

• Find comments / Find scripts / Find references: quick greps over sitemap content.
• Discover content: in-tool brute force.
• Schedule task: fire a scan at 3am.
• Generate CSRF PoC: auto-build a CSRF HTML form from any request.
• Simulate manual testing: fake activity timer for… let’s not dwell on that one.

10. Essential BApp Extensions

The BApp Store is Burp’s curated extension repository. The practitioner starter pack:

Access control and authorization

• Autorize — runs every in-scope request twice with an alternate cookie/token set and flags responses that match the authenticated baseline. The canonical IDOR/BOLA tool.
• AuthMatrix — matrix-based access control testing. Define roles, define requests, run the matrix, see which role can hit which endpoint.
• AutoRepeater — automatically replays every in-scope request with header replacements (e.g. swap Authorization) and surfaces diffs.

Discovery and recon

• Param Miner (PortSwigger) — guesses hidden parameters and headers via diffing. Mandatory. Also detects cache poisoning via header oracle.
• Backslash Powered Scanner — transforms-based fuzzer that finds injection in places Burp’s native scanner misses. Descended from James Kettle’s research.
• Content Type Converter — JSON↔XML on the fly, exposing XXE/SSRF in APIs that accept both.
• JSpector — crawls linked JavaScript files for endpoints, secrets, URLs.
• GAP — parameter and endpoint harvester from JS and responses.
• SleuthQL — Python script that parses Burp history looking for SQLi-worthy parameters.

Scanning enhancement

• Active Scan++ — adds payloads and checks for SSTI, XML injection, subtle XSS, host header injection, CRLF, stacked SQLi. Free, essential.
• Burp Bounty — rule-based custom scanner; write your own “if X in response when Y sent” checks in YAML.
• Retire.js — flags outdated JS libs with known CVEs. Quick wins.
• Software Vulnerability Scanner — checks software versions against vulnerability databases.

Cryptography and tokens

• JWT Editor — decode/edit/sign JWTs inline in Repeater. Supports the none/alg confusion attacks, key confusion (RS→HS), JWK injection.
• SignSaboteur — edit and re-sign a broad range of signed token formats (JWT, Paseto, ASP.NET, Flask, Ruby cookies).
• Hackvertor — tag-based encoder/decoder with hundreds of transforms, including AES/HMAC/custom. Great for apps with bespoke request signing.

Logging and analysis

• Logger++ — replacement for the default HTTP history with better filtering, column customization, Elasticsearch export, regex rules, and cross-tool logging (Repeater, Scanner, Intruder also logged).
• Request Smuggler — dedicated HTTP request smuggling probe extension.
• Flow — alternative proxy history with a view-per-tool timeline.

Out-of-band and SSRF

• Collaborator Everywhere — automatic Collaborator injection into headers on all proxied traffic.
• Taborator — pins Collaborator output as a Burp tab so you don’t have to open the separate window.
• DNS Analyzer — finds DNS-level vulnerabilities (zone transfers, dangling records, subdomain takeovers).

API-specific

• JSON Beautifier / JSON Web Tokens / JSON Decoder — tidy and dissect.
• Postman Integration / OpenAPI Parser — import collections/specs to seed scope and scanner insertion points.
• HTTP Smuggler (NCC) — smuggling payload builder.
• GraphQL Raider / InQL — GraphQL introspection, query builder, abuse testing.

Convenience

• Turbo Intruder (PortSwigger) — see §11.
• Piper — pipe requests/responses through arbitrary command-line tools.
• Reshaper — declarative rewriting of requests matching pattern X (similar to Match/Replace but programmable).
• Copy As (curl/Python/PowerShell/Node) — right-click-export any request for sharing or scripting.
• HopLa — AI-assisted payload generation, wordlists, inline suggestions.
• Burp Share Requests — generate shareable links for requests (handy in team engagements).

Installing

Extender → BApp Store → Install. Most BApps are written in Java or Python (via the embedded Jython). Jython must be configured once (Extender → Options → Python environment). Ruby extensions require JRuby, which is rarer.

11. Turbo Intruder

Turbo Intruder is a PortSwigger extension by James Kettle, purpose-built for high-volume, high-precision attacks that the built-in Intruder cannot handle. It’s the tool you reach for when you need tens of thousands of requests per second, HTTP/2 frame manipulation, or race-condition timing at millisecond precision.

The model

Turbo Intruder exposes a Python (Jython) scripting interface. You write a small script that creates an engine, queues requests, and defines a handleResponse callback.

def queueRequests(target, wordlists):
    engine = RequestEngine(endpoint=target.endpoint,
                           concurrentConnections=30,
                           requestsPerConnection=100,
                           pipeline=False)
    for word in open('/usr/share/wordlists/rockyou.txt'):
        engine.queue(target.req, word.rstrip())

def handleResponse(req, interesting):
    if req.status != 302:
        table.add(req)

When to use it

• Credential stuffing / password spraying — thousands of attempts per minute.
• Race conditions — the gate feature queues N requests then releases them in one TCP push, exploiting single-packet attacks. Devastating for coupon-application and wallet-withdraw bugs.
• Rate-limit bypass probing — vary headers (X-Forwarded-For, user agents) at volume to find the leaky dimension.
• Cache poisoning at scale — collect a big enough sample to distinguish deterministic from stochastic response differences.

Single-packet attack

HTTP/2’s MUX allows multiple requests in a single packet. Turbo Intruder uses this to eliminate network jitter — all racing requests hit the server in the same kernel read. The canonical way to find “double spend” / “apply coupon twice” / “use gift card from two tabs” bugs.

12. Bambdas

Bambdas (introduced 2023.10.3) are small Java snippets written directly in Burp’s UI that customize behavior. The name is PortSwigger’s play on “Burp lambda”.

Where Bambdas run

• Proxy HTTP history filter — the original home. Write a predicate (return true to keep the row).
• Custom columns — return a value to populate a new column.
• Highlight / annotate — colorize rows matching a condition, auto-comment them.
• Proxy match/replace — programmatic request/response transforms.
• Repeater — Bambda-driven request transforms before send.

Example: find unusual JWT algorithms

if (!requestResponse.hasResponse()) return false;
var auth = requestResponse.request().headerValue("Authorization");
if (auth == null || !auth.startsWith("Bearer ")) return false;
var token = auth.substring(7);
if (!token.contains(".")) return false;
var header = token.split("\\.")[0];
var decoded = new String(utilities().base64Utils()
    .decode(header, Base64DecodingOptions.URL).getBytes());
return decoded.contains("\"alg\":\"HS512\"");

This Bambda was famously used by Dana Epp to parse through hundreds of thousands of proxied requests in seconds and find a P1 JWT-algorithm-confusion bug. It turns an otherwise tedious grep-and-decode task into a one-shot filter.

Example: flag requests that leak PII in responses

if (!requestResponse.hasResponse()) return false;
var body = requestResponse.response().bodyToString();
return body.matches("(?s).*\\b\\d{3}-\\d{2}-\\d{4}\\b.*");  // US SSN

Saving and sharing

Each Bambda editor has a gear menu with Save settings / Load settings — writes/reads a JSON file you can version-control. Community repos like 254Labs/awesome-bambdas and BugBountyzip/Bambdas aggregate good ones: PII finders, GraphQL filters, parameter-anomaly highlighters, SSRF candidate hunters.

Limitations

No step debugger, no System.out.println — error output is limited to runtime stack traces. Test incrementally, start simple. The Montoya API is your reference: interfaces like HttpRequestResponse, Annotations, Utilities.

13. BChecks

BChecks (introduced 2023.10) are a DSL for authoring custom active scan checks without writing a Java extension. They slot straight into Scanner: write a .bcheck, drop it in User → Settings → Scanner → BChecks → Add, and every active scan runs it.

Anatomy

metadata:
    language: v2-beta
    name: "Custom SSRF via custom header"
    description: "Probe for SSRF reachable via X-Original-URL"
    author: "you"

run for each:
    payload = "http://{BC}"

given request then
    send request called check:
        replacing header "X-Original-URL": `{payload}`

    if interactions (from {BC}) then
        report issue:
            severity: high
            confidence: firm
            detail: "X-Original-URL triggered a Collaborator hit"
            remediation: "Strip X-Original-URL at the edge"
    end if

What they’re good at

• API-specific checks — apps with a custom header convention, a bespoke CSRF mechanism, or a vendor-specific insertion point.
• Organization-wide rule enforcement — “every scan we run should look for this custom error string” → ship it as a BCheck.
• Lightweight PoC automation — turn a finding from one engagement into a repeatable probe on the next.

PortSwigger publishes a BCheck library on GitHub. For most practitioners, writing a BCheck is dramatically faster than writing a full Montoya extension.

14. Writing Custom Extensions (Montoya API)

When BChecks and Bambdas run out, you write a full extension. Burp has had two APIs:

• Legacy API (IBurpExtender) — deprecated but still widely used in older extensions. Java, Python (Jython), Ruby (JRuby).
• Montoya API (2023+) — the current API, Java-only, cleaner, immutable data model, explicit capabilities. All new extensions should use Montoya.

Skeleton Montoya extension

package com.example;

import burp.api.montoya.BurpExtension;
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.http.handler.*;

public class MyExt implements BurpExtension {
    @Override
    public void initialize(MontoyaApi api) {
        api.extension().setName("My Extension");
        api.http().registerHttpHandler(new HttpHandler() {
            @Override
            public RequestToBeSentAction handleHttpRequestToBeSent(
                    HttpRequestToBeSent req) {
                api.logging().logToOutput("outbound: " + req.url());
                return RequestToBeSentAction.continueWith(req);
            }
            @Override
            public ResponseReceivedAction handleHttpResponseReceived(
                    HttpResponseReceived resp) {
                return ResponseReceivedAction.continueWith(resp);
            }
        });
    }
}

Key interfaces

Python extensions

Jython 2.7 still ships as the Python runtime. Swing-based UIs are common for Python extensions — import javax.swing.* and build panels as you would a Java app. Python extensions are faster to prototype but slower at runtime and lock you to Jython’s ancient Python version.

Distribution

Build a fat JAR (Maven/Gradle with shade plugin). Extender → Extensions → Add. For community distribution, submit to the BApp Store — PortSwigger reviews each extension.

Starter resources

• PortSwigger’s Montoya API javadoc
• federicodotta/Burp-Suite-Extender-Montoya-Course — structured course repo
• coreyd97/BurpCustomizer, Burp-Montoya-Utilities — reference implementations
• snoopysecurity/awesome-burp-extensions — curated list of open-source extensions to learn from

15. Burp AI

Burp AI arrived in Burp Suite Professional 2025.2 as an opt-in, credit-metered set of features integrated into existing primitives — not a chatbot bolted on the side.

Feature set

1. Burp AI in Repeater — task-based assistant. You highlight text, request, or response; ask a question; Burp creates a task and logs the AI’s HTTP traffic for reproducibility. No conversation history — each task must carry its own context.
2. Explainer — highlight any bytes in Repeater and get an on-the-spot explanation of unfamiliar headers, JWTs, obfuscated JS, odd encodings. Low-scope and cheap.
3. Explore Issue — attached to Burp Scanner findings. The AI performs automated follow-up on an issue: attempts exploitation, probes for escalation, summarizes findings. Not a general-purpose “hack this app” autopilot — it is scoped to a detected issue.
4. AI-enhanced scanning — starts with Broken Access Control false-positive reduction. The AI reviews suspected BAC findings and discards ones that are non-exploitable.
5. AI-powered recorded login sequences — makes Burp’s login recorder robust to layout changes.
6. AI-powered extensions (Montoya API) — extensions can invoke Burp AI via a stable API, so you can build your own agentic workflows on top of the same credits.

Credits and privacy

Credits are mandatory, per-user (not pooled), and expire after 12 months. Every task deducts credits based on complexity. Practical implication: treat Burp AI as “use when stuck”, not “always on”. Provide minimum context — it both cuts cost and improves answer quality.

Data handling: PortSwigger documents what goes to the AI provider and under what conditions. For engagements where customer traffic cannot leave the box, Burp AI must be disabled.

Guardrails for responsible use

• Every AI-produced claim must be reproducible. The task logs the HTTP traffic the AI generated — replay it, verify it in Repeater, then it enters your report.
• Prefer “prove or disprove X” prompts with explicit success criteria.
• Never paste customer PII into a prompt. Redact before asking Explainer to decode.
• AI-enhanced scanning reduces noise but is not a substitute for human triage.

Community extensions that predate Burp AI

• HopLa (Synacktiv) — LLM-assisted payload suggestions and autocomplete in Repeater/Intruder.
• Burp Suite Integration for Neuron — third-party AI integration.

16. Keyboard Shortcuts

Burp’s power users live on the keyboard. The defaults (and a few recommended custom bindings) that matter most:

Rebind via User → Settings → User interface → Hotkeys. Common custom bindings: a single keystroke for “send to organizer” and “toggle pretty/raw”.

17. Real-World Workflows

Workflow: fresh web app engagement

1. Scope: create a new project, set target scope to the in-scope hosts. Exclude auth / logout / billing endpoints that will wreck session state.
2. Browse: use the embedded browser to exercise every reachable feature — signup, login, settings, every form, every file upload, every role. Burp’s passive scan and sitemap populate in the background.
3. Content discovery: right-click the top node → Engagement tools → Discover content. Also run GAP/JSpector against the site to pull endpoints out of JS bundles.
4. Param Miner: run guess params on hot endpoints. Any new parameter that changes behavior is worth an Intruder session.
5. Autorize: configure a second user, browse again, Autorize flags every broken access control.
6. Active scan: queue a scan on the sitemap with a tuned config. Not the “audit coverage” default — the tight one. Let it run while you manual-test.
7. Intruder / Repeater: any interesting parameter goes to Repeater first for a handful of manual variants, then Intruder for the fuzz wordlist.
8. Collaborator: enable Collaborator Everywhere for the whole session — free SSRF/header-injection coverage.
9. Triage: review issues every few hours, kill false positives, send the keepers to Repeater for PoC construction.
10. Report: export issues, build PoCs, write up.

Workflow: API pentest

1. Ingest spec: import OpenAPI/Swagger/Postman collection via the relevant extension. Scope is now seeded.
2. Auth: ATOR or native session handling for the bearer token flow.
3. Auth matrix: AuthMatrix with admin/user/guest roles.
4. Content-Type Converter: on every JSON endpoint, try XML — classic XXE discovery.
5. Param Miner guess headers: APIs often accept undocumented headers (X-Original-URL, X-Rewrite-URL, X-Forwarded-Host) that open up BAC or cache poisoning.
6. BChecks: any org-specific checks run as part of active scan.
7. GraphQL: if the API is GraphQL, InQL for introspection + query generation, then manual auth checks.

Workflow: race-condition hunting

1. Identify a stateful action (apply coupon, withdraw, redeem, vote) in Repeater.
2. Send to Turbo Intruder, load the race-single-packet-attack template.
3. Queue 20–50 copies, run.
4. Check the state — if the coupon applied twice, the balance went negative, or you got two of the prize, you have a bug.
5. Verify without Turbo Intruder (two browser tabs + tight timing) to rule out off-by-one in counting.

Workflow: blind injection via OAST

1. Start Collaborator client in a separate tab.
2. Enable Collaborator Everywhere.
3. Browse every input-accepting feature, including file metadata, exif, SVGs, admin-only panels, webhooks, import/export features.
4. After the session, review Collaborator client for any interactions. Correlate by time, source IP, DNS vs HTTP, and subdomain prefix (Collaborator Everywhere tags each injection with a unique label).
5. For each hit, reconstruct the triggering request in Repeater with a fresh Collaborator payload and prove causation.

Workflow: JWT algorithm confusion

1. Catch a JWT-bearing request in Repeater.
2. Open JWT Editor’s custom tab in the message editor.
3. Try alg: none, removing the signature.
4. Try RS256 → HS256 key confusion using the server’s public key as the HMAC secret.
5. Try kid header traversal (../../dev/null) and JWK injection.
6. Bambda filter across history for any other endpoint using the same token layout — scale the bug beyond the one you caught.

18. Troubleshooting & Tuning

• Out of memory: edit Burp’s JVM args in the startup script/shortcut — -Xmx8g or higher for big engagements. Huge proxy histories also slow the UI; periodically export and archive.
• UI sluggishness: disable unused BApps. Logger++ and heavy extensions consume CPU per request. Close Repeater tabs you aren’t using.
• TLS handshake failures: add TLS pass-through for pinned hosts; or extract client certs and load them via User → Settings → TLS → Client certificates.
• Upstream proxy / corporate proxy: Network → Connections → Upstream proxy servers.
• Slow Scanner: tune the scan config — disable insertion points you don’t need (cookie values on a JWT-only API is wasted work).
• Noisy passive scan: filter out informational issues in the dashboard; they drown out the real findings.
• Jython import errors: some Python extensions pin old Jython module versions. Check Extender → Extensions → {ext} → Errors.
• Lost work on crash: always use project files in Pro, not “temporary project”. Auto-save is frequent but not instant.

19. Learning Resources

• PortSwigger Web Security Academy — the best free web security training on the internet, written by Burp’s authors. Every lab is solvable in Burp.
• Burp Suite Certified Practitioner (BSCP) — PortSwigger’s practical exam. Community study repos (e.g. botesjuan/Burp-Suite-Certified-Practitioner-Exam-Study) are dense and well-organized.
• PortSwigger Research blog — James Kettle’s smuggling, param mining, cache poisoning, single-packet attack research dropped here first.
• PortSwigger YouTube — release walkthroughs, Academy lab walkthroughs.
• snoopysecurity/awesome-burp-extensions — curated extension list.
• 254Labs/awesome-bambdas and BugBountyzip/Bambdas — Bambda collections.
• federicodotta/Burp-Suite-Extender-Montoya-Course — Montoya API course.
• Dana Epp’s blog — practical API pentesting with Burp, Bambdas, BChecks, extension writing.
• TCM Security / Cyber Advisors / KSEC ARK — blog posts cataloguing extension picks and workflows.
• Community Discord / PortSwigger forum — “Great getting started resources for new users of Burp Suite Professional” threads are updated yearly.

Appendix A: Extension quick-pick matrix

Appendix B: Montoya API cheat sheet

api.http().sendRequest(req)                 // one-shot send
api.http().registerHttpHandler(handler)     // pre-send/post-recv hooks
api.proxy().registerRequestHandler(h)       // proxy-only
api.scanner().registerScanCheck(check)      // custom scan check
api.userInterface().registerContextMenuItemsProvider(p)
api.userInterface().registerSuiteTab(name, component)
api.persistence().extensionData()           // per-extension KV in project
api.collaborator().createClient()           // mint Collaborator payloads
api.utilities().base64Utils().encode(...)
api.utilities().urlUtils().decode(...)
api.logging().logToOutput("...")

Appendix C: Quick Bambda recipes

// In-scope only
return requestResponse.request().isInScope();

// Status 500s
return requestResponse.hasResponse()
    && requestResponse.response().statusCode() == 500;

// Responses containing reflected input of parameter "q"
var q = requestResponse.request().parameterValue("q", HttpParameterType.URL);
if (q == null || q.length() < 4) return false;
return requestResponse.hasResponse()
    && requestResponse.response().bodyToString().contains(q);

// GraphQL queries
return requestResponse.request().path().endsWith("/graphql")
    && requestResponse.request().method().equals("POST");

// Large responses
return requestResponse.hasResponse()
    && requestResponse.response().body().length() > 1_000_000;

// Set highlight on 401s
if (requestResponse.hasResponse()
    && requestResponse.response().statusCode() == 401) {
    requestResponse.annotations().setHighlightColor(HighlightColor.RED);
}
return true;

Appendix D: BCheck recipes

BChecks slot into Scanner. Drop into User → Settings → Scanner → BChecks → Load.

Detect an auth-bypass header

metadata:
    language: v2-beta
    name: "X-Original-URL auth bypass"
    description: "Checks whether restricted paths become reachable via X-Original-URL"
    author: "appsec"

given host then
    send request called base:
        method: "GET"
        path: "/admin"
    send request called bypass:
        method: "GET"
        path: "/public"
        headers:
            "X-Original-URL": "/admin"

    if {base.response.status_code} is "403"
       and {bypass.response.status_code} is "200" then
        report issue:
            severity: high
            confidence: firm
            detail: "X-Original-URL exposed /admin"
            remediation: "Strip X-Original-URL at reverse proxy"
    end if

Detect verbose error stack traces

metadata:
    language: v2-beta
    name: "Verbose stack trace in response"

given response then
    if {latest.response.body} matches "at java\\..*\\(.*:\\d+\\)" then
        report issue:
            severity: low
            confidence: firm
            detail: "Java stack trace leaked"
    end if

Detect SSTI via math probe

metadata:
    language: v2-beta
    name: "Template injection math probe"

given insertion point then
    send payload:
        value: "{{7*7}}"
    if {latest.response.body} contains "49" then
        report issue:
            severity: high
            confidence: tentative
    end if

The BCheck DSL is intentionally narrow — arithmetic, string matching, regex, and HTTP. For anything beyond that scope, graduate to a Montoya extension.

Appendix E: Intruder payload-type quick reference

Appendix F: Scanner issue classes (abbreviated)

Burp Scanner currently detects (and the list grows each release) — passive and active combined:

• Injection: SQLi (6+ variants), NoSQLi, command injection, LDAP injection, XPath/XQuery injection, SMTP header injection, SSI injection, expression language injection, SSTI (Jinja/Twig/Velocity/Freemarker/Razor/Handlebars), XML injection, XXE, SOAP array abuse, JSON hijacking via MIME confusion.
• Cross-site scripting: reflected, stored, DOM-based (DOM Invader integration), client-side template injection.
• Access control: path-relative style sheet import, verb tampering, direct request to restricted endpoints, BOLA candidates.
• Authentication: weak/missing auth, cleartext credentials, session token in URL, missing Secure flag on auth cookies, missing HttpOnly, predictable tokens (feeding Sequencer).
• Cryptography: weak TLS, mixed content, insecure cipher, HSTS missing, Certificate transparency, insecure randomness in tokens.
• SSRF: URL parameter SSRF, Host header SSRF, Referer-based SSRF, Collaborator-validated blind SSRF, cloud metadata probes.
• Request smuggling: CL.TE, TE.CL, TE.TE, HTTP/2-to-HTTP/1.1 downgrade smuggling, H2.TE, H2.CL.
• Deserialization: Java, .NET, PHP, Python pickle signatures in responses.
• Open redirect and DOM-based open redirect.
• Header injection: CRLF injection, host header injection, cache poisoning via unkeyed headers.
• Information disclosure: source code, internal IPs, version numbers, stack traces, debug endpoints, email addresses, private keys.
• Web cache: cacheable HTTPS response, cache poisoning via unkeyed input.
• File upload: unrestricted upload, upload path traversal, server-side file inclusion.
• CORS: wildcard with credentials, reflection of arbitrary origin, trust of null origin.
• Client-side: tabnabbing, clickjacking (missing X-Frame-Options/frame-ancestors), postMessage eavesdropping.

Most of these each have a dedicated PortSwigger research blog post explaining the detection logic; Scanner is as much a research output as it is a tool.

Appendix G: Recommended user-settings tweaks

• Project options → Sessions → Cookie jar: enable for Proxy, Scanner, Repeater, Intruder, Extender so cookies flow across tools consistently.
• User options → Misc → Logging → Proxy history → Omit out-of-scope: keep history tight.
• User options → Display → HTTP message display → Font: bump to 14pt minimum. Reading tiny HTTP is a recipe for missed bugs.
• User options → Hotkeys: bind “toggle proxy intercept” to a single key.
• Scanner → Configuration: create custom configs “quick”, “deep”, “API”, “smuggling”. Saves clicks per engagement.
• Network → TLS → Negotiation: enable all protocols and all ciphers for broad target compatibility, then tighten when testing a TLS config.
• Network → Connections → Hostname resolution: override DNS on a per-host basis when testing staging behind split-horizon DNS without rewriting /etc/hosts.
• Project → Save options → Save automatically: enable in-place auto-save every 5 minutes on long engagements.
• Extender → Options → Java environment → Folder for loading library JARs: drop shared JARs (Burp extensions sometimes share dependencies) so you don’t bundle them per-extension.

Appendix H: Common pitfalls

• Running active scans out of scope. Out-of-scope hosts still get scanned if you right-click “Active scan this branch” on a sitemap node containing them. Always confirm scope.
• Leaking data via auto-submit extensions. Some extensions phone home to third-party APIs by default (submitting requests for analysis). Read the extension source before enabling on sensitive targets.
• Running Burp AI on customer PII. Check your engagement rules before enabling AI features; disable the whole AI subsystem for NDA’d assessments.
• Huge projects = slow crash-recovery. Split long engagements across multiple project files, one per sprint or per scope zone.
• Intruder attacks without grep-extract. Sorting by length alone misses bugs where the response differs in content but not size. Always add a grep-match or grep-extract column.
• Forgetting to disable intercept before demos. Watch senior testers trip on this. Two-key shortcut.
• Relying on passive scan alone. Passive scan is free but finds only low-hanging fruit. Active scan plus manual Repeater work is where the real bugs live.
• Mis-tuned session handling. If your macro fails silently, Scanner thinks the app is anonymous and misses auth’d bugs. Always verify by checking the macro runs successfully via the test button.

Appendix I: Workflow walkthrough — finding an SSRF in under an hour

A representative “day in the life” walkthrough using only techniques covered above.

Context. In-scope SaaS product with an image-proxy feature: users supply a URL, the app fetches it and returns a thumbnail.

1. Open the feature in the embedded browser. Submit https://example.com/logo.png. Observe the outbound request in Proxy history: POST /api/fetch-image with body {"url":"https://example.com/logo.png"}.
2. Send to Repeater. Note tab “fetch — baseline”.
3. Test for full-response SSRF. Change URL to http://127.0.0.1/. Response: 200 OK with small HTML. The app is a reverse proxy — you have a full-response SSRF with a localhost HTTP stack behind it.
4. Bambda-filter history for the fetch endpoint. Create a filter request.path().equals("/api/fetch-image") to isolate every test iteration.
5. Enable Collaborator Everywhere and re-run with a Collaborator URL — verify the outbound IP to understand the egress point (EC2 IMDSv1? vpc-internal NAT?).
6. IMDS probe. Try http://169.254.169.254/latest/meta-data/. Response: 200 with ami-id list. The target runs EC2 with IMDSv1 allowed from user-controlled fetch.
7. Credential extraction. http://169.254.169.254/latest/meta-data/iam/security-credentials/ → role name → .../{role} → access key, secret, session token.
8. BCheck it. Before writing the report, convert the core check into a BCheck so the next engagement auto-detects “fetch-image accepts 169.254.169.254 without a deny-list”.
9. Report. Export the Repeater tab’s raw request/response, redact the real credentials, include the Collaborator interaction log as evidence of egress path, impact writeup covering IAM blast radius.

Total time: 20–40 minutes if you know the loop. Every step happens inside Burp — no shell, no scripts.

Appendix J: Versions worth knowing

Stay on the latest stable — PortSwigger ships fast and deprecates APIs with warning.

This guide is a synthesis of 69 research articles clipped to the vault, spanning PortSwigger documentation, community tutorials, extension READMEs, release notes (2025.2–2026.1), practitioner blog posts, and Burp AI coverage. It is intended as a living reference — update as tools evolve, extensions get deprecated, and new bug classes emerge.