diff --git a/content/manuals/dhi/about/_index.md b/content/manuals/dhi/about/_index.md index 5d96bc217fff..6d15154814fa 100644 --- a/content/manuals/dhi/about/_index.md +++ b/content/manuals/dhi/about/_index.md @@ -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 diff --git a/content/manuals/dhi/about/available.md b/content/manuals/dhi/about/available.md index 269b6eaeedb6..192c675f507c 100644 --- a/content/manuals/dhi/about/available.md +++ b/content/manuals/dhi/about/available.md @@ -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: diff --git a/content/manuals/dhi/about/build-process.md b/content/manuals/dhi/about/build-process.md new file mode 100644 index 000000000000..e3fd04921180 --- /dev/null +++ b/content/manuals/dhi/about/build-process.md @@ -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 | +'-------------------' '-------------------' '-------------------' +``` diff --git a/content/manuals/dhi/how-to/customize.md b/content/manuals/dhi/how-to/customize.md index 04dbb68f1020..0be4dad3fd1e 100644 --- a/content/manuals/dhi/how-to/customize.md +++ b/content/manuals/dhi/how-to/customize.md @@ -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 /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. \ No newline at end of file