Docker Image Scanning in CI/CD Pipelines

OX Security supports scanning container images immediately after they are built in your CI/CD pipeline. This allows you to detect vulnerabilities at the earliest possible stage, before the image is pushed to a registry or used in any runtime environment.

The scan is performed as a dedicated pipeline step, using an OX-provided scanner image and configuration. The integration runs within CI/CD pipelines for repositories that are monitored in OX.

Note: OX supports scanning compressed container images up to 2 GB. Images that exceed this size are not scanned.

First, you need to configure container scanning, and then you can view the results as follows:

1. Pipeline Configuration (Outside OX)

2. Workflow Configuration (Inside OX)

3. Viewing Scan Results

Pipeline Configuration

To scan Docker images during pipeline execution, you must add a new step to your CI/CD configuration. OX provides a Docker image published on Docker Hub that runs the scanner: https://hub.docker.com/r/oxsecurity/ox-image-scanner.

Prerequisites

• OX CI/CD Integration key

• Docker image name and tag to be scanned

• CI/CD environment that supports injecting environment variables

• CI/CD environment that supports mounting the host's Docker socket into the container, OR providing remote access to the Docker daemon using TCP

Environment Variables

The scanner is configured entirely through environment variables.

On GitHub Actions, every variable below can also be supplied with an INPUT_ prefix (for example, INPUT_OX_API_KEY).

Core configuration

Variable	Required	Default	Description
OX_API_KEY	Yes	—	Authentication credentials for the OX platform.
OX_HOST_URL	Yes	https://api.cloud.ox.security	The default URL applies to the OX SaaS platform. For on-premises deployments, the Host URL depends on the customer's environment/setup.
OX_MODE	Yes	scan	Set to docker_scan to run the container image scanner.

Selecting the image to scan

Provide the image by name plus a tag or digest, or point directly at a pre-saved image tarball.

Variable	Description
OX_ARTIFACT_NAME	Name of the Docker image to scan (for example, myregistry.com/myapp).
OX_ARTIFACT_TAG	Tag of the image to scan (for example, v1.0.0 or latest). Provide either a tag or a digest.
OX_ARTIFACT_DIGEST	Pin the image by digest instead of a tag. Provide either a tag or a digest.
OX_ARTIFACT_TYPE	Type of artifact being scanned. Accepts dockerimage.
OX_REGISTRY_TYPE	Registry type for the image. Accepts awsecr for Amazon Elastic Container Registry.
OX_ARTIFACT_PATH	Path to a pre-saved image tarball. When set, the image is scanned directly from the file instead of being pulled from the Docker daemon — skipping the image export step. When provided, OX_ARTIFACT_NAME and the tag/digest become optional.
OX_DOCKER_TARGET_PLATFORM	Target platform for multi-architecture images (for example, linux/amd64 or linux/arm64).

Reliability and performance

Variable	Required	Default	Description
OX_TIMEOUT	No	20	Overall scan timeout, in minutes.
OX_CVE_ONLY	No	false	When true, skips secret scanning and scans for CVEs only.
OX_DOCKER_SAVE_MAX_RETRIES	No	3	Number of retry attempts when exporting the image from the Docker daemon.
OX_DOCKER_SAVE_RETRY_DELAY_MS	No	3000	Delay between export retry attempts, in milliseconds.
OX_CACHE_DIR	No	—	Absolute path to a mounted directory where the scanner keeps its package cache between builds. Speeds up repeated scans of Java images. See Reusing the package cache

Reusing the package cache

Resolving JAR files to their Maven coordinates requires a package database of approximately 913 MiB that is not bundled in the scanner image. By default, the scanner keeps the database inside the container, so it is retrieved again on each build.

This is noticeable only when scanning Java images, mainly when runners are ephemeral or outbound traffic passes through a proxy that inspects large transfers.

The cache directory must be writable by UID 1000, which is the user the scanner runs as. The directory must not be located inside the workspace .ox directory because that directory is cleared on every run. Allow approximately 2 GB of storage for the cache.

The first build after you configure the cache still retrieves the database. Subsequent builds reuse it. A cached database is not re-verified, so the cache directory should be writable only by your scan jobs.

If you use ephemeral runners, a host directory does not persist between builds. Use your CI cache mechanism to restore the directory instead, and reapply ownership after a cache hit.

To reuse the package cache:

1. Create the cache directory once on each runner:

   sudo mkdir -p /opt/ox-scanner-cache
   sudo chown 1000:1000 /opt/ox-scanner-cache

2. Mount the cache directory and set OX_CACHE_DIR for every scan:

   -v /opt/ox-scanner-cache:/ox-cache \
   -e OX_CACHE_DIR=/ox-cache

Build behavior and failure handling

Variable	Default	Description
OX_FAIL_ON_TIMEOUT	false	When true, fails the pipeline job if the scan times out.
OX_FAIL_ON_ERROR	false	When true, fails the pipeline job if the scan encounters an error.
OX_OVERRIDE_BLOCKING	false	When true, prevents blocking issues from failing the build.
OX_EXIT_CODE_SUCCESS	0	Exit code returned on a successful scan.
OX_EXIT_CODE_WARNING	0	Exit code returned when the scan completes with warnings.
OX_EXIT_CODE_ERROR	1	Exit code returned when the scan fails with an error.

Output

Variable	Description
OX_OUTPUT	File path to write the scan results to.

Debugging and security

Variable	Default	Description
OX_DISABLE_SSL_VALIDATION	false	When true, disables TLS certificate validation. Use only in trusted environments — disabling certificate validation exposes connections to interception.

Custom Request Headers

Set these when the OX platform is reachable only through an access proxy that requires service-token headers, such as Cloudflare Access. No dedicated image is required, the standard oxsecurity/ox-image-scanner image reads them.

Variable	Description
CF_ACCESS_CLIENT_ID	Sent as the CF-Access-Client-Id request header on requests to the OX API. Set this only when your OX deployment sits behind an access proxy that requires service-token headers, such as Cloudflare Access.
CF_ACCESS_CLIENT_SECRET	Sent as the CF-Access-Client-Secret request header on requests to the OX API. Use together with CF_ACCESS_CLIENT_ID.

Scanning Methods

The OX container scanner supports two ways to access the image, as follows:

• Connecting to a running Docker daemon and identifying the image by name and tag

• Skipping the daemon entirely and pointing the scanner at a pre-saved image tarball.

Both methods produce the same scan results; the choice depends on what your CI/CD environment supports and how your pipeline is structured.

Scanning with Docker daemon

The scanner connects to a running Docker daemon, which exports the image by name and tag for scanning. This is the default method.

Variable	Description
DOCKER_HOST	Address of the Docker daemon. Use a mounted socket such as unix:///var/run/docker.sock (local default), or a remote endpoint such as tcp://192.168.1.100:2375.

When the image is not already present locally and must be pulled from a registry, the pull uses the credentials configured on the Docker daemon.

Set OX_ARTIFACT_NAME and OX_ARTIFACT_TAG (or OX_ARTIFACT_DIGEST) to identify the image to scan.

Scanning with the Tarball file

Instead of connecting to a Docker daemon, you can save the image to a tarball file and point the scanner directly at it. The scanner reads the image from the file, bypassing the Docker daemon entirely.

Set OX_ARTIFACT_PATH to the path of the tarball. When this is set, OX_ARTIFACT_NAME and the tag/digest become optional, and DOCKER_HOST is not required.

This is useful when:

• Your CI/CD environment does not support Docker socket mounting.

• The image has already been built and saved to disk as part of an earlier pipeline step.

• You want to avoid an additional image export step.

Secret scanning size limit: Files larger than 2 MB are skipped during secret scanning.

System Requirements

Requirement Type	CPU	Memory
Minimum	1 core	512 MB RAM
Recommended	1–2 cores	1 GB RAM

CI/CD Platform Examples

The scanner automatically detects the CI/CD environment it runs in. Supported platforms include:

• GitHub Actions

• GitLab CI/CD

• Bitbucket Pipelines

• Jenkins

• Azure Pipelines and Azure DevOps

• BuildPiper

• Generic CI (set OX_GENERIC_CI when running in an unlisted environment)

Example: GitLab CI

image_scan:
  stage: scan
  image: oxsecurity/ox-image-scanner:latest
  variables:
    OX_API_KEY: <your_api_key>
    OX_HOST_URL: <your_host_url> 
    OX_ARTIFACT_NAME: <image_name>
    OX_ARTIFACT_TAG: <image_tag>
    DOCKER_HOST: <docker_host_url or path_to_socket, defaults to unix:///var/run/docker.sock>

Example: Azure Pipelines

- job: OX
  displayName: OX Security Image Scan
  steps:
    - script: |
        docker run \
          --rm \
          -e OX_API_KEY=<your_api_key> \
          -e OX_HOST_URL=<your_host_url> \
          -e OX_ARTIFACT_NAME=<image_name> \
          -e OX_ARTIFACT_TAG=<image_tag> \
          -e DOCKER_HOST=unix:///var/run/docker.sock \
          --env-file <(env | grep 'SYSTEM_\|BUILD_') \
          -v /var/run/docker.sock:/var/run/docker.sock \
          oxsecurity/ox-image-scanner:latest

Example: GitHub Actions

name: OX Image Scan

on: [push, pull_request]

jobs:
  ox-image-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Make the image available to the Docker daemon
        run: docker pull <image_name>:<image_tag>

      - name: OX image scan
        env:
          INPUT_OX_API_KEY: ${{ secrets.OX_API_KEY }}
        run: |
          docker run --rm \
        -v /var/run/docker.sock:/var/run/docker.sock \
        -e GITHUB_ACTIONS \
        -e GITHUB_SERVER_URL \
        -e GITHUB_REPOSITORY \
        -e GITHUB_RUN_ID \
        -e GITHUB_EVENT_NAME \
        -e GITHUB_REF \
        -e GITHUB_REF_NAME \
        -e GITHUB_SHA \
        -e INPUT_GITHUB_REPOSITORY_ID="$GITHUB_REPOSITORY_ID" \
        -e INPUT_OX_API_KEY \
        -e INPUT_OX_HOST_URL=<your_host_url> \
        -e INPUT_OX_MODE=docker_scan \
        -e INPUT_OX_ARTIFACT_NAME=<image_name> \
        -e INPUT_OX_ARTIFACT_TAG=<image_tag> \
        oxsecurity/ox-image-scanner:latest

Pipeline Workflow Configuration

After configuring the pipeline, you must define how OX handles the scan results. This is done in the Pipeline Workflows area of the OX platform.

To configure the workflow:

1. Go to Pipeline Workflows in the OX UI.

2. Drag the Container Security policy from the left panel into your active workflow.

3. Define actions based on issue severity or type (e.g., alert, block the pipeline).

1. Save the updated workflow.