Jenkins Plugin

Jenkins is a continuous integration (CI) application that can be used to build, deploy and run applications. The Contrast Jenkins Plugin is a tool for integrating Contrast with your Jenkins CI instance. You can use it to test your connection to Contrast and verify your build with threshold conditions.

Use the Plugin

You can view the plugin code in Jenkins' Github repository. In the Jenkins dashboard, go to Manage Jenkins in the left sidebar, and select the Configure System page to find the "Contrast TeamServer" profiles section.

Contrast API settings

Contrast API settings enable the plugin to connect to Contrast and query for results. The plugin leverages these result to authenticate to Contrast and make API calls in post-build actions. Among the following requirements, you'll need a unique profile name to identify your configuration and use it in a specific job.

  • Enter your Contrast Username. Your username is usually the email address you use for your account in Contrast.
  • Enter your Contrast API Key and Contrast Service Key. Log in to the Contrast UI, and go to the user menu > Your Account > Your Keys section to find both keys.
  • Enter the Contrast URL (the API URL to your Contrast instance). Use https://app.contrastsecurity.com/Contrast/api if you're a SaaS customer; all others use the URL of your Contrast UI (e.g., https://contrastserver/Contrast/api).
  • Enter the Organization UUID. Go to the user menu > Organization Settings > API tab to find the Organization UUID of the configured user in the Contrast UI. (You can also copy it from the URL after logging in to the Contrast UI.)
  • Choose the Result of a vulnerable build from the dropdown menu.
  • Check the box to fail a build if the application is not found in the Contrast application.
  • Choose to allow global threshold conditions to be overridden in post-build actions. (See the Global threshold conditions section for more details.)
  • Click the Apply button to save the profile settings.

Test the connection

When you add a Contrast profile, use the Test TeamServer Connection button to test your connection and make sure that all the fields are accurate. Contrast prompts you if the test is successful, or gives an error message if it fails.

Global threshold conditions

Once a connection is made, complete the following fields for Contrast Vulnerability Threshold Conditions.

  • Select a Profile from the dropdown.
  • Add a Count. The count is exclusive; if you set a count for "5", it fails on six or more vulnerabilities. This field is required.
  • Choose a Severity from the options in the dropdown menu (Note, Low, Medium, High or Critical). The plugin sets a filter in the API call for all vulnerabilities greater than or equal to this field. This field is recommended to reduce your results, but not required.
  • Choose a Vulnerability Type (rule name) from the dropdown menu. If you specify a single rule for which to filter, the plugin checks for the number of vulnerabilities with the rule type and compares it to the count. This field is recommended to reduce your results, but not required.
  • Choose from the list of Vulnerability Statuses. Statues aren't required, but can be helpful if you want to exclude vulnerabilities with certain statuses - for example, "Not a Problem" - from the results. If you don't select any statuses, the plugin won't filter vulnerabilities by statuses.

You can add as many rules as you like. The plugin fails on the first bad condition and tells you on which condition it failed.

Note: Even if your build succeeds, the plugin fails the overall build if the test finds a bad condition.

Threshold conditions in a post-build action

Complete the following fields for Post-Build Actions.

  • Select a Profile from the dropdown.
  • Select Query vulnerabilities by. By default, the plugin uses the first option: "appVersionTag, format: applicationId-buildNumber".
  • If the profile is configured to allow the global threshold conditions to be overridden, you can choose to do so.
  • Select the Application Id from the dropdown menu. This field is required.
  • If you chose to override the global threshold conditions, fill in the rest of the fields, including Count, Severity, Vulnerability Type, and Vulnerability Statuses similarly to the global threshold conditions described above.

Threshold conditions in a Pipeline step

When you add a Pipeline step with the name contrastVerification, it follows the same principles as the post-build action but in a newer format for Jenkins 2.0 improvements. Pipeline configuration:

contrastVerification applicationId: '1e6ad9c6-89d4-4f06-bdf6-92c569ec89de', count: 1, profile: 'new-profile', queryBy: 3, rule: 'cache-controls-missing', severity: 'High'

Test for Vulnerabilities

For the Jenkins plugin to get accurate information, you must add a unique identifier built from the Jenkins CI configuration as an agent property. The corresponding property for the Java agent is contrast.override.appversion.

The plugin can use either the unique identifier appVersionTag or the startDate to filter vulnerabilities and check conditions. You can change the format used by the plugin to create appVersionTag or set the plugin to use startDate using queryBy pipeline parameter. Three options are available:

  • appVersionTag, format: applicationId-${BUILD_NUMBER} (default)
  • appVersionTag, format: applicationId-${JOB_NAME}-${BUILD_NUMBER}
  • startDate (Build timestamp)

Note: The queryBy option should match the contrast.override.appversion parameter you pass to the Contrast Java agent when running your application. If you use the third option (startDate), you aren't required to pass the contrast.override.appversion parameter to the Java agent.

Both JOB_NAME and BUILD_NUMBER are available as a Jenkins environment properties.

Bamboo Plugin

This plugin adds functionality to Bamboo so that you can configure profiles for connecting to Contrast and verify builds against vulnerability thresholds.

Installing the Plugin

The first step is to build the plugin. To begin, clone the plugin from our Github repository.

git clone https://github.com/Contrast-Security-OSS/contrast-bamboo-plugin.git
cd contrast-bamboo-plugin
mvn package

This builds the contrast-bamboo-plugin-#.#.#-SNAPSHOT.jar and the a .obr file. They can both be found within the contrast-bamboo-plugin/target directory of the cloned project.

Once you have built the plugin, you can upload it to your Bamboo instance. Begin by selecting the Add-Ons option from the top left settings menu.

Then select the Upload add-on link.

You should now be prompted to upload a file. Select contrast-bamboo-plugin-#.#.#-SNAPSHOT.obr.

After uploading the plugin, you should see it appear under User Installed Add-Ons.

Creating a Contrast profile

To use the plugin, you should first configure a Contrast profile. To do this, select the TeamServer Profiles button under Add-Ons within the Bamboo Administration dashboard.

You'll then be brought to the Profile Configuration page. Select the New Profile button to see fields for adding a profile. Fill out the form fields according to their labels. The server name that you enter should correspond to a server name on Contrast.

If you are a SaaS customer you do not need to enter a Contrast URL. Once you have filled out all the fields, select the Test Connection button to verify that your settings are correct.

Vulnerability Thresholds

The plugin can be added as a task to build jobs to check for vulnerability conditions that you configure. This checks Contrast for the number of vulnerabilities in the applications as well as types of vulnerabilities.

Configuring vulnerability thresholds

To add a task to a build job, you must either create a new plan or use an existing build plan. For the purpose of these instructions, you'll walk through creating a new build plan.

Select the Create a New Build Plan button.

You'll now be prompted to give the build plan a project name, plan name and link to the repository host. The project key and plan key is auto-generated.

Once you create the plan, add a task to the build process by clicking the Add Task button.

A dialog will appear. Find the Contrast CI for Assess task and select it.

The task configuration screen relies on a Contrast profile, which you configured in the previous steps, and an application name. The application name must be on the server that you defined when creating the profile.

The next part of the task configuration is defining conditions for when to fail a build. This involves entering three pieces of data:

  • Threshold Count: the minimum number of findings required to fail the build.
  • Threshold Severity: the minimum severity at which to count a finding towards the threshold count.
  • Threshold Vulnerability Type: the type of finding required to count a finding towards a threshold count.

Note: Using the Any option means that any severity or vulnerability type is counted towards the max threshold count.

You can configure multiple conditions for each task by selecting the Add New Threshold Condition button.

The last step is to enable the build plan by selecting the checkbox in the bottom left.

Running the build

To run your build for the first time, you'll need to select the Run button and then in the dropdown select the Run Plan option.

Once the build is finished, you can see if it passed or failed. To view the Contrast task details, look at the logs of the job to which the task is attached. In the following example, this is the default job. As you can see in the logs, the task only found two vulnerabilities that met your conditions, therefore the job passes.

You can also see charts of data from the task by clicking the Contrast Report tab. This presents the past 10 builds, and charts the severities over build numbers as well as the vulnerability types of build numbers.