The InsightAppSec Jenkins plugin provides an easy way to integrate your build process with the InsightAppSec REST API. Using this plugin, Jenkins can automatically run a scan against your web apps and make a decision about the pass/fail status of the build based on the scan result. This decision can be made by using different rules, for example, the maximum number of vulnerabilities found or thresholds of vulnerability severity.
To use the plugin you will need:
- A user account on the Insight Platform with
- Access to InsightAppSec. Note that free trial users are unable to start a scan via the API and so may not use the plugin.
The plugin may be installed using the plugin manager. For more information, see https://plugins.jenkins.io/insightappsec.
Additionally, the plugin can be installed by manually building the
hpi file and uploading to your Jenkins installation.
There are two ways to use this integration - as a build step of a freestyle project, or as part of a pipeline.
You can use the plugin as a build step of a freestyle projectAfter opening a freestyle project, enable the plugin by selecting Add build step in the dropdown menu and select "Scan using InsightAppSec".
You will then be presented with the plugin configuration pane. The configuration options are as follows:
- Data Storage Region [required] - The data storage region of the target InsightAppSec instance.
- Insight API Key [required] - The Insight API Key you wish to use for scanning. More information on Jenkins-managed Insight API Keys can be found here.
- App [required] - The app containing the scan config you wish to scan. Provided the region and API key are compatible, a list of apps that the API key has access to will pre-populate in the dropdown. This may take some seconds to load.
- Scan Config [required] - The existing scan config you wish to scan. Provided the region and API key are compatible, as well as having previously selected an app, the scan configs belonging to the selected app will pre-populate in the dropdown. This may take some seconds to load.
- Advance build when [required] - This configuration option augments how the build advances based on the status of the scan submitted. There are four options to choose from:
- Scan has been submitted - Advance the build when the scan has been submitted successfully.
- Scan has been started - Advance the build when the scan has been started successfully.
- Scan has been completed - Advance the build when the scan has been completed successfully.
- Vulnerability query has returned no vulnerabilities - Advance the build when the scan has been completed and the vulnerability search query has returned no vulnerabilities.
- Vulnerability query [optional] - An InsightAppSec search query may be supplied to search vulnerabilities found by the scan. For example, if you wish to fail the build when high severity vulnerabilities have been found, use:
vulnerability.severity='HIGH'. The query supplied will automatically be scoped to the scan. For more information on vulnerability search queries, consult the InsightAppSec API search documentation here. If left blank, the build will fail when any vulnerabilities have been found in the scan.
This option is ignored unless "Vulnerability results query has returned no vulnerabilities" has been selected as the build advance option.
- Max scan pending duration [optional] - A max scan pending duration may be provided so that the length of time the CI process takes to provide feedback can be controlled. The duration will take effect when the scan has been submitted. Upon reaching the duration, the scan will be cancelled and the build will fail. The following format must be used for defining a duration:
10d 5h 30m2(d) - Days3(h) - Hours4(m) - Minutes
A quantity must be supplied for each of the above. For example:
11 day: 1d 0h 0m25 hours: 0d 5h 0m33 hours, 30 minutes: 0d 3h 30m
This option is ignored if "Scan has been submitted" has been selected as the build advance option.
- Max scan execution duration [optional] - A max scan execution duration may be provided to control the amount of time the CI process takes to provide feedback. The duration will take effect when the scan moves into scanning state. Upon reaching the duration, the in-progress scan will be stopped and the build will advance as normal. The format is the same as above.
This option is ignored if "Scan has been submitted" or "Scan has been started" has been selected as the build advance option.
- Enable scan results [optional] - This option is disabled by default. Use this as a flag to indicate if scan results should be viewable after a build has finished. When enabled, a new action to view scan results, labeled "InsightAppSec Scan Results" will appear.
All users with access to view the build job history can view InsightAppSec scan results**. This option is ignored if "Scan has been submitted" or "Scan has been started" has been selected as the build advance option.
You can use the plugin as part of a pipeline. The following table describes the configuration options.
|< your credentials id >||true|
|< your scan config id>||true|
|A valid vulnerability search query||false|
|A duration string in the format described above||false|
|A duration string in the format described above||false|
1insightAppSec region: 'US', insightCredentialsId: 'My ID', scanConfigId: 'f5984f53-2399-47e2-a6b9-010933cbc440', buildAdvanceIndicator: VULNERABILITY_QUERY
1insightAppSec region: 'US', insightCredentialsId: 'My ID', scanConfigId: 'f5984f53-2399-47e2-a6b9-010933cbc440', buildAdvanceIndicator: VULNERABILITY_QUERY, vulnerabilityQuery: 'vulnerability.severity=\'HIGH\'', maxScanPendingDuration: '0d 0h 10m', maxScanExecutionDuration: '0d 10h 0m', enableScanResults: true
The Jenkins Managed Insight API Key
This plugin provides a new type of managed Jenkins credential called the Insight API Key. A credential can be added while building a configuration or using the credentials manager.
During build configuration, use the Add button next to the "Insight API Key" field to open the credentials modal.
- From the Jenkins homepage, select "Credentials".
- Select the desired scope, global is appropriate.
- Click Add Credentials.
- Select "Insight API Key" as the kind, then provide:
- Name (A friendly name to refer to these credentials. For example, "Bob's API Key")
- Insight API Key (the API Key to connect to the Insight Platform). Instructions for creating an API Key can be found here.
When using the credentials manager there is a known UI issue that blocks the API Key field with the OK button, and you may need to resize the page to view it.
To run the plugin locally,
cd to the root directory and invoke:
When the output shows
INFO: Jenkins is fully up and running navigate to
http://localhost:8080/jenkins/ and you will see the sandbox Jenkins homepage.
- InsightAppSec API documentation: https://help.rapid7.com/insightappsec/en-us/api/v1/docs.html
- Jenkins plugin tutorial: https://wiki.jenkins.io/display/JENKINS/Plugin+tutorial