Burp Suite Tutorial 2026 — From First Intercept to Custom Extension

Published May 20, 2026 · By AxVeil Research · 14 min read

Burp Suite has been the industry standard web-app proxy for two decades, and 2026 has not changed that. What has changed is the surface area: an HTTP/3 proxy, full Bambda filter language, the Montoya API replacing the legacy IBurpExtender interface, and a tightly integrated Collaborator that quietly carries half of modern OAST workflows. This tutorial walks an engineer from first install through writing a production extension, with the keyboard shortcuts and config snippets we use daily on engagements. Pair it with our VAPT service when you need a partner who already operates this toolchain at scale.

1. Install and first launch

Download the Community or Pro installer from portswigger.net/burp/releases. Pro is a USD 449/year per-user licence; Community is free and unlimited in time but throttles Intruder and disables the Scanner. Burp ships its own bundled OpenJDK so you no longer need a system Java install. On Linux, prefer the headless .jar + .vmoptions pair when you plan to customise heap size.

# Linux first run with 4 GB heap and a project file
java -jar -Xmx4g burpsuite_pro_v2026.5.1.jar --project-file=engagement-acme.burp \
     --config-file=axveil-defaults.json --user-config-file=~/.BurpSuite/UserConfigPro.json

# Headless mode for CI (Pro and Enterprise only)
java -jar -Djava.awt.headless=true burpsuite_pro.jar --unpause-spider-and-scanner \
     --project-file=ci-scan.burp --config-file=ci-config.json

Use a per-engagement .burpproject file. The default temporary project loses state on crash and will cost you a half-day's work the first time it happens. Configure heap at least 4 GB; Burp will silently swap to disk and stall scans if the JVM is starved.

2. Proxy setup - browser + mobile

Burp's default listener is 127.0.0.1:8080. Do not change the system proxy globally; you will forget and tunnel half of Slack through your engagement project. Use FoxyProxy in Firefox with a per-pattern rule so only the in-scope hosts are routed.

// FoxyProxy pattern config (export -> JSON)
{
  "title": "Burp - acme engagement",
  "type": "manual",
  "host": "127.0.0.1",
  "port": 8080,
  "patterns": [
    { "type": "wildcard", "pattern": "*.acme-staging.com/*", "whitelist": true },
    { "type": "wildcard", "pattern": "*.acme-api.com/*",     "whitelist": true },
    { "type": "wildcard", "pattern": "burpsuite",            "whitelist": true },
    { "type": "wildcard", "pattern": "oastify.com",          "whitelist": true }
  ]
}

Install the Burp CA. Browse to http://burpsuitewhile proxied, click "CA Certificate", import the DER into Firefox's certificate authority store (Settings -> Privacy & Security -> View Certificates -> Authorities -> Import). Trust it for websites only.

Mobile and certificate pinning. For Android 14+ the system trust store rejects user-installed CAs by default. Either root the device and push the Burp CA to /system/etc/security/cacerts, or repackage the APK with apk-mitm to inject a network_security_config.xml that trusts user certs. For pinned apps, run Frida with the universal pinning bypass:

# Android, rooted + adb
adb push burp.crt /data/local/tmp/
frida -U -f com.acme.banking -l frida-multiple-unpinning.js --no-pause

# iOS jailbroken
ssh root@iphone "cp /tmp/burp.crt /Library/Keychains/System.keychain"
frida -U -f com.acme.banking -l ios-ssl-kill-switch.js

Full mobile chain - emulator selection, MagiskTrustUserCerts, Frida server install - is in our mobile pentest methodology.

3. Target tab and sitemap discipline

The Target tab is the most under-used part of Burp. Configure Scope first, every time. Right-click the engagement root -> Add to scope -> check "Only show in-scope items". Now the Proxy history, Logger, and Scanner all auto-filter to your engagement.

Sitemap auto-populates from passive traffic. Add manual entries for endpoints you know exist but haven't crawled (from API docs, JS bundle analysis, or the customer's OpenAPI spec). Right-click a host -> Engagement tools -> Find scripts to pull every .js reference for further mining. The Issues sub-tab aggregates Scanner findings per host with severity and confidence - export it as XML or HTML at engagement close.

Use the "Search" tool (Engagement tools -> Search) to grep every captured request and response for tokens, secrets, debug strings, and internal hostnames. A common engagement workflow is to search for api_key, secret, bearer, and the customer's internal domain across all sitemap entries on the last day - it surfaces leaked credentials in JavaScript bundles that no one would otherwise notice. Tag interesting hosts and paths with comments and highlights; these export with the report and survive across project reloads. If you import a Postman or OpenAPI definition, Burp will materialise every documented endpoint into the sitemap, giving Scanner a much larger surface to chew through than crawl alone.

4. Intruder - four attack types you must know

Intruder fires a base request repeatedly with payload substitution. The four attack types pick the substitution strategy. Mastery of all four separates an Intruder user from a button-clicker.

• Sniper - one payload set, one position at a time, others held constant. Use for fuzzing a single parameter, header, or path segment.
• Battering Ram - one payload set, all positions get the same value simultaneously. Use when the same token must appear in body and header.
• Pitchfork - N payload sets, one per position, advanced in lockstep. Use for credential stuffing: usernames in set 1, passwords in set 2.
• Cluster Bomb - N payload sets, cartesian product. Use for full credential brute force or any combinatorial fuzz - tens of thousands of requests fast.

# Cluster Bomb payload sets - credential brute force
# Position 1 (username): payload set 1
admin
root
service
api

# Position 2 (password): payload set 2
P@ssw0rd!
Welcome123
ChangeMe2026
Acme@2026

# Total requests = 4 x 4 = 16
# Sort response column by Length descending to surface the successful login

Use the "Grep - Extract" option to pull a regex-captured value from each response into a column (e.g. CSRF tokens, account IDs). Use "Grep - Match" to flag responses containing a marker string. Pro removes the request throttling that Community imposes (one request every two seconds). For numeric ranges, the "Numbers" payload type generates sequential or random integers with custom step, base, and zero-padding; for credential lists, prefer pasting a SecLists wordlist into "Simple list" and resource-pool the attack to four concurrent threads so you do not melt the target's session backend. Save and reload Intruder positions inside the project file - on a long engagement you will repeat the same fuzz against fresh credentials a dozen times.

5. Repeater - manual exploitation harness

Repeater sends a single request and shows the response, with full edit on every replay. Send a request from Proxy or Sitemap with Ctrl+R. Use tabs for related requests (auth, target, logout) and rename them. Ctrl+Space autocompletes headers; right-click -> Change request method converts GET to POST including form-encoding the parameters. The history arrows at the top let you walk every prior version of the request - critical when an exploit chain takes ten attempts to land.

Repeater is also the right place to decode JWTs in flow. Install JWT Editor from the BApp Store and you get a context-menu "JWT Editor" tab in every Repeater response that contains one.

# JWT decode + tamper flow in Burp
# 1. Send request with Authorization: Bearer <jwt> to Repeater
# 2. JWT Editor tab parses header + payload
# 3. Modify "role": "user" -> "role": "admin"
# 4. Sign with key from /tools/jwt-decoder if known, or set "alg": "none"
# 5. Repeater -> Send -> compare response

# Original
{"alg":"HS256","typ":"JWT"}.{"sub":"42","role":"user","exp":1747776000}.<sig>

# Tampered (alg:none attack)
{"alg":"none","typ":"JWT"}.{"sub":"42","role":"admin","exp":1747776000}.

Quick JWT triage outside Burp lives in our JWT decoder tool.

6. Decoder, Comparer, Sequencer

Decoder chains encodings - paste a value, click Decode-as URL, then Decode-as Base64, then Decode-as Gzip, until you reach plaintext. Use Smart Decode to let Burp guess.

Comparer diffs two responses or two requests. Send a 200 and a 403 to Comparer and the byte-level diff highlights the cookie or header that flips the outcome. Faster than staring at two windows.

Sequencer measures token randomness. Capture 200+ session tokens (Live capture from a login response), let Sequencer run FIPS-140-2, Maurer, compression, and entropy tests. Anything under 64 bits of effective entropy is a weakness - report it with the test output as evidence. Sequencer also accepts a manual token load when you have already harvested values from another tool; use this for password-reset tokens and one-time-code generators where automated login capture is impractical. A homegrown PRNG that scored 31 bits of effective entropy in the FIPS test on one of our recent engagements turned into a full account-takeover finding by brute forcing the reset link in under four hours.

7. Collaborator - out-of-band detection

Collaborator is a hosted DNS+HTTP+SMTP responder that gives you unique subdomains. When a target triggers a DNS lookup or HTTP request to your subdomain, Burp shows it in the Collaborator client tab. This is how you detect blind SSRF, blind XSS, blind XXE, log4shell-style template injection, and exfiltration in commands you cannot see the output of.

# Blind SSRF detection payload
POST /api/import HTTP/2
Host: target.acme-staging.com
Content-Type: application/json

{"source_url": "http://abc123xyz.oastify.com/probe"}

# In Burp -> Burp -> Collaborator client -> Poll now
# DNS lookup recorded => target's resolver fetched the URL => SSRF confirmed
# HTTP GET recorded => target's app fetched the URL => exploitable SSRF

Pro ships a private Collaborator domain by default. Self-host with the Collaborator server JAR if customer policy forbids third-party DNS. For deep API testing patterns see our API pentest methodology.

8. Macros and session-handling rules

Modern apps log you out after fifteen minutes, rotate CSRF tokens per request, and require the value of one response to feed the next request. Burp's session-handling rules automate this. Configure once, then Scanner, Intruder, and Repeater all stay authenticated forever.

# Project options -> Sessions -> Session handling rules -> Add
# Rule actions (in order):
#   1. Check session is valid - request GET /api/me, check response contains "username"
#   2. If invalid -> Run macro "login"
#      Macro = sequence of recorded requests:
#        GET  /login           -> extract CSRF token from <input name="_csrf">
#        POST /login           -> body: user=tester&pass=...&_csrf=<from prior>
#        GET  /api/me          -> verify 200 + username present
#   3. Update request with cookie + CSRF header from macro response

# Scope: scanner, intruder, repeater - tools that benefit from auto-relogin

Combine session-handling rules with Burp's built-in CSRF token tracker (Project options -> Sessions -> Cookie jar + token tracker) and you can scan single-page apps that rotate tokens on every request.

9. BApp Store - the four extensions you need

The BApp Store ships ~250 community extensions. Install these on day one:

• Logger++ - replaces the cramped Proxy history with a sortable, filterable, exportable grid. The Bambda filter language is its killer feature.
• Autorize - authorisation testing. Provide a low-priv cookie; Autorize replays every in-scope request with that cookie and flags responses that succeed when they should not.
• JWT Editor - parse, modify, and sign JWTs with HS256, RS256, ES256, EdDSA. Includes the alg:none, key confusion, and weak-secret crack workflows.
• ActiveScan++ - adds CVE-grade checks (SSRF, host header injection, cache poisoning, request smuggling) to Burp's active scanner.

# Logger++ Bambda filter - find every authenticated 500-class response
// Bambda DSL evaluates against each row
requestResponse.response().statusCode() >= 500
  && requestResponse.request().headers().stream()
        .anyMatch(h -> h.name().equalsIgnoreCase("Authorization"))
  && !requestResponse.request().path().endsWith(".png")
  && !requestResponse.request().path().endsWith(".css");

# Bambda for IDOR hunting - integer in path differs from logged-in user ID
var path = requestResponse.request().path();
return path.matches(".*/users/\\d+.*")
       && !path.contains("/users/" + currentUserId);

10. Burp Suite Pro vs Community vs Enterprise

11. Writing a custom Montoya API extension

The Montoya API is Java-first. A minimum-viable extension is one class implementing BurpExtension. Build with Maven or Gradle, ship a single shaded JAR, load via Extensions -> Installed -> Add -> Java.

// AxVeilHeaderTagger.java
// A Montoya extension that adds an "X-AxVeil" header to every outgoing request
// and highlights any response containing "internal-only" in the proxy history.

package com.axveil.burp;

import burp.api.montoya.BurpExtension;
import burp.api.montoya.MontoyaApi;
import burp.api.montoya.core.Annotations;
import burp.api.montoya.core.HighlightColor;
import burp.api.montoya.http.handler.*;
import burp.api.montoya.proxy.http.*;

public class AxVeilHeaderTagger implements BurpExtension {
    @Override
    public void initialize(MontoyaApi api) {
        api.extension().setName("AxVeil Header Tagger");

        // 1) Tag every outgoing HTTP request
        api.http().registerHttpHandler(new HttpHandler() {
            @Override
            public RequestToBeSentAction handleHttpRequestToBeSent(HttpRequestToBeSent req) {
                return RequestToBeSentAction.continueWith(
                    req.withAddedHeader("X-AxVeil", "engagement-2026"));
            }
            @Override
            public ResponseReceivedAction handleHttpResponseReceived(HttpResponseReceived resp) {
                return ResponseReceivedAction.continueWith(resp);
            }
        });

        // 2) Highlight proxy rows mentioning "internal-only"
        api.proxy().registerResponseHandler(new ProxyResponseHandler() {
            @Override
            public ProxyResponseReceivedAction handleResponseReceived(InterceptedResponse r) {
                if (r.bodyToString().toLowerCase().contains("internal-only")) {
                    return ProxyResponseReceivedAction.continueWith(
                        r, Annotations.annotations("internal-only leak", HighlightColor.RED));
                }
                return ProxyResponseReceivedAction.continueWith(r);
            }
            @Override
            public ProxyResponseToBeSentAction handleResponseToBeSent(InterceptedResponse r) {
                return ProxyResponseToBeSentAction.continueWith(r);
            }
        });

        api.logging().logToOutput("AxVeil Header Tagger loaded");
    }
}

Build with mvn package -DskipTests, drop the resulting JAR in Burp Extensions tab. Python via Jython is still supported for Community users without a JDK toolchain, but Jython's last release targeted Python 2.7 and PortSwigger has signalled deprecation; do not start new extensions on Jython in 2026.

12. Burp Suite Enterprise in CI/CD

Enterprise runs as a server with a web UI, a REST API, and worker nodes that execute scans. The common pattern is a nightly authenticated scan of staging, with findings pushed to Jira and a PR-comment integration for changed endpoints.

# .github/workflows/burp-scan.yml
name: Burp Enterprise Scheduled Scan
on:
  schedule: [{cron: '0 2 * * *'}]
  workflow_dispatch:

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Burp Enterprise scan
        env:
          BURP_API_KEY: ${{ secrets.BURP_API_KEY }}
          BURP_SERVER: https://burp.acme.internal/api/v0.1
        run: |
          curl -sS -X POST "$BURP_SERVER/scan" \
            -H "Authorization: $BURP_API_KEY" \
            -H "Content-Type: application/json" \
            -d '{
              "scan_configurations":[{"name":"Crawl and audit - balanced"}],
              "urls":["https://staging.acme.com/"],
              "application_logins":[{"label":"qa-user",
                "credential":{"username":"qa@acme","password":"${{ secrets.QA_PASS }}"}}]
            }' | tee scan.json
      - name: Poll until complete
        run: |
          ID=$(jq -r .id scan.json)
          until [ "$(curl -sS -H "Authorization: $BURP_API_KEY" \
                   "$BURP_SERVER/scan/$ID" | jq -r .status)" = "succeeded" ]; do
            sleep 30
          done

13. Common pitfalls

• Forgetting scope - Scanner crawls Google Analytics, CDNs, and ad networks. Always set scope before enabling passive scan.
• Default heap - 2 GB on a large engagement leads to GC stalls and lost requests. Bump -Xmx to 4-8 GB.
• Mixing engagements in one project - cookies cross, scope gets noisy, exports leak data. One .burp file per engagement, period.
• Trusting Scanner without manual triage - false-positive rate on reflected XSS in SPA frameworks is ~30%. Validate every issue in Repeater before reporting.
• Pinning bypass in production - Frida pinning bypass works in staging; in production with attestation (Play Integrity API, DeviceCheck) it fails silently. Coordinate with the customer for attestation bypass.
• Skipping Collaborator - if Scanner found nothing and you tested no OAST payloads, you tested less than half of the modern attack surface.

Related reading

Move on to specialised methodologies: API pentest methodology, mobile pentest methodology, our hands-on JWT decoder, and the VAPT glossary entry if a teammate is new to the terminology. When you are ready to engage a partner, our VAPT service runs the toolchain in this tutorial against your production every quarter.