$ export ROX_API_TOKEN=<api_token>
Red Hat Advanced Cluster Security for Kubernetes (RHACS) 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.
Red Hat Advanced Cluster Security for Kubernetes 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 or merge requests from being merged if the build stage, which includes Red Hat Advanced Cluster Security for Kubernetes checks, fails.
The integration with your CI product functions by contacting your Red Hat Advanced Cluster Security for Kubernetes installation to check whether the image complies with build-phase policies you have configured. If there are policy violations, a detailed message is displayed on the console log, including the policy 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 Red Hat Advanced Cluster Security for Kubernetes with your CI system, follow these steps:
Configure access to your Red Hat Advanced Cluster Security for Kubernetes instance.
To check Red Hat Advanced Cluster Security for Kubernetes policies during builds, you must first configure policies that apply to the build phase of the container lifecycle. And then you must integrate with the registry that images are pushed to during the build.
Use the RHACS portal to check any existing build-phase policies that you have configured in Red Hat Advanced Cluster Security for Kubernetes.
On the RHACS portal, navigate to Platform Configuration → System Policies.
Use global search to search for Lifecycle Stage:Build
.
In addition to using the default policies, you can also create custom policies in Red Hat Advanced Cluster Security for Kubernetes.
On the RHACS portal, navigate to Platform Configuration → System Policies.
Click + New Policy.
Enter the Name for the policy.
Select a Severity level for the policy: Critical, High, Medium, or Low.
Choose the Lifecycle Stages for which the policy is applicable, from Build, Deploy, or Runtime. You can select more than one stage.
If you create a new policy for integrating with a CI system, select Build as the lifecycle stage. |
Build-time policies apply to image fields such as CVEs and Dockerfile instructions.
Deploy-time policies can include all build-time policy criteria. They can also have data from your cluster configurations, such as running in privileged mode or mounting the Docker daemon socket.
Runtime policies can include all build-time and deploy-time policy criteria, as well as data about process executions during runtime.
Enter information about the policy in the Description, Rationale, and Remediation fields. When CI validates the build, the data from these fields is displayed. Therefore, include all information explaining the policy.
Select a category from the Categories drop-down menu.
Select a notifier from the Notifications drop-down menu that receives alert notifications when a violation occurs for this policy.
You must integrate Red Hat Advanced Cluster Security for Kubernetes with your notification providers, such as webhooks, Jira, or PagerDuty, to receive alert notifications. Notifiers only show up if you have integrated any notification providers with Red Hat Advanced Cluster Security for Kubernetes. |
Use Restrict to Scope to enable this policy only for a specific cluster, namespace, or label. You can add multiple scopes and also use regular expressions in RE2 Syntax for namespaces and labels.
Use Exclude by Scope to exclude deployments, clusters, namespaces, and labels. This field indicates that the policy will not apply to the entities that you specify. You can add multiple scopes and also use regular expressions in RE2 Syntax for namespaces and labels. However, you cannot use regular expressions for selecting deployments.
For Excluded Images (Build Lifecycle only), select all the images from the list for which you do not want to trigger a violation for the policy.
The Excluded Images (Build Lifecycle only) setting only applies when you check images in a continuous integration system (the Build lifecycle stage). It does not have any effect if you use this policy to check running deployments (the Deploy lifecycle stage) or runtime activities (the Runtime lifecycle stage). |
In the Policy Criteria section, configure the attributes that will trigger the policy.
Select Next on the panel header.
The new policy panel shows a preview of the violations that are triggered if you enable the policy.
Select Next on the panel header.
Choose the enforcement behavior for the policy. Enforcement settings are only available for the stages that you selected for the Lifecycle Stages option. Select ON to enforce policy and report a violation. Select OFF to only report a violation.
The enforcement behavior is different for each lifecycle stage.
|
Policy enforcement can impact running applications or development processes. Before you enable enforcement options, inform all stakeholders and plan how to respond to the automated enforcement actions. |
To scan images, you must provide Red Hat Advanced Cluster Security for Kubernetes with access to the image registry you are using in your build pipeline.
You can use the RHACS portal to check if you have already integrated with a registry.
On the RHACS portal, navigate to Platform Configuration → Integrations.
Under the Image Integration section, look for highlighted Registry tiles. The tiles also list the number of items already configured for that tile.
If none of the Registry tiles are highlighted, you must first integrate with an image registry.
Red Hat Advanced Cluster Security for Kubernetes provides a command-line interface (CLI) roxctl
to make it easy to integrate Red Hat Advanced Cluster Security for Kubernetes policies into your build pipeline.
The roxctl
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.
To securely authenticate to the Red Hat Advanced Cluster Security for Kubernetes API server, you must create an API token.
For authentication, you can use an authentication token or your administrator password. Red Hat recommends using an authentication token in a production environment because each token is assigned specific access control permissions.
Use the following steps to generate an authentication token.
Navigate to the RHACS portal.
Go to Platform Configuration → Integrations.
Scroll down to the Authentication Tokens category, and click API Token.
Click Generate Token.
Enter a name for the token and select a role that provides the required level of access (for example, Continuous Integration or Sensor Creator).
Click Generate.
Copy the generated token and securely store it. You will not be able to view it again. |
After you have generated the authentication token, export it as
You can also save the token in a file and use it with the
|
You can install the roxctl
CLI to interact with Red Hat Advanced Cluster Security for Kubernetes from a
command-line interface. You can install roxctl
on Linux, Windows, or macOS.
You can install the roxctl
CLI binary on Linux by using the following procedure.
Download the latest version of the roxctl
CLI:
$ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.66.1/bin/Linux/roxctl
Make the roxctl
binary executable:
$ chmod +x roxctl
Place the roxctl
binary in a directory that is on your PATH
:
To check your PATH
, execute the following command:
$ echo $PATH
Verify the roxctl version you have installed:
$ roxctl version
You can install the roxctl
CLI binary on macOS by using the following procedure.
Download the latest version of the roxctl
CLI:
$ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.66.1/bin/Darwin/roxctl
Remove all extended attributes from the binary:
$ xattr -c roxctl
Make the roxctl
binary executable:
$ chmod +x roxctl
Place the roxctl
binary in a directory that is on your PATH
:
To check your PATH
, execute the following command:
$ echo $PATH
Verify the roxctl version you have installed:
$ roxctl version
You can install the roxctl
CLI binary on Windows by using the following procedure.
Download the latest version of the roxctl
CLI:
$ curl -O https://mirror.openshift.com/pub/rhacs/assets/3.66.1/bin/Windows/roxctl.exe
Verify the roxctl version you have installed:
$ roxctl version
The roxctl
client is the default entry point in Red Hat Advanced Cluster Security for Kubernetes roxctl
image.
To run the roxctl
client in a container image:
Log in to the registry.redhat.io
registry.
$ docker login registry.redhat.io
Pull the latest container image for the roxctl
CLI.
$ docker pull registry.redhat.io/rh-acs/roxctl:3.66.1
After you install the CLI, you can run it by using the following command:
$ docker run -e ROX_API_TOKEN=$ROX_API_TOKEN \
-it registry.redhat.io/rh-acs/roxctl:3.66.1 \
-e $ROX_CENTRAL_ADDRESS <command>
Verify the roxctl version you have installed.
$ docker run -it registry.redhat.io/rh-acs/roxctl:3.66.1 version
After you have finished these procedures, the next step is to integrate with your CI pipeline.
Each CI system might require a slightly different configuration.
Use the StackRox Container Image Scanner Jenkins plugin for integrating with Jenkins. You can use this plugin in both Jenkins freestyle projects and pipelines.
You can integrate Red Hat Advanced Cluster Security for Kubernetes with CircleCI.
You have a token with read
and write
permissions for the Image
resource.
You have a username and password for your Docker Hub account.
Log in to CircleCI and open an existing project or create a new project.
Click Project Settings.
Click Environment variables.
Click Add variable and create the following three environment variables:
Name: STACKROX_CENTRAL_HOST - The DNS name or IP address of Central.
Name: ROX_API_TOKEN - The API token to access Red Hat Advanced Cluster Security for Kubernetes.
Name: DOCKERHUB_PASSWORD - The password for your Docker Hub account.
Name: DOCKERHUB_USER - The username for your Docker Hub account.
Create a directory called .circleci
in the root directory of your local code repository for your selected project, if you do not already have a CircleCI configuration file.
Create a config.yml
configuration file with the following lines in the .circleci
directory:
version: 2
jobs:
check-policy-compliance:
docker:
- image: 'circleci/node:latest'
auth:
username: $DOCKERHUB_USER
password: $DOCKERHUB_PASSWORD
steps:
- 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>" (1)
- run:
name: Scan deployment files for policy deviations
command: |
./roxctl image check --endpoint "$STACKROX_CENTRAL_HOST:443" --image "<your_deployment_file>" (2)
# Important note: This step assumes the YAML file you'd like to test is located in the project.
workflows:
version: 2
build_and_test:
jobs:
- check-policy-compliance
1 | Replace <your_registry/repo/image_name> with your registry and image path. |
2 | Replace <your_deployment_file> with the path to your deployment file. |
If you already have a |
After you commit the configuration file to your repository, navigate to the Jobs queue in your CircleCI dashboard to verify the build policy enforcement.