InsightVM

Containers CI/CD Plugin

Overview

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.

Whitelist Platform Traffic

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

Region
Hostname

United States

us.api.insight.rapid7.com

Europe

eu.api.insight.rapid7.com

Canada

ca.api.insight.rapid7.com

Japan

ap.api.insight.rapid7.com

Australia

au.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 platform.

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

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

Follow these steps to generate the Rapid7 API key:

  1. Go to https://insight.rapid7.com/platform#/
  2. Log in to your Rapid7 Insight platform account.
  3. Go to API Keys.
  4. 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 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 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:
    a. In the “Domain” field, select "Global credentials (unrestricted)."
    b. In the “Kind” field, select "Secret text."
    c. In the "Scope" field, select “Global (Jenkins, nodes, items, all child items, etc).”
    d. In the “Secret” field, enter your API key.
    e. Leave the “ID” field blank.
    f. 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 Job 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.
// Assess the image
       assessContainerImage failOnPluginError: true,
           imageId: "${my_image.id}",
           thresholdRules: [
              exploitableVulnerabilities(action: 'Mark Unstable', threshold: '1')
            ],
            nameRules: [
              vulnerablePackageName(action: 'Fail', contains: 'nginx')
           ]
  1. See the following example for correct location and syntax:
node {
   // Define a variable to use across stages
   def my_image
   stage('Build') {
       // Get Dockerfile and code from Git (or other source control)
       checkout scm
       // Build Docker image and set image reference
       my_image = docker.build("test-app:${env.BUILD_ID}")
       echo "Built image ${my_image.id}"
   }
   stage('Test') {
       // Assess the image
       assessContainerImage failOnPluginError: true,
           imageId: "${my_image.id}",
           thresholdRules: [
              exploitableVulnerabilities(action: 'Mark Unstable', threshold: '1')
            ],
            nameRules: [
              vulnerablePackageName(action: 'Fail', contains: 'nginx')
           ]
   }
   stage('Deploy') {
       echo "Deploying image ${my_image.id} to somewhere..."
       // Push image and deploy a container
   }
}
  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.


Containers CI/CD Plugin


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.