From 310a4bc2931cf597419ee6719527f6fddcaccf43 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Fri, 31 Oct 2025 11:12:19 -0700 Subject: [PATCH 1/3] dhi: add compare Signed-off-by: Craig Osterhout --- content/manuals/dhi/get-started.md | 47 ++++++- content/manuals/dhi/how-to/_index.md | 77 ++++++++--- content/manuals/dhi/how-to/compare.md | 176 ++++++++++++++++++++++++++ content/manuals/dhi/how-to/helm.md | 2 +- content/manuals/dhi/how-to/k8s.md | 2 +- content/manuals/dhi/how-to/manage.md | 2 +- content/manuals/dhi/how-to/migrate.md | 12 +- content/manuals/dhi/how-to/scan.md | 2 +- 8 files changed, 295 insertions(+), 25 deletions(-) create mode 100644 content/manuals/dhi/how-to/compare.md diff --git a/content/manuals/dhi/get-started.md b/content/manuals/dhi/get-started.md index 6aa4a95afbd6..165ccf6dd56f 100644 --- a/content/manuals/dhi/get-started.md +++ b/content/manuals/dhi/get-started.md @@ -117,7 +117,52 @@ 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 +`` with your organization's namespace: + +```console +$ docker scout compare /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 index 6019cf2dc1e9..cb94dca8db7a 100644 --- 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" >}} \ No newline at end of file diff --git a/content/manuals/dhi/how-to/compare.md b/content/manuals/dhi/how-to/compare.md new file mode 100644 index 000000000000..1bcd1b48cc2b --- /dev/null +++ b/content/manuals/dhi/how-to/compare.md @@ -0,0 +1,176 @@ +--- +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 /dhi-: --to : --platform +``` + +For example, to compare a DHI Node.js image with the official Node.js image: + +```console +$ docker scout compare /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 /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 /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 /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 /dhi-python:3.13-custom --to /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 /dhi-node:22-debian13 --to /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 index d764fc7f3b53..c4e3e9514614 100644 --- 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 index 1aa8557642b1..d924e1f90b69 100644 --- 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 index ca653a2737b4..cc25482bfaa4 100644 --- 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 index 164d902f7d55..5fb26f0721af 100644 --- a/content/manuals/dhi/how-to/migrate.md +++ b/content/manuals/dhi/how-to/migrate.md @@ -2,7 +2,7 @@ title: Migrate an existing application to use Docker Hardened Images linktitle: Migrate an app description: Follow a step-by-step guide to update your Dockerfiles and adopt Docker Hardened Images for secure, minimal, and production-ready builds. -weight: 50 +weight: 36 keywords: migrate dockerfile, hardened base image, multi-stage build, non-root containers, secure container build --- @@ -322,3 +322,13 @@ Alternatively, you can request assistance to migrate your Dockerfile: {{% include "gordondhi.md" %}} + +## What's next + +After migrating to Docker Hardened Images, you can: + +- [Compare images](./compare.md) to see the security improvements and + differences between your DHI and the original image +- [Verify the image](./verify.md) to check signed attestations like SBOMs and + provenance +- [Scan the image](./scan.md) to analyze it for known vulnerabilities diff --git a/content/manuals/dhi/how-to/scan.md b/content/manuals/dhi/how-to/scan.md index c5c382728b21..c2d1c9818a29 100644 --- a/content/manuals/dhi/how-to/scan.md +++ b/content/manuals/dhi/how-to/scan.md @@ -3,7 +3,7 @@ title: Scan Docker Hardened Images linktitle: Scan an image description: Learn how to scan Docker Hardened Images for known vulnerabilities using Docker Scout, Grype, or Trivy. keywords: scan container image, docker scout cves, grype scanner, trivy container scanner, vex attestation -weight: 45 +weight: 46 --- {{< summary-bar feature_name="Docker Hardened Images" >}} From 6d66456d96242ae18099b7981b529e06124aa26d Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Mon, 3 Nov 2025 11:50:24 -0800 Subject: [PATCH 2/3] formatting Signed-off-by: Craig Osterhout --- content/manuals/dhi/get-started.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/manuals/dhi/get-started.md b/content/manuals/dhi/get-started.md index 165ccf6dd56f..0492920aff05 100644 --- a/content/manuals/dhi/get-started.md +++ b/content/manuals/dhi/get-started.md @@ -158,7 +158,7 @@ Example output: This comparison shows that the Docker Hardened Image: -- Removes vulnerabilities: 1 HIGH, 5 MEDIUM, 141 LOW, and 2 unspecified severity CVEs removed +- 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) From ca4804c0b3885403cd81d64c600333f044eab4ba Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Mon, 3 Nov 2025 11:53:07 -0800 Subject: [PATCH 3/3] wrap codeblocks Signed-off-by: Craig Osterhout --- content/manuals/dhi/get-started.md | 6 ++++- content/manuals/dhi/how-to/compare.md | 33 +++++++++++++++++++++------ 2 files changed, 31 insertions(+), 8 deletions(-) diff --git a/content/manuals/dhi/get-started.md b/content/manuals/dhi/get-started.md index 0492920aff05..cdafa09c344f 100644 --- a/content/manuals/dhi/get-started.md +++ b/content/manuals/dhi/get-started.md @@ -133,7 +133,11 @@ Run the following command to see a summary comparison, replacing `` with your organization's namespace: ```console -$ docker scout compare /dhi-python:3.13 --to python:3.13 --platform linux/amd64 --ignore-unchanged 2>/dev/null | sed -n '/## Overview/,/^ ## /p' | head -n -1 +$ docker scout compare /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: diff --git a/content/manuals/dhi/how-to/compare.md b/content/manuals/dhi/how-to/compare.md index 1bcd1b48cc2b..6c173a60d4cd 100644 --- a/content/manuals/dhi/how-to/compare.md +++ b/content/manuals/dhi/how-to/compare.md @@ -34,13 +34,17 @@ To compare a Docker Hardened Image with another image, use the [`docker scout compare`](/reference/cli/docker/scout/compare/) command: ```console -$ docker scout compare /dhi-: --to : --platform +$ docker scout compare /dhi-: \ + --to : \ + --platform ``` For example, to compare a DHI Node.js image with the official Node.js image: ```console -$ docker scout compare /dhi-node:22-debian13 --to node:22 --platform linux/amd64 +$ docker scout compare /dhi-node:22-debian13 \ + --to node:22 \ + --platform linux/amd64 ``` This command provides a detailed comparison including: @@ -55,7 +59,10 @@ To focus only on the differences and ignore unchanged packages, use the `--ignore-unchanged` flag: ```console -$ docker scout compare /dhi-node:22-debian13 --to node:22 --platform linux/amd64 --ignore-unchanged +$ docker scout compare /dhi-node:22-debian13 \ + --to node:22 \ + --platform linux/amd64 \ + --ignore-unchanged ``` This output highlights only the packages and vulnerabilities that differ between @@ -68,7 +75,11 @@ For a concise overview of the comparison results, you can extract just the overview section using standard shell tools: ```console -$ docker scout compare /dhi-node:22-debian13 --to node:22 --platform linux/amd64 --ignore-unchanged 2>/dev/null | sed -n '/## Overview/,/^ ## /p' | head -n -1 +$ docker scout compare /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 @@ -152,7 +163,10 @@ Before migrating from a Docker Official Image to a DHI, compare them to understand the security improvements. For example: ```console -$ docker scout compare /dhi-python:3.13 --to python:3.13 --platform linux/amd64 --ignore-unchanged +$ docker scout compare /dhi-python:3.13 \ + --to python:3.13 \ + --platform linux/amd64 \ + --ignore-unchanged ``` This helps justify the migration by showing concrete vulnerability reductions @@ -164,7 +178,9 @@ 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 /dhi-python:3.13-custom --to /dhi-python:3.13 --platform linux/amd64 +$ docker scout compare /dhi-python:3.13-custom \ + --to /dhi-python:3.13 \ + --platform linux/amd64 ``` ### Track updates over time @@ -172,5 +188,8 @@ $ docker scout compare /dhi-python:3.13-custom --to /dhi-node:22-debian13 --to /dhi-node:20-debian12 --platform linux/amd64 --ignore-unchanged +$ docker scout compare /dhi-node:22-debian13 \ + --to /dhi-node:20-debian12 \ + --platform linux/amd64 \ + --ignore-unchanged ```