Skip to content

Burp Suite Executor

Category: Web Application Scanners Script: burp.py Integration: REST API Faraday Plugin: BurpPlugin Website: https://portswigger.net/burp

Description

Connects to a running Burp Suite Professional instance via its REST API, initiates a scan against one or more target URLs, polls for completion, retrieves the discovered issues, generates an XML report, and parses it into Faraday.

Prerequisites

  • Burp Suite Professional with the REST API enabled
  • REST API key generated (Burp > Settings > Suite > REST API)
  • Burp running as a service/daemon accessible from the dispatcher host

Configuration

Environment Variables (Setup)

Variable Required Description
BURP_HOST Yes Burp REST API endpoint (e.g., http://burp.local:1337)
BURP_API_KEY Yes REST API authentication key
BURP_API_PULL_INTERVAL No Polling interval in seconds (default: 30)

Execution Arguments

Parameter Type Mandatory Description
TARGET_URL list Yes JSON array of target URLs (e.g., ["https://example.com"])
NAMED_CONFIGURATION string No Burp named configuration (default: "Crawl strategy - fastest")

Common Agent Parameters Supported

AGENT_CONFIG_IGNORE_INFO, AGENT_CONFIG_RESOLVE_HOSTNAME, AGENT_CONFIG_VULN_TAG, AGENT_CONFIG_SERVICE_TAG, AGENT_CONFIG_HOSTNAME_TAG

YAML Configuration Example

executors:
  burp_scan:
    repo_executor: burp.py
    max_size: 65536
    varenvs:
      BURP_HOST: "http://burp.local:1337"
      BURP_API_KEY: "${BURP_API_KEY}"
      BURP_API_PULL_INTERVAL: "30"
    params:
      TARGET_URL:
        mandatory: true
        type: list
        base: list
      NAMED_CONFIGURATION:
        mandatory: false
        type: string
        base: string

How It Works

  1. Connects to the Burp REST API at the configured host
  2. Submits a scan request to /v0.1/scan with the target URLs and named configuration
  3. Polls /v0.1/scan/{task_id} at the configured interval until status is succeeded or failed
  4. Retrieves issue details and issue type definitions from the scan results
  5. Constructs an XML report matching Burp's native format
  6. Parses the XML through BurpPlugin and outputs Faraday JSON

Notes

  • Multiple URLs can be scanned in a single execution by providing a JSON array
  • The default crawl strategy ("Crawl strategy - fastest") prioritizes speed; use "Crawl strategy - most complete" for thorough scans
  • The BURP_API_PULL_INTERVAL controls how frequently the executor checks scan status; lower values increase responsiveness but also API load