---
title: Container Image Scanning in CI/CD
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: >-
  Docs > Datadog Security > Cloud Security > Setting up Cloud Security >
  Container Image Scanning in CI/CD
---

# Container Image Scanning in CI/CD

## Overview{% #overview %}

Cloud Security enables you to scan container images for vulnerabilities during CI/CD, before images are deployed to production. By integrating vulnerability scanning directly into your pipelines, you can detect and remediate security issues early in the development lifecycle.

To support CI/CD-based container image scanning, Datadog provides the **Datadog Security CLI**. The CLI is designed to be run directly inside your CI jobs, giving you full control over when and how scans are executed as part of your pipelines.

**Note**: For vulnerability management in production environments, see [Cloud Security Vulnerabilities](https://docs.datadoghq.com/security/cloud_security_management/vulnerabilities).

## Get started{% #get-started %}

To get started with container image scanning in CI/CD:

1. Configure Datadog credentials
1. Install the Datadog Security CLI in your CI/CD pipeline
1. View scan results on the [Cloud Security Vulnerabilities](https://app.datadoghq.com/security/csm/vm) page
1. Optionally, run local scans during development for faster iteration

### Configure Datadog credentials{% #configure-datadog-credentials %}

To upload scan results to Datadog, configure the following environment variables in your CI pipeline:

| Name         | Description                                                                                                                                                                                                                        | Required | Default         |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------- |
| `DD_API_KEY` | Your Datadog API key. This key is created by your [Datadog organization](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys) and should be stored as a secret.                                                   | Yes      |
| `DD_APP_KEY` | Your Datadog application key. This key, created by your [Datadog organization](https://docs.datadoghq.com/account_management/api-app-keys/#application-keys), should include the `appsec_vm_read` scope and be stored as a secret. | Yes      |
| `DD_SITE`    | The [Datadog site](https://docs.datadoghq.com/getting_started/site/) to send information to. Your Datadog site is .                                                                                                                | No       | `datadoghq.com` |

{% alert level="info" %}
Store your API and application keys as secrets in your CI/CD platform to protect sensitive credentials.
{% /alert %}

### Install the Datadog Security CLI{% #install-the-datadog-security-cli %}

{% callout %}
##### Join the Preview

The Datadog Security CLI is in Preview and available to install from Datadog package repositories.
{% /callout %}

You can install Datadog Security CLI on Debian/Ubuntu, Red Hat/CentOS, and macOS systems. Container image scanning works with all major CI/CD platforms, including:

- GitHub Actions
- GitLab CI/CD
- Azure DevOps
- Other CI providers that can execute shell scripts

The customizable script approach gives you full control over when and how scans are executed in your pipelines. Choose your installation method below.

{% tab title="Debian/Ubuntu" %}
#### Install from package repository{% #install-from-package-repository %}

```bash
# Import Datadog APT signing key
DD_APT_KEY_URL="https://keys.datadoghq.com/DATADOG_APT_KEY_CURRENT.public"
curl -fsSL "$DD_APT_KEY_URL" | sudo gpg --dearmor -o /usr/share/keyrings/datadog-archive-keyring.gpg

# Add Datadog repository
echo "deb [signed-by=/usr/share/keyrings/datadog-archive-keyring.gpg] https://apt.datadoghq.com/ stable datadog-security-cli" \
| sudo tee /etc/apt/sources.list.d/datadog-security-cli.list

# Update package list and install
sudo apt update
sudo apt install datadog-security-cli
```

{% /tab %}

{% tab title="Red Hat/CentOS" %}
#### Install from package repository{% #install-from-package-repository %}

```bash
# Import Datadog RPM signing key
sudo rpm --import https://keys.datadoghq.com/DATADOG_RPM_KEY_CURRENT.public

# Add Datadog repository
sudo tee /etc/yum.repos.d/datadog-security-cli.repo > /dev/null <<'EOF'
[datadog-security-cli]
name=Datadog Security CLI
baseurl=https://yum.datadoghq.com/stable/datadog-security-cli/\$basearch/
enabled=1
gpgcheck=1
gpgkey=https://keys.datadoghq.com/DATADOG_RPM_KEY_CURRENT.public
repo_gpgcheck=1
EOF

# Install the CLI
sudo yum install datadog-security-cli
```

{% /tab %}

{% tab title="macOS" %}
#### Install with Homebrew{% #install-with-homebrew %}

```bash
# Install via Homebrew
brew install --cask datadog-security-cli
```

{% /tab %}

#### Run your first scan{% #run-your-first-scan %}

After installing the Datadog Security CLI, configure your Datadog credentials and scan a container image:

```bash
# Configure Datadog credentials
export DD_API_KEY=<your_api_key>
export DD_APP_KEY=<your_app_key>
export DD_SITE=

# Scan your container image
datadog-security-cli image myimage:tag
```

The CLI outputs scan results directly to your terminal, showing:

- Image information (name, digest, operating system)
- Total number of vulnerabilities found
- Severity breakdown (Critical, High, Medium, Low)
- Detailed table of vulnerabilities with CVE IDs, affected packages, and available fixes

{% image
   source="https://datadog-docs.imgix.net/images/security/vulnerabilities/csm-vm-cli-output.830bcbac59d2431e9e6b88146831350b.png?auto=format"
   alt="Datadog Security CLI output showing vulnerability scan results for a container image" /%}

### View scan results{% #view-scan-results %}

After running your first scan, results appear on the [Cloud Security Vulnerabilities](https://app.datadoghq.com/security/csm/vm) page within minutes. You can:

- **Filter by resource type**: View vulnerabilities specific to container images scanned in CI/CD
- **Prioritize by severity**: Focus on critical and high-severity vulnerabilities first
- **Track remediation**: Assign vulnerabilities to team members and track resolution
- **Set up notifications**: Get alerted when new critical vulnerabilities are detected

{% image
   source="https://datadog-docs.imgix.net/images/security/vulnerabilities/csm-vm-explorer-actionability-2.63a73c19e78e6a12bba978668a76fcc5.png?auto=format"
   alt="The Cloud Security Vulnerabilities Findings page" /%}

### Run local scans during development{% #run-local-scans-during-development %}

For faster iteration before committing to CI, install the Datadog Security CLI locally using the same installation methods described in the installation section above.

#### Scan locally without persisting results{% #scan-locally-without-persisting-results %}

When testing locally, scan images without uploading results to Datadog using the `--no-persist` flag:

```bash
# Scan locally without sending results to Datadog
datadog-security-cli image myapp:latest --no-persist
```

This is useful for:

- Testing the CLI functionality without affecting your Datadog data
- Validating container images during local development
- Iterating quickly on image builds before committing to CI

## Scan options{% #scan-options %}

The Datadog Security CLI supports various options to customize your container image scans:

### Configure severity thresholds{% #configure-severity-thresholds %}

```bash
# Fail the build if critical vulnerabilities are found
datadog-security-cli image myapp:latest --fail-on critical

# Fail on high or critical vulnerabilities
datadog-security-cli image myapp:latest --fail-on high
```

### Output formats{% #output-formats %}

```bash
# Output results in JSON format
datadog-security-cli image myapp:latest --output json
```

## Link Dockerfile to vulnerabilities{% #link-dockerfile-to-vulnerabilities %}

To enable Datadog to link detected vulnerabilities back to the source code (Dockerfile), you must include specific **OCI image annotations** when building your container image.

This allows Datadog to:

- Display a **preview of the Dockerfile** directly in the Container Image Vulnerabilities panel
- Enable **source-based remediation**, helping you identify and fix issues in context

These annotations provide the metadata needed to associate a scanned image with its corresponding repository, commit, and Dockerfile path.

### Required annotations{% #required-annotations %}

Add the following annotations to your image at build time:

- `org.opencontainers.image.source` The repository URL (for example, `https://github.com/org/repo`)

- `org.opencontainers.image.revision` The commit SHA used to build the image

- `com.datadoghq.image.source_path` The path to the Dockerfile within the repository (for example, `Dockerfile` or `docker/Dockerfile`)

### Optional annotations{% #optional-annotations %}

These annotations help Datadog improve base image remediation suggestions:

- `org.opencontainers.image.base.name` The base image name (for example, `ubuntu:22.04`)

- `org.opencontainers.image.base.digest` The base image digest

For more details, see the [OCI Image Spec annotations documentation](https://specs.opencontainers.org/image-spec/annotations/).

### Example{% #example %}

#### Using docker build{% #using-docker-build %}

Annotations are the preferred method. Labels are also supported as a fallback.

```bash
docker build \
  --annotation org.opencontainers.image.source="https://github.com/org/repo" \
  --annotation org.opencontainers.image.revision="$(git rev-parse HEAD)" \
  --annotation com.datadoghq.image.source_path="Dockerfile" \
  -t myapp:latest .
```

#### Using the Datadog Security CLI{% #using-the-datadog-security-cli %}

As an alternative to adding annotations manually, the Datadog Security CLI can inject the required metadata directly when scanning, using the `--dockerfile` flag:

```bash
datadog-security-cli image myapp:latest --dockerfile ./Dockerfile
```

## Troubleshooting{% #troubleshooting %}

### Authentication errors{% #authentication-errors %}

If you encounter authentication errors:

1. Verify your `DD_API_KEY` and `DD_APP_KEY` are correctly set.
1. Ensure the application key has the `appsec_vm_read` scope.
1. Check that your `DD_SITE` matches your Datadog organization's site.

### Image not found errors{% #image-not-found-errors %}

If the CLI cannot find your image:

1. Verify the image exists locally: `docker images`.
1. Use the full image name, including registry (if applicable).
1. Ensure the image is built before scanning.

### Network connectivity issues{% #network-connectivity-issues %}

If scans fail due to network issues:

1. Verify your CI environment can reach the Datadog site.
1. Check for proxy or firewall restrictions.
1. Ensure outbound HTTPS connections are allowed.

For additional help, see the [Cloud Security troubleshooting guide](https://docs.datadoghq.com/security/cloud_security_management/troubleshooting/vulnerabilities/) or contact [Datadog support](https://docs.datadoghq.com/help/).

## Further reading{% #further-reading %}

- [Cloud Security Vulnerabilities](https://docs.datadoghq.com/security/cloud_security_management/vulnerabilities)
- [Viewing Container Images](https://docs.datadoghq.com/infrastructure/containers/container_images)
- [Setting up the Datadog Agent for Cloud Security](https://docs.datadoghq.com/security/cloud_security_management/setup/agent)