ENTERPRISE

Creating a configuration file for a CI-driven scan with no dashboard

• Last updated: September 14, 2023

• Read time: 3 Minutes

The configuration file enables you to define the site settings and the scan configurations that Burp Scanner uses to perform a scan. The file is in YAML format.

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):

Mandatory settings

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 scan container 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.url, enterpriseServer.apiKey). You can find these on your user account.

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 site.inScopeUrlPrefixes or site.outOfScopeUrlPrefixes parameters.

Authentication

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

Login credentials

To define login credentials, enter a list of username and password pairs in the logins.loginCredentials setting.

Recorded logins

You can use our Chrome plugin to record login sequences. For more information, see Recording login sequences:

1. Follow the instructions in the link above to install our Chrome plugin, and save the recorded login sequence to the clipboard.
2. Save the contents of the clipboard as a JSON file in the same directory as the configuration file.
3. In the logins.recordedLogins parameter, enter the path for the JSON file.

Selecting a built-in scan configuration

You can select from the list of built-in scan configurations. These are the same built-in scan configurations used by Burp Suite Enterprise Edition and Burp Suite Professional.

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.

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 threshold.minimumSeverity to:

• INFO
• LOW
• MEDIUM
• HIGH

You can set the threshold.minimumConfidence to:

• TENTATIVE
• FIRM
• CERTAIN

If you don't input values for these parameters, the default values are LOW and TENTATIVE.