README.md

StackRox Container Image Scanner

The StackRox Container Image Scanner plugin enables scanning of container images for published software vulnerabilities. You can add it as a build step in your freestyle projects or pipeline, to ensure your infrastructure is in adherence with the StackRox Kubernetes Security Platform vulnerability management policies.

The StackRox Kubernetes Security Platform protects your cloud-native applications across the entire container lifecycle: build, deploy, and runtime. Leverage StackRox to gain visibility into your cloud-native environment, to detect vulnerabilities and misconfigurations in your container images and Kubernetes deployments, to identify high-risk runtime activity, and to meet your internal and external compliance requirements.

Contents

• Prerequisites
• Install the StackRox Container Image Scanner plugin
  • Web UI
  • Jenkins CLI
• Use the StackRox Container Image Scanner plugin
  • Freestyle project
  • Pipeline
• View scan reports

Prerequisites

To install, configure, and use the StackRox Container Image Scanner plugin you must meet the following requirements:

1. Use Jenkins version LTS 2.204.1 or newer.

2. Use the StackRox Kubernetes Security Platform version 3.0.38 or newer.

3. Create an API token with the Continuous Integration (CI) role in the StackRox Kubernetes Security Platform.

4. Integrate the StackRox Kubernetes Security Platform with the image registry you use.

Important

This Jenkins plugin operates on the Jenkins controller, not on an agent. To ensure its proper functionality, please make sure to configure your Jenkins controller and RedHat ACS to allow connections.

Install the StackRox Container Image Scanner plugin

You can use Web UI or Jenkins CLI to install the StackRox Container Image Scanner plugin.

Web UI

Use the Jenkins Plugin Manager in your Jenkins instance to install the StackRox Container Image Scanner plugin.

1. On the Jenkins homepage, go to the Manage Jenkins > Manage Plugins view.

2. Select the Available tab.

3. Enter stackrox in the Filter box to search for the StackRox Container Image Scanner plugin.

4. Select the checkbox under the Install column for the StackRox Container Image Scanner plugin.

5. Select Install without restart.

Jenkins CLI

Use the install-plugin command in Jenkins CLI to install the StackRox Container Image Scanner plugin.

java -jar jenkins-cli.jar -s <jenkins-address> install-plugin stackrox-container-image-scanner -deploy

Use the StackRox Container Image Scanner plugin

You can use the StackRox Container Image Scanner plugin in both freestyle projects and pipelines.

Important

You must push your images to the registry you configured in your build steps, before you invoke the StackRox Container Image Scanner plugin step in a Jenkins FreeStyle project or a Pipeline.

Freestyle project

1. Add the StackRox Container Image Scanner plugin step. Select Add build step > StackRox Image Security.

2. Enter details for the following plugin configuration variables:

   Variable	Name	Description
   portalAddress	Portal address *	Your StackRox Portal address.
   apiToken	API token *	The StackRox access token with the Continuous Integration (CI) authorization role.
   enableTLSVerification	Enable TLS verification	Use it to enable TLS. You must also specify a CA certificate.
   caCertPEM	CA certificate	Use it to specify a CA certificate in PEM format. Make sure to include the BEGIN CERTIFICATE and END CERTIFICATE tags for your certificate. Note You can download the certificate in PEM format from the sensor bundle in any of cluster where you’ve installed StackRox Sensor. If you don’t have administrative access to your cluster, please ask your system administrator to get the certificate.
   failOnCriticalPluginError	Fail on critical plugin errors	Enable this to fail the build if the plugin encounters any errors. This value is TRUE by default.
   failOnPolicyEvalFailure	Fail if policy violations exist	Enable this to fail the build if scanned images violate any enforced system policies in the StackRox Kubernetes Security Platform. This value is TRUE by default. Note If you don’t enable failOnPolicyEvalFailure, the plugin will not fail the build even if the StackRox Kubernetes Security Platform reports system policy violations.
   imageNames	Comma separated list of images to scan	If you leave it blank then provide list in $BUILD_TAG/rox_images_to_scan file. Note If you don’t enable failOnPolicyEvalFailure, the plugin will not fail the build even if the StackRox Kubernetes Security Platform reports system policy violations.
   cluster	The Secured Cluster name or ID to delegate image scans to	Leave this blank to use the default delegated scanning config. Note Requires version 4.3+ of the StackRox Kubernetes Security Platform.
   * Required

   

3. If you need to generate list of images to scan. Then leave Images Names field bank and add a build step in your project to save names of all the images you want to scan in the <jenkins-workspace>/${BUILD_TAG}/rox_images_to_scan file. Each image name must be on a separate line.

For example, to do this:

• Select Add build step > Execute shell.

• In the command box, enter:

  mkdir $BUILD_TAG
  cd $BUILD_TAG
  echo "nginx:latest" >> rox_images_to_scan
  echo "stackrox/vuln-images:django-cve-2019-14235" >> rox_images_to_scan
  

4. Select Save and then select Apply.

Pipeline

To use the StackRox Container Image Scanner plugin in your pipeline:

1. Go to the pipeline configuration screen.

2. In the Script text area, enter the following script:

   pipeline {
       agent any
   
       stages {
           stage('Test') {
               steps {
                   stackrox (
                       apiToken: '...',
                       caCertPEM: '',
                       enableTLSVerification: false,
                       failOnCriticalPluginError: true,
                       failOnPolicyEvalFailure: true,
                       portalAddress: 'https://central.stackrox:443',
                       imageNames: "nginx:latest,ubuntu:bionic,busybox:stable",
                       cluster: ""
                   )
               }
           }
       }
   }

   • For more information about the variables, see the plugin configuration variables section.

   

View scan reports

Whenever you use the StackRox Container Image Scanner plugin to scan images, the StackRox Container Image Scanner creates reports as build artifacts. These reports include detailed information in CSV format. The StackRox Container Image Scanner generates the following two CSV format reports for every scanned image:

1. CVEs found in the image.

2. Policy violations for the image.

The StackRox Container Image Scanner also creates an HTML report for every build. This report includes a summary of the scan results for all scanned images in your environment.

To view the HTML report:

1. Select StackRox Image Security Report from the left-hand navigation menu.