Chapter 2. Integrating with CI systems Red Hat Advanced Cluster Security for Kubernetes (RHACS) integrates with a variety of continuous integration (CI) products. Before you deploy images, you can use RHACS to apply build-time and deploy-time security rules to your images. After images are built and pushed to a registry, RHACS integrates into CI pipelines. 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, configure the version control system to block pull or merge requests from being merged if the build stage, which includes RHACS checks, fails. The integration with your CI product functions by contacting your RHACS installation to check whether the image complies with build-time 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-time 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 build policies . Configure a registry integration . Configure access to your RHACS instance. Integrate with your CI pipeline . 2.1. Configuring build policies You can check RHACS policies during builds. Procedure Configure policies that apply to the build time of the container lifecycle. Integrate with the registry that images are pushed to during the build. Additional resources Integrating with image registries 2.1.1. Checking existing build-time policies Use the RHACS portal to check any existing build-time policies that you have configured in Red Hat Advanced Cluster Security for Kubernetes. Procedure In the RHACS portal, go to Platform Configuration Policy Management . Use global search to search for Lifecycle Stage:Build . 2.1.2. Creating a new system policy In addition to using the default policies, you can also create custom policies in Red Hat Advanced Cluster Security for Kubernetes. Procedure In the RHACS portal, go to Platform Configuration Policy Management . 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. Note 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, and 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. Note You must integrate RHACS 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 RHACS. 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. Note 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 on the panel header. The new policy panel shows a preview of the violations that are triggered if you enable the policy. Select 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. Note The enforcement behavior is different for each lifecycle stage. For the Build stage, RHACS fails your CI builds when images match the conditions of the policy. For the Deploy stage, RHACS blocks the creation and update of deployments that match the conditions of the policy if the RHACS admission controller is configured and running. In clusters with admission controller enforcement, the Kubernetes or OpenShift Container Platform API server blocks all noncompliant deployments. In other clusters, RHACS edits noncompliant deployments to prevent pods from being scheduled. For existing deployments, policy changes only result in enforcement at the detection of the criteria, when a Kubernetes event occurs. For more information about enforcement, see "Security policy enforcement for the deploy stage". For the Runtime stage, RHACS stops all pods that match the conditions of the policy. Warning 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. 2.1.2.1. Security policy enforcement for the deploy stage Red Hat Advanced Cluster Security for Kubernetes supports two forms of security policy enforcement for deploy-time policies: hard enforcement through the admission controller and soft enforcement by RHACS Sensor. The admission controller blocks creation or updating of deployments that violate policy. If the admission controller is disabled or unavailable, Sensor can perform enforcement by scaling down replicas for deployments that violate policy to 0 . Warning 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. 2.1.2.1.1. Hard enforcement Hard enforcement is performed by the RHACS admission controller. In clusters with admission controller enforcement, the Kubernetes or OpenShift Container Platform API server blocks all noncompliant deployments. The admission controller blocks CREATE and UPDATE operations. Any pod create or update request that satisfies a policy configured with deploy-time enforcement enabled will fail. Note Kubernetes admission webhooks support only CREATE , UPDATE , DELETE , or CONNECT operations. The RHACS admission controller supports only CREATE and UPDATE operations. Operations such as kubectl patch , kubectl set , and kubectl scale are PATCH operations, not UPDATE operations. Because PATCH operations are not supported in Kubernetes, RHACS cannot perform enforcement on PATCH operations. For blocking enforcement, you must enable the following settings for the cluster in RHACS: Enforce on Object Creates : This toggle in the Dynamic Configuration section controls the behavior of the admission control service. You must have the Configure Admission Controller Webhook to listen on Object Creates toggle in the Static Configuration section turned on for this to work. Enforce on Object Updates : This toggle in the Dynamic Configuration section controls the behavior of the admission control service. You must have the Configure Admission Controller Webhook to listen on Object Updates toggle in the Static Configuration section turned on for this to work. If you make changes to settings in the Static Configuration setting, you must redeploy the secured cluster for those changes to take effect. 2.1.2.1.2. Soft enforcement Soft enforcement is performed by RHACS Sensor. This enforcement prevents an operation from being initiated. With soft enforcement, Sensor scales the replicas to 0, and prevents pods from being scheduled. In this enforcement, a non-ready deployment is available in the cluster. If soft enforcement is configured, and Sensor is down, then RHACS cannot perform enforcement. 2.1.2.1.3. Namespace exclusions By default, RHACS excludes certain administrative namespaces, such as the stackrox , kube-system , and istio-system namespaces, from enforcement blocking. The reason for this is that some items in these namespaces must be deployed for RHACS to work correctly. 2.1.2.1.4. Enforcement on existing deployments For existing deployments, policy changes only result in enforcement at the detection of the criteria, when a Kubernetes event occurs. If you make changes to a policy, you must reassess policies by selecting Policy Management and clicking Reassess All . This action applies deploy policies on all existing deployments regardless of whether there are any new incoming Kubernetes events. If a policy is violated, then RHACS performs enforcement. Additional resources Using admission controller enforcement 2.2. Configuring registry integration 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. 2.2.1. Checking for existing registry integration You can use the RHACS portal to check if you have already integrated with a registry. Procedure In the RHACS portal, go 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. 2.2.1.1. Additional resources Integrating with image registries 2.3. Configuring access RHACS provides the roxctl command-line interface (CLI) to make it easy to integrate RHACS 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. 2.3.1. Exporting and saving the API token Procedure After you have generated the authentication token, export it as the ROX_API_TOKEN variable by entering the following command: USD export ROX_API_TOKEN=<api_token> (Optional): You can also save the token in a file and use it with the --token-file option by entering the following command: USD roxctl central debug dump --token-file <token_file> Note the following guidelines: You cannot use both the -password ( -p ) and the --token-file options simultaneously. If you have already set the ROX_API_TOKEN variable, and specify the --token-file option, the roxctl CLI uses the specified token file for authentication. If you have already set the ROX_API_TOKEN variable, and specify the --password option, the roxctl CLI uses the specified password for authentication. 2.3.2. Installing the roxctl CLI by downloading the binary 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. 2.3.2.1. Installing the roxctl CLI on Linux You can install the roxctl CLI binary on Linux by using the following procedure. Note roxctl CLI for Linux is available for amd64 , arm64 , ppc64le , and s390x architectures. Procedure Determine the roxctl architecture for the target operating system: USD arch="USD(uname -m | sed "s/x86_64//")"; arch="USD{arch:+-USDarch}" Download the roxctl CLI: USD curl -L -f -o roxctl "https://mirror.openshift.com/pub/rhacs/assets/4.5.6/bin/Linux/roxctlUSD{arch}" Make the roxctl binary executable: USD chmod +x roxctl Place the roxctl binary in a directory that is on your PATH : To check your PATH , execute the following command: USD echo USDPATH Verification Verify the roxctl version you have installed: USD roxctl version 2.3.2.2. Installing the roxctl CLI on macOS You can install the roxctl CLI binary on macOS by using the following procedure. Note roxctl CLI for macOS is available for amd64 and arm64 architectures. Procedure Determine the roxctl architecture for the target operating system: USD arch="USD(uname -m | sed "s/x86_64//")"; arch="USD{arch:+-USDarch}" Download the roxctl CLI: USD curl -L -f -o roxctl "https://mirror.openshift.com/pub/rhacs/assets/4.5.6/bin/Darwin/roxctlUSD{arch}" Remove all extended attributes from the binary: USD xattr -c roxctl Make the roxctl binary executable: USD chmod +x roxctl Place the roxctl binary in a directory that is on your PATH : To check your PATH , execute the following command: USD echo USDPATH Verification Verify the roxctl version you have installed: USD roxctl version 2.3.2.3. Installing the roxctl CLI on Windows You can install the roxctl CLI binary on Windows by using the following procedure. Note roxctl CLI for Windows is available for the amd64 architecture. Procedure Download the roxctl CLI: USD curl -f -O https://mirror.openshift.com/pub/rhacs/assets/4.5.6/bin/Windows/roxctl.exe Verification Verify the roxctl version you have installed: USD roxctl version 2.3.3. Running the roxctl CLI from a container The roxctl client is the default entry point in the RHACS roxctl image. To run the roxctl client in a container image: Prerequisites You must first generate an authentication token from the RHACS portal. Procedure Log in to the registry.redhat.io registry. USD docker login registry.redhat.io Pull the latest container image for the roxctl CLI. USD docker pull registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:4.5.6 After you install the CLI, you can run it by using the following command: USD docker run -e ROX_API_TOKEN=USDROX_API_TOKEN \ -it registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:4.5.6 \ -e USDROX_CENTRAL_ADDRESS <command> Note In Red Hat Advanced Cluster Security Cloud Service (RHACS Cloud Service), when using roxctl commands that require the Central address, use the Central instance address as displayed in the Instance Details section of the Red Hat Hybrid Cloud Console. For example, use acs-ABCD12345.acs.rhcloud.com instead of acs-data-ABCD12345.acs.rhcloud.com . Verification Verify the roxctl version you have installed. USD docker run -it registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:4.5.6 version 2.4. Integrating with your CI pipeline After you have finished these procedures, the step is to integrate with your CI pipeline. Each CI system might require a slightly different configuration. 2.4.1. Using Jenkins Use the StackRox Container Image Scanner Jenkins plugin for integrating with Jenkins. You can use this plugin in both Jenkins freestyle projects and pipelines. 2.4.2. Using CircleCI You can integrate Red Hat Advanced Cluster Security for Kubernetes with CircleCI. Prerequisites You have a token with read and write permissions for the Image resource. You have a username and password for your Docker Hub account. Procedure 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: USDDOCKERHUB_USER password: USDDOCKERHUB_PASSWORD steps: - checkout - run: name: Install roxctl command: | curl -H "Authorization: Bearer USDROX_API_TOKEN" https://USDSTACKROX_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 "USDSTACKROX_CENTRAL_HOST:443" --image "<your_registry/repo/image_name>" 1 - run: name: Scan deployment files for policy deviations command: | ./roxctl image check --endpoint "USDSTACKROX_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. Note 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. After you commit the configuration file to your repository, go to the Jobs queue in your CircleCI dashboard to verify the build policy enforcement.

Commands:
export ROX_API_TOKEN=<api_token>
roxctl central debug dump --token-file <token_file>
arch="USD(uname -m | sed "s/x86_64//")"; arch="USD{arch:+-USDarch}"
curl -L -f -o roxctl "https://mirror.openshift.com/pub/rhacs/assets/4.5.6/bin/Linux/roxctlUSD{arch}"
chmod +x roxctl
echo USDPATH
roxctl version
arch="USD(uname -m | sed "s/x86_64//")"; arch="USD{arch:+-USDarch}"
curl -L -f -o roxctl "https://mirror.openshift.com/pub/rhacs/assets/4.5.6/bin/Darwin/roxctlUSD{arch}"
xattr -c roxctl
chmod +x roxctl
echo USDPATH
roxctl version
curl -f -O https://mirror.openshift.com/pub/rhacs/assets/4.5.6/bin/Windows/roxctl.exe
roxctl version
docker login registry.redhat.io
docker pull registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:4.5.6
docker run -e ROX_API_TOKEN=USDROX_API_TOKEN -it registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:4.5.6 -e USDROX_CENTRAL_ADDRESS <command>
docker run -it registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:4.5.6 version
version: 2 jobs: check-policy-compliance: docker: - image: 'circleci/node:latest' auth: username: USDDOCKERHUB_USER password: USDDOCKERHUB_PASSWORD steps: - checkout - run: name: Install roxctl command: | curl -H "Authorization: Bearer USDROX_API_TOKEN" https://USDSTACKROX_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 "USDSTACKROX_CENTRAL_HOST:443" --image "<your_registry/repo/image_name>" 1 - run: name: Scan deployment files for policy deviations command: | ./roxctl image check --endpoint "USDSTACKROX_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