Integrate with CI systems

Assure build quality by integrating StackRox with your Continuous Integration (CI) pipeline.

6 minute read

The StackRox Kubernetes Security Platform integrates with a variety of continuous integration (CI) products and allows you to apply build-time and deploy-time security rules before you deploy images.

The StackRox Kubernetes Security Platform integrates into CI pipelines after images are built and pushed to a registry. Pushing the image first allows developers to continue testing their artifacts while dealing with any policy violations alongside any other CI test failures, linter violations, or other problems.

If possible, you should configure the version control system to block pull/merge requests from being merged if the build stage that includes StackRox checks has failed.

The integration functions by contacting your StackRox installation to check whether the image complies with build-phase policies you’ve configured. If there are policy violations, a detailed message gets displayed on the console log, including the policy’s description, rationale, and remediation instructions. Each policy includes an optional enforcement setting; if you mark a policy for build-phase enforcement, failure of that policy causes the client to exit with a nonzero error code.

To integrate the StackRox Kubernetes Security Platform with your CI product, follow these steps:

  1. Configure build policies
  2. Configure a registry integration
  3. Configure access to your StackRox Kubernetes Security Platform instance.
  4. Integrate with your CI pipeline

Configure build policies

To check StackRox policies during builds, you must configure policies that apply to the Build phase of the container lifecycle.

Then, you must integrate with the registry that images are pushed to during the build.

To see if you have any build-phase policies configured:

  1. On the StackRox portal, navigate to Platform Configuration > System Policies.
  2. Enter a search query for Lifecycle Stage with the value Build.
    Search for Build Policies
    Search for Build Policies

To add a new policy:

  1. On the System Policies page, click the + New Policy button.

  2. Fill out the policy details, including a name, description, and category. Select Build in the Lifecycle Stages menu.

    Build Phase Setting
    Build Phase Setting

    The Description, Rationale, and Remediation fields will be displayed when a build is validated, so StackRox recommends spending time to explain the policy.

  3. Under Policy Configuration, click Add a field and select a value to check during the build. For example, you might select:

    • CVE to match a specific vulnerability you are concerned about;
    • CVSS to match vulnerabilities by their assigned severity score;
    • Component to identify packages (or package versions) you don’t want installed in images; or
    • Dockerfile Line to identify poor practices in Dockerfile builds.
  4. Click Next twice to advance to enforcement settings. Select the On button for Build Enforcement if you want violations of this policy to cause builds to fail.

  5. Click Save.

To use CVE, CVSS, Component, or other fields that inspect the contents of the image, you must have a scanner integration configured in StackRox for the registry to which you push images.

Configure a registry integration

To scan images, you must provide StackRox with access to the image registry used in your build pipeline.

To see if you already have an integration configured:

  1. On the StackRox portal, navigate to Platform Configuration > Integrations.
  2. Click the active Registry tiles and see if there is an integration configured for the registry.

If you need to create a new integration:

  1. Select the most appropriate Registry tile for your registry. If you use a registry with its own tile, click that tile; otherwise, click Generic Docker Registry.
  2. Fill out the fields shown:
    • Name: Provide a descriptive name for the registry.
    • Types: Select Registry, and also select Scanner if available.
    • Endpoint: Enter the hostname (and port number, if not 443) of the registry. This typically corresponds to the first portion of an image reference, such as for Exception: For Docker Hub, you must enter the endpoint due to the way Docker Hub serves registry APIs.
    • Username and Password: If your registry requires authentication to pull images, provide a username and password.
    • Disable TLS Certificate Validation (Insecure): If your registry uses a certificate that’s not trusted, such as a self-signed certificate, turn on this toggle. (You can configure custom trusted Certificate Authorities during installation, contact StackRox Support for more details.) Otherwise, leave this toggle off.
  3. Click the Checkmark icon to validate that a connection can be made. Fix any issues, then click Create.

Configure access

StackRox provides a command-line interface (CLI) client to make it easy to integrate StackRox policies into your build pipeline. The CLI prints detailed information about problems, and how to fix them, so that developers can maintain high standards in the early phases of the container lifecycle.

When you have completed these steps, you will be ready to configure your CI pipeline.

Create an API Token

To securely authenticate to the StackRox API server, you must create an API token.

  1. On the StackRox portal, navigate to Platform Configuration > Integrations.
  2. Scroll down to the Authentication section and click the API Token tile.
  3. Click + Generate Token and fill in the required fields:
    • Token Name: Provide a descriptive name for where this token will be used, such as “Back-end Team Jenkins.”
    • Role: Select Continuous Integration. This token will have access to the necessary APIs to check build-phase policies.
  4. Click Generate.
  1. Click the copy button (
    copy icon
    copy icon
    ) to copy the token to your computer clipboard. Save it for use when configuring your Jenkins build.

If this token is ever compromised:

  1. Return to the API Token tile.
  2. Revoke button
    Revoke button
    Hover over the relevant token in the table, and click the trash-can icon to revoke the token’s access privileges.

Download the StackRox client

Use the roxctl command-line client to submit images and Kubernetes configuration files (YAML) to the StackRox Kubernetes Security Platform and check them against your security policies. You can download the roxctl client or use its container image.

Download the roxctl CLI

To download the roxctl client:

  1. Open the StackRox portal.
  2. Select the CLI menu in the upper right corner and choose the operating system that your CI system uses. (Most users should choose Linux.)

Use the roxctl CLI in a container image

The roxctl client is the default entry point in the StackRox Kubernetes Security Platform roxctl image.

To run the roxctl client in a container image:

  1. Log in to the registry:
    docker login
  2. Pull the latest container image for the roxctl CLI:
    docker pull
  3. Run the roxctl CLI:
    docker run -e ROX_API_TOKEN=$ROX_API_TOKEN -it -e $ROX_ENDPOINT [command]

Integrate with your CI pipeline

Once you’ve finished these procedures, the next step is to integrate with your CI pipeline.

Each CI system may require a slightly different configuration. Find instructions for your provider below, or contact StackRox Support for assistance.

Configure Jenkins

If you are using the StackRox Kubernetes Security Platform version 3.0.37 or newer, we recommend that you use the StackRox Container Image Scanner Jenkins plugin for integrating with Jenkins. You can use this plugin in both Jenkins freestyle projects and pipelines.

For the StackRox Kubernetes Security Platform version 3.0.36 and older, follow the steps below to configure Jenkins.

Log in to your Jenkins server and select the build job you want to modify.

  1. Click the Platform Configuration button to view the build job’s settings.
  2. Under Build Environment, enable the Use secret text(s) or file(s) option if it’s not yet enabled. Click Add and add a Secret text value.
    1. Set the Variable name to ROX_API_TOKEN.
    2. Create a Credential containing the API token saved in the previous step.
      Jenkins secret value
      Jenkins secret value
  3. Under Build, click Add Build Step and create an Execute shell step. In this step, invoke the StackRox command line. Ensure that the command-line program itself is available in the build executor environment or is downloaded in this step. You will need to substitute your StackRox endpoint (including a port number) and the reference to the image that was just built.
roxctl image check --endpoint "" --image ""

Tip: To make testing easier, consider adding this invocation to a script and checking it into your source code repository. Then, invoke the script in Jenkins.

This build step must be executed after the image is built and pushed to the registry.

Configure CircleCI

  1. Log in to CircleCI and open an existing project or create a new project.

  2. Select Project Settings.

  3. Select Environment variables.

  4. Select Add variable and create the following three environment variables:

    • Name: STACKROX_CENTRAL_HOST - the DNS name or IP address of your Central.
    • Name: ROX_API_TOKEN - the API token to access StackRox Kubernetes Security Platform. You need a token with both read and write permissions for the Image resource. For details, see the Authentication. section of Use the API topic.
    • Name: DOCKERHUB_PASSWORD - The password for your DockerHub account.
    • Name: DOCKERHUB_USER - The username for your DockerHub account.
  5. Create a directory called .circleci in the root directory of your local code repository for your selected project, if you don’t already have a Circle CI configuration file.

  6. Create a config.yml configuration file with the following lines in the .circleci directory.

    version: 2
          - image: 'circleci/node:latest'
              username: $DOCKERHUB_USER
              password: $DOCKERHUB_PASSWORD  
          - checkout
          - run: 
              name: Install roxctl
              command: |
                  curl -H "Authorization: Bearer $ROX_API_TOKEN" https://$STACKROX_CENTRAL_HOST:443/api/cli/download/roxctl-linux -o roxctl && chmod +x ./roxctl
          - run: 
              name: Scan images for policy deviations and vulnerabilities
              command: |
                  ./roxctl image check --endpoint "$STACKROX_CENTRAL_HOST:443" --image "<your-registry/repo/image-name>"
          - run: 
              name: Scan deployment files for policy deviations
              command: |
                  ./roxctl image check --endpoint "$STACKROX_CENTRAL_HOST:443" --image "<your-deployment-file>"
                  # Important note: This step assumes the YAML file you'd like to test is located in the project.
      version: 2
          - check-policy-compliance
    • You must replace <your-registry/repo/image-name> with your registry and image path.
    • You must replace <your-deployment-file> with the path to your deployment file.

    If you already have a config.yml file for CircleCI in your repository, add a new jobs section with the specified details in your existing configuration file.

  7. After you commit the configuration file to your repository, navigate to the Jobs queue in your CircleCI dashboard to verify the build policy enforcement.


We're happy to help! Reach out to us to discuss questions, issues, or feature requests.

© 2021 StackRox Inc. All rights reserved.