Skip to content

dhi: add compare #23637

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 6, 2025
Merged

dhi: add compare #23637

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
310a4bc
dhi: add compare
craig-osterhout Oct 31, 2025
6d66456
formatting
craig-osterhout Nov 3, 2025
ca4804c
wrap codeblocks
craig-osterhout Nov 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 50 additions & 1 deletion content/manuals/dhi/get-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
77 changes: 58 additions & 19 deletions content/manuals/dhi/how-to/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,12 @@
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
Expand Down Expand Up @@ -36,6 +37,12 @@
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
Expand All @@ -44,40 +51,72 @@
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.

Check warning on line 74 in content/manuals/dhi/how-to/_index.md

View workflow job for this annotation

GitHub Actions / validate (vale) 

[vale] reported by reviewdog 🐶
[Docker.RecommendedWords] Consider using 'following' instead of 'below'

Raw Output:
{"message": "[Docker.RecommendedWords] Consider using 'following' instead of 'below'", "location": {"path": "content/manuals/dhi/how-to/_index.md", "range": {"start": {"line": 74, "column": 20}}}, "severity": "INFO"}

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"
>}}
195 changes: 195 additions & 0 deletions content/manuals/dhi/how-to/compare.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
```
2 changes: 1 addition & 1 deletion content/manuals/dhi/how-to/helm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion content/manuals/dhi/how-to/k8s.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" >}}
Expand Down
2 changes: 1 addition & 1 deletion content/manuals/dhi/how-to/manage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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" >}}
Expand Down
Loading