burp-headless

Overview

Per portswigger.net/burp/documentation/desktop/automated-scanning (opens in new window), Burp Scanner "is a web vulnerability scanning tool built into Burp Suite Professional" that maps the attack surface and identifies vulnerabilities in web applications and APIs.

How you run it headless depends on your license edition - see Step 1.

When to use

• The team has a Burp Suite Professional or Enterprise license.
• ZAP coverage isn't sufficient for a specific use case (e.g., Burp's BApp Store has a tool ZAP doesn't).
• A penetration-testing team uses Burp interactively and wants CI-runnable scans for the same target.
• Enterprise edition's scheduled scan + dashboard model fits the team's scale.

For most teams, zap-baseline + nightvision-dast cover the same surface without Burp's licensing friction.

How to use

1. Confirm the license edition - Pro (per-user desktop) or Enterprise (CI-enabled) - before authoring workflows (Step 1).
2. Install and activate: Pro via license file, Enterprise on a dedicated server + database (Step 1).
3. Drive scans: Pro via the local REST API (Step 2), Enterprise via its server REST API from CI (Step 3).
4. Load any needed BApp Store extensions and configure session-handling rules plus a login macro for authenticated targets (Steps 4-5).
5. Run against staging, then triage findings and record every false-positive suppression with a justification (Step 6).
6. Export issues (HTML / XML / CSV / JSON, or SARIF via BurpToSarif) and aggregate with ZAP + NightVision output (Step 7).
7. Gate the CI job per severity threshold (Step 3, references/enterprise-ci.md).

Step 1 - License + install

Licensing (canonical, referenced elsewhere): Burp Pro is per-user desktop tooling whose headless / unattended use is constrained; Enterprise is "enterprise-enabled" and the intended fit for CI-driven scanning per burp-as (opens in new window). Verify your edition's headless / CI terms before authoring workflows.

Burp Pro: download Burp Suite Pro from portswigger.net/burp/pro; each user activates via license file. Headless invocation requires the Pro license to be valid (license-server activation for multi-user setups).

Burp Enterprise: server-side install per portswigger.net/burp/documentation/enterprise. Requires dedicated infrastructure + DB (MySQL/PostgreSQL).

Step 2 - Pro: REST API for scan control

Burp Pro exposes a REST API (when enabled in User Settings → REST API). Pattern:

# Start a scan via Pro REST API
curl -X POST "http://127.0.0.1:1337/v0.1/scan" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": { "include": [{"rule": "https://app.example.com/.*"}] },
    "scan_configurations": [{"name": "Crawl strategy - fastest", "type": "NamedConfiguration"}],
    "urls": ["https://app.example.com/"]
  }'

Returns a task ID. Poll for completion + retrieve issues:

curl http://127.0.0.1:1337/v0.1/scan/<task_id>

The REST API surface is documented in Burp's User Settings → REST API → API Documentation tab.

Step 3 - Enterprise: CI integration

Burp Enterprise stores scan configurations and targets server-side and is the intended fit for CI-driven scanning: a CI script triggers a scan via the Enterprise REST API, polls for completion, downloads issues as JSON, then gates per severity. See references/enterprise-ci.md for the full workflow and a GitHub Actions example.

Step 4 - BApp Store extensions

Per burp-as (opens in new window) the "BApp Store" model - extensions distributed via the in-Burp store. Common useful extensions:

• BCheck - custom-rule DSL for Burp; community + paid rules
• Active Scan++ - additional active scan checks
• HTTP Request Smuggler - specialized smuggling tests
• JWT Editor - JWT manipulation for auth testing
• Param Miner - parameter discovery

For headless / CI use, extensions can be loaded via Burp's extension config (Burp → Extender → Extensions → Add → load .jar / .py / BApp). Enterprise edition manages extension allowlists centrally.

Step 5 - Authentication via session-handling rules

Burp's session handling is rule-based (User Options → Sessions → Session Handling Rules). Each rule defines:

• Scope (which URLs trigger this rule)
• Actions (run a macro to re-login, set headers, etc.)
• Conditions (run only if logged-out indicator detected)

Macros record a multi-step login flow (visit → fill form → submit → assert success). Burp re-runs the macro mid-scan when sessions expire.

For CI/headless use, embed the configured session handling rules in the project file - Burp re-loads them on --project-file=....

Step 6 - False-positive triage (MANDATORY)

Burp's three suppression mechanisms:

Justification template (mandatory in BCheck or Enterprise notes):

# BCheck: suppress SQL injection finding on /search?q=
# Reason: parameter pre-validated via Joi schema (line 42)
# Reviewer: alice@example.com (2026-05-15)
# Expires: 2026-12-15
# Re-review-date: 2026-12-15

given response.body matches "alice|bob|charlie"
then
    suppress

Cadence: Enterprise dashboard's "Resolved as False Positive" filter periodically; review for staleness. Pro requires manual notes audit.

Step 7 - Output formats

Burp Pro export: Issue → Right-click → Report selected issues → HTML / XML / CSV / Burp's own JSON.

Burp Enterprise REST API returns issues as JSON natively; aggregate it with ZAP + NightVision output for a combined verdict.

For SARIF (GitHub Code Scanning): use the BurpToSarif community converter (BApp Store).

Worked example

A team holds a Burp Suite Enterprise license and wants CI-gated coverage of app.example.com staging, layered on their existing ZAP baseline.

1. In the Enterprise dashboard they register the site (site_id: 42) and a scan configuration (scan_configuration_id: 7) that skips SSL/TLS issue types (staging is HTTP-only).
2. A session-handling rule with a login macro re-authenticates when the scanner hits the logged-out banner, keeping authenticated routes in scope (Step 5).
3. The GitHub Actions job (references/enterprise-ci.md) triggers the scan, polls until status: succeeded, and downloads burp-issues.json.
4. A suppression BCheck marks the known /search?q= finding as a false positive with reviewer + expiry, committed to the repo (Step 6).
5. The job parses burp-issues.json, fails on any High severity, and uploads the SARIF conversion to GitHub Code Scanning (Step 7).

Result: every merge to the staging branch runs a licensed Burp scan whose findings sit alongside ZAP and NightVision output in one severity-gated verdict.

Anti-patterns

Limitations

• Headless / CI licensing differs by edition (see Step 1).
• Burp Enterprise requires dedicated server infrastructure + database; non-trivial ops cost.
• BApp Store extensions vary in quality; some are abandoned.
• REST API surface is stable but version-specific; consult in-tool API docs.

References

• burp-as (opens in new window) - automated scanning overview
• portswigger.net/burp/documentation - Pro + Enterprise docs
• portswigger.net/burp/documentation/enterprise - Enterprise CI
• portswigger.net/bappstore - BApp Store
• zap-baseline, nightvision-dast - sister DAST tools (use ZAP first; Burp adds layered paid coverage)
• dast-scan-cadence-author - build-an-X for layered DAST