Contrast Jenkins plugin
Jenkins is a continuous integration (CI) tool that automates the process of building, testing, deploying, and running applications.
With the Contrast plugin for Jenkins, you can add application security gates to this pipeline. These gates contain criteria that can fail the Jenkins job for a vulnerable application with a build result like "Failure" or "Unstable".
Tip
You can view the plugin source code in the Jenkins Github repository.
Use these versions to ensure compatibility:
Jenkins | Contrast-Jenkins plugin | Contrast |
|---|---|---|
2.60.3 | 3.4 | 3.7.6 |
2.60.3 | 3.7 | 3.7.10 |
2.60.3 | 3.8 | 3.8.0 |
To install and use the Jenkins plugin:
Define a connection between Contrast and Jenkins.
Depending on your situation, decide how you will use Jenkins:
If you are using freestyle jobs, you can define vulnerability security controls at a system level or as a post-build action step.
Define vulnerability security controls for pipeline steps.
Optionally, a Contrast Organization Administrator define a job outcome policy.
Connect
To define a connection to Contrast in Jenkins:
In your Jenkins dashboard, go to Manage Jenkins in the left sidebar.
Select Configure System to find the Contrast Connections section.
Next to Contrast username , enter your username. Your username is usually the email address you use for your account in Contrast.
Enter the Contrast API key, Contrast service key, Contrast URL and Organization ID. You can find these in your profile.
Next to Result of a vulnerable build , use the drop-down menu to select how you want Contrast to mark your Jenkins job when your application is too vunerable. Options are Failure, Unstable, Success, Not_built and Aborted.
Check the box next to Apply this vulnerable build result to the job when Jenkins encounters an error with Contrast if you want the Jenkins job to automatically fail whenever your Jenkins instance can't find your application.
You can define the criteria that the Contrast plugin will use to determine whether an application is too vulnerable at the Jenkins system level. Check the box next to Allow job level application vulnerability security controls to override those controls set here at the system level if you want job level controls to override system level controls. Leave the box unchecked if you want to enforce consistency of criteria across all Jenkins jobs in your instance.
Note
If you are using a job outcome policy to set security controls, those policies will override any policies set at the job level or system level.
Select Test Contrast connection to make sure that the plugin can authenticate to Contrast and retrieve information about your applications' vulnerabilities.
Select Save .
Define security controls at a system level
After you define a connection in Jenkins, define if you are using freestyle jobs, you may want to set Contrast vulnerability security controls at a system level. Alternatively, you can set security controls at a job level, or if you use a job outcome policy those security controls will take precedence.
Under Contrast Connections > Contrast Vulnerability Security Controls, select a Connection you have previously created, from the drop-down menu.
Set the Number of Allowed Vulnerabilities . This number is exclusive; if you set it to "5", Jenkins will fail if there are six or more vulnerabilities. This field is required.
Choose a Vulnerability Severity from the options in the drop-down menu. (These are the same vulnerability severity options in Contrast.) The plugin sets a filter in the API call for all vulnerabilities greater than or equal to this field. This field is not required, but selecting it will narrow your results. So if the number is set to "5" and the severity to High, Jenkins will fail if there are six or more critical vulnerabilities.
Choose a Vulnerability Type (rule name) from the drop-down menu. The plugin checks for the number of vulnerabilities with the rule type selected and compares it to the number of allowed vulnerabilities for that rule. This field is not required, but selecting it will narrow your results. You can choose one severity and one rule type per security control.
Choose from the list of Vulnerability Statuses . Statuses aren't required, but can be helpful. For example, select Confirmed and Suspicious to only return vulnerabilities with an open status. Leave this blank if you don't want to filter vulnerabilities by statuses.
You can add multiple vulnerability security controls, but the plugin will fail the job on the first bad condition. The plugin will set the build result on the first violated vulnerability security control.
Define security controls as a post-build action step
After you have set security controls at the system level in Jenkins, you can also add security controls at a job level for freestyle jobs that are not part of a Jenkins Pipeline. To do this:
When defining a job in Jenkins, find the Post-Build Actions section.
Select a Connection you have previously created, from the drop-down menu.
Choose your application. This field is required.
If your application has been instrumented, select your application from the Choose your application drop-down menu.
If your application has not yet been instrumented, indicate your application using the Application Name and Application Language fields. You must provide the same application name in Jenkins that you will use when you do instrument your application. Contrast will use that same name and language during the post-build action step after the application has been instrumented.
If the connection is configured to allow the system-level vulnerability security controls to be overridden, you can override that setting by checking the box next to Override Vulnerability Security Controls at the Jenkins system level .
If you do this, you will also need to indicate the Number of Allowed Vulnerabilities, Vulnerability Severity, Vulnerability Type, and Vulnerability Statuses for this job.
Select how you want to query vulnerabilities by selecting an option under Query vulnerabilities by . That way, only those vulnerabilities found from that job will be considered. By default, the plugin uses the first option:
appVersionTag,format: applicationId-buildNumber.
Download with contrastAgent
A pipeline step with the name contrastAgent downloads the latest Contrast agent.
Parameter | Required | Description | Examples |
|---|---|---|---|
| Required | Contrast connection profile used to communicate with Contrast |
|
| Required | This defines where to put the downloaded agent. |
|
| Required if | Type of agent used to instrument the application (not case sensitive) Options are: |
|
Here is an example of how to add a pipeline step with the name contrastAgent :
node{ stage('Download Latest Contrast Agent'){ contrastAgent profile:'MyConnection', outputDirectory: env.WORKSPACE, agentType: 'Java' } }
Define vulnerability security controls for pipelines in Jenkins
You can use the contrastAgent pipeline step to download the Contrast agent, then instrument and exercise your application. You can use the contrastVerification pipeline step to verify your application and set parameters for a security control.
Verify application with contrastVerification
You can use a pipeline step with the name contrastVerification to verify whether an application is vulnerable.
Parameter | Required | Description | Examples |
|---|---|---|---|
| Required | Use | Contrast Connection |
| Required | Use Enter the option number for how you want to query vulnerabilities (defaults to 1):
| 1 |
| Required, if | The ID of the application or application module you are trying to verify |
|
| Required, if | The name of the application you are trying to verify (not case sensitive) | MyApp |
| Optional | The total number of allowed vulnerabilities, defaults to 0 | 10 |
| Optional | Defaults to All |
|
| Optional | Defaults to All. Other options are Critical, High, Medium and Low. | High |
| Optional | The value that was passed to the | v1.2.3 |
Here are some examples of how to add a pipeline step with the name contrastVerification :
Use
queryBystartDate:contrastVerification applicationId: '1e6ad9c6-89d4-4f06-bdf6-92c569ec89de', count: 1, profile: 'new-profile', queryBy: 3, rule: 'cache-controls-missing', severity: 'High'
Use
queryBycustomappVersionTagparameter:contrastVerification applicationId: '1e6ad9c6-89d4-4f06-bdf6-92c569ec89de', count: 1, profile: 'new-profile', queryBy: 4, appVersionTag: 'v1.2.3' rule: 'cache-controls-missing', severity: 'High'
Use
applicationNameandAgentTypeto define the application:contrastVerification applicationName: 'MyApp', agentType: 'Java', count: 1, profile: 'new-profile', queryBy: 3, rule: 'cache-controls-missing', severity: 'High'
Verify an application with a preset or overridden vulnerability security control.
If you know that the vulnerability security control has been preset in Contrast, then you only need to define the profile and either the
applicationIdor (applicationNameandagentType):contrastVerification applicationId: '35ae7b89-1c76-414b-b317-c444ce27608b', profile: 'ContrastConnection'
Define a job outcome policy
Job outcome policies (supported in the Contrast Jenkins plugin version 3.3 and later) assign build outcomes to Jenkins jobs that use the Contrast plugin. These policies mark jobs with a build outcome status such as Failure, Unstable, or Success based on criteria you set.
You must be an Organization Administrator to define a job outcome policy in Contrast.
To define a job outcome policy:
Under organization settings, select Integrations in the left navigation.
In the Jenkins row, select Add job outcome policy.
Define a name for the job outcome policy (required).
Under Applications, indicate the applications to which the policy should apply. You can identify applications by their name, importance level, or tag. If you select by application name, you can select individual or merged applications.
Under Vulnerability properties, define a limit of which vulnerabilities, in which environments will be included in the policy. Use the Environment, Vulnerability status and Vulnerability first seen to filter the vulnerabilities that you want to include in this policy. Use the Vulnerability rules and severities to set a threshold for how many of those rules (at a particular severity) will trigger the outcome status change.
Environment(s): Select the environment where you want to apply the policy.
For example, to block vulnerabilities from moving from test (QA) to production, select QA. (However, if you do that, vulnerabilities in the development environment are not considered. Select Development to also include those vulnerabilities. Or select All environments if you want vulnerabilities from all environments to be included.)
Vulnerability statuses: Select which statuses will be included. Statuses are determined by Contrast.
Tip
In most cases, you should only select open statuses like Reported, Confirmed, and Suspicious (rather than closed statuses like Not a problem, Remediated or Fixed). That way, Jenkins jobs won't fail or turn unstable due to vulnerabilities that developers have already remediated.
Vulnerability first seen: Set a time range for the vulnerabilities you'd like to include in this policy according to when they were first seen.
Use From and Until fields to set the beginning and end of the time range. Select the beginning of the time range to be: the Job start time, a predetermined period of time before the Contrast step runs, or the day of Application onboarding. Select the end of the time range to be a predetermined number of days before the Contrast step runs, or until the Contrast step runs in Jenkins, or choose an option for a specific amount of time. You can also select Custom to choose a specific date for either field.
If vulnerabilities were first found outside of this time range, they will not be included in the policy.
Tip
To incentivize developers to remediate vulnerabilities within a time period (for example, a week), define the policy so that only vulnerabilities found more than 7 days ago would be considered for policy violation. To do this, set From to Application onboarding and Until to Last 7 days.
Vulnerability rules and severities: Use this section to set a threshold for the number, type and severity of vulnerabilities you want the policy to allow.
For each rule, select the Severity or Assess rule type, and then the Number of allowed vulnerabilities. Select Add another rule to add multiple rules.
The Number of allowed vulnerabilities determines how many vulnerabilities of this severity will be permitted without affecting this build. If you set it to "0", then a single vulnerability will change the build outcome status. If you set it to "10", then the build outcome status won't change until 11 vulnerabilities of that type are found. If you leave the Number of allowed vulnerabilities blank for a specific rule type or severity, it will allow all vulnerabilities of that rule type or severity.
For example, if you set this to All rules and 1 vulnerability, any single vulnerability would trigger the policy. You could also limit this policy to 5 critical vulnerability rules and 2 cross-site-scripting vulnerability by adding another rule.
Check the box next to Apply the "Query vulnerabilites by" selection from the plugin when filtering vulnerabilities. You can define how to query vulnerabilities in a Jenkins job either using the Contrast Assess post build step or pipeline step. For example, you can use the
AppVersionTag, or the date when the vulnerability was last seen. If this checkbox is checked, then the query is included when the job outcome policy is evaluated.
This example shows possible rules and settings for a job outcome policy that will change the outcome status in Jenkins if these conditions are met.
With this example, the following vulnerabilities will be considered for policy violation:
All vulnerabilities found on a server designated as a QA environment.
All vulnerabilities that have a status of Reported, Confirmed or Suspicious.
Any vulnerability that was first discovered between application onboarding and when the Contrast step runs in Jenkins.
The policy will be violated and the outcome status will change, if at least ONE of these occur:
There is at least 1 Critical vulnerability.
There are at least a combined total of 4 High, Medium, Low or Note severity vulnerabilities of any rule type except SQL injection.
Note
Vulnerabilities are only counted once, with precedence given to the most specific setting (for example, a particular rule type) to the least specific (All rules). If vulnerability limits are set for both a rule type and its severity level, the vulnerabilities will be included in the rule type count, but not in the severity’s vulnerability count. So in this example, Critical vulnerabilities are counted under severity, but High, Medium, Low and Note severities are combined under All rules.
Under Policy outcome, select the outcome of the policy. Contrast marks jobs that match the selected criteria as Failure, Unstable, or Success. For applications with multiple job outcome policies, the most severe outcome from all violating policies will apply.
At any point, you can use uncheck the box next to Enable this job outcome policy to pause Contrast from enforcing policies on Jenkins jobs without having to delete the individual policy.
Run a build
To run a build for the first time:
In Jenkins, select the job or project you want to run.
In the menu on the left, select Build Now .
To see more details, you can view the log output.
If you are using a freestyle job, you can view data from the task. Select the run and, in the left menu, select Vulnerability Report .
Important
You may also see a chart in the job or project overview, however the chart is not visible if you used a Contrast pipeline step, or if at least one of the applications selected is being overridden by a job outcome policy.