1. Support Center
  2. Documentation
  3. Enterprise Edition
  4. How do I
  5. Integrate with CI

Integrate with your CI system

You can easily integrate your existing CI system with Burp Suite Enterprise Edition using the REST API. We already provide native plugins for both Jenkins and TeamCity, as well as a generic CI driver so that you can manually integrate any other platform that you use.

Once you have completed the integration, scans will automatically be triggered as part of your CI pipeline.

Creating an API user for the integration

Regardless of which CI system you want to integrate, the first step is to create a dedicated API user that the CI system will use to communicate with Burp.

  1. Log in to Burp Suite Enterprise Edition as an administrator.
  2. From the burger menu, go to the "Team" page.
  3. On the "Users" tab, click the "New User" button.
  4. Enter a name and username that will help you easily identify the user later, for example, "Jenkins Build".
  5. Enter an email address, for example, the email address of the admin user.
  6. Select the login type "API Key".
  7. Select the checkbox to add the user to the default "Scan initiators" group.
  8. When you are happy with your changes, click the save icon in the upper-right corner.
  9. When prompted, copy the API key and URL, and save them somewhere secure. You will need these later.

Note that you cannot retrieve the API key for an existing user. If you lose it, you will have to generate a new key and manually update any files where it's used.

Now that you've created an API user, you can use it to configure the integration with your chosen CI system.

Creating an API user

Integrating Jenkins

Integrating Burp Suite Enterprise Edition with Jenkins is made simple thanks to our ready-made plugin. Note that you need to create an API user in Burp before you can perform the next steps.

The following steps are the minimum configuration requirements to integrate Jenkins with Burp Suite Enterprise Edition. These steps will enable unauthenticated scans with the default scan definition.

  1. Go to our website and download the Burp plugin for Jenkins. The download contains a simple .hpi file.
  2. Log in to Jenkins as an administrator.
  3. Go to "Manage Jenkins" > "Manage Plugins" and open the "Advanced" tab.
  4. Under "Upload Plugin", upload the .hpi file that you just downloaded.
  5. Restart Jenkins.
  6. Select an existing pipeline in Jenkins and open the configuration settings.
  7. Depending on your platform, add either an "Execute shell" or "Execute Windows batch command" build step containing the following command:
    echo BURP_SCAN_URL = http://your-target-server/
    This step will output the target URL in its build log in the correct format for the plugin to process in the next step. If you use a more dynamic deployment, for example, to a Docker container, this step should output multiple URLs, all of which will be aggregated and scanned based on your scan configuration.
  8. Add a "Burp scan" build step.
  9. Under "URL of Burp API", enter the API URL that you copied after creating the API user earlier. This should be in the format http://your-enterprise-server/api/your-burp-api-key/
  10. You can adjust various other settings based on your needs. For example, you can specify the lowest severity issue that will cause the build to fail.
  11. Save your settings.

You have completed the basic Jenkins integration. For more information about optional configuration steps, including extra configuration steps if you are using TLS to connect to the Enterprise server, see the Additional configuration section below.

Build steps in Jenkins

Integrating TeamCity

Integrating Burp Suite Enterprise Edition with TeamCity is made simple thanks to our ready-made plugin. Note that you need to create an API user in Burp Suite before you can perform the next steps.

The following steps are the minimum configuration requirements to integrate TeamCity and Burp Suite Enterprise Edition. These steps will enable unauthenticated scans with the default scan definition.

  1. Go to our website and download the Burp plugin for TeamCity. The download contains a .zip file that can be imported in TeamCity.
  2. Log in to TeamCity as an administrator.
  3. Go to "Administration" > "Plugins List" and click "Upload plugin zip".
  4. Upload the .zip file you just downloaded.
  5. Restart TeamCity.
  6. Select an existing pipeline and open the configuration settings.
  7. Add a "Command Line" build step containing the following command:
    echo BURP_SCAN_URL = http://your-target-server/
    This step will output the target URL in its build log in the correct format for the plugin to process in the next step. If you use a more dynamic deployment, for example, to a Docker container, this step should output multiple URLs, all of which will be aggregated and scanned based on your scan configuration.
  8. Add a "Burp scan" build step.
  9. Under "URL of Burp API", enter the API URL that you copied after creating the API user earlier. This should be in the format http://your-enterprise-server/api/your-burp-api-key/
  10. You can adjust various other settings based on your needs. For example, you can specify the lowest severity issue that will cause the build to fail.
  11. Save your settings.

You have completed the basic integration. For more information about optional configuration steps, see the Additional configuration section below.

Integrating other CI systems

If you use a CI system other than Jenkins or TeamCity, you can still integrate a Burp scan as part of your build pipeline using our generic CI driver. This provides a command-line interface that you can use to integrate any CI system for which a native plugin is not available.

The driver accepts URLs to scan as standard input (stdin) in the format BURP_SCAN_URL = http://your-target-server/. You can generate a list of target URLs any way you want, as long as the output is passed in this format to the driver. However, for the purposes of this guide, we'll assume that you are generating the target URLs from a build step in your preferred CI system.

  1. Go to our website and download the generic Burp CI driver. The download contains a .jar file and a readme file, which contains some example commands and background information.
  2. In your CI system, select an existing pipeline and, depending on your platform, add an appropriate build step that executes the following command:
    echo BURP_SCAN_URL = http://your-target-server/
    This step will output the target URL in its build log in the correct format for the driver to process. If you use a more dynamic deployment, for example, to a Docker container, this step should output multiple URLs, all of which will be aggregated and scanned based on your scan configuration.
  3. Add another build step that executes the following command:
    java -jar ci-driver.jar http://your-burp-api-url/ < build_log_from_previous_step.log
    This step accepts the BURP_SCAN_URLs that were output to the build log in the previous step, and uses the REST API to invoke the scan in Burp. Note that you need to specify the path to the build log manually.
  4. You can tailor the scan settings according to your needs by appending the command with various optional parameters. For example, adding --min-confidence=certain means the build will only fail if Burp identifies issues during the scan with the confidence level "certain". For a complete list of parameters and their possible values, please refer to the command line help by running java -jar ci-driver-vXXX.jar --help
  5. Save your settings.
  6. When you trigger a build in your CI system, the driver will initiate a scan only when the standard input terminates, and will block until the scan completes. Throughout the scan, issues that exceed the defined thresholds will also be output either as a summary or in detailed JSON format, depending on your configuration. When the scan is finished, the BURP_SCAN_STATUS indicates whether the scan was able to run successfully. The BURP_SCAN_RESULT line indicates whether any issues were found. It terminates with an exit code of either 0 if no applicable issues were found, or 1 if issues were found. A non-zero exit code will cause the build to fail.

Additional configuration (optional)

Now that you have completed the basic configuration steps for integrating your CI system, you can perform the following additional steps to tailor the integration to your needs.

Integration using HTTPS

If you selected the "Use TLS" option in the Network settings for Burp Suite Enterprise Edition, you need to perform some additional steps so that the CI plugin or driver trusts the Enterprise server's certificate.

For the Jenkins and TeamCity native plugins

  1. In your CI system, go to the build configuration and open the "Burp scan" build step that you created during the initial configuration.
  2. In the "URL of Burp API" field, make sure that the URL uses HTTPS:
    https://your-enterprise-server/api/your-api-key
  3. When you chose to use TLS in your Burp network settings, you uploaded a self-signed certificate. Open the certificate and copy the public part of it.
  4. Back in the "Burp scan" build step, paste the public part of the certificate into the "Self-signed TLS certificate (public part)" field.
  5. Save your settings

The Burp plugin now trusts the certificate and accesses the Enterprise server using HTTPS.

For the generic CI driver

  1. When you chose to use TLS in your Burp network settings, you uploaded a certificate. Open the certificate, copy the public part, and save it in an X509 base64-encoded format, for example, a .pem file.
  2. In the build step where you invoke the scan, append the command with the parameter --self-signed-cert=name_of_the_file.pem.
  3. Make sure you change the URL of your Burp API to use HTTPS. In other words, the command for invoking the scan should now look something like this:
    java -jar ci-driver.jar https://your-burp-api-url/ < build_log_from_previous_step.log --self-signed-cert=name_of_the_file.pem

The Burp CI driver now trusts the certificate and accesses the Enterprise server using HTTPS.

Configuring a detailed scan definition

Using the built-in toolkit for the REST API, you can quickly create much more detailed scan definition to integrate with your CI pipeline.

  1. In your browser, access the API URL that you copied after creating the API user earlier. This is the entry point for the Burp Suite Enterprise Edition REST API.
  2. Click on the POST method to open the request toolkit.
  3. In the toolkit, use the various entry fields to set the configuration you want. As a minimum, you need to enter at least one target URL, a name for the scan, and the scope. If the entire domain of the target URL is in scope, just create one scope entry containing the target URL.
  4. As you make changes to the configuration, the toolkit automatically generates a corresponding curl request at the bottom of the screen. For example:
    curl -vgw "\n" -X POST 'http://your-enterprise-server/api/your-api-key/v0.1/scan' -d '{"name":"Example","scope":{"include":[{"rule":"https://your-target-server/"}],"type":"SimpleScope"},"urls":["https://your-target-server"]}'
  5. When you are happy with your settings, copy the JSON part of the curl request (everything after the -d command).
  6. Log in to your CI system as an administrator.
  7. If you are using the Jenkins or TeamCity plugins:
    • Open the project that you created during the basic configuration and edit the "Burp scan" build step.
    • Under "Scan definition in JSON format", paste the JSON that you copied from the REST API toolkit.
    If you are using the generic CI driver:
    • Save the JSON in a separate file and append the command that invokes the scan with the parameter --scan-definition=name_of_the_file.json
  8. Save your settings.

The next time the scan is invoked by your CI system, the new scan definition will be used.

Advanced build steps in Jenkins

Ignoring issues

You can configure the scan to ignore certain issues or ignore all issues on a particular path, for example, if the path only leads to resources that are not relevant for the scan.

To do this, in the build step for generating the BURP_SCAN_URLs, include ignore rules in the following formats:

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

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

echo BURP_SCAN_IGNORE_GLOB = * @ http://your-target-server/example/

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

Ignore rules for the CI driver