Skip to content

Commit a717419

Browse files
craig-osterhoutcraig-osterhout
committed
dhi: add compare
Signed-off-by: Craig Osterhout <[email protected]>
1 parent 577bf3e commit a717419

File tree

8 files changed

+298
-25
lines changed

8 files changed

+298
-25
lines changed

‎content/manuals/dhi/get-started.md‎

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,7 +117,52 @@ a simple Python command just like you would with any other Docker image:
117117
This starts a container from the `dhi-python:3.13` image and runs a simple
118118
Python script that prints `Hello from DHI`.
119119

120-
To dive deeper into using images see [Use a Docker Hardened Image](./how-to/use.md).
120+
To dive deeper into using images, see:
121+
122+
- [Use a Docker Hardened Image](./how-to/use.md) for general usage
123+
- [Use in Kubernetes](./how-to/k8s.md) for Kubernetes deployments
124+
- [Use a Helm chart](./how-to/helm.md) for deploying with Helm
125+
126+
## Step 5: Compare with the other images
127+
128+
You can quickly compare DHIs with other images to see the security
129+
improvements and differences. This comparison helps you understand the value of
130+
using hardened images.
131+
132+
Run the following command to see a summary comparison, replacing
133+
`<your-namespace>` with your organization's namespace:
134+
135+
```console
136+
$ 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
137+
```
138+
139+
Example output:
140+
141+
```plaintext
142+
## Overview
143+
144+
│ Analyzed Image │ Comparison Image
145+
────────────────────┼───────────────────────────────────────────────────────┼───────────────────────────────────────────────
146+
Target │ docker/dhi-python:3.13 │ python:3.13
147+
digest │ c215e9da9f84 │ 7f48e892134c
148+
tag │ 3.13 │ 3.13
149+
platform │ linux/amd64 │ linux/amd64
150+
provenance │ https://github.com/docker-hardened-images/definitions │ https://github.com/docker-library/python.git
151+
│ 77a629b3d0db035700206c2a4e7ed904e5902ea8 │ 3f2d7e4c339ab883455b81a873519f1d0f2cd80a
152+
vulnerabilities │ 0C 0H 0M 0L │ 0C 1H 5M 141L 2?
153+
│ -1 -5 -141 -2 │
154+
size │ 35 MB (-377 MB) │ 412 MB
155+
packages │ 80 (-530) │ 610
156+
│ │
157+
```
158+
159+
This comparison shows that the Docker Hardened Image:
160+
161+
- Removes vulnerabilities: 1 HIGH, 5 MEDIUM, 141 LOW, and 2 unspecified severity CVEs removed
162+
- Reduces size: From 412 MB down to 35 MB (91% reduction)
163+
- Minimizes packages: From 610 packages down to 80 (87% reduction)
164+
165+
To dive deeper into comparing images see [Compare Docker Hardened Images](./how-to/compare.md).
121166

122167
## What's next
123168

‎content/manuals/dhi/how-to/_index.md‎

Lines changed: 58 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,12 @@ title: How-tos
33
description: Step-by-step guidance for working with Docker Hardened Images, from discovery to debugging.
44
weight: 20
55
params:
6-
grid_howto:
6+
grid_discover:
77
- title: Explore Docker Hardened Images
88
description: Learn how to find and evaluate image repositories, variants, metadata, and attestations in the DHI catalog on Docker Hub.
99
icon: travel_explore
1010
link: /dhi/how-to/explore/
11+
grid_adopt:
1112
- title: Mirror a Docker Hardened Image repository
1213
description: Learn how to mirror an image into your organization's namespace and optionally push it to another private registry.
1314
icon: compare_arrows
@@ -36,6 +37,12 @@ params:
3637
description: Follow a step-by-step guide to update your Dockerfiles and adopt Docker Hardened Images for secure, minimal, and production-ready builds.
3738
icon: directions_run
3839
link: /dhi/how-to/migrate/
40+
grid_evaluate:
41+
- title: Compare Docker Hardened Images
42+
description: Learn how to compare Docker Hardened Images with other container images to evaluate security improvements and differences.
43+
icon: compare
44+
link: /dhi/how-to/compare/
45+
grid_verify:
3946
- title: Verify a Docker Hardened Image
4047
description: Use Docker Scout or cosign to verify signed attestations like SBOMs, provenance, and vulnerability data for Docker Hardened Images.
4148
icon: check_circle
@@ -44,40 +51,72 @@ params:
4451
description: Learn how to scan Docker Hardened Images for known vulnerabilities using Docker Scout, Grype, or Trivy.
4552
icon: bug_report
4653
link: /dhi/how-to/scan/
54+
grid_govern:
4755
- title: Enforce Docker Hardened Image usage with policies
4856
description: Learn how to use image policies with Docker Scout for Docker Hardened Images.
4957
icon: policy
5058
link: /dhi/how-to/policies/
59+
grid_troubleshoot:
5160
- title: Debug a Docker Hardened Image
5261
description: Use Docker Debug to inspect a running container based on a hardened image without modifying it.
5362
icon: terminal
5463
link: /dhi/how-to/debug/
5564
---
5665

57-
This section provides practical, step-by-step guidance for working with Docker
66+
This section provides practical, task-based guidance for working with Docker
5867
Hardened Images (DHIs). Whether you're evaluating DHIs for the first time or
59-
integrating them into a production CI/CD pipeline, these topics walk you
60-
through each phase of the adoption journey, from discovery to debugging.
68+
integrating them into a production CI/CD pipeline, these topics cover the key
69+
tasks across the adoption journey, from discovery to debugging.
6170

62-
To help you get started and stay secure, the topics are organized around the
63-
typical lifecycle of working with DHIs.
71+
The topics are organized around the typical lifecycle of working with DHIs, but
72+
you can use them as needed based on your specific workflow.
6473

65-
## Lifecycle flow
74+
Explore the topics below that match your current needs.
6675

67-
1. Explore available images and metadata in the DHI catalog.
68-
2. Mirror trusted images into your namespace or registry.
69-
3. Adopt DHIs in your workflows by pulling, using in development and CI, and
70-
migrating existing applications to use secure, minimal base images.
71-
4. Analyze images by verifying signatures, SBOMs, and provenance, and scanning
72-
for vulnerabilities.
73-
5. Enforce policies to maintain security and compliance.
74-
6. Debug containers based on DHIs without modifying the image.
76+
## Discover
7577

76-
Each of the following topics aligns with a step in this lifecycle, so you can progress
77-
confidently through exploration, implementation, and ongoing maintenance.
78+
Explore available images and metadata in the DHI catalog.
7879

79-
## Step-by-step topics
80+
{{< grid
81+
items="grid_discover"
82+
>}}
83+
84+
## Adopt
85+
86+
Mirror trusted images, customize as needed, and integrate into your workflows.
87+
88+
{{< grid
89+
items="grid_adopt"
90+
>}}
91+
92+
## Evaluate
93+
94+
Compare with other images to understand security improvements.
95+
96+
{{< grid
97+
items="grid_evaluate"
98+
>}}
99+
100+
## Verify
101+
102+
Check signatures, SBOMs, and provenance, and scan for vulnerabilities.
103+
104+
{{< grid
105+
items="grid_verify"
106+
>}}
107+
108+
## Govern
109+
110+
Enforce policies to maintain security and compliance.
111+
112+
{{< grid
113+
items="grid_govern"
114+
>}}
115+
116+
## Troubleshoot
117+
118+
Debug containers based on DHIs without modifying the image.
80119

81120
{{< grid
82-
items="grid_howto"
121+
items="grid_troubleshoot"
83122
>}}

‎content/manuals/dhi/how-to/compare.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
title: Compare Docker Hardened Images
3+
linktitle: Compare images
4+
description: Learn how to compare Docker Hardened Images with other container images to evaluate security improvements and differences.
5+
keywords: compare docker images, docker scout compare, image comparison, vulnerability comparison, security comparison
6+
weight: 40
7+
---
8+
9+
{{< summary-bar feature_name="Docker Hardened Images" >}}
10+
11+
Docker Hardened Images (DHIs) are designed to provide enhanced security,
12+
minimized attack surfaces, and production-ready foundations for your
13+
applications. Comparing a DHI to a standard image helps you understand the
14+
security improvements, package differences, and overall benefits of adopting
15+
hardened images.
16+
17+
This page explains how to use Docker Scout to compare a Docker Hardened Image
18+
with another image, such as a Docker Official Image (DOI) or a custom image, to
19+
evaluate differences in vulnerabilities, packages, and configurations.
20+
21+
## Compare images using Docker Scout
22+
23+
Docker Scout provides a built-in comparison feature that lets you analyze the
24+
differences between two images. This is useful for:
25+
26+
- Evaluating the security improvements when migrating from a standard image to a
27+
DHI
28+
- Understanding package and vulnerability differences between image variants
29+
- Assessing the impact of customizations or updates
30+
31+
### Basic comparison
32+
33+
To compare a Docker Hardened Image with another image, use the `docker scout
34+
compare` command:
35+
36+
```console
37+
$ docker scout compare <your-namespace>/dhi-<image>:<tag> --to <comparison-image>:<tag> --platform <platform>
38+
```
39+
40+
For example, to compare a DHI Node.js image with the official Node.js image:
41+
42+
```console
43+
$ docker scout compare <your-namespace>/dhi-node:22-debian13 --to node:22 --platform linux/amd64
44+
```
45+
46+
This command provides a detailed comparison including:
47+
48+
- Vulnerability differences (CVEs added, removed, or changed)
49+
- Package differences (packages added, removed, or updated)
50+
- Overall security posture improvements
51+
52+
For more details on the `docker scout compare` command and all available options,
53+
see the [Docker Scout compare reference](/reference/cli/docker/scout/compare/).
54+
55+
### Filter unchanged packages
56+
57+
To focus only on the differences and ignore unchanged packages, use the
58+
`--ignore-unchanged` flag:
59+
60+
```console
61+
$ docker scout compare <your-namespace>/dhi-node:22-debian13 --to node:22 --platform linux/amd64 --ignore-unchanged
62+
```
63+
64+
This output highlights only the packages and vulnerabilities that differ between
65+
the two images, making it easier to identify the security improvements and
66+
changes.
67+
68+
### Show overview only
69+
70+
For a concise overview of the comparison results, you can extract just the
71+
overview section using standard shell tools:
72+
73+
```console
74+
$ 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
75+
```
76+
77+
The result is a clean summary showing the key differences between the two
78+
images. Example output:
79+
80+
```console
81+
## Overview
82+
83+
│ Analyzed Image │ Comparison Image
84+
────────────────────┼───────────────────────────────────────────────────────┼─────────────────────────────────────────────
85+
Target │ docker/dhi-node:22-debian13 │ node:22
86+
digest │ 55d471f61608 │ 9ee3220f602f
87+
tag │ 22-debian13 │ 22
88+
platform │ linux/amd64 │ linux/amd64
89+
provenance │ https://github.com/docker-hardened-images/definitions │ https://github.com/nodejs/docker-node.git
90+
│ 9fe491f53122b84eebba81e13f20157c18c10de2 │ bf78d7603fbea92cd3652edb3b2edadd6f5a3fe8
91+
vulnerabilities │ 0C 0H 0M 0L │ 0C 1H 3M 153L 4?
92+
│ -1 -3 -153 -4 │
93+
size │ 41 MB (-367 MB) │ 408 MB
94+
packages │ 19 (-726) │ 745
95+
│ │
96+
```
97+
98+
## Interpret comparison results
99+
100+
The comparison output includes the following sections.
101+
102+
### Overview
103+
104+
The overview section provides high-level statistics about both images:
105+
106+
- Target and comparison image details (digest, tag, platform, provenance)
107+
- Vulnerability counts for each image
108+
- Size comparison
109+
- Package counts
110+
111+
Look for:
112+
113+
- Vulnerability reductions (negative numbers in the delta row)
114+
- Size reductions showing storage efficiency
115+
- Package count reductions indicating a minimal attack surface
116+
117+
### Environment Variables
118+
119+
The environment variables section shows environment variables that differ between
120+
the two images, prefixed with `+` for added or `-` for removed.
121+
122+
Look for:
123+
124+
- Removed environment variables that may have been necessary for your specific use-case
125+
126+
### Labels
127+
128+
The labels section displays labels that differ between the two images, prefixed
129+
with `+` for added or `-` for removed.
130+
131+
### Packages and Vulnerabilities
132+
133+
The packages and vulnerabilities section lists all package differences and their
134+
associated security vulnerabilities. Packages are prefixed with:
135+
136+
- `-` for packages removed from the target image (not present in the compared image)
137+
- `+` for packages added to the target image (not present in the base image)
138+
- `↑` for packages upgraded in the target image
139+
- `↓` for packages downgraded in the target image
140+
141+
For packages with associated vulnerabilities, the CVEs are listed with their
142+
severity levels and identifiers.
143+
144+
Look for:
145+
146+
- Removed packages and vulnerabilities: Indicates a reduced attack surface in the DHI
147+
- Added packages: May indicate DHI-specific tooling or dependencies
148+
- Upgraded packages: Shows version updates that may include security fixes
149+
150+
## When to compare images
151+
152+
### Evaluate migration benefits
153+
154+
Before migrating from a Docker Official Image to a DHI, compare them to
155+
understand the security improvements. For example:
156+
157+
```console
158+
$ docker scout compare <your-namespace>/dhi-python:3.13 --to python:3.13 --platform linux/amd64 --ignore-unchanged
159+
```
160+
161+
This helps justify the migration by showing concrete vulnerability reductions
162+
and package minimization.
163+
164+
### Assess customization impact
165+
166+
After customizing a DHI, compare the customized version with the original to
167+
ensure you haven't introduced new vulnerabilities. For example:
168+
169+
```console
170+
$ docker scout compare <your-namespace>/dhi-python:3.13-custom --to <your-namespace>/dhi-python:3.13 --platform linux/amd64
171+
```
172+
173+
### Track updates over time
174+
175+
Compare different versions of the same DHI to see what changed between releases. For example:
176+
177+
```console
178+
$ docker scout compare <your-namespace>/dhi-node:22-debian13 --to <your-namespace>/dhi-node:20-debian12 --platform linux/amd64 --ignore-unchanged
179+
```

‎content/manuals/dhi/how-to/helm.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Use a Docker Hardened Image chart
33
linktitle: Use a Helm chart
44
description: Learn how to use a Docker Hardened Image chart.
55
keywords: use hardened image, helm, k8s, kubernetes, dhi chart, chart
6-
weight: 36
6+
weight: 32
77
params:
88
sidebar:
99
badge:

‎content/manuals/dhi/how-to/k8s.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Use a Docker Hardened Image in Kubernetes
33
linktitle: Use an image in Kubernetes
44
description: Learn how to use Docker Hardened Images in Kubernetes deployments.
55
keywords: use hardened image, kubernetes, k8s
6-
weight: 35
6+
weight: 31
77
---
88

99
{{< summary-bar feature_name="Docker Hardened Images" >}}

‎content/manuals/dhi/how-to/manage.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Manage Docker Hardened Images
33
linktitle: Manage images
44
description: Learn how to manage your mirrored and customized Docker Hardened Images in your organization.
55
keywords: manage docker hardened images, custom hardened images
6-
weight: 45
6+
weight: 35
77
---
88

99
{{< summary-bar feature_name="Docker Hardened Images" >}}

0 commit comments

Comments
 (0)