scout: add new dhi policy

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**](../../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.
+
 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,18 @@ 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, 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 optional 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 +87,30 @@ $ docker scout enroll YOUR_ORG
 $ docker scout repo enable --org YOUR_ORG YOUR_ORG/my-dhi-app
 ```
 
-#### Step 4: Create a policy
+#### Step 4: Configure the DHI policy
+
+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. 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**.
+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
 
-#### Step 5: Evaluate 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**.
 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 now [evaluate policy compliance in your CI](/scout/policy/ci/).

content/manuals/scout/policy/_index.md

@@ -63,11 +63,17 @@ 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
-[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
@@ -358,6 +364,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