Burp Suite Enterprise Integration Guide

Overview

The Burp Suite Enterprise integration (integration service: burp-suite) allows your NINA workflows to manage DAST (Dynamic Application Security Testing) scans, sites, vulnerabilities, and reports in Burp Suite Enterprise Edition. This integration communicates with Burp Suite's GraphQL API to automate security scanning workflows, retrieve vulnerability findings, and generate compliance reports.

Important: This integration targets Burp Suite Enterprise Edition only. Burp Suite Professional uses a local-only REST API (127.0.0.1:1337) that is not suitable for remote automation.

Status

The integration currently supports:

• Site Management: Create, list, retrieve, and delete sites in the site tree
• Scan Management: Schedule scans, list/retrieve scan details, cancel running scans
• Vulnerability Issues: List and retrieve vulnerability findings with full evidence details
• Report Generation: Generate HTML or XML scan reports with severity filtering
• Scan Configurations: List available scan configurations

Credential Configuration

Authentication Method

Burp Suite Enterprise uses API Key authentication:

Field	Description	Required	Example
Server URL	URL of your Burp Suite Enterprise instance	Yes	https://burp-enterprise.example.com
API Key	API key generated from Burp Suite Enterprise settings	Yes	—

Requirements:

• The server URL must use HTTPS — HTTP connections are rejected for security reasons
• The API key must have sufficient permissions for the operations you intend to use

Generating an API Key

1. Log in to your Burp Suite Enterprise web interface
2. Navigate to Settings > API Keys (or User Settings > API Keys depending on your version)
3. Click Create API Key
4. Assign appropriate permissions — for full integration functionality, the key needs:
   • Site read/write permissions (for site management)
   • Scan read/write permissions (for scan scheduling and management)
   • Issue read permissions (for vulnerability retrieval)
   • Report generation permissions
5. Copy the generated API key — it will not be shown again

Creating a Burp Suite Credential in NINA

1. Navigate to the Credentials section in NINA
2. Click Add New Credential
3. Fill in the credential details:
   • Name: A descriptive name (e.g., "Burp Suite Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "Burp Suite Enterprise"
   • Server URL: Your Burp Suite Enterprise URL (e.g., https://burp-enterprise.example.com)
   • API Key: Your generated API key
4. Click Create to save and validate the credential
5. Validation connects to your instance and verifies the API key works

Supported Resources and Operations

Site

Operation	Description
List	List all sites in the site tree
Get	Retrieve details of a specific site
Create	Create a new site with scan scope configuration
Delete	Delete a site from Burp Suite Enterprise

Scan

Operation	Description
List	List scans with optional filtering by site, status, and date range
Get	Retrieve details of a specific scan including issue counts
Schedule	Schedule a new scan for one or more sites or folders
Cancel	Cancel a running or queued scan

Issue

Operation	Description
List	List vulnerability issues found in a specific scan
Get	Retrieve a specific issue with full evidence details (requests, responses, HTTP interactions)

Report

Operation	Description
Get	Generate a scan report in HTML or XML format

Scan Configuration

Operation	Description
List	List all available scan configurations

Example: Creating a Site

{
  "resource": "site",
  "operation": "create",
  "parameters": {
    "name": "Production Web App",
    "parentId": "0",
    "startUrls": ["https://app.example.com/"],
    "inScopeUrlPrefixes": ["https://app.example.com/api/"],
    "outOfScopeUrlPrefixes": ["https://app.example.com/logout"],
    "protocolOptions": "USE_SPECIFIED_PROTOCOLS"
  }
}

Create Site Parameters

Parameter	Type	Required	Default	Description
name	string	Yes	—	Name of the site
parentId	string	No	0	Parent folder ID (0 for root)
startUrls	array	Yes	—	Starting URLs for scan scope
inScopeUrlPrefixes	array	No	—	URL prefixes to include in scope
outOfScopeUrlPrefixes	array	No	—	URL prefixes to exclude from scope
protocolOptions	string	No	USE_SPECIFIED_PROTOCOLS	USE_SPECIFIED_PROTOCOLS or USE_HTTP_AND_HTTPS

Example: Scheduling a Scan

Note: The schedule operation creates a scheduled scan via Burp Suite's scheduler. The scan may not start immediately — it enters the queue and begins when resources are available.

{
  "resource": "scan",
  "operation": "schedule",
  "parameters": {
    "siteIds": ["{{site_id}}"],
    "scanConfigurationIds": ["{{config_id}}"]
  }
}

Schedule Scan Parameters

Parameter	Type	Required	Description
siteIds	array	No*	IDs of sites to scan
folderIds	array	No*	IDs of folders to scan (all sites in the folder)
scanConfigurationIds	array	No	IDs of scan configurations to use

*At least one of siteIds or folderIds must be provided.

Example: Listing Scans with Filters

{
  "resource": "scan",
  "operation": "list",
  "parameters": {
    "siteId": "42",
    "scanStatus": ["succeeded", "failed"],
    "sortColumn": "end",
    "sortOrder": "desc",
    "limit": 20,
    "offset": 0
  }
}

List Scans Parameters

Parameter	Type	Required	Default	Description
siteId	string	No	—	Filter by site ID
scanStatus	array	No	—	Filter by status: queued, running, succeeded, cancelled, failed, paused
sortColumn	string	No	—	Sort by: start, end, status, site_name
sortOrder	string	No	—	asc or desc
limit	number	No	10	Max results to return
offset	number	No	0	Pagination offset
scanEndTimeFrom	string	No	—	Filter scans ending after this timestamp (ISO 8601)
scanEndTimeTo	string	No	—	Filter scans ending before this timestamp (ISO 8601)

Example: Retrieving Vulnerability Issues

Listing Issues from a Scan

{
  "resource": "issue",
  "operation": "list",
  "parameters": {
    "scanId": "{{scan_id}}",
    "severities": ["high", "medium"],
    "confidences": ["certain", "firm"],
    "novelties": ["new"],
    "count": 100
  }
}

List Issues Parameters

Parameter	Type	Required	Default	Description
scanId	string	Yes	—	Scan ID to list issues for
start	number	No	0	Pagination start index
count	number	No	50	Number of issues to return
severities	array	No	—	Filter: high, medium, low, info
confidences	array	No	—	Filter: certain, firm, tentative
novelties	array	No	—	Filter: new, existing
acceptedRisks	array	No	—	Filter: true, false
typeIndex	string	No	—	Filter by issue type index

Getting Full Issue Evidence

{
  "resource": "issue",
  "operation": "get",
  "parameters": {
    "scanId": "{{scan_id}}",
    "serialNumber": "{{issue_serial_number}}"
  }
}

The response includes full evidence details: HTTP requests, responses, interactions, and descriptive evidence depending on the vulnerability type.

Example: Generating a Report

HTML Report with Severity Filter

{
  "resource": "report",
  "operation": "get",
  "parameters": {
    "scanId": "{{scan_id}}",
    "reportType": "detailed",
    "format": "html",
    "severities": ["high", "medium"],
    "includeFalsePositives": false
  }
}

XML Report (Burp Format)

{
  "resource": "report",
  "operation": "get",
  "parameters": {
    "scanId": "{{scan_id}}",
    "format": "xml",
    "base64EncodeRequestsAndResponses": true
  }
}

Report Parameters

Parameter	Type	Required	Default	Description
scanId	string	Yes	—	Scan ID to generate report for
reportType	string	No	detailed	summary or detailed
format	string	No	html	html or xml (Burp format)
severities	array	No	All	Filter: high, medium, low, info
includeFalsePositives	boolean	No	false	Include false positives in report
timezoneOffset	number	No	—	Timezone offset in minutes for timestamps
base64EncodeRequestsAndResponses	boolean	No	false	Base64 encode requests/responses in XML reports

Example: Full DAST Workflow

A typical automated DAST workflow in NINA:

Step 1: List available scan configurations

{
  "resource": "scanConfiguration",
  "operation": "list"
}

Step 2: Schedule a scan

{
  "resource": "scan",
  "operation": "schedule",
  "parameters": {
    "siteIds": ["{{target_site_id}}"],
    "scanConfigurationIds": ["{{selected_config_id}}"]
  }
}

Step 3: Check scan status (in a subsequent workflow execution or polling node)

{
  "resource": "scan",
  "operation": "get",
  "parameters": {
    "scanId": "{{scheduled_scan_id}}"
  }
}

Step 4: Retrieve high-severity findings

{
  "resource": "issue",
  "operation": "list",
  "parameters": {
    "scanId": "{{completed_scan_id}}",
    "severities": ["high"],
    "novelties": ["new"]
  }
}

Step 5: Generate a report for stakeholders

{
  "resource": "report",
  "operation": "get",
  "parameters": {
    "scanId": "{{completed_scan_id}}",
    "reportType": "detailed",
    "format": "html",
    "severities": ["high", "medium"]
  }
}

Step 6: Send report via SMTP or Slack to the security team

Use the SMTP or Slack integration nodes downstream to distribute findings.

Troubleshooting

Common Issues

Issue	Resolution
Connection refused	Verify the Server URL is correct and your network can reach the Burp Suite Enterprise instance.
Authentication failed (401/403)	Double-check the API key. Keys may have been revoked or may lack required permissions.
HTTPS required error	The integration enforces HTTPS. Ensure your Server URL uses https://, not http://.
Scan not starting	The schedule operation queues a scan — it doesn't start immediately. Check the Burp Suite Enterprise UI for queue status.
Empty issue list	The scan may still be running, or no vulnerabilities were found. Check scan status first.
Permission denied on specific operation	Your API key may not have the required role. Check API key permissions in Burp Suite Enterprise settings.
Report generation timeout	Large scans with many issues can take time to generate reports. Consider filtering by severity to reduce report size.

Best Practices

1. Use Least-Privilege API Keys: Create API keys with only the permissions needed for your workflow. Avoid using admin keys for automated scanning.

2. Scope Sites Carefully: Use inScopeUrlPrefixes and outOfScopeUrlPrefixes when creating sites to avoid scanning unintended targets (e.g., logout endpoints, third-party services).

3. Filter Issues by Severity: When listing issues, filter by severity and confidence to focus on actionable findings and reduce noise.

4. Monitor Scan Status: Scans can take hours for large applications. Build workflows that check scan status before attempting to retrieve results.

5. Use New Issue Filtering: Filter issues by novelties: ["new"] to focus on newly discovered vulnerabilities rather than previously known ones.

6. Generate Reports for Compliance: Use the detailed HTML report format for stakeholder communication and the XML format for tool integration.

7. Leverage Dynamic Fields: When configuring nodes in the NINA canvas, use the site dropdown selector instead of manually entering site IDs.

8. Rotate API Keys: Periodically rotate API keys and update credentials in NINA, especially for production scanning workflows.

Updated: 2026-04-16