Burp Suite Enterprise CI-Driven Scan

This extension provides a task that enables you to integrate vulnerability scans into your Azure pipeline. A CI-driven scan runs Burp Scanner from a Docker container on an Azure agent node. On completion, it generates a JUnit XML report about the vulnerabilities found. This report includes:

• The locations of the vulnerabilities
• Additional information about each vulnerability
• Links to our learning resources, with remediation advice

About CI-driven scans

• Easily integrate Burp Suite Enterprise Edition with your CI/CD pipeline
• Run Burp Scanner directly from your CI/CD platform
• Supports login details and recorded login sequences

For full documentation about CI-driven scans with no dashboard, please see Integrating CI-driven scans with no dashboard. For full documentation about CI-driven scans with a dashboard, please see Integrating CI-driven scans.

Prerequisites

To use this extension, you need a license to use Burp Suite Enterprise Edition. You will need an API key to run the scan. If you host your own Burp Suite Enterprise Edition server, see Creating API Users. If you wish to use no-dashboard CI-driven scans, see Getting started with CI-driven scans with no dashboard.

Inputs

Inputs can be used to provide values to the container. If you use a configuration file, the values in that file have priority over the input values.

enterpriseServerUrl

(Required) The URL supplied with your PortSwigger account.

enterpriseApiKey

(Required) The API key supplied with your PortSwigger account.

scanTargetUrl

(Required) The URL of the website you want Burp Scanner to scan.

The above values must be specified either as inputs or in a configuration file.

outputFilePath

(Optional) The output path for the scan report. This is relative to the working directory of the pipeline agent.

The default value is burp_junit_report.xml.

config-file-path

(Optional) The path to the configuration file. This path must be an absolute path.

The default value is burp_config.yml in the agent's working directory.

Examples

Below are some examples of how to use the action to run a scan against our very own Gin and Juice Shop site. This is a deliberately vulnerable web application designed for testing web vulnerability scanners.

Basic Usage

Make sure you include the URL, and API key for your license, and at least one Start URL. Due to their sensitive nature, we recommend setting the API key and server URL as pipeline secret variables. Then pass them as environment variables directly in the azure-pipelines.yml file. For more information about secret pipeline variables, see Set secret variables.

- task: enterprise-scan-in-azure@<latest-major-version-number>
  inputs:
    scanTargetUrl: "https://ginandjuice.shop"
    enterpriseApiKey: $(YOUR_API_KEY_SECRET)
    enterpriseServerUrl: $(YOUR_SERVER_URL_SECRET)
  displayName: Run Enterprise Scan 

By default, if the scanner finds any issue with a severity level of LOW or above, it fails the workflow build (the scan container exits with a non-zero exit code).

To edit your scan configuration, see Using a configuration file.

Test Reporting

The scan produces a JUnit XML report when the scan completes. This report only includes vulnerability details if vulnerabilities are found by Burp Scanner. By default, the report is saved as burp_junit_report.xml in the agent's working directory. If you want to view the results of the scan in the built-in pipeline tests view, you can use Azure's task to publish the scan report as test results. To learn more about this task, see Publish Test Results v2. For how to implement this with a Burp Suite Enterprise Edition scan, see the example below.

- task: enterprise-scan-in-azure@<latest-major-version-number>
  inputs:
    scanTargetUrl: "https://ginandjuice.shop"
    enterpriseApiKey: $(YOUR_API_KEY_SECRET)
    enterpriseServerUrl: $(YOUR_SERVER_URL_SECRET)
- task: PublishTestResults@2
  condition: always()
  inputs: 
    testResultsFormat: 'JUnit'
    testResultsFiles: 'burp_junit_report.xml'

Using a configuration file

You can use a configuration file to set more advanced options. Create a configuration file and save it as burp_config.yml in the root of your repository. To learn more, see Creating a configuration file.

You can edit your configuration file to change the threshold for exiting with a non-zero exit code.

Using With Artifacts

To view the report file after the pipeline runs, save it as a pipeline artifact. For more information on pipeline Artifacts, see Publish and Download pipeline Artifacts. For how to implement this with a Burp Suite Enterprise Edition scan, see the example below.

- task: enterprise-scan-in-azure@<latest-major-version-number>
  inputs:
    scanTargetUrl: "https://ginandjuice.shop"
    enterpriseApiKey: $(YOUR_API_KEY_SECRET)
    enterpriseServerUrl: $(YOUR_SERVER_URL_SECRET)
- publish: $(System.DefaultWorkingDirectory)/burp_junit_report.xml
  artifact: EnterpriseReport
  condition: always()
- download: current
  artifact: EnterpriseReport
  condition: always()

To view pipeline Artifacts, navigate to the Summary page of your pipeline run. In this example we have used task conditions to make sure the artifact is published and downloaded even if the scan fails. To learn more about conditions, see Task types and usage.

Support

If you'd like help with this extension, or you have an issue or feature request, let us know. You can use our user forum. The extension is maintained by PortSwigger.

If you're reporting an issue, please include:

• the version of the extension
• relevant logs and error messages
• steps to reproduce

License

Copyright PortSwigger 2023. MIT licensed.