Chapter 2. Integrating with CI systems

Procedure

1. In the RHACS portal, go to Platform Configuration Policy Management.
2. Use global search to search for Lifecycle Stage:Build.

Procedure

1. In the RHACS portal, go to Platform Configuration Policy Management.
2. Click + New Policy.
3. Enter the Name for the policy.
4. Select a Severity level for the policy: Critical, High, Medium, or Low.

5. 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.
6. 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.
7. Select a category from the Categories drop-down menu.

8. 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.

9. 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.
10. 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.

11. 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).

12. In the Policy Criteria section, configure the attributes that will trigger the policy.
13. Select Next on the panel header.
14. The new policy panel shows a preview of the violations that are triggered if you enable the policy.
15. Select Next on the panel header.

16. 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 next 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.

Procedure

1. In the RHACS portal, go to Platform Configuration Integrations.
2. Under the Image Integration section, look for highlighted Registry tiles. The tiles also list the number of items already configured for that tile.

Procedure

1. After you have generated the authentication token, export it as the ROX_API_TOKEN variable by entering the following command:

   $ export ROX_API_TOKEN=<api_token>

2. (Optional): You can also save the token in a file and use it with the --token-file option by entering the following command:

   $ roxctl central debug dump --token-file <token_file>

Procedure

1. Log in to the registry.redhat.io registry.

   $ docker login registry.redhat.io

2. Pull the latest container image for the roxctl CLI.

   $ docker pull registry.redhat.io/advanced-cluster-security/rhacs-roxctl-rhel8:4.6.1

Procedure

1. Log in to CircleCI and open an existing project or create a new project.
2. Click Project Settings.
3. Click Environment variables.

4. 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.
5. 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.

6. 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.

   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.

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