Burp Suite Professional

Introduction

To report Audit Issues found by Burp Suite Professional to Orangebeard, we provide a Burp extension. The source code and download can be found on GitHub: Burp Extension.

Installation

To install the extension in Burp Suite, download the jar-with-dependencies asset for the latest release (See GitHub link above) and register it with Burp Suite Professional.

Burp UI

To install an extension in the Burp Suite UI, navigate to the Extensions tab and press 'Add'.

• Choose Extension type: Java
• Point to the downloaded Jar file
• Choose how to handle Output and Error

Clicking 'Next' will load the extension. If all went well, no output or errors will be displayed and the event log will show that the extension has been loaded.
The extension auto-registers and will start a run in Orangebeard if no UUID is provided. When the extension is unloaded (i.e. Burp Suite is closed), the extension will report the run finished.

User Settings File

Extensions can also be configured through the user settings file. This is particularly useful when running crawl & audit tasks from the commandline.
To register the extension in the settings file, open the file and find (or add) the extender object in user options. The extension can be configured as below:

{
    "user_options":{
        "extender":{
            "extensions":[
                {
                    "errors":"ui",
                    "extension_file":"burp-extension-1.1-jar-with-dependencies.jar",
                    "extension_type":"java",
                    "loaded":true,
                    "name":"Orangebeard reporter",
                    "output":"ui"
                }
            ]
        }
    }
}

Note that in this example, the extension jar file is expected to be in the same directory as burpsuite_pro.jar.

Configuration

The extension will only report AuditIssues to Orangebeard if:

• The orangebeard system property is set and has the value true. (set from commandline: java -Dorangebeard=true -jar burpsuite_pro.jar)
• A valid Orangebeard configuration is present.

Json Configuration

Just like test runs, security alert runs can be configured using a json configuration file:

{
	"endpoint": "https://my-instance.orangebeard.app",
	"token": "listener-access-token",
	"project": "my project",
	"testset": "Gin and Juice Shop demo",
	"description": "A run from Burp Suite Pro",
	"attributes": [
		{
			"key": "Key",
			"value": "Value"
		},
		{
			"value": "Tag value"
		}
	]
}

System Properties / Environment

The json Configuration can be combined with system properties or environment variables. This is useful when setting certain properties at runtime, or when getting information like the access token from secrets.

Running Headless

To run Burp Suite headless, with Orangebeard reporting enabled, the following example can be used for inspiration:

#!/bin/bash

# Start the run in Orangebeard, using the Orangebeard CLI
# This ensures the run can be cleanly finished by the script after killing Burp Suite
alertRunUuid=$(java -cp burp-extension-1.1-jar-with-dependencies.jar \
               io.orangebeard.client.Cli -x start -k security -at BURPSUITE)

# Start Burp Suite in the background
java -Dorangebeard=true \
     -Dorangebeard.testRunUUID="$alertRunUuid" \
     -Djava.awt.headless=true \
     -Xmx4g -jar burpsuite_pro.jar \
     --project-file=my-project.burp \
     --user-config-file=burp-user-settings.json \
     --unpause-spider-and-scanner &
BURP_PID=$!

# Wait for Burp Suite to initialize...
sleep 25

# Read scan config from file
SCAN_CONFIG=$(cat scan-config.json | jq -c .)

# Start the scan using Burp's API and get the location header's value (Task ID)
HEADERS=$(mktemp)
curl -s -o /dev/null -w "\n" -X POST 'http://127.0.0.1:1337/v0.1/scan' \
    -H "Content-Type: application/json" -d "$SCAN_CONFIG" -D "$HEADERS"
TASK_ID=$(grep -i "^Location:" "$HEADERS" | cut -d' ' -f2 | tr -d '\r\n')
rm -f "$HEADERS"

# Poll for scan status every minute
STATUS=""
ALERT_RUN_STATUS="COMPLETED"
while true; do
  STATUS=$(curl -s "http://127.0.0.1:1337/v0.1/scan/$TASK_ID" | jq -r '.scan_status')
  if [[ "$STATUS" == "succeeded" ]]; then
    break
  elif [[ "$STATUS" == "failed" ]]; then
    ALERT_RUN_STATUS="INTERRUPTED"
    break
  fi
  sleep 60
done

# Finish alert run in Orangebeard. 
# (When stopping Burp using kill, the extensions are not gracefully unloaded)
java -cp burp-extension-1.1-jar-with-dependencies.jar io.orangebeard.client.Cli \
     -x finish -id "$alertRunUuid" -k security -as "$ALERT_RUN_STATUS"

# Kill the Burp process
kill $BURP_PID

Now when burp starts, the audit issues are reported to Orangebeard.