> For the complete documentation index, see [llms.txt](https://docs.ox.security/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/docker-image-scanning-in-ci-cd-pipelines.md). # 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. First, you need to configure the container scanning, and then you can view the results, as follows: 1. [Pipeline Configuration (Outside OX)](#pipeline-configuration) 2. [Workflow Configuration (Inside OX)](#pipeline-workflow-configuration) 3. [Viewing Scan Results](/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/understanding-pipeline-scan-results.md) ### 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: . #### 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 | — | URL of the OX platform. | | `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 | Default | Description | | ------------------------------- | ------- | ------------------------------------------------------------------------- | | `OX_TIMEOUT` | `20` | Overall scan timeout, in minutes. | | `OX_CVE_ONLY` | `false` | When `true`, skips secret scanning and scans for CVEs only. | | `OX_DOCKER_SAVE_MAX_RETRIES` | `3` | Number of retry attempts when exporting the image from the Docker daemon. | | `OX_DOCKER_SAVE_RETRY_DELAY_MS` | `3000` | Delay between export retry attempts, in milliseconds. | #### 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. | ## 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. {% hint style="info" %} **Secret scanning size limit:** Files larger than 2 MB are skipped during secret scanning. {% endhint %} ### 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](https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/github-actions.md) * [GitLab CI/CD](https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/gitlab-ci-cd.md) * [Bitbucket Pipelines](https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/bitbucket-pipelines.md) * [Jenkins](https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/jenkins.md) * [Azure Pipelines and Azure DevOps](https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/integrating-source-control-platforms/direct-source-control-pipeline-integration/azure-pipelines-and-azure-devops.md) * BuildPiper * Generic CI (set `OX_GENERIC_CI` when running in an unlisted environment) #### Example: GitLab CI ```yaml image_scan: stage: scan image: oxsecurity/ox-image-scanner:latest variables: OX_API_KEY: OX_ARTIFACT_NAME: OX_ARTIFACT_TAG: DOCKER_HOST: ``` #### Example: Azure Pipelines ```yaml - job: OX displayName: OX Security Image Scan steps: - script: | docker run \ --rm \ -e OX_API_KEY= \ -e OX_ARTIFACT_NAME= \ -e OX_ARTIFACT_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 ``` ## 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.](/automate-with-ox-workflows/pipeline-workflows.md) **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).
4. Save the updated workflow. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.ox.security/scan-and-analyze-with-ox/scanning/scanning-ci-cd-pipelines/docker-image-scanning-in-ci-cd-pipelines.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.