From 3c8619fada21c8d8a8f3f29c44fc5c7a71e8159f Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Tue, 14 Jul 2026 14:01:07 -0700 Subject: [PATCH 1/5] dhi: apply scout policy Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/_index.md | 4 +- content/manuals/dhi/how-to/policies.md | 238 +++++++++++++++++-------- content/manuals/dhi/resources.md | 3 + 3 files changed, 168 insertions(+), 77 deletions(-) diff --git a/content/manuals/dhi/how-to/_index.md b/content/manuals/dhi/how-to/_index.md index 2b1177955014..eb616dbf1210 100644 --- a/content/manuals/dhi/how-to/_index.md +++ b/content/manuals/dhi/how-to/_index.md @@ -49,8 +49,8 @@ params: icon: bug-ant link: /dhi/how-to/scan/ grid_govern: - - title: Enforce Docker Hardened Image usage with policies - description: Learn how to use image policies with Docker Scout for Docker Hardened Images. + - title: Apply Docker Hardened Image policies to your images + description: Learn how to hold your own images to Docker Hardened Image security and compliance standards using the Docker Scout CLI. icon: shield-check link: /dhi/how-to/policies/ --- diff --git a/content/manuals/dhi/how-to/policies.md b/content/manuals/dhi/how-to/policies.md index 853625193e33..00f5c82deb7c 100644 --- a/content/manuals/dhi/how-to/policies.md +++ b/content/manuals/dhi/how-to/policies.md @@ -1,57 +1,81 @@ --- -title: Enforce Docker Hardened Image usage with policies -linktitle: Enforce image usage -description: Learn how to use image policies with Docker Scout for Docker Hardened Images. +title: Apply Docker Hardened Image policies to your images +linktitle: Apply image policies +description: Learn how to hold your own images to Docker Hardened Image security and compliance standards using the Docker Scout CLI. weight: 50 -keywords: docker scout policies, enforce image compliance, container security policy, image provenance, vulnerability policy check +keywords: docker scout policies, image security policy, container compliance, dhi policies, vulnerability policy check --- -When you have a Docker Hardened Images Enterprise subscription, mirroring a -Docker Hardened Image (DHI) repository automatically enables [Docker -Scout](/scout/), allowing you to start enforcing security and compliance -policies for your images without additional setup. Using Docker Scout policies, -you can define and apply rules that ensure only approved and secure images, such -as those based on DHIs, are used across your environments. +Docker publishes the set of security and compliance policies that Docker +Hardened Images (DHIs) are built to meet, so you can hold your own images to the +same standards. You evaluate images against these policies with the +[`docker scout policy`](../../scout/policy/local.md) command. + +These policies encode requirements such as running as a non-root user, being +free of fixable critical and high vulnerabilities, containing no embedded +malware or secrets, and shipping signed supply chain attestations. They don't +verify whether an image is a DHI or built on a DHI base image; they check +whether an image meets the same bar that DHIs are held to. + +Unlike the built-in Docker Scout policies, the DHI policies aren't embedded in +the CLI. They're maintained as Rego source in the +[`docker-hardened-images/policies`](https://github.com/docker-hardened-images/policies) +repository and published as an OCI policy bundle at +[`dhi/policies`](https://hub.docker.com/repository/docker/dhi/policies/general). +You pull the bundle at evaluation time with the `--policy-bundle` flag, so you +can apply DHI standards locally, in CI, or both, without sending any data to the +Docker Scout service. + +## Policies in the DHI bundle + +The `dhi/policies` bundle includes the following policies: + +| Policy | What it checks | +| --- | --- | +| No default root user for non-dev images | The image is configured to run as a non-root user. | +| No fixable vulnerabilities past their remediation SLA | No fixable CVEs remain unaddressed past their remediation SLA (7 days for critical and high, 30 days for others). | +| No high-profile vulnerabilities | The image is free of a curated list of well-known CVEs, optionally including the CISA KEV catalog. | +| No embedded malware | A malware scan attestation is present and passing. | +| No embedded secrets | A secret scan attestation is present and passing. | +| No failing tests | A test attestation is present and passing. | +| Signed supply chain attestations | SBOM and provenance attestations are attached and signed. | +| Unintentional shell or package manager | No undeclared shell or package manager is present in the image. | +| STIG scan | For FIPS-compliant images, the STIG scan meets the required score. | + +For the authoritative list and the Rego source for each policy, see the +[`docker-hardened-images/policies`](https://github.com/docker-hardened-images/policies) +repository. + +## Prerequisites + +- The [Docker Scout CLI plugin](/manuals/scout/install.md). It's included with + Docker Desktop. +- Access to pull the `dhi/policies` bundle from Docker Hub. Authentication uses + your existing Docker registry credentials, so sign in first: + + ```console + $ docker login + ``` + +## Evaluate an image against the DHI policies + +To evaluate an image against the DHI policy bundle, pass the bundle reference to +`docker scout policy` with the `--policy-bundle` flag: -Docker Scout includes a dedicated **Valid Docker Hardened Image (DHI) or DHI -base -image** -policy type that validates whether your images are Docker Hardened Images or are -built using a DHI as the base image. This policy checks for valid Docker signed -verification summary attestations. - -With policy evaluation built into Docker Scout, you can monitor image compliance -in real time, integrate checks into your CI/CD workflows, and maintain -consistent standards for image security and provenance. - -## View existing policies - -To see the current policies applied to a mirrored DHI repository: - -1. Go to the mirrored DHI repository in [Docker Hub](https://hub.docker.com). -2. Select **View on Scout**. - - This opens the [Docker Scout dashboard](https://scout.docker.com), where you - can see which policies are currently active and whether your images meet the - policy criteria. - -Docker Scout automatically evaluates policy compliance when new images are -pushed. Each policy includes a compliance result and a link to the affected -images and layers. - -## Evaluate DHI policy compliance for your images - -When you enable Docker Scout for your repositories, you can configure the -**Valid Docker Hardened Image (DHI) or DHI base -image** -policy. This optional policy validates whether your images are DHIs or built with DHI -base images by checking for Docker signed verification summary attestations. +```console +$ docker scout policy --policy-bundle dhi/policies:latest +``` -The following example shows how to build an image using a DHI base image and -evaluate its compliance with the DHI policy. +The CLI pulls the bundle, indexes the image into an SBOM, enriches it with CVE +and VEX data, and evaluates each policy in the bundle against that data. Bundles +are cached by digest, so re-running against the same bundle doesn't re-download +it. ### Example: Build and evaluate a DHI-based image +The following example builds an image from a DHI base image and evaluates it +against the DHI policy bundle. + #### Step 1: Use a DHI base image in your Dockerfile Create a Dockerfile that uses a Docker Hardened Image mirrored repository as the @@ -59,57 +83,121 @@ base. For example: ```dockerfile # Dockerfile -FROM /dhi-python:3.13-alpine3.21 +FROM /dhi-python:3.13 ENTRYPOINT ["python", "-c", "print('Hello from a DHI-based image')"] ``` -#### Step 2: Build and push the image +#### Step 2: Build the image Open a terminal and navigate to the directory containing your Dockerfile. Then, -build and push the image to your Docker Hub repository: +build the image and load it into your local image store: ```console -$ docker build \ - --push \ - -t /my-dhi-app:v1 . +$ docker build --load -t my-dhi-app:v1 . ``` -#### Step 3: Enable Docker Scout +#### Step 3: Evaluate the image against the DHI policies -To enable Docker Scout for your organization and the repository, run the -following commands in your terminal: +Sign in and evaluate the local image against the DHI policy bundle: ```console $ docker login -$ docker scout enroll -$ docker scout repo enable --org /my-dhi-app +$ docker scout policy my-dhi-app:v1 \ + --policy-bundle dhi/policies:latest ``` -#### Step 4: Configure the DHI policy +The command prints a compliance result for each policy in the bundle, along with +the details of any violations. + +## Customize the DHI policies -Once Docker Scout is enabled, you can configure the **Valid Docker Hardened -Image (DHI) or DHI base image** policy for your organization: +You can tune which policies run and their thresholds with a `--policy-config` +file. The +[`docker-hardened-images/policies`](https://github.com/docker-hardened-images/policies) +repository includes an example `config.json` you can start from. -1. Go to the [Docker Scout dashboard](https://scout.docker.com). -2. Select your organization and navigate to **Policies**. -3. Configure the **Valid Docker Hardened Image (DHI) or DHI base image** policy - to enable it for your repositories. +```console +$ docker scout policy my-dhi-app:v1 \ + --policy-bundle dhi/policies:latest \ + --policy-config ./config.json +``` -For more information on configuring policies, see -[Configure policies](../../scout/policy/dashboard.md). +The config file matches policies by their stable name and lets you disable +individual policies or adjust their settings, such as severity levels and grace +periods. For the config file format, see +[Configure built-in policies](../../scout/policy/local.md#configure-built-in-policies). -#### Step 5: View policy compliance +You can also combine the DHI bundle with the built-in Docker Scout policies, +additional bundles, or your own custom Rego files. `--policy-bundle`, +`--policy-file`, and `--policy-dir` are all repeatable: -Once the DHI policy is configured and active, you can view compliance results: +```console +$ docker scout policy my-dhi-app:v1 \ + --policy-bundle dhi/policies:latest \ + --policy-file ./custom.rego +``` + +For more on authoring custom policies and combining policy sources, see +[Evaluate policies](../../scout/policy/local.md). + +## Enforce policy compliance in CI + +Use the [Docker Scout GitHub Action](https://github.com/docker/scout-action) to +evaluate the DHI policies on every push and fail the workflow when an image +doesn't meet them. The following workflow builds the image, then evaluates it +against the DHI policy bundle: + +```yaml +name: DHI policy check + +on: + push: + +env: + IMAGE_NAME: my-dhi-app:${{ github.sha }} + +jobs: + policy: + runs-on: ubuntu-latest + steps: + - name: Check out the repository + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Log in to Docker Hub + uses: docker/login-action@v3 + with: + username: ${{ secrets.DOCKER_USER }} + password: ${{ secrets.DOCKER_PAT }} + + - name: Build the image + uses: docker/build-push-action@v6 + with: + context: . + load: true + tags: ${{ env.IMAGE_NAME }} + + - name: Evaluate DHI policies + uses: docker/scout-action@v1.23.1 + with: + command: policy + image: ${{ env.IMAGE_NAME }} + policy-bundle: dhi/policies:latest + exit-code: true +``` -1. Go to the [Docker Scout dashboard](https://scout.docker.com). -2. Select your organization and navigate to **Images**. -3. Find your image, `/my-dhi-app:v1`, and select the link in the **Compliance** column. +The `docker/login-action` step authenticates with Docker Hub so the runner can +pull the DHI base image and the `dhi/policies` bundle. Store your Docker Hub +username and a [personal access token](/manuals/security/access-tokens.md) as the +`DOCKER_USER` and `DOCKER_PAT` repository secrets. -This shows the policy compliance results for your image. The **Valid Docker -Hardened Image (DHI) or DHI base image** policy evaluates whether your image has -a valid Docker signed verification summary attestation or if its base image has -such an attestation. +Set `exit-code: true` to fail the step when any policy isn't met. The +`policy-bundle` input accepts a comma-separated list of bundles, and you can +combine it with the `policy-file`, `policy-dir`, and `policy-config` inputs, just +like the CLI flags. -You can now [evaluate policy compliance in your CI](/scout/policy/ci/). \ No newline at end of file +For more on running policy evaluation in CI, see +[Evaluate policies](../../scout/policy/local.md#use-in-ci). diff --git a/content/manuals/dhi/resources.md b/content/manuals/dhi/resources.md index 1f7c7e0cf68a..66c8f2e8dc1e 100644 --- a/content/manuals/dhi/resources.md +++ b/content/manuals/dhi/resources.md @@ -42,6 +42,9 @@ organization: keys and verification tools - [Log](https://github.com/docker-hardened-images/log): Log of references (tag > digest) for Docker Hardened Images +- [Policies](https://github.com/docker-hardened-images/policies): Rego source + for the Docker Scout policies used to enforce DHI security and compliance + standards - [dhictl](https://github.com/docker-hardened-images/dhictl): Command-line interface for managing and interacting with Docker Hardened Images - [Terraform Provider](https://github.com/docker-hardened-images/terraform-provider-dhi): From cd9a799af85608777b8d06ef6f1f4368a3f47ec5 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Tue, 14 Jul 2026 14:07:25 -0700 Subject: [PATCH 2/5] use public image Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/policies.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/manuals/dhi/how-to/policies.md b/content/manuals/dhi/how-to/policies.md index 00f5c82deb7c..3a6fe4275d6c 100644 --- a/content/manuals/dhi/how-to/policies.md +++ b/content/manuals/dhi/how-to/policies.md @@ -78,12 +78,12 @@ against the DHI policy bundle. #### Step 1: Use a DHI base image in your Dockerfile -Create a Dockerfile that uses a Docker Hardened Image mirrored repository as the -base. For example: +Create a Dockerfile that uses a Docker Hardened Image from the DHI catalog as +the base. For example: ```dockerfile # Dockerfile -FROM /dhi-python:3.13 +FROM dhi.io/python:3.13 ENTRYPOINT ["python", "-c", "print('Hello from a DHI-based image')"] ``` From aede791f052933fc6c659fd1aa388a8f3052ec60 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Tue, 14 Jul 2026 14:10:40 -0700 Subject: [PATCH 3/5] agent feedback Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/policies.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/manuals/dhi/how-to/policies.md b/content/manuals/dhi/how-to/policies.md index 3a6fe4275d6c..fe5560014514 100644 --- a/content/manuals/dhi/how-to/policies.md +++ b/content/manuals/dhi/how-to/policies.md @@ -196,8 +196,8 @@ username and a [personal access token](/manuals/security/access-tokens.md) as th Set `exit-code: true` to fail the step when any policy isn't met. The `policy-bundle` input accepts a comma-separated list of bundles, and you can -combine it with the `policy-file`, `policy-dir`, and `policy-config` inputs, just -like the CLI flags. +combine it with the `policy-file`, `policy-dir`, and `policy-config` inputs, the +same as the CLI flags. For more on running policy evaluation in CI, see [Evaluate policies](../../scout/policy/local.md#use-in-ci). From 0d9d125c823af2ae6b1173e715b40367a427f381 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Tue, 14 Jul 2026 14:13:57 -0700 Subject: [PATCH 4/5] more agent feedback Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/policies.md | 51 +++++++++++++++++++------- 1 file changed, 37 insertions(+), 14 deletions(-) diff --git a/content/manuals/dhi/how-to/policies.md b/content/manuals/dhi/how-to/policies.md index fe5560014514..8eb0cc0f5d49 100644 --- a/content/manuals/dhi/how-to/policies.md +++ b/content/manuals/dhi/how-to/policies.md @@ -30,17 +30,20 @@ Docker Scout service. The `dhi/policies` bundle includes the following policies: -| Policy | What it checks | -| --- | --- | -| No default root user for non-dev images | The image is configured to run as a non-root user. | -| No fixable vulnerabilities past their remediation SLA | No fixable CVEs remain unaddressed past their remediation SLA (7 days for critical and high, 30 days for others). | -| No high-profile vulnerabilities | The image is free of a curated list of well-known CVEs, optionally including the CISA KEV catalog. | -| No embedded malware | A malware scan attestation is present and passing. | -| No embedded secrets | A secret scan attestation is present and passing. | -| No failing tests | A test attestation is present and passing. | -| Signed supply chain attestations | SBOM and provenance attestations are attached and signed. | -| Unintentional shell or package manager | No undeclared shell or package manager is present in the image. | -| STIG scan | For FIPS-compliant images, the STIG scan meets the required score. | +| Policy | Policy name | What it checks | +| --- | --- | --- | +| No default root user for non-dev images | `dhi-default-non-root-user` | The image is configured to run as a non-root user. | +| No fixable vulnerabilities past their remediation SLA | `fixable-vulnerabilities` | No fixable CVEs remain unaddressed past their remediation SLA (7 days for critical and high, 30 days for others). | +| No high-profile vulnerabilities | `high-profile-vulnerabilities` | The image is free of a curated list of well-known CVEs, optionally including the CISA KEV catalog. | +| No embedded malware | `dhi-no-embedded-malware` | A malware scan attestation is present and passing. | +| No embedded secrets | `dhi-no-embedded-secrets` | A secret scan attestation is present and passing. | +| No failing tests | `dhi-no-failing-tests` | A test attestation is present and passing. | +| Signed supply chain attestations | `dhi-signed-supply-chain-attestations` | SBOM and provenance attestations are attached and signed. | +| Unintentional shell or package manager | `dhi-unintentional-shell-or-package-manager` | No undeclared shell or package manager is present in the image. | +| STIG scan | `dhi-stig-scan-score` | For FIPS-compliant images, the STIG scan meets the required score. | + +The **Policy name** is the stable ID you reference in a `--policy-config` file to +enable, disable, or tune a policy. For the authoritative list and the Rego source for each policy, see the [`docker-hardened-images/policies`](https://github.com/docker-hardened-images/policies) @@ -123,9 +126,29 @@ $ docker scout policy my-dhi-app:v1 \ --policy-config ./config.json ``` -The config file matches policies by their stable name and lets you disable -individual policies or adjust their settings, such as severity levels and grace -periods. For the config file format, see +The config file matches policies by the **Policy name** listed in +[Policies in the DHI bundle](#policies-in-the-dhi-bundle) and lets you disable +individual policies or adjust their settings. For example, the following config +disables the STIG scan policy and only flags critical fixable vulnerabilities: + +```json +{ + "policies": [ + { + "name": "dhi-stig-scan-score", + "enabled": false + }, + { + "name": "fixable-vulnerabilities", + "config": { + "severities": ["CRITICAL"] + } + } + ] +} +``` + +For the full config file format, see [Configure built-in policies](../../scout/policy/local.md#configure-built-in-policies). You can also combine the DHI bundle with the built-in Docker Scout policies, From 2f6b8e5a2436349920c20fdab7a4faecae134805 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Thu, 16 Jul 2026 08:40:42 -0700 Subject: [PATCH 5/5] use real example Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/policies.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/content/manuals/dhi/how-to/policies.md b/content/manuals/dhi/how-to/policies.md index 8eb0cc0f5d49..e909dfdfadc7 100644 --- a/content/manuals/dhi/how-to/policies.md +++ b/content/manuals/dhi/how-to/policies.md @@ -129,7 +129,8 @@ $ docker scout policy my-dhi-app:v1 \ The config file matches policies by the **Policy name** listed in [Policies in the DHI bundle](#policies-in-the-dhi-bundle) and lets you disable individual policies or adjust their settings. For example, the following config -disables the STIG scan policy and only flags critical fixable vulnerabilities: +disables the STIG scan policy and opts out of CISA KEV checks in the +high-profile vulnerabilities policy: ```json { @@ -139,9 +140,9 @@ disables the STIG scan policy and only flags critical fixable vulnerabilities: "enabled": false }, { - "name": "fixable-vulnerabilities", + "name": "high-profile-vulnerabilities", "config": { - "severities": ["CRITICAL"] + "include_cisa_kev": false } } ]