StackRox Container Image Scanner

ID: 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

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.

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.

    * Required

    plugin config

  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.

build step

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
    
  1. 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"
                    )
                }
            }
        }
    }

    plugin pipeline

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.

    view html report