dhi: add compare (#23637)

craig-osterhout · web-flow · commit 8b7793bf42f4 · 2025-11-06T09:55:44.000-08:00
## Description Added how to compare images so that users can see a quick benefit of using DHI. - [Added compare topic](https://deploy-preview-23637--docsdocker.netlify.app/dhi/how-to/compare/) - [Added compare step to quickstart](https://deploy-preview-23637--docsdocker.netlify.app/dhi/get-started/#step-5-compare-with-the-other-images) - [Added what's next to migrate topic to point to compare](https://deploy-preview-23637--docsdocker.netlify.app/dhi/how-to/migrate/#whats-next) Additional changes: - [Updated the ordering of the how-to topics as they're growing](https://deploy-preview-23637--docsdocker.netlify.app/dhi/how-to/) - [Updated more info for "use" in quickstart to also point to k8 and helm topics](https://deploy-preview-23637--docsdocker.netlify.app/dhi/get-started/#step-4-pull-and-run-the-image) Will also incorporate compare into the image-specific docs. ## Related issues or tickets [ENGDOCS-3082](https://docker.atlassian.net/browse/ENGDOCS-3082) ## Reviews   - [ ] Editorial review - [ ] Product review [ENGDOCS-3082]: https://docker.atlassian.net/browse/ENGDOCS-3082?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ --------- Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
diff --git a/content/manuals/dhi/get-started.md b/content/manuals/dhi/get-started.md
@@ -117,7 +117,56 @@ a simple Python command just like you would with any other Docker image:
     This starts a container from the `dhi-python:3.13` image and runs a simple
     Python script that prints `Hello from DHI`.
 
-To dive deeper into using images see [Use a Docker Hardened Image](./how-to/use.md).
+To dive deeper into using images, see:
+
+- [Use a Docker Hardened Image](./how-to/use.md) for general usage
+- [Use in Kubernetes](./how-to/k8s.md) for Kubernetes deployments
+- [Use a Helm chart](./how-to/helm.md) for deploying with Helm
+
+## Step 5: Compare with the other images
+
+You can quickly compare DHIs with other images to see the security
+improvements and differences. This comparison helps you understand the value of
+using hardened images.
+
+Run the following command to see a summary comparison, replacing
+`<your-namespace>` with your organization's namespace:
+
+```console
+$ docker scout compare <your-namespace>/dhi-python:3.13 \
+    --to python:3.13 \
+    --platform linux/amd64 \
+    --ignore-unchanged \
+    2>/dev/null | sed -n '/## Overview/,/^  ## /p' | head -n -1
+```
+
+Example output:
+
+```plaintext
+  ## Overview
+
+                      │                    Analyzed Image                     │               Comparison Image
+  ────────────────────┼───────────────────────────────────────────────────────┼───────────────────────────────────────────────
+    Target            │  docker/dhi-python:3.13                               │  python:3.13
+      digest          │  c215e9da9f84                                         │  7f48e892134c
+      tag             │  3.13                                                 │  3.13
+      platform        │ linux/amd64                                           │ linux/amd64
+      provenance      │ https://github.com/docker-hardened-images/definitions │ https://github.com/docker-library/python.git
+                      │  77a629b3d0db035700206c2a4e7ed904e5902ea8             │  3f2d7e4c339ab883455b81a873519f1d0f2cd80a
+      vulnerabilities │    0C     0H     0M     0L                            │    0C     1H     5M   141L     2?
+                      │           -1     -5   -141     -2                     │
+      size            │ 35 MB (-377 MB)                                       │ 412 MB
+      packages        │ 80 (-530)                                             │ 610
+                      │                                                       │
+```
+
+This comparison shows that the Docker Hardened Image:
+
+- Removes vulnerabilities: 1 high, 5 medium, 141 low, and 2 unspecified severity CVEs removed
+- Reduces size: From 412 MB down to 35 MB (91% reduction)
+- Minimizes packages: From 610 packages down to 80 (87% reduction)
+
+To dive deeper into comparing images see [Compare Docker Hardened Images](./how-to/compare.md).
 
 ## What's next
 
diff --git a/content/manuals/dhi/how-to/_index.md b/content/manuals/dhi/how-to/_index.md
@@ -3,11 +3,12 @@ title: How-tos
 description: Step-by-step guidance for working with Docker Hardened Images, from discovery to debugging.
 weight: 20
 params:
-  grid_howto:
+  grid_discover:
     - title: Explore Docker Hardened Images
       description: Learn how to find and evaluate image repositories, variants, metadata, and attestations in the DHI catalog on Docker Hub.
       icon: travel_explore
       link: /dhi/how-to/explore/
+  grid_adopt:
     - title: Mirror a Docker Hardened Image repository
       description: Learn how to mirror an image into your organization's namespace and optionally push it to another private registry.
       icon: compare_arrows
@@ -36,6 +37,12 @@ params:
       description: Follow a step-by-step guide to update your Dockerfiles and adopt Docker Hardened Images for secure, minimal, and production-ready builds.
       icon: directions_run
       link: /dhi/how-to/migrate/
+  grid_evaluate:
+    - title: Compare Docker Hardened Images
+      description: Learn how to compare Docker Hardened Images with other container images to evaluate security improvements and differences.
+      icon: compare
+      link: /dhi/how-to/compare/
+  grid_verify:
     - title: Verify a Docker Hardened Image
       description: Use Docker Scout or cosign to verify signed attestations like SBOMs, provenance, and vulnerability data for Docker Hardened Images.
       icon: check_circle
@@ -44,40 +51,72 @@ params:
       description: Learn how to scan Docker Hardened Images for known vulnerabilities using Docker Scout, Grype, or Trivy.
       icon: bug_report
       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.
       icon: policy
       link: /dhi/how-to/policies/
+  grid_troubleshoot:
     - title: Debug a Docker Hardened Image
       description: Use Docker Debug to inspect a running container based on a hardened image without modifying it.
       icon: terminal
       link: /dhi/how-to/debug/
 ---
 
-This section provides practical, step-by-step guidance for working with Docker
+This section provides practical, task-based guidance for working with Docker
 Hardened Images (DHIs). Whether you're evaluating DHIs for the first time or
-integrating them into a production CI/CD pipeline, these topics walk you
-through each phase of the adoption journey, from discovery to debugging.
+integrating them into a production CI/CD pipeline, these topics cover the key
+tasks across the adoption journey, from discovery to debugging.
 
-To help you get started and stay secure, the topics are organized around the
-typical lifecycle of working with DHIs.
+The topics are organized around the typical lifecycle of working with DHIs, but
+you can use them as needed based on your specific workflow.
 
-## Lifecycle flow
+Explore the topics below that match your current needs.
 
-1. Explore available images and metadata in the DHI catalog.
-2. Mirror trusted images into your namespace or registry.
-3. Adopt DHIs in your workflows by pulling, using in development and CI, and
-   migrating existing applications to use secure, minimal base images.
-4. Analyze images by verifying signatures, SBOMs, and provenance, and scanning
-   for vulnerabilities.
-5. Enforce policies to maintain security and compliance.
-6. Debug containers based on DHIs without modifying the image.
+## Discover
 
-Each of the following topics aligns with a step in this lifecycle, so you can progress
-confidently through exploration, implementation, and ongoing maintenance.
+Explore available images and metadata in the DHI catalog.
 
-## Step-by-step topics
+{{< grid
+  items="grid_discover"
+>}}
+
+## Adopt
+
+Mirror trusted images, customize as needed, and integrate into your workflows.
+
+{{< grid
+  items="grid_adopt"
+>}}
+
+## Evaluate
+
+Compare with other images to understand security improvements.
+
+{{< grid
+  items="grid_evaluate"
+>}}
+
+## Verify
+
+Check signatures, SBOMs, and provenance, and scan for vulnerabilities.
+
+{{< grid
+  items="grid_verify"
+>}}
+
+## Govern
+
+Enforce policies to maintain security and compliance.
+
+{{< grid
+  items="grid_govern"
+>}}
+
+## Troubleshoot
+
+Debug containers based on DHIs without modifying the image.
 
 {{< grid
-  items="grid_howto"
+  items="grid_troubleshoot"
 >}}
diff --git a/content/manuals/dhi/how-to/compare.md b/content/manuals/dhi/how-to/compare.md
@@ -0,0 +1,195 @@
+---
+title: Compare Docker Hardened Images
+linktitle: Compare images
+description: Learn how to compare Docker Hardened Images with other container images to evaluate security improvements and differences.
+keywords: compare docker images, docker scout compare, image comparison, vulnerability comparison, security comparison
+weight: 40
+---
+
+{{< summary-bar feature_name="Docker Hardened Images" >}}
+
+Docker Hardened Images (DHIs) are designed to provide enhanced security,
+minimized attack surfaces, and production-ready foundations for your
+applications. Comparing a DHI to a standard image helps you understand the
+security improvements, package differences, and overall benefits of adopting
+hardened images.
+
+This page explains how to use Docker Scout to compare a Docker Hardened Image
+with another image, such as a Docker Official Image (DOI) or a custom image, to
+evaluate differences in vulnerabilities, packages, and configurations.
+
+## Compare images using Docker Scout
+
+Docker Scout provides a built-in comparison feature that lets you analyze the
+differences between two images. This is useful for:
+
+- Evaluating the security improvements when migrating from a standard image to a
+  DHI
+- Understanding package and vulnerability differences between image variants
+- Assessing the impact of customizations or updates
+
+### Basic comparison
+
+To compare a Docker Hardened Image with another image, use the [`docker scout
+compare`](/reference/cli/docker/scout/compare/) command:
+
+```console
+$ docker scout compare <your-namespace>/dhi-<image>:<tag> \
+    --to <comparison-image>:<tag> \
+    --platform <platform>
+```
+
+For example, to compare a DHI Node.js image with the official Node.js image:
+
+```console
+$ docker scout compare <your-namespace>/dhi-node:22-debian13 \
+    --to node:22 \
+    --platform linux/amd64
+```
+
+This command provides a detailed comparison including:
+
+- Vulnerability differences (CVEs added, removed, or changed)
+- Package differences (packages added, removed, or updated)
+- Overall security posture improvements
+
+### Filter unchanged packages
+
+To focus only on the differences and ignore unchanged packages, use the
+`--ignore-unchanged` flag:
+
+```console
+$ docker scout compare <your-namespace>/dhi-node:22-debian13 \
+    --to node:22 \
+    --platform linux/amd64 \
+    --ignore-unchanged
+```
+
+This output highlights only the packages and vulnerabilities that differ between
+the two images, making it easier to identify the security improvements and
+changes.
+
+### Show overview only
+
+For a concise overview of the comparison results, you can extract just the
+overview section using standard shell tools:
+
+```console
+$ docker scout compare <your-namespace>/dhi-node:22-debian13 \
+    --to node:22 \
+    --platform linux/amd64 \
+    --ignore-unchanged \
+    2>/dev/null | sed -n '/## Overview/,/^  ## /p' | head -n -1
+```
+
+The result is a clean summary showing the key differences between the two
+images. Example output:
+
+```console
+  ## Overview
+  
+                      │                    Analyzed Image                     │              Comparison Image
+  ────────────────────┼───────────────────────────────────────────────────────┼─────────────────────────────────────────────
+    Target            │  docker/dhi-node:22-debian13                          │  node:22
+      digest          │  55d471f61608                                         │  9ee3220f602f
+      tag             │  22-debian13                                          │  22
+      platform        │ linux/amd64                                           │ linux/amd64
+      provenance      │ https://github.com/docker-hardened-images/definitions │ https://github.com/nodejs/docker-node.git
+                      │  9fe491f53122b84eebba81e13f20157c18c10de2             │  bf78d7603fbea92cd3652edb3b2edadd6f5a3fe8
+      vulnerabilities │    0C     0H     0M     0L                            │    0C     1H     3M   153L     4?
+                      │           -1     -3   -153     -4                     │
+      size            │ 41 MB (-367 MB)                                       │ 408 MB
+      packages        │ 19 (-726)                                             │ 745
+                      │                                                       │
+```
+
+## Interpret comparison results
+
+The comparison output includes the following sections.
+
+### Overview
+
+The overview section provides high-level statistics about both images:
+
+- Target and comparison image details (digest, tag, platform, provenance)
+- Vulnerability counts for each image
+- Size comparison
+- Package counts
+
+Look for:
+
+- Vulnerability reductions (negative numbers in the delta row)
+- Size reductions showing storage efficiency
+- Package count reductions indicating a minimal attack surface
+
+### Environment Variables
+
+The environment variables section shows environment variables that differ between
+the two images, prefixed with `+` for added or `-` for removed.
+
+Look for:
+
+- Removed environment variables that may have been necessary for your specific use-case
+
+### Labels
+
+The labels section displays labels that differ between the two images, prefixed
+with `+` for added or `-` for removed.
+
+### Packages and Vulnerabilities
+
+The packages and vulnerabilities section lists all package differences and their
+associated security vulnerabilities. Packages are prefixed with:
+
+- `-` for packages removed from the target image (not present in the compared image)
+- `+` for packages added to the target image (not present in the base image)
+- `↑` for packages upgraded in the target image
+- `↓` for packages downgraded in the target image
+
+For packages with associated vulnerabilities, the CVEs are listed with their
+severity levels and identifiers.
+
+Look for:
+
+- Removed packages and vulnerabilities: Indicates a reduced attack surface in the DHI
+- Added packages: May indicate DHI-specific tooling or dependencies
+- Upgraded packages: Shows version updates that may include security fixes
+
+## When to compare images
+
+### Evaluate migration benefits
+
+Before migrating from a Docker Official Image to a DHI, compare them to
+understand the security improvements. For example:
+
+```console
+$ docker scout compare <your-namespace>/dhi-python:3.13 \
+    --to python:3.13 \
+    --platform linux/amd64 \
+    --ignore-unchanged
+```
+
+This helps justify the migration by showing concrete vulnerability reductions
+and package minimization.
+
+### Assess customization impact
+
+After customizing a DHI, compare the customized version with the original to
+ensure you haven't introduced new vulnerabilities. For example:
+
+```console
+$ docker scout compare <your-namespace>/dhi-python:3.13-custom \
+    --to <your-namespace>/dhi-python:3.13 \
+    --platform linux/amd64
+```
+
+### Track updates over time
+
+Compare different versions of the same DHI to see what changed between releases. For example:
+
+```console
+$ docker scout compare <your-namespace>/dhi-node:22-debian13 \
+    --to <your-namespace>/dhi-node:20-debian12 \
+    --platform linux/amd64 \
+    --ignore-unchanged
+```
diff --git a/content/manuals/dhi/how-to/helm.md b/content/manuals/dhi/how-to/helm.md
@@ -3,7 +3,7 @@ title: Use a Docker Hardened Image chart
 linktitle: Use a Helm chart
 description: Learn how to use a Docker Hardened Image chart.
 keywords: use hardened image, helm, k8s, kubernetes, dhi chart, chart
-weight: 36
+weight: 32
 params:
   sidebar:
     badge:
diff --git a/content/manuals/dhi/how-to/k8s.md b/content/manuals/dhi/how-to/k8s.md
@@ -3,7 +3,7 @@ title: Use a Docker Hardened Image in Kubernetes
 linktitle: Use an image in Kubernetes
 description: Learn how to use Docker Hardened Images in Kubernetes deployments.
 keywords: use hardened image, kubernetes, k8s
-weight: 35
+weight: 31
 ---
 
 {{< summary-bar feature_name="Docker Hardened Images" >}}
diff --git a/content/manuals/dhi/how-to/manage.md b/content/manuals/dhi/how-to/manage.md
@@ -3,7 +3,7 @@ title: Manage Docker Hardened Images
 linktitle: Manage images
 description: Learn how to manage your mirrored and customized Docker Hardened Images in your organization.
 keywords: manage docker hardened images, custom hardened images
-weight: 45
+weight: 35
 ---
 
 {{< summary-bar feature_name="Docker Hardened Images" >}}
diff --git a/content/manuals/dhi/how-to/migrate.md b/content/manuals/dhi/how-to/migrate.md
diff --git a/content/manuals/dhi/how-to/scan.md b/content/manuals/dhi/how-to/scan.md
