Optional settings for the CI/CD integration

  • Last updated: October 14, 2021

  • Read time: 5 Minutes

In addition to configuring the integration between your CI/CD system and Burp Suite Enterprise Edition, both the native plugins and generic driver provide various optional settings that let you fine-tune how the scan and its results should impact your build pipeline.

In the case of the native plugins, these options are controlled using input fields and menus in the custom build steps that they provide. For the generic driver, you specify your settings by appending parameters to the command that triggers the scan. Please refer to the parameter reference guide for details.

Configuring optional settings using the native platform plugins

Once you have added the relevant build steps to your pipeline and added your API link and key, you can adjust the following settings directly in the "Burp site-driven scan" or "Burp scan" build step.

Setting Description Example
Scan definition in JSON format
(Available for Burp scans only)
A custom scan definition that you have created in the same JSON format used by the REST API. You can use this option to override the default scan configuration used by a site, or to provide a detailed scan definition for a one-off scan that is not matched with an existing site. {"name":"Example","scan_configurations":[{"name":"Audit checks - light active","type":"NamedConfiguration"}],"urls":["https://example.com/"]}
Lowest severity issue required to fail the build The minimum severity of issue that must be found by a scan before the build will fail. Default: medium
Lowest confidence issue required to fail the build The minimum issue confidence level that must be found by a scan before the build will fail. Default: tentative
Lowest number of issues permitted before the build will fail The number of issues that are permitted before the build will fail. Default: 0
This means that any issues that exceed the configured severity/confidence threshold will cause the build to fail.
Length of time in seconds to wait before giving up The maximum number of seconds that the CI/CD system should wait to receive a response from the scan. If no response has been received after the time is up, the build will fail. Default: 120
Output issues in JSON form (verbose mode)
(Available for Burp scans only)
By default, when you view the results of your scan in the console output, only the severity/confidence level, the issue type, and the URL where the issue was found are displayed. However, when verbose mode is enabled, the full issue details are displayed in JSON format. Default: disabled
Self-signed TLS certificate (public part) If you normally access Burp Suite Enterprise Edition over HTTPS (the "Use TLS" option is enabled in your network settings) and you use a self-signed TLS certificate, upload the public part of your certificate here. This must be in X504 base64-encoded format and is usually found in a .pem file. N/A
Scan report file The location and file name where you want the HTML scan report to be saved. If empty, no scan report will be generated. $WORKSPACE/scan-report.html
Scan report type The level of detail that you want to include in the scan report. You can choose either a summary report or detailed report. Default: detailed

Configuring optional settings using the generic CI/CD driver

To configure optional settings when using the generic CI/CD driver, you append the command that triggers the scan with the corresponding parameters. For more information, please refer to the parameter reference guide.

Overriding the default scan configurations from your CI/CD system

If a "Burp scan" is matched with an existing site, this site's default scan configurations are used. If the scan could not be matched with a site, Burp Scanner's default configuration is used instead. However, you can manually control the scan configuration from your CI/CD system by overriding the scan definition.

To do this, you first need to generate a new scan definition in the same JSON format used by the REST API.


This approach is primarily a workaround for legacy integrations that use the "Burp scan" option. It is much easier to use a site-driven scan instead as this allows you to set the scan configuration you want using the Burp Suite Enterprise Edition web UI. For more information, see Integration types.

  1. In your browser, go to the API link that you saved after generating the API user. By default, this should be something like:
  2. Click on the entry for the POST /scan endpoint. A dialog opens containing the scan definition toolkit.
  3. Use the various entry fields to set the definition you want. You need to enter at least one target URL, a name for the scan, and the scope. If the entire domain of the site is in scope, just create one scope entry containing the site's top-level URL. Note that if you want the scan to be matched with an existing site, you should keep the site-matching rules in mind when entering these URLs.
  4. Add the scan configurations that you want to use:
    • To use Burp Suite Enterprise Edition's built-in scan configurations, select the NamedConfiguration option and enter the relevant configuration name, for example, Audit checks - light active. You need to create a new array item for each scan configuration you want to include.
    • Alternatively, to use a custom scan configuration, select the CustomConfiguration option and enter the settings that you want to apply in JSON format. The easiest way to do this is to create the configurations you want using Burp Suite Professional or Community Edition, export them, then copy and paste the resulting JSON into this field.
  5. As you make changes to the various input fields, the toolkit automatically generates a corresponding curl command at the bottom of the screen. For example:
    curl -vgw "\n" -X POST 'http://your-enterprise-server:8080/api/your-api-key/v0.1/scan' -d '{"name":"Example","scan_configurations":[{"name":"Audit checks - light active","type":"NamedConfiguration"}],"urls":["https://example.com/"]}'
  6. When you're happy with your settings, copy the JSON part of the curl command. This is everything between the single quotation marks after the -d.
  7. Log in to your CI/CD platform as an administrator.
  8. If you're using the Jenkins or TeamCity plugins:
    • Open your pipeline and edit the "Burp scan" build step.
    • Under "Scan definition in JSON format", paste the JSON that you copied from the REST API toolkit.
  9. If you're using the generic CI driver:
    • Save the copied definition in a separate JSON file and append the command that invokes the scan with the parameter --scan-definition=your-definition.json
    • Save your changes to the build step. The next time the scan is triggered by your pipeline, the new scan definition will be used.

Ignoring issues

When using a "Burp scan", you can configure rules that tell the scan to ignore certain issues or ignore all issues on a particular path.

You do this by adding ignore rules to the build step that outputs the BURP_SCAN_URL as follows:

echo BURP_SCAN_URL = http://your-target-site.com
echo BURP_SCAN_IGNORE_EXACT = (High, Certain) - name @ http://your-target-site.com/example/
echo BURP_SCAN_IGNORE_GLOB = (High, Certain) - name @ http://your-target-site.com/*
echo BURP_SCAN_IGNORE_REGEX = \(High, Certain\) - .+ @ http://your-target-site.com(1|2)/.*

For example, to ignore all issues in the path http://your-target-site.com/example/, you would include the following command:

echo BURP_SCAN_IGNORE_GLOB = * @ http://your-target-site.com/example/

Note that you might need to escape special characters, such as parentheses.