Creating a configuration file for a CI-driven scan
Last updated: January 29, 2024
Read time: 5 Minutes
We provide a template configuration file. The file includes comments to help you to understand and edit each of the parameters. After you edit the configuration file, you can rename it to
burp_config.yml, to match the integration examples we give in this section.
You can get the template YAML file here (opens in a new tab):
The mandatory settings determine the URLs that you want to scan, and the name and location of the report file. If you only define the mandatory settings, the Burp Scanner uses the default scan configuration. To configure the mandatory settings, enter the following mandatory values:
Your start URLs (
site.startUrls). These are the URLs where Burp Scanner starts scanning from.
The Enterprise server URL and API key (
enterpriseServer.apiKey). See Creating API users.
If you need to use a proxy to connect to your Enterprise server, add the URL and authentication credentials into the following fields. The authentication credentials are optional:
Defining the scope
Burp Scanner only visits URLs that are in scope. Use the YAML file to set the scope of your scan, to make sure Burp Scanner only visits URLs that you have permission to scan. You can also use the scope to focus on particular paths that you're interested in.
To define the scope, enter URLs as values in the
The start URLs are automatically added to the
Public key certificate
If your Burp Suite Enterprise Edition server is configured with a self-signed or private CA TLS certificate, you can add this to the
enterpriseServer.tlsCertificate parameter. This verifies the certificate received from your server, to make sure your scan results are transmitted over a secure connection.
Alternatively, you can add the TLS certificate as an environment variable in your
docker run command. For more information, see Getting started with CI-driven scans.
You can use Authenticated scanning to scan content that is behind authentication. We support two methods of authentication:
- Login credentials (usernames and passwords)
- Recorded logins, for more complex authentication processes
To define login credentials, enter a list of
password pairs in the
You can use our Chrome plugin to record login sequences. For more information, see Recording login sequences:
- Follow the instructions in the link above to install our Chrome plugin, and save the recorded login sequence to the clipboard.
- Save the contents of the clipboard as a JSON file in the same directory as the configuration file.
logins.recordedLoginsparameter, enter the path for the JSON file.
You can select from built-in scan configurations, or you can use your own custom scan configuration.
Selecting a built-in scan configuration
If you don't select a built-in scan configuration, the default configuration is used.
To use a built-in scan configuration, enter the name of the configuration in the
scanConfigurations.builtIn setting. The configuration names are case-sensitive.
Selecting a custom scan configuration
You can create custom scan configurations in Burp Suite Enterprise Edition and Burp Suite Professional. You can then export the scan configuration as a JSON file. For more information, see Using custom scan configurations.
Once you have created a custom scan configuration, save it as a JSON file in the same directory as the configuration file. Enter the path for the JSON file in the
If you select more than one scan configuration, Burp Scanner combines the settings from these scan configurations. If settings in two or more scan configurations conflict, the setting from the lowest configuration in the list takes precedence.
Configuring connection settings
The JSON file contains some environment variables that enable you to configure the connection settings used when running CI-driven scans:
headersCookiesConfigenables you to add a list of custom headers and cookies to requests made when scanning a site. This enables you to, for example, configure header authentication. For more information on configuring request headers and cookies, see Adding headers and cookies.
platformAuthenticationenables you to add authentication credentials for HTTP Basic and NTLM authentication. For more information on the settings available, see Configuring platform authentication.
proxiesenables you to enter a list of upstream proxy servers for the connection to use. For more information on the settings available, see Configuring upstream proxy servers.
Viewing scan results in the dashboard
If you want to view the progress and results of scans in the Burp Suite Enterprise Edition dashboard, you must provide a correlation ID (
site.correlationId). Burp Suite Enterprise Edition creates a site with the same name as your correlation ID. You can choose any unique text string for the correlation ID, up to 64 characters long.
If you don't provide a correlation ID, Burp Suite Enterprise Edition doesn't show the progress or results of your scans. The scan data is only saved to the
Specifying report format
By default, CI-driven scans output reports in JUnit XML format. However, they can also output in Burp XML format if required. Use the
reporting.reportFormats parameter to specify the format to use.
Ignoring specific vulnerabilities
You can ignore specific vulnerabilities, so that they do not cause the build to fail. Burp Scanner still looks for these vulnerabilities, and records them in the results. For a list of vulnerabilities, see Vulnerabilities detected by Burp Scanner.
Enter the name of the vulnerabilities in the
reporting.ignoredIssues parameter. Names are case-sensitive. If you name an issue and don't supply a path, the issue is ignored everywhere.
We support the use of regex for the paths.
Setting the threshold
Enter a minimum severity and a minimum confidence. If Burp Scanner detects an issue with at least this severity and confidence, it finishes with a non-zero exit code. This tells your CI/CD system to fail the pipeline step.
You can set the
You can set the
If you don't input values for these parameters, the default values are LOW and TENTATIVE.
Was this article helpful?
An error occurred, please try again.