Skip to content

Commit 44ca27c

Browse files
craig-osterhoutcraig-osterhout
committed
dhi: feedback
Signed-off-by: Craig Osterhout <[email protected]>
1 parent c152b60 commit 44ca27c

File tree

4 files changed

+234
-19
lines changed

4 files changed

+234
-19
lines changed

‎content/manuals/dhi/about/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ params:
88
description: Learn what a hardened image is, how Docker Hardened Images are built, what sets them apart from typical base and application images, and why you should use them.
99
icon: info
1010
link: /dhi/about/what/
11+
- title: Build process
12+
description: Learn how Docker builds, tests, and maintains Docker Hardened Images through an automated, security-focused pipeline.
13+
icon: build
14+
link: /dhi/about/build-process/
1115
- title: Image testing
1216
description: See how Docker Hardened Images are automatically tested for standards compliance, functionality, and security.
1317
icon: science

‎content/manuals/dhi/about/available.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,9 @@ requirements:
4040
Each image maintains a minimal and secure runtime layer by removing
4141
non-essential components like shells, package managers, and debugging tools.
4242
This helps reduce the attack surface while retaining compatibility with common
43-
runtime environments.
43+
runtime environments. To maintain this lean, secure foundation, DHI standardizes
44+
on Debian for glibc-based images, which provides broad compatibility while
45+
minimizing complexity and maintenance overhead.
4446

4547
Example tags include:
4648

‎content/manuals/dhi/about/build-process.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
---
2+
title: How Docker Hardened Images are built
3+
linkTitle: Build process
4+
description: Learn how Docker builds, tests, and maintains Docker Hardened Images through an automated, security-focused pipeline.
5+
keywords: docker hardened images, slsa build level 3, automated patching, ai guardrail, build process, signed sbom, supply chain security
6+
weight: 15
7+
---
8+
9+
Docker Hardened Images are built through an automated pipeline that monitors
10+
upstream sources, applies security updates, and publishes signed artifacts.
11+
This page explains the build process for both DHI images and customized
12+
images built from them.
13+
14+
## Build triggers
15+
16+
Builds start automatically. You don't trigger them manually. The system monitors
17+
for changes and starts builds in two scenarios:
18+
19+
- [Upstream updates](#upstream-updates)
20+
- [Customization changes](#customization-changes)
21+
22+
### Upstream updates
23+
24+
New releases, package updates, or CVE fixes from upstream projects trigger base
25+
image rebuilds. These builds go through quality checks to ensure security and
26+
reliability.
27+
28+
#### Monitoring for updates
29+
30+
Docker continuously monitors upstream projects for new releases, package
31+
updates, and security advisories. When changes are detected, the system
32+
automatically queues affected images for rebuild using a SLSA Build Level
33+
3-compliant build system.
34+
35+
Docker uses three strategies to track updates:
36+
37+
- GitHub releases: Monitors specific GitHub repositories for new releases and
38+
automatically updates the image definition when a new version is published.
39+
- GitHub tags: Tracks tags in GitHub repositories to detect new versions.
40+
- Package repositories: Monitors Alpine Linux, Debian, and Ubuntu package
41+
repositories through Docker Scout's package database to detect updated
42+
packages.
43+
44+
In addition to explicit upstream tracking, Docker also monitors transitive
45+
dependencies. When a package update is detected (for example, a security patch
46+
for a library), Docker automatically identifies and rebuilds all images within
47+
the support window that use that package.
48+
49+
### Customization changes
50+
51+
Updates to your OCI artifact customizations trigger rebuilds of your customized
52+
images.
53+
54+
When you customize a DHI image, your changes are packaged as OCI artifacts that
55+
layer on top of the base image. Docker monitors your artifact repositories and
56+
automatically rebuilds your customized images whenever you push updates.
57+
58+
The rebuild process fetches the current base image, applies your OCI artifacts,
59+
signs the result, and publishes it automatically. You don't need to manage
60+
builds or maintain CI pipelines for your customized images.
61+
62+
Customized images are also rebuilt automatically when the base DHI image they
63+
depend on receives updates, ensuring your images always include the latest
64+
security patches.
65+
66+
## Build pipeline
67+
68+
The following sections describe the build pipeline architecture and workflow for
69+
Docker Hardened Images based on:
70+
71+
- [Base image pipeline](#base-image-pipeline)
72+
- [Customized image pipeline](#customized-image-pipeline)
73+
74+
### Base image pipeline
75+
76+
Each Docker Hardened Image is built through an automated pipeline:
77+
78+
1. Monitoring: Docker monitors upstream sources for updates (new releases,
79+
package updates, security advisories).
80+
2. Rebuild trigger: When changes are detected, an automated rebuild starts.
81+
3. AI guardrail: An AI system fetches upstream diffs and scans them with
82+
language-aware checks. The guardrail focuses on high-leverage issues that can
83+
cause significant problems, such as inverted error checks, ignored failures,
84+
resource mishandling, or suspicious contributor activity. When it spots
85+
potential risks, it blocks the PR from auto-merging.
86+
4. Human review: If the AI identifies risks with high confidence,
87+
Docker engineers review the flagged code, reproduce the issue, and decide on
88+
the appropriate action. Engineers often contribute fixes back to upstream
89+
projects, improving the code for the entire community. When fixes are accepted
90+
upstream, the DHI build pipeline applies the patch immediately to protect
91+
customers while the fix moves through the upstream release process.
92+
5. Testing: Images undergo comprehensive testing for compatibility and
93+
functionality.
94+
6. Signing and attestations: Docker signs each image and generates
95+
attestations (SBOMs, VEX documents, build provenance).
96+
7. Publishing: The signed image and attestations are published to Docker Hub.
97+
8. Cascade rebuilds: If any customized images use this base, their rebuilds
98+
are automatically triggered.
99+
100+
Docker responds quickly to critical vulnerabilities. By building essential
101+
components from source rather than waiting for packaged updates, Docker can
102+
patch Critical and High-severity CVEs within days of upstream fixes and publish
103+
updated images with new attestations.
104+
105+
The following diagram shows the base image build flow:
106+
107+
```goat {class="text-sm"}
108+
.-------------------. .-------------------. .-------------------. .-------------------.
109+
| Docker monitors |----->| Trigger rebuild |----->| AI guardrail |----->| Human review |
110+
| upstream sources | | | | scans changes | | |
111+
'-------------------' '-------------------' '-------------------' '-------------------'
112+
|
113+
v
114+
.-------------------. .-------------------. .-------------------. .-------------------.
115+
| Cascade rebuilds |<-----| Publish to |<-----| Sign & generate |<-----| Testing |
116+
| (if needed) | | Docker Hub | | attestations | | |
117+
'-------------------' '-------------------' '-------------------' '-------------------'
118+
```
119+
120+
### Customized image pipeline
121+
122+
When you customize a DHI image, the build process is simplified:
123+
124+
1. Monitoring: Docker monitors your OCI artifact repositories for changes.
125+
2. Rebuild trigger: When you push updates to your OCI artifacts, or when the base
126+
DHI image is updated, an automated rebuild starts.
127+
3. Fetch base image: The latest base DHI image is fetched.
128+
4. Apply customizations: Your OCI artifacts are applied to the base image.
129+
5. Signing and attestations: Docker signs the customized image and generates
130+
attestations (SBOMs, VEX documents, build provenance).
131+
6. Publishing: The signed customized image and attestations are published to
132+
Docker Hub.
133+
134+
Docker handles the entire process automatically, so you don't need to manage
135+
builds for your customized images. However, you're responsible for testing your
136+
customized images and managing any CVEs introduced by your OCI artifacts.
137+
138+
The following diagram shows the customized image build flow:
139+
140+
```goat {class="text-sm"}
141+
.-------------------. .-------------------. .-------------------.
142+
| Docker monitors |----->| Trigger rebuild |----->| Fetch base |
143+
| OCI artifacts | | | | DHI image |
144+
'-------------------' '-------------------' '-------------------'
145+
|
146+
v
147+
.-------------------. .-------------------. .-------------------.
148+
| Publish to |<-----| Sign & generate |<-----| Apply |
149+
| Docker Hub | | attestations | | customizations |
150+
'-------------------' '-------------------' '-------------------'
151+
```

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

Lines changed: 76 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -92,21 +92,28 @@ To customize a Docker Hardened Image, follow these steps:
9292
- The UID and GID ownership of the script
9393
- The octal file permissions of the script
9494

95-
1. Select **Next: Configure** and then configure the following options.
96-
1. Specify a suffix that is appended to the customized image's tag. For
97-
example, if you specify `custom` when customizing the `dhi-python:3.13`
98-
image, the customized image will be tagged as `dhi-python:3.13_custom`.
99-
1. Select the platforms you want to build the image for.
100-
1. Add [`ENTRYPOINT`](/reference/dockerfile/#entrypoint) and
101-
[`CMD`](/reference/dockerfile/#cmd) arguments to the image. These
102-
arguments are appended to the base image's entrypoint and command.
103-
1. Specify the users to add to the image.
104-
1. Specify the user groups to add to the image.
105-
1. Select which [user](/reference/dockerfile/#user) to run the images as.
106-
1. Specify the [environment variables](/reference/dockerfile/#env) and their
107-
values that the image will contain.
108-
1. Add [annotations](/build/metadata/annotations/) to the image.
109-
1. Add [labels](/reference/dockerfile/#label) to the image.
95+
1. Select **Next: Configure** and then configure the following image settings:
96+
97+
1. Specify the [environment variables](/reference/dockerfile/#env) and their
98+
values that the image will contain.
99+
1. Add [labels](/reference/dockerfile/#label) to the image.
100+
1. Add [annotations](/build/metadata/annotations/) to the image.
101+
1. Specify the users to add to the image.
102+
1. Specify the user groups to add to the image.
103+
1. Select which [user](/reference/dockerfile/#user) to run the images as.
104+
1. Add [`ENTRYPOINT`](/reference/dockerfile/#entrypoint) arguments to the
105+
image. These arguments are appended to the base image's entrypoint.
106+
1. Add [`CMD`](/reference/dockerfile/#cmd) arguments to the image. These
107+
arguments are appended to the base image's command.
108+
1. Specify a suffix for the customization name that is appended to the
109+
customized image's tag. For example, if you specify `custom` when
110+
customizing the `dhi-python:3.13` image, the customized image will be
111+
tagged as `dhi-python:3.13_custom`.
112+
1. Select the platforms you want to build the image for. You must select at
113+
least one platform.
114+
115+
1. Select **Next: Review customization**.
116+
110117
1. Select **Create Customization**.
111118

112119
A summary of the customization appears. It may take some time for the image
@@ -168,6 +175,57 @@ Install the necessary tools or libraries in the first stage, and then copy the
168175
relevant files to the final stage that uses `FROM scratch`. This ensures that
169176
your OCI artifact is minimal and contains only the necessary files.
170177

171-
Build and push the OCI artifact image to a repository in your organization's
172-
namespace and it automatically appears in the customization workflow when you
173-
select the OCI artifacts to add to your customized Docker Hardened Image.
178+
In order for the OCI artifact to be available in a DHI customization, it must be built and
179+
pushed to a repository in the same namespace as the mirrored DHI repository.
180+
181+
If you're customizing a DHI for multiple platforms (such as `linux/amd64` and
182+
`linux/arm64`), build your OCI artifact for all the platforms using the
183+
`--platform` flag:
184+
185+
```console
186+
$ docker buildx build --platform linux/amd64,linux/arm64 \
187+
-t <your-namespace>/my-oci-artifact:latest \
188+
--push .
189+
```
190+
191+
This creates a single image manifest that you can use for each platform. The
192+
customization build system automatically selects the correct platform variant
193+
when building each customized image.
194+
195+
> [!IMPORTANT]
196+
>
197+
> The customization UI will only allow you to select platforms that are
198+
> available in all OCI artifacts you've added. If a platform is missing from
199+
> any OCI artifact, you won't be able to select that platform for your
200+
> customization.
201+
202+
Once pushed to a repository in your organization's namespace, the OCI artifact
203+
automatically appears in the customization workflow when you select OCI
204+
artifacts to add to your customized Docker Hardened Image.
205+
206+
### Best practices for OCI artifacts
207+
208+
Follow these best practices when creating OCI artifacts for DHI customizations:
209+
210+
- Use multi-stage builds: Build or install dependencies in a builder stage,
211+
then copy only the necessary files to a `FROM scratch` final stage. This keeps
212+
the OCI artifact minimal and free of unnecessary build tools.
213+
214+
- Include only essential files: OCI artifacts should contain only the files
215+
you need to add to the customized image. Avoid including package managers,
216+
shells, or other utilities that won't be used in the final image.
217+
218+
- Match target platforms: Build your OCI artifact for all platforms you plan
219+
to use in your customizations. Use `docker buildx build --platform` to create
220+
multi-platform images when needed.
221+
222+
- Use specific tags: Tag your OCI artifacts with specific versions or dates
223+
(like `v1.0` or `20250101`) rather than relying solely on `latest`. This
224+
ensures reproducible builds and makes it easier to track which artifacts are
225+
used in which customizations.
226+
227+
- Enable immutable tags: Consider enabling [immutable
228+
tags](../../docker-hub/repos/manage/hub-images/immutable-tags.md) for your
229+
OCI artifact repositories. This prevents accidental overwrites and ensures that
230+
each version of your OCI artifact remains unchanged, improving reproducibility
231+
and reliability of your customizations.

0 commit comments

Comments
 (0)