docker · craig-osterhout · Nov 5, 2025
@@ -8,6 +8,10 @@ params:
       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.
       icon: info
       link: /dhi/about/what/
+    - title: Build process
+      description: Learn how Docker builds, tests, and maintains Docker Hardened Images through an automated, security-focused pipeline.
+      icon: build
+      link: /dhi/about/build-process/
     - title: Image testing
       description: See how Docker Hardened Images are automatically tested for standards compliance, functionality, and security.
       icon: science

@@ -40,7 +40,9 @@ requirements:
 Each image maintains a minimal and secure runtime layer by removing
 non-essential components like shells, package managers, and debugging tools.
 This helps reduce the attack surface while retaining compatibility with common
-runtime environments.
+runtime environments. To maintain this lean, secure foundation, DHI standardizes
+on Debian for glibc-based images, which provides broad compatibility while
+minimizing complexity and maintenance overhead.
 
 Example tags include:
 

@@ -0,0 +1,151 @@
+---
+title: How Docker Hardened Images are built
+linkTitle: Build process
+description: Learn how Docker builds, tests, and maintains Docker Hardened Images through an automated, security-focused pipeline.
+keywords: docker hardened images, slsa build level 3, automated patching, ai guardrail, build process, signed sbom, supply chain security
+weight: 15
+---
+
+Docker Hardened Images are built through an automated pipeline that monitors
+upstream sources, applies security updates, and publishes signed artifacts.
+This page explains the build process for both DHI images and customized
+images built from them.
+
+## Build triggers
+
+Builds start automatically. You don't trigger them manually. The system monitors
+for changes and starts builds in two scenarios:
+
+- [Upstream updates](#upstream-updates)
+- [Customization changes](#customization-changes)
+
+### Upstream updates
+
+New releases, package updates, or CVE fixes from upstream projects trigger base
+image rebuilds. These builds go through quality checks to ensure security and
+reliability.
+
+#### Monitoring for updates
+
+Docker continuously monitors upstream projects for new releases, package
+updates, and security advisories. When changes are detected, the system
+automatically queues affected images for rebuild using a SLSA Build Level
+3-compliant build system.
+
+Docker uses three strategies to track updates:
+
+- GitHub releases: Monitors specific GitHub repositories for new releases and
+  automatically updates the image definition when a new version is published.
+- GitHub tags: Tracks tags in GitHub repositories to detect new versions.
+- Package repositories: Monitors Alpine Linux, Debian, and Ubuntu package
+  repositories through Docker Scout's package database to detect updated
+  packages.
+
+In addition to explicit upstream tracking, Docker also monitors transitive
+dependencies. When a package update is detected (for example, a security patch
+for a library), Docker automatically identifies and rebuilds all images within
+the support window that use that package.
+
+### Customization changes
+
+Updates to your OCI artifact customizations trigger rebuilds of your customized
+images.
+
+When you customize a DHI image, your changes are packaged as OCI artifacts that
+layer on top of the base image. Docker monitors your artifact repositories and
+automatically rebuilds your customized images whenever you push updates.
+
+The rebuild process fetches the current base image, applies your OCI artifacts,
+signs the result, and publishes it automatically. You don't need to manage
+builds or maintain CI pipelines for your customized images.
+
+Customized images are also rebuilt automatically when the base DHI image they
+depend on receives updates, ensuring your images always include the latest
+security patches.
+
+## Build pipeline
+
+The following sections describe the build pipeline architecture and workflow for
+Docker Hardened Images based on:
+
+- [Base image pipeline](#base-image-pipeline)
+- [Customized image pipeline](#customized-image-pipeline)
+
+### Base image pipeline
+
+Each Docker Hardened Image is built through an automated pipeline:
+
+1. Monitoring: Docker monitors upstream sources for updates (new releases,
+   package updates, security advisories).
+2. Rebuild trigger: When changes are detected, an automated rebuild starts.
+3. AI guardrail: An AI system fetches upstream diffs and scans them with
+   language-aware checks. The guardrail focuses on high-leverage issues that can
+   cause significant problems, such as inverted error checks, ignored failures,
+   resource mishandling, or suspicious contributor activity. When it spots
+   potential risks, it blocks the PR from auto-merging.
+4. Human review: If the AI identifies risks with high confidence,
+   Docker engineers review the flagged code, reproduce the issue, and decide on
+   the appropriate action. Engineers often contribute fixes back to upstream
+   projects, improving the code for the entire community. When fixes are accepted
+   upstream, the DHI build pipeline applies the patch immediately to protect
+   customers while the fix moves through the upstream release process.
+5. Testing: Images undergo comprehensive testing for compatibility and
+   functionality.
+6. Signing and attestations: Docker signs each image and generates
+   attestations (SBOMs, VEX documents, build provenance).
+7. Publishing: The signed image and attestations are published to Docker Hub.
+8. Cascade rebuilds: If any customized images use this base, their rebuilds
+   are automatically triggered.
+
+Docker responds quickly to critical vulnerabilities. By building essential
+components from source rather than waiting for packaged updates, Docker can
+patch Critical and High-severity CVEs within days of upstream fixes and publish
+updated images with new attestations.
+
+The following diagram shows the base image build flow:
+
+```goat {class="text-sm"}
+.-------------------.      .-------------------.      .-------------------.      .-------------------.
+| Docker monitors   |----->| Trigger rebuild   |----->| AI guardrail      |----->| Human review      |
+| upstream sources  |      |                   |      | scans changes     |      |                   |
+'-------------------'      '-------------------'      '-------------------'      '-------------------'
+                                                                                           |
+                                                                                           v
+.-------------------.      .-------------------.      .-------------------.      .-------------------.
+| Cascade rebuilds  |<-----| Publish to        |<-----| Sign & generate   |<-----| Testing           |
+| (if needed)       |      | Docker Hub        |      | attestations      |      |                   |
+'-------------------'      '-------------------'      '-------------------'      '-------------------'
+```
+
+### Customized image pipeline
+
+When you customize a DHI image, the build process is simplified:
+
+1. Monitoring: Docker monitors your OCI artifact repositories for changes.
+2. Rebuild trigger: When you push updates to your OCI artifacts, or when the base
+   DHI image is updated, an automated rebuild starts.
+3. Fetch base image: The latest base DHI image is fetched.
+4. Apply customizations: Your OCI artifacts are applied to the base image.
+5. Signing and attestations: Docker signs the customized image and generates
+   attestations (SBOMs, VEX documents, build provenance).
+6. Publishing: The signed customized image and attestations are published to
+   Docker Hub.
+
+Docker handles the entire process automatically, so you don't need to manage
+builds for your customized images. However, you're responsible for testing your
+customized images and managing any CVEs introduced by your OCI artifacts.
+
+The following diagram shows the customized image build flow:
+
+```goat {class="text-sm"}
+.-------------------.      .-------------------.      .-------------------.
+| Docker monitors   |----->| Trigger rebuild   |----->| Fetch base        |
+| OCI artifacts     |      |                   |      | DHI image         |
+'-------------------'      '-------------------'      '-------------------'
+                                                               |
+                                                               v
+.-------------------.      .-------------------.      .-------------------.
+| Publish to        |<-----| Sign & generate   |<-----| Apply             |
+| Docker Hub        |      | attestations      |      | customizations    |
+'-------------------'      '-------------------'      '-------------------'
+```
@@ -92,21 +92,28 @@ To customize a Docker Hardened Image, follow these steps:
       - The UID and GID ownership of the script
       - The octal file permissions of the script
 
-1. Select **Next: Configure** and then configure the following options.
-1. Specify a suffix that is appended to the customized image's tag. For
-   example, if you specify `custom` when customizing the `dhi-python:3.13`
-   image, the customized image will be tagged as `dhi-python:3.13_custom`.
-1. Select the platforms you want to build the image for.
-1. Add [`ENTRYPOINT`](/reference/dockerfile/#entrypoint) and
-   [`CMD`](/reference/dockerfile/#cmd) arguments to the image. These
-   arguments are appended to the base image's entrypoint and command.
-1. Specify the users to add to the image.
-1. Specify the user groups to add to the image.
-1. Select which [user](/reference/dockerfile/#user) to run the images as.
-1. Specify the [environment variables](/reference/dockerfile/#env) and their
-   values that the image will contain.
-1. Add [annotations](/build/metadata/annotations/) to the image.
-1. Add [labels](/reference/dockerfile/#label) to the image.
+1. Select **Next: Configure** and then configure the following image settings:
+
+   1. Specify the [environment variables](/reference/dockerfile/#env) and their
+      values that the image will contain.
+   1. Add [labels](/reference/dockerfile/#label) to the image.
+   1. Add [annotations](/build/metadata/annotations/) to the image.
+   1. Specify the users to add to the image.
+   1. Specify the user groups to add to the image.
+   1. Select which [user](/reference/dockerfile/#user) to run the images as.
+   1. Add [`ENTRYPOINT`](/reference/dockerfile/#entrypoint) arguments to the
+      image. These arguments are appended to the base image's entrypoint.
+   1. Add [`CMD`](/reference/dockerfile/#cmd) arguments to the image. These
+      arguments are appended to the base image's command.
+   1. Specify a suffix for the customization name that is appended to the
+      customized image's tag. For example, if you specify `custom` when
+      customizing the `dhi-python:3.13` image, the customized image will be
+      tagged as `dhi-python:3.13_custom`.
+   1. Select the platforms you want to build the image for. You must select at
+      least one platform.
+
+1. Select **Next: Review customization**.
+
 1. Select **Create Customization**.
 
    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
 relevant files to the final stage that uses `FROM scratch`. This ensures that
 your OCI artifact is minimal and contains only the necessary files.
 
-Build and push the OCI artifact image to a repository in your organization's
-namespace and it automatically appears in the customization workflow when you
-select the OCI artifacts to add to your customized Docker Hardened Image.
+In order for the OCI artifact to be available in a DHI customization, it must be built and
+pushed to a repository in the same namespace as the mirrored DHI repository.
+
+If you're customizing a DHI for multiple platforms (such as `linux/amd64` and
+`linux/arm64`), build your OCI artifact for all the platforms using the
+`--platform` flag:
+
+```console
+$ docker buildx build --platform linux/amd64,linux/arm64 \
+  -t <your-namespace>/my-oci-artifact:latest \
+  --push .
+```
+
+This creates a single image manifest that you can use for each platform. The
+customization build system automatically selects the correct platform variant
+when building each customized image.
+
+> [!IMPORTANT]
+>
+> The customization UI will only allow you to select platforms that are
+> available in all OCI artifacts you've added. If a platform is missing from
+> any OCI artifact, you won't be able to select that platform for your
+> customization.
+
+Once pushed to a repository in your organization's namespace, the OCI artifact
+automatically appears in the customization workflow when you select OCI
+artifacts to add to your customized Docker Hardened Image.
+
+### Best practices for OCI artifacts
+
+Follow these best practices when creating OCI artifacts for DHI customizations:
+
+- Use multi-stage builds: Build or install dependencies in a builder stage,
+  then copy only the necessary files to a `FROM scratch` final stage. This keeps
+  the OCI artifact minimal and free of unnecessary build tools.
+
+- Include only essential files: OCI artifacts should contain only the files
+  you need to add to the customized image. Avoid including package managers,
+  shells, or other utilities that won't be used in the final image.
+
+- Match target platforms: Build your OCI artifact for all platforms you plan
+  to use in your customizations. Use `docker buildx build --platform` to create
+  multi-platform images when needed.
+
+- Use specific tags: Tag your OCI artifacts with specific versions or dates
+  (like `v1.0` or `20250101`) rather than relying solely on `latest`. This
+  ensures reproducible builds and makes it easier to track which artifacts are
+  used in which customizations.
+
+- Enable immutable tags: Consider enabling [immutable
+  tags](../../docker-hub/repos/manage/hub-images/immutable-tags.md) for your
+  OCI artifact repositories. This prevents accidental overwrites and ensures that
+  each version of your OCI artifact remains unchanged, improving reproducibility
+  and reliability of your customizations.