Skip to content

Commit 310a4bc

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

File tree

8 files changed

+295
-25
lines changed

8 files changed

+295
-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: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
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`](/reference/cli/docker/scout/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+
### Filter unchanged packages
53+
54+
To focus only on the differences and ignore unchanged packages, use the
55+
`--ignore-unchanged` flag:
56+
57+
```console
58+
$ docker scout compare <your-namespace>/dhi-node:22-debian13 --to node:22 --platform linux/amd64 --ignore-unchanged
59+
```
60+
61+
This output highlights only the packages and vulnerabilities that differ between
62+
the two images, making it easier to identify the security improvements and
63+
changes.
64+
65+
### Show overview only
66+
67+
For a concise overview of the comparison results, you can extract just the
68+
overview section using standard shell tools:
69+
70+
```console
71+
$ 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
72+
```
73+
74+
The result is a clean summary showing the key differences between the two
75+
images. Example output:
76+
77+
```console
78+
## Overview
79+
80+
│ Analyzed Image │ Comparison Image
81+
────────────────────┼───────────────────────────────────────────────────────┼─────────────────────────────────────────────
82+
Target │ docker/dhi-node:22-debian13 │ node:22
83+
digest │ 55d471f61608 │ 9ee3220f602f
84+
tag │ 22-debian13 │ 22
85+
platform │ linux/amd64 │ linux/amd64
86+
provenance │ https://github.com/docker-hardened-images/definitions │ https://github.com/nodejs/docker-node.git
87+
│ 9fe491f53122b84eebba81e13f20157c18c10de2 │ bf78d7603fbea92cd3652edb3b2edadd6f5a3fe8
88+
vulnerabilities │ 0C 0H 0M 0L │ 0C 1H 3M 153L 4?
89+
│ -1 -3 -153 -4 │
90+
size │ 41 MB (-367 MB) │ 408 MB
91+
packages │ 19 (-726) │ 745
92+
│ │
93+
```
94+
95+
## Interpret comparison results
96+
97+
The comparison output includes the following sections.
98+
99+
### Overview
100+
101+
The overview section provides high-level statistics about both images:
102+
103+
- Target and comparison image details (digest, tag, platform, provenance)
104+
- Vulnerability counts for each image
105+
- Size comparison
106+
- Package counts
107+
108+
Look for:
109+
110+
- Vulnerability reductions (negative numbers in the delta row)
111+
- Size reductions showing storage efficiency
112+
- Package count reductions indicating a minimal attack surface
113+
114+
### Environment Variables
115+
116+
The environment variables section shows environment variables that differ between
117+
the two images, prefixed with `+` for added or `-` for removed.
118+
119+
Look for:
120+
121+
- Removed environment variables that may have been necessary for your specific use-case
122+
123+
### Labels
124+
125+
The labels section displays labels that differ between the two images, prefixed
126+
with `+` for added or `-` for removed.
127+
128+
### Packages and Vulnerabilities
129+
130+
The packages and vulnerabilities section lists all package differences and their
131+
associated security vulnerabilities. Packages are prefixed with:
132+
133+
- `-` for packages removed from the target image (not present in the compared image)
134+
- `+` for packages added to the target image (not present in the base image)
135+
- `↑` for packages upgraded in the target image
136+
- `↓` for packages downgraded in the target image
137+
138+
For packages with associated vulnerabilities, the CVEs are listed with their
139+
severity levels and identifiers.
140+
141+
Look for:
142+
143+
- Removed packages and vulnerabilities: Indicates a reduced attack surface in the DHI
144+
- Added packages: May indicate DHI-specific tooling or dependencies
145+
- Upgraded packages: Shows version updates that may include security fixes
146+
147+
## When to compare images
148+
149+
### Evaluate migration benefits
150+
151+
Before migrating from a Docker Official Image to a DHI, compare them to
152+
understand the security improvements. For example:
153+
154+
```console
155+
$ docker scout compare <your-namespace>/dhi-python:3.13 --to python:3.13 --platform linux/amd64 --ignore-unchanged
156+
```
157+
158+
This helps justify the migration by showing concrete vulnerability reductions
159+
and package minimization.
160+
161+
### Assess customization impact
162+
163+
After customizing a DHI, compare the customized version with the original to
164+
ensure you haven't introduced new vulnerabilities. For example:
165+
166+
```console
167+
$ docker scout compare <your-namespace>/dhi-python:3.13-custom --to <your-namespace>/dhi-python:3.13 --platform linux/amd64
168+
```
169+
170+
### Track updates over time
171+
172+
Compare different versions of the same DHI to see what changed between releases. For example:
173+
174+
```console
175+
$ docker scout compare <your-namespace>/dhi-node:22-debian13 --to <your-namespace>/dhi-node:20-debian12 --platform linux/amd64 --ignore-unchanged
176+
```

‎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" >}}

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

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: Migrate an existing application to use Docker Hardened Images
33
linktitle: Migrate an app
44
description: Follow a step-by-step guide to update your Dockerfiles and adopt Docker Hardened Images for secure, minimal, and production-ready builds.
5-
weight: 50
5+
weight: 36
66
keywords: migrate dockerfile, hardened base image, multi-stage build, non-root containers, secure container build
77
---
88

@@ -322,3 +322,13 @@ Alternatively, you can request assistance to
322322
migrate your Dockerfile:
323323

324324
{{% include "gordondhi.md" %}}
325+
326+
## What's next
327+
328+
After migrating to Docker Hardened Images, you can:
329+
330+
- [Compare images](./compare.md) to see the security improvements and
331+
differences between your DHI and the original image
332+
- [Verify the image](./verify.md) to check signed attestations like SBOMs and
333+
provenance
334+
- [Scan the image](./scan.md) to analyze it for known vulnerabilities

0 commit comments

Comments
 (0)