From 3dc13baca12e33dfe042e93e4aac30a291281340 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Mon, 3 Nov 2025 09:30:14 -0800 Subject: [PATCH 1/3] scout: add new dhi policy Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/policies.md | 59 +++++++++++++------------- content/manuals/scout/policy/_index.md | 21 +++++++++ 2 files changed, 51 insertions(+), 29 deletions(-) diff --git a/content/manuals/dhi/how-to/policies.md b/content/manuals/dhi/how-to/policies.md index 147c1aad8dc4..efee3d9834dd 100644 --- a/content/manuals/dhi/how-to/policies.md +++ b/content/manuals/dhi/how-to/policies.md @@ -14,6 +14,13 @@ 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 Scout includes a dedicated [**Valid Docker Hardened Image (DHI) or DHI +base +image**](/manuals/scout/policy/#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. @@ -33,23 +40,17 @@ 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. -## Create policies for your DHI-based images - -To ensure that the images you build using Docker Hardened Images remain secure, -you can create Docker Scout policies tailored to your requirements for your own -repositories. These policies help enforce security standards such as preventing -high-severity vulnerabilities, requiring up-to-date base images, or validating -the presence of key metadata. +## Evaluate DHI policy compliance for your images -Policies evaluate images when they are pushed to a repository, allowing you to -track compliance, get notified of deviations, and integrate policy checks into -your CI/CD pipeline. +When you enable Docker Scout for your repositories, Docker Scout automatically +provides default policies, including the [**Valid Docker Hardened Image (DHI) or DHI base image**](/manuals/scout/policy/#valid-docker-hardened-image-dhi-or-dhi-base-image) +policy. This policy validates whether your images are DHIs or built with DHI base +images by checking for Docker signed verification summary attestations. -### Example: Create a policy for DHI-based images +The following example shows how to build an image using a DHI base image and +evaluate its compliance with the DHI policy. -This example shows how to create a policy that requires all images in your -organization to use Docker Hardened Images as their base. This ensures that -your applications are built on secure, minimal, and production-ready images. +### Example: Build and evaluate a DHI-based image #### Step 1: Use a DHI base image in your Dockerfile @@ -85,26 +86,26 @@ $ docker scout enroll YOUR_ORG $ docker scout repo enable --org YOUR_ORG YOUR_ORG/my-dhi-app ``` -#### Step 4: Create a policy - -1. Go to the [Docker Scout dashboard](https://scout.docker.com). -2. Select your organization and navigate to **Policies**. -3. Select **Add policy**. -4. Select **Configure** for **Approved Base Images Policy**. -5. Give the policy a compliant name, such as **Approved DHI Base Images**. -6. In **Approved base image sources**, delete the default item. -7. In **Approved base image sources**, add approved base image sources. For this - example, use the wildcard (`*`) to allow all mirrored DHI repositories, - `docker.io/ORG_NAME/dhi-*`. Replace `ORG_NAME` with your organization name. -8. Select **Save policy**. +#### Step 4: View policy compliance -#### Step 5: Evaluate policy compliance +Once Docker Scout is enabled, the default policies, including the **Valid Docker +Hardened Image (DHI) or DHI base image** policy, are automatically active. 1. Go to the [Docker Scout dashboard](https://scout.docker.com). 2. Select your organization and navigate to **Images**. 3. Find your image, `YOUR_ORG/my-dhi-app:v1`, and select the link in the **Compliance** column. -This shows the policy compliance results for your image, including whether it -meets the requirements of the **Approved DHI Base Images** policy. +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. + +You can also view all active policies for your organization: + +1. Go to the [Docker Scout dashboard](https://scout.docker.com). +2. Select your organization and navigate to **Policies**. + +Here you can see the **Valid Docker Hardened Image (DHI) or DHI base image** +policy along with other default policies that Docker Scout provides. You can now [evaluate policy compliance in your CI](/scout/policy/ci/). \ No newline at end of file diff --git a/content/manuals/scout/policy/_index.md b/content/manuals/scout/policy/_index.md index bba14157e98b..8d974815e139 100644 --- a/content/manuals/scout/policy/_index.md +++ b/content/manuals/scout/policy/_index.md @@ -63,6 +63,7 @@ Docker Scout supports the following policy types: - [Default Non-Root User](#default-non-root-user) - [Approved Base Images](#approved-base-images) - [SonarQube Quality Gates](#sonarqube-quality-gates) +- [Valid Docker Hardened Image (DHI) or DHI base image](#valid-docker-hardened-image-dhi-or-dhi-base-image) Docker Scout automatically provides default policies for repositories where it is enabled, except for the SonarQube Quality Gates policy, which requires @@ -358,6 +359,26 @@ in the CLI. > a SonarQube analysis and policy evaluation after enabling the integration to > view the results in Docker Scout. +### Valid Docker Hardened Image (DHI) or DHI base image + +The **Valid Docker Hardened Image (DHI) or DHI base image** policy type ensures +that your images are either Docker Hardened Images (DHI) or are built using a +DHI as the base image. + +This policy validates images by checking for a valid Docker signed verification +summary attestation. The policy considers an image compliant if either: + +- The image itself is a Docker Hardened Image with a valid Docker signed + verification summary attestation, or +- The base image used in the build (identified from SLSA provenance + attestations) has a valid Docker signed verification summary attestation + +Images are non-compliant with this policy if they lack the required Docker +signed verification summary attestation and are not built from a base image +with such an attestation. + +This policy has no configurable parameters. + ## No base image data There are cases when it's not possible to determine information about the base From 855b4258f76fcc8bf85f03a6b914b7fdfe5b27e4 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Mon, 3 Nov 2025 09:54:31 -0800 Subject: [PATCH 2/3] fix link Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/policies.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/content/manuals/dhi/how-to/policies.md b/content/manuals/dhi/how-to/policies.md index efee3d9834dd..e39cac8cb6b6 100644 --- a/content/manuals/dhi/how-to/policies.md +++ b/content/manuals/dhi/how-to/policies.md @@ -16,7 +16,7 @@ DHIs, are used across your environments. Docker Scout includes a dedicated [**Valid Docker Hardened Image (DHI) or DHI base -image**](/manuals/scout/policy/#valid-docker-hardened-image-dhi-or-dhi-base-image) +image**](../../scout/policy/_index.md#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. @@ -43,9 +43,11 @@ images and layers. ## Evaluate DHI policy compliance for your images When you enable Docker Scout for your repositories, Docker Scout automatically -provides default policies, including the [**Valid Docker Hardened Image (DHI) or DHI base image**](/manuals/scout/policy/#valid-docker-hardened-image-dhi-or-dhi-base-image) -policy. This policy validates whether your images are DHIs or built with DHI base -images by checking for Docker signed verification summary attestations. +provides default policies, including the [**Valid Docker Hardened Image (DHI) or +DHI base +image**](../../scout/policy/_index.md#valid-docker-hardened-image-dhi-or-dhi-base-image) +policy. This policy validates whether your images are DHIs or built with DHI +base images by checking for Docker signed verification summary attestations. The following example shows how to build an image using a DHI base image and evaluate its compliance with the DHI policy. From cb671dd4b1f52c8caf50d4e74db823a9d3c89150 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Tue, 4 Nov 2025 08:50:00 -0800 Subject: [PATCH 3/3] policy is optionally configured Signed-off-by: Craig Osterhout --- content/manuals/dhi/how-to/policies.md | 33 ++++++++++++++------------ content/manuals/scout/policy/_index.md | 11 ++++++--- 2 files changed, 26 insertions(+), 18 deletions(-) diff --git a/content/manuals/dhi/how-to/policies.md b/content/manuals/dhi/how-to/policies.md index e39cac8cb6b6..cbcf04351a7f 100644 --- a/content/manuals/dhi/how-to/policies.md +++ b/content/manuals/dhi/how-to/policies.md @@ -42,11 +42,10 @@ images and layers. ## Evaluate DHI policy compliance for your images -When you enable Docker Scout for your repositories, Docker Scout automatically -provides default policies, including the [**Valid Docker Hardened Image (DHI) or -DHI base +When you enable Docker Scout for your repositories, you can configure the +[**Valid Docker Hardened Image (DHI) or DHI base image**](../../scout/policy/_index.md#valid-docker-hardened-image-dhi-or-dhi-base-image) -policy. This policy validates whether your images are DHIs or built with DHI +policy. This optional policy validates whether your images are DHIs or built with DHI base images by checking for Docker signed verification summary attestations. The following example shows how to build an image using a DHI base image and @@ -88,10 +87,22 @@ $ docker scout enroll YOUR_ORG $ docker scout repo enable --org YOUR_ORG YOUR_ORG/my-dhi-app ``` -#### Step 4: View policy compliance +#### Step 4: Configure the DHI policy -Once Docker Scout is enabled, the default policies, including the **Valid Docker -Hardened Image (DHI) or DHI base image** policy, are automatically active. +Once Docker Scout is enabled, you can configure the **Valid Docker Hardened +Image (DHI) or DHI base image** policy for your organization: + +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. + +For more information on configuring policies, see +[Configure policies](../../scout/policy/configure.md). + +#### Step 5: View policy compliance + +Once the DHI policy is configured and active, you can view compliance results: 1. Go to the [Docker Scout dashboard](https://scout.docker.com). 2. Select your organization and navigate to **Images**. @@ -102,12 +113,4 @@ 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. -You can also view all active policies for your organization: - -1. Go to the [Docker Scout dashboard](https://scout.docker.com). -2. Select your organization and navigate to **Policies**. - -Here you can see the **Valid Docker Hardened Image (DHI) or DHI base image** -policy along with other default policies that Docker Scout provides. - You can now [evaluate policy compliance in your CI](/scout/policy/ci/). \ No newline at end of file diff --git a/content/manuals/scout/policy/_index.md b/content/manuals/scout/policy/_index.md index 8d974815e139..63b6e4fccc19 100644 --- a/content/manuals/scout/policy/_index.md +++ b/content/manuals/scout/policy/_index.md @@ -66,9 +66,14 @@ Docker Scout supports the following policy types: - [Valid Docker Hardened Image (DHI) or DHI base image](#valid-docker-hardened-image-dhi-or-dhi-base-image) Docker Scout automatically provides default policies for repositories where it -is enabled, except for the SonarQube Quality Gates policy, which requires -[integration with SonarQube](/manuals/scout/integrations/code-quality/sonarqube.md) -before use. +is enabled, except for the following policies, which are optional and must be +configured: + +- The **SonarQube Quality Gates** policy, which requires + [integration with SonarQube](/manuals/scout/integrations/code-quality/sonarqube.md) + before use. +- The **Valid Docker Hardened Image (DHI) or DHI base image** policy, which can + be configured if you want to enforce the use of Docker Hardened Images. You can create custom policies from any of the supported policy types, or delete a default policy if it isn't applicable to your project. For more