Enterprise Edition

Running a basic CI-driven scan

  • Last updated: January 29, 2024

  • Read time: 3 Minutes

You can integrate CI-driven scans with any CI/CD platform that supports containers. This enables you to use Burp Scanner to run web vulnerability scans as a stage in your existing CI/CD pipeline.

Use this guide to quickly integrate a CI-driven scan with your chosen CI/CD platform. These instructions enable you to run a scan with the default scan configuration against a single URL, using a shell script.

Before you start

Before you start, you need to perform the following steps:

System requirements

Make sure you meet the system requirements, in order to run scans successfully:

  • We recommend that you run a CI-driven scan on a machine that has a minimum of 4 CPU cores and 8 GB of RAM. We also recommend that you have 30 GB of free disk space. While this should be suitable for most use cases, larger or more complex target applications may require more resources.
  • Your CI/CD build agent or node must be configured to run Docker containers.
  • The container must be able to access your Enterprise server.
  • The CI/CD build agent or node where the container is running must be able to access PortSwigger's public image repository public.ecr.aws/portswigger/ as well as the target application you want to scan.

Running a scan

To run a CI-driven scan, include the following docker run command in your pipeline script:

docker run --rm --pull=always \ -u $(id -u) -v $(pwd):$(pwd) -w $(pwd) \ -e BURP_ENTERPRISE_SERVER_URL=https://ent-server.com \ -e BURP_ENTERPRISE_API_KEY=XXXXxxxxXXXXxxxx \ -e BURP_START_URL=https://ginandjuice.shop \ -e BURP_CORRELATION_ID=my_vulnerable_website \ public.ecr.aws/portswigger/enterprise-scan-container:latest

You need to input the correct values for the environment variables in the command:

  • BURP_ENTERPRISE_SERVER_URL: This is the URL of your Enterprise server.
  • BURP_ENTERPRISE_API_KEY: This is the API key that you copied when you created an API user.
  • BURP_START_URL: This is the URL of the website you want Burp Scanner to scan.
  • BURP_CORRELATION_ID: This is optional. You only need to input a correlation ID if you want to view the scan results on the Burp Suite Enterprise Edition web interface. Burp Suite Enterprise Edition saves the results in a new site with the same name as the correlation ID. You can use a text string up to 64 characters long.

Setting the public key certificate

If your Enterprise server uses a self-signed TLS certificate, you need to include this environment variable in your docker run command:

  1. Run the following command:

    export BURP_ENTERPRISE_SERVER_TLS_CERTIFICATE=`cat self-signed-cert.pem`
  2. Add the following environment variable to the docker run command:

    -e BURP_ENTERPRISE_SERVER_TLS_CERTIFICATE=XXXXxxxxXXXX

Alternatively, you can include your TLS certificate with the configuration file. For more information, see Creating a configuration file for a CI-driven scan.

Scan results

The results from Burp Scanner are available as a JUnit or Burp XML file when a scan is complete. The file is saved in the working directory of the container for your CI-driven scan.

Remediation advice

The results from Burp Scanner include remediation advice for any security issues they find. This advice includes links to relevant sections of the free Web Security Academy resource, which provide further detail on web security vulnerabilities.

Evidence

The results from Burp Scanner include evidence for any security issues found. This evidence includes the request sent by Burp Scanner to produce the issue, as well as the response sent by the application.

Configuring CI-driven scans

To use more advanced features, such as custom scan configurations or application logins with CI-driven scans, you need to create a configuration file.

CI-driven scan configuration files work with any CI platform that supports containers.

Was this article helpful?