Artifact Integrity

The Artifact Integrity policy ensures that container images in your registries were built by your organization's CI/CD pipeline, and not pushed from an unknown or unauthorized source, such as a developer's local machine or a malicious actor.

The main goals are:

• Verifying artifact origin prevents the risk of running images that might be tampered with or injected with malicious code.

• Providing assurance that all deployed artifacts are traceable to your build process.

Currently OX Security supports artifact integrity in GitLab and GitHub pipelines.

Verifying artifact integrity in container images contains the following steps:

1. Update images with metadata labels

2. Enable the Artifact Integrity policy and exlude trusted images

3. Run a security scan

4. Analyze the results

Prerequisites

Use the following environment variables in your pipeline:

• For GitLab: CI_PROJECT_ID, CI_JOB_ID

• For GitHub: GITHUB_REPOSITORY, GITHUB_RUN_ID

Updating your CI/CD pipelines with labels

When building the image, you need to include specific metadata labels in the image. Then, during the security scan, OX Security analyzes image labels and corresponding pipeline logs to ensure the integrity and trustworthiness of the image, as follows:

• If OX finds a match in the build logs, the image is marked as verified.

• If no match is found, the image is flagged as unverified, and you are advised to review it.

The labels are added to the docker build command during the Docker build process. The label keys are the same for all CI/CD systems, but the values differ depending on the platform.

Important: Do not use docker build --push. Use separate docker build and docker push commands. This ensures the image hash is visible and can be verified during artifact integrity checks.

Docker build command example:

docker build -t $YOUR_IMAGE_NAME \
  --label "security.ox.image.ci.repo.id=..." \
  --label "security.ox.image.ci.job.id=..." \
  --label "security.ox.image.ci.source=..."

docker push $YOUR_IMAGE_NAME

Before the scan

Before running a scan on the container image to which you have added the metadata labels, you need to enable the policy that verifies the image.

In addition, you can exclude images from scan by name or registry name.

To enable the Artifact Integrity policy:

1. In the OX Security platform, go to Policies > Artifact Integrity.

1. Enable Registry artifact not from CI/CD.

2. To reduce load during the scan, exclude trusted images, as follows: in the Trusted registries and images box, add trusted images/registries names.

1. To save your policy definitions, select SAVE AS or SAVE.

Analyzing the container image scan results

After running a security scan, you can view the artifact integrity status and plan your further actions.

To view the artifact integrity status:

1. In the Artifact BOM page, select the image you have scanned and check the artifact integrity status in the image overview.

The following integrity statuses are available:

1. When artifact integrity is not verified, a new security issue is added in the Issues page.

The following issue types can be added by OX Security: