Containers CI/CD Plugin

InsightVM features a container assessment plugin that you can utilize via a Continuous Integration, Continuous Delivery (CI/CD) tool. Use this plugin to analyze a container image for vulnerability assessment on the Insight platform.

The plugin has the following capabilities:

  • Configure custom rules for compliant container images
  • Trigger build actions based on compliance to your rules
  • Generate an assessment report

Container assessment plugin results are available both through your CI/CD tool and the Builds tab of InsightVM’s “Containers” screen.

Configure firewall rules to allow Insight Platform traffic

Is your Rapid7 product subscription provisioned for the United States? Check your region code first!

As of April 12th, 2021, all new customers subscribing to Rapid7 Insight products that elect to store their data in the United States will be provisioned for one of three data centers. Since these data centers have unique endpoints, any firewall rules you configure must correspond to the data center your organization is assigned to. Follow these steps to determine which United States data center your organization is part of:

  1. Go to insight.rapid7.com and sign in with your Insight account email address and password.
  2. Navigate to the Platform Home page.
    • If you are not taken to this page by default, expand the product dropdown in the upper left and click My Account.
  3. Look for the Data Storage Region tag in the upper right corner of the page below your account name. Your United States region tag will show one of the following data centers:
    • United States - 1
    • United States - 2
    • United States - 3

The plugin uses the following hostnames to communicate with the Insight Platform:

RegionHostname
United States - 1us.api.insight.rapid7.com
United States - 2us2.api.insight.rapid7.com
United States - 3us3.api.insight.rapid7.com
Canadaca.api.insight.rapid7.com
Europeeu.api.insight.rapid7.com
Japanap.api.insight.rapid7.com
Australiaau.api.insight.rapid7.com

In order for the plugin to transmit data, you must configure your network to allow traffic to the corresponding hostname of your designated InsightVM region.

NOTE

The region you chose for your plugin MUST match the region that has been selected previously in InsightVM. The plugin cannot communicate through a different region.

Install and configure the Jenkins plugin

Complete the following steps to configure your Jenkins plugin:

  1. Generate the Rapid7 API key
  2. Install and configure the Jenkins plugin

Generate the Rapid7 API key

To use the Jenkins plugin, you need the Rapid7 API key to access the Rapid7 Insight Platform.

In order to access the Rapid7 Insight Platform, you will need a Rapid7 Insight account, which is different from your Security Console user account.

Here's how to get a Rapid7 Insight Platform account:

  • If you are an InsightIDR, InsightAppSec, or InsightOps customer, you already have a Rapid7 Insight Platform account. You can link your existing InsightVM Security Console to the Rapid7 Insight Platform account you created with your other Rapid7 product by following the instructions here.
  • If you are already using the cloud capabilities of InsightVM and don’t have a Rapid7 Insight Platform account, contact the Rapid7 Technical Support team to request one.

Follow these steps to generate the Rapid7 API key:

  1. Go to insight.rapid7.com and sign in with your Insight account email address and password.
  2. Go to API Keys.
  3. Under Organization Key, click on New Organization Key.
  1. In the Organization dropdown menu, select your InsightVM organization name.
  2. Enter a name for your key in the field.
  3. Click Generate.
  4. Copy and save the provided API key.

NOTE

This is the only time you will be able to see the API key, so store it in a safe place. If you misplace your API key, you can always generate a new one.

  1. Click Done.
  2. Your new API key will display in the “Organization Key” table.

Install the Jenkins plugin

There are two ways to install the Jenkins plugin. Both ways require Jenkins administrative privileges. Jenkins version 2.89.3 is the minimum supported version.

NOTE

For the latest version information and dependency requirements, see https://plugins.jenkins.io/rapid7-insightvm-container-assessment.

Install the Jenkins plugin through the Jenkins Update Center

We recommend this method to install the Jenkins plugin because it’s the simplest and most common way to install plugins. You must be a Jenkins administrator to navigate through this path: Manage Jenkins > Manage Plugins

  1. In the "Filter" box, search for "InsightVM."
  2. Under the Available tab, select the checkbox for the InsightVM Container Image Scanner.
  3. Click the desired install button.

Install the Jenkins plugin manually

Follow these steps for manual installation:

  1. Download the plugin from Jenkins website. Verify your download with SHA1.
  2. Log into Jenkins as an admin user.
  3. Click Manage Jenkins in your navigation menu.
  4. On the “Manage Jenkins” page, click Manage Plugins.
  5. Click the Advanced tab.
  6. Under the “Upload Plugin” section, click Choose file to browse to the Rapid7 Jenkins plugin.
  7. Click Upload.
  8. Select the “Restart Jenkins” option.

Configure the Jenkins plugin

Use the API key and follow these steps:

  1. After Jenkins restarts, return to the “Manage Jenkins” page.
  2. Click Configure System.
  3. Scroll to the “Rapid7 InsightVM Container Assessment” section.
  4. In the “InsightVM Region” field, select the region that InsightVM uses to access the Insight Platform.
  5. In the “Insight Platform API Key” field, click Add. In the dropdown menu, select “Jenkins” to configure the Insight platform API key that you generated earlier.
  1. In the window that appears, complete these fields:
    1. In the “Domain” field, select "Global credentials (unrestricted)."
    2. In the “Kind” field, select "Secret text."
    3. In the "Scope" field, select “Global (Jenkins, nodes, items, all child items, etc).”
    4. In the “Secret” field, enter your API key.
    5. Leave the “ID” field blank.
    6. Enter a description for your reference.
  1. Click Add.
  2. Select your newly configured credential from the dropdown menu.

NOTE

Click Test Connection to verify that the region and token are valid.

  1. Click Save to complete your plugin configuration.

Job setup

You must configure your build jobs to use the plugin after installation. Complete the steps for your chosen CI/CD tool:

Jenkins build bob setup

The plugin supports the following Jenkins build methods:

Freestyle build

“Freestyle” is the classic job builder. Build steps can be added or removed via the user interface:

  1. In a new or existing job, click Add build step.
  2. Select Assess Container Image with Rapid7 InsightVM. This will add a build step with a blank configuration.
  3. Configure the items under “Options” as desired.
  4. Click Add under the respective “Rules” section to configure the conditions that will trigger a build action. Two rule types are available:
    • “Threshold Rules” - Sets a numeric limit. Values that exceed this limit will trigger the build action.
    • “Name Rules” - Matches text using the “contains” operator. A match will trigger the build action.

NOTE

The order of your configured rules will not matter when the job is run. Any individual rule can trigger the build action specified.

  1. Click Save when finished.

Pipeline build

The “Pipeline” method involves generating build step scripts from the plugin and adding them to the existing Pipeline script:

  1. In a new or existing job, browse to the “Pipeline” section.
  2. Click Pipeline Syntax below the “Script” field.
  3. Open the dropdown next to “Sample Step” and select "assessContainerImage: Assess Container Image with Rapid7 InsightVM".
  4. Configure your build options and rules in the same manner as before.
  5. Click Generate Pipeline Script when finished.
  6. Add your new step script to the existing Pipeline script.
Pipeline Script
1
// Assess the image
2
assessContainerImage failOnPluginError: true,
3
imageId: "${my_image.id}",
4
thresholdRules: [
5
exploitableVulnerabilities(action: 'Mark Unstable', threshold: '1')
6
],
7
nameRules: [
8
vulnerablePackageName(action: 'Fail', contains: 'nginx')
9
]
10
  1. See the following example for correct location and syntax:
Pipeline Script Example
1
node {
2
// Define a variable to use across stages
3
def my_image
4
stage('Build') {
5
// Get Dockerfile and code from Git (or other source control)
6
checkout scm
7
// Build Docker image and set image reference
8
my_image = docker.build("test-app:${env.BUILD_ID}")
9
echo "Built image ${my_image.id}"
10
}
11
stage('Test') {
12
// Assess the image
13
assessContainerImage failOnPluginError: true,
14
imageId: "${my_image.id}",
15
thresholdRules: [
16
exploitableVulnerabilities(action: 'Mark Unstable', threshold: '1')
17
],
18
nameRules: [
19
vulnerablePackageName(action: 'Fail', contains: 'nginx')
20
]
21
}
22
stage('Deploy') {
23
echo "Deploying image ${my_image.id} to somewhere..."
24
// Push image and deploy a container
25
}
26
}
27
  1. Click Save when finished.

NOTE

Threshold rules must be unique per type. For example, you cannot have two rules for Critical Vulnerabilities. Only one instance of the rule will be applied.

View assessment results

After running a build, you can view assessment results in the following ways:

Assessment results in Jenkins

Jenkins will generate an assessment report once the build finishes.

  1. Open the individual build that ran the plugin.
  2. Click Rapid7 Assessment on your navigation menu.

Assessment results in InsightVM

The results of your build jobs are viewable on the Builds tab of the “Containers” screen in InsightVM. See Containers Build Interface to learn more about this feature.