Welcome to the Rapid7 InsightAppSec Jenkins Plugin.
More information about Rapid7 InsightAppSec can be found here: https://www.rapid7.com/products/insightappsec/
To use the plugin you will need
Read Write
or Admin
access.
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.
The plugin may be used as a build step of a freestyle project.
To enabled the plugin:
Add build step
dropdown of a freestyle project, select Scan using InsightAppSec
.You will then be presented with the plugin configuration pane. The configuration options are as follows:
Data Storage Region [required]
Insight API Key [required]
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 drop-down.
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 drop-down.
Advance build when [required]
This configuration option can be used to augment how the build advances based on the status of the scan submitted.
There are four options to choose from:
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.
⚠️ Ignored unless Vulnerability results query has returned no vulnerabilities
has been selected as 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 affect 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:
0d 5h 30m
A quantity must be supplied for each of the above. e.g.
⚠️ Ignored if Scan has been submitted
has been selected as build advance option.
Max scan execution duration [optional]
A max scan execution duration may be provided so that the length of time the CI process takes to provide feedback can be controlled.
The duration will take affect 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 same as above.
⚠️ Ignored if Scan has been submitted
or Scan has been started
has been selected as build advance option.
Enable scan results [optional]
Disabled by default
Flag to indicate if scan results should be viewable when a build has finished.
When enabled, a new action will be provided to view scan results, labeled 'InsightAppSec Scan Results'.
Note: All users with access to view the build job history will be able to view InsightAppSec scan results.
⚠️ Ignored if Scan has been submitted
or Scan has been started
has been selected as build advance option.
The plugin may be used as part of a pipeline.
The following configuration options may be used
Field | Valid Values | Required |
---|---|---|
region |
US // united states EU // europe AU // australia CA // canada AP // japan |
true |
insightCredentialsId |
< your credentials id > | true |
scanConfigId |
< your scan config id> | true |
buildAdvanceIndictor |
SCAN_SUBMITTED SCAN_STARTED SCAN_COMPLETED VULNERABILITY_QUERY
|
true |
vulnerabilityQuery |
A valid vulnerability search query | false |
maxScanPendingDuration |
A duration string in the format described above | false |
maxScanExecutionDuration |
A duration string in the format described above | false |
enableScanResults |
true false
|
false |
Minimal configuration:
insightAppSec region: 'US', insightCredentialsId: 'My ID', scanConfigId: 'f5984f53-2399-47e2-a6b9-010933cbc440', buildAdvanceIndicator: VULNERABILITY_QUERY
Full configuration:
insightAppSec 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
This plugin provides a new type of managed jenkins credential; Insight API Key
.
A credential can be added in two ways:
During build configuration
Add
button next to Insight API Key
field to open the credentials modal.Using the credentials manager
Credentials
.Add Credentials
.Select Insight API Key
as the kind, then provide:
Note: When using the credentials manager there is a known UI issue that blocks the API Key field with OK button, resize the page to fix the rendering.
To run the plugin locally, cd
to the root directory and invoke:
mvn hpi:run
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.