mirror/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-06-19 07:35:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

dhi: add initial docs (#22852)

Browse Source 
<!--Delete sections as needed -->

## Description

Add initial DHI docs

## Related issues or tickets

ENGDOCS- 22650

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review

---------

Signed-off-by: Craig <craig.osterhout@docker.com>
This commit is contained in:
Craig Osterhout
2025-06-16 14:06:49 -07:00
committed by GitHub
parent f456066c2b
commit 983d541636
49 changed files with 3731 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.vscode/docker.code-snippets
Vendored
+1 -1
View File
@@ -54,4 +54,4 @@
"body": ["{{< button url=\"$1\" text=\"$2\" >}}"],
"description": "Insert a Hugo button",
},
}
}
assets/icons/dhi.svg
+13
View File
@@ -0,0 +1,13 @@
<svg
class="w-5 h-5 text-gray-800 dark:text-white"
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="2"
stroke-linecap="round"
stroke-linejoin="round"
xmlns="http://www.w3.org/2000/svg"
focusable="false"
aria-hidden="true"
>
<path d="M18.1639 21.6147V18.6147M18.1639 18.6147V15.6147M18.1639 18.6147H15.1639M18.1639 18.6147H21.1639M19.8692 13.3281C19.9541 12.8974 20 12.4544 20 11.9999V7.21747C20 6.41796 20 6.0182 19.8692 5.67457C19.7537 5.37101 19.566 5.10015 19.3223 4.8854C19.0465 4.64231 18.6722 4.50195 17.9236 4.22122L12.5618 2.21054C12.3539 2.13258 12.25 2.0936 12.143 2.07815C12.0482 2.06444 11.9518 2.06444 11.857 2.07815C11.75 2.0936 11.6461 2.13258 11.4382 2.21054L6.0764 4.22122C5.3278 4.50195 4.9535 4.64231 4.67766 4.8854C4.43398 5.10015 4.24627 5.37101 4.13076 5.67457C4 6.0182 4 6.41796 4 7.21747V11.9999C4 16.9083 9.35396 20.4783 11.302 21.6147C11.5234 21.7439 11.6341 21.8085 11.7903 21.842C11.9116 21.868 12.0884 21.868 12.2097 21.842C12.3659 21.8085 12.4766 21.7439 12.698 21.6147C12.986 21.4467 13.3484 21.2255 13.757 20.9547M14.517 9.70865C14.517 10.4365 14.2081 11.0922 13.7143 11.5517C13.5354 11.7181 13.446 11.8013 13.4126 11.8658C13.3774 11.9337 13.3672 11.9737 13.3656 12.0501C13.364 12.1227 13.3936 12.2115 13.4528 12.3891L14.2225 14.6983C14.322 14.9966 14.3717 15.1458 14.3419 15.2645C14.3158 15.3684 14.2509 15.4584 14.1606 15.516C14.0574 15.5818 13.9002 15.5818 13.5858 15.5818H10.4142C10.0998 15.5818 9.94255 15.5818 9.83936 15.516C9.74903 15.4584 9.68416 15.3684 9.65807 15.2645C9.62826 15.1458 9.67797 14.9966 9.7774 14.6983L10.5472 12.3891C10.6063 12.2115 10.6359 12.1227 10.6344 12.0501C10.6328 11.9737 10.6226 11.9337 10.5874 11.8658C10.5539 11.8013 10.4645 11.7181 10.2857 11.5517C9.79182 11.0922 9.48291 10.4365 9.48291 9.70865C9.48291 8.31852 10.6098 7.19159 12 7.19159C13.3901 7.19159 14.517 8.31852 14.517 9.70865Z" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path></svg>
Side by Side

After

Width:  |  Height:  |  Size: 2.0 KiB

content/manuals/_index.md
+4
View File
@@ -49,6 +49,10 @@ params:
description: Your command center for container development.
icon: /icons/Whale.svg
link: /desktop/
- title: Docker Hardened Images
description: Secure, minimal base images for trusted software delivery.
icon: /icons/dhi.svg
link: /dhi/
- title: Build Cloud
description: Build your images faster in the cloud.
icon: /icons/logo-build-cloud.svg
content/manuals/dhi/_index.md
+50
View File
@@ -0,0 +1,50 @@
---
title: Docker Hardened Images
description: Secure, minimal, and production-ready base images
weight: 13
params:
sidebar:
badge:
color: green
text: New
group: Products
grid_sections:
- title: Quickstart
description: Follow a step-by-step guide to explore, mirror, and run a Docker Hardened Image.
icon: rocket_launch
link: /dhi/get-started/
- title: About
description: Learn what Docker Hardened Images are, how they're built, and what sets them apart from typical base images.
icon: info
link: /dhi/about/
- title: Features
description: Discover the security, compliance, and enterprise-readiness features built into Docker Hardened Images.
icon: lock
link: /dhi/features/
- title: How-tos
description: Step-by-step guides for using, verifying, scanning, and migrating to Docker Hardened Images.
icon: play_arrow
link: /dhi/how-to/
- title: Core concepts
description: Understand the secure supply chain principles that make Docker Hardened Images production-ready.
icon: fact_check
link: /dhi/core-concepts/
- title: Troubleshoot
description: Resolve common issues with building, running, or debugging Docker Hardened Images.
icon: help_center
link: /dhi/troubleshoot/
---
{{< summary-bar feature_name="Docker Hardened Images" >}}
Docker Hardened Images (DHIs) are minimal, secure, and production-ready
container base and application images maintained by Docker. Designed to reduce
vulnerabilities and simplify compliance, DHIs integrate easily into your
existing Docker-based workflows with little to no retooling required.
Explore the sections below to get started with Docker Hardened Images, integrate
them into your workflow, and learn what makes them secure and enterprise-ready.
{{< grid
items="grid_sections"
>}}
content/manuals/dhi/about/_index.md
+35
View File
@@ -0,0 +1,35 @@
---
title: About
description: Learn about Docker Hardened Images, their purpose, how they are built and tested, and the shared responsibility model for security.
weight: 5
params:
grid_about:
- title: What are hardened images and why use them?
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: Image testing
description: See how Docker Hardened Images are automatically tested for standards compliance, functionality, and security.
icon: science
link: /dhi/about/test/
- title: Responsibility overview
description: Understand Docker's role and your responsibilities when using Docker Hardened Images as part of your secure software supply chain.
icon: group
link: /dhi/about/responsibility/
- title: Image types
description: Learn about the different image types, distributions, and variants offered in the Docker Hardened Images catalog.
icon: view_module
link: /dhi/about/available/
---
Docker Hardened Images (DHIs) are purpose-built for security, compliance, and
reliability in modern software supply chains. This section explains what makes
these images different from standard base and application images, how they're
built and tested, and how Docker and users share responsibility in securing
containerized workloads.
## Learn about Docker Hardened Images
{{< grid
items="grid_about"
>}}
content/manuals/dhi/about/available.md
+73
View File
@@ -0,0 +1,73 @@
---
linktitle: Image types
title: Available types of Docker Hardened Images
description: Learn about the different image types, distributions, and variants offered in the Docker Hardened Images catalog.
keywords: docker hardened images, distroless containers, distroless images, docker distroless, alpine base image, debian base image, development containers, runtime containers, secure base image, multi-stage builds
weight: 20
---
Docker Hardened Images (DHI) is a comprehensive catalog of
security-hardened container images built to meet diverse
development and production needs.
## Framework and application images
DHI includes a selection of popular frameworks and application images, each
hardened and maintained to ensure security and compliance. These images
integrate seamlessly into existing workflows, allowing developers to focus on
building applications without compromising on security.
For example, you might find repositories like the following in the DHI catalog:
- `node`: framework for Node.js applications
- `python`: framework for Python applications
- `nginx`: web server image
## Compatibility options
Docker Hardened Images are available in different base image options, giving you
flexibility to choose the best match for your environment and workload
requirements:
- Debian-based images: A good fit if you're already working in glibc-based
environments. Debian is widely used and offers strong compatibility across
many language ecosystems and enterprise systems.
- Alpine-based images: A smaller and more lightweight option using musl libc.
These images are faster to pull and have a reduced footprint, though you may
need to account for musl-glibc differences in some applications.
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.
Example tags include:
- `3.9.23-alpine3.21`: Alpine-based image for Python 3.9.23
- `3.9.23-debian12`: Debian-based image for Python 3.9.23
If you're not sure which to choose, start with the base you're already familiar
with. Debian tends to offer the broadest compatibility.
## Development and runtime variants
To accommodate different stages of the application lifecycle, DHI offers images
in several variants:
- Development (dev) images: Equipped with necessary development tools and
libraries, these images facilitate the building and testing of applications in a
secure environment. They include a shell, package manager, a root user, and
other tools needed for development.
- Runtime images: Stripped of development tools, these images contain only the
essential components needed to run applications, ensuring a minimal attack
surface in production.
This separation supports multi-stage builds, enabling developers to compile code
in a secure build environment and deploy it using a lean runtime image.
For example, you might find tags like the following in a DHI repository:
- `3.9.23-debian12`: runtime image for Python 3.9.23
- `3.9.23-debian12-dev`: development image for Python 3.9.23
content/manuals/dhi/about/responsibility.md
+66
View File
@@ -0,0 +1,66 @@
---
title: Understanding roles and responsibilities for Docker Hardened Images
linkTitle: Responsibility overview
description: Understand the division of responsibilities between Docker, upstream projects, and you when using Docker Hardened Images.
keywords: software supply chain security, signed sbom, vex document, container provenance, image attestation
weight: 46
---
Docker Hardened Images (DHIs) are curated and maintained by Docker, and built
using upstream open source components. To deliver security, reliability, and
compliance, responsibilities are shared among three groups:
- Upstream maintainers: the developers and communities responsible for the
open source software included in each image.
- Docker: the provider of hardened, signed, and maintained container images.
- You (the customer): the consumer who runs and, optionally, customizes DHIs
in your environment.
This topic outlines who handles what, so you can use DHIs effectively and
securely.
## Releases
- Upstream: Publishes and maintains official releases of the software
components included in DHIs. This includes versioning, changelogs, and
deprecation notices.
- Docker: Builds, hardens, and signs Docker Hardened Images based on
upstream versions. Docker maintains these images in line with upstream release
timelines and internal policies.
- You: Ensure you're staying on supported versions of DHIs and upstream
projects. Using outdated or unsupported components can introduce security
risk.
## Patching
- Upstream: Maintains and updates the source code for each component,
including fixing vulnerabilities in libraries and dependencies.
- Docker: Rebuilds and re-releases images with upstream patches applied.
Docker also monitors for vulnerabilities and rapidly publishes updates to
affected images.
- You: Apply DHI updates in your environments and patch any software or
dependencies you install on top of the base image.
## Testing
- Upstream: Defines the behavior and functionality of the original software,
and is responsible for validating core features.
- Docker: Validates that DHIs start, run, and behave consistently with
upstream expectations. Docker also runs security scans and includes a [testing
attestation](../core-concepts/attestations.md) with each image.
- You: Test your application on top of DHIs and validate that any changes or
customizations function as expected in your environment.
## Security and compliance
- Docker: Publishes signed SBOMs, VEX documents, provenance data, and CVE
scan results with each image to support compliance and supply chain security.
- You: Integrate DHIs into your security and compliance workflows, including
vulnerability management and auditing.
## Summary
Docker Hardened Images give you a secure foundation, complete with signed
metadata and upstream transparency. Your role is to make informed use of these
images, apply updates promptly, and validate that your configurations and
applications meet your internal requirements.
content/manuals/dhi/about/test.md
+148
View File
@@ -0,0 +1,148 @@
---
title: How Docker Hardened Images are tested
linktitle: Image testing
description: See how Docker Hardened Images are automatically tested for standards compliance, functionality, and security.
keywords: docker scout, test attestation, cosign verify, image testing, vulnerability scan
weight: 45
---
Docker Hardened Images (DHIs) are designed to be secure, minimal, and
production-ready. To ensure their reliability and security, Docker employs a
comprehensive testing strategy, which you can independently verify using signed
attestations and open tooling.
Every image is tested for standards compliance, functionality, and security. The
results of this testing are embedded as signed attestations, which can be
[inspected and verified](#view-and-verify-the-test-attestation) programmatically
using the Docker Scout CLI.
## Testing strategy overview
The testing process for DHIs focuses on two main areas:
- Image standards compliance: Ensuring that each image adheres to strict size,
security, and compatibility standards.
- Application functionality: Verifying that applications within the images
function correctly and meet expected performance benchmarks.
## Image standards compliance
Each DHI undergoes rigorous checks to meet the following standards:
- Minimal attack surface: Images are built to be as small as possible, removing
unnecessary components to reduce potential vulnerabilities.
- Near-zero known CVEs: Images are scanned using tools like Docker Scout to
ensure they are free from known Common Vulnerabilities and Exposures (CVEs).
- Multi-architecture support: DHIs are built for multiple architectures,
including `linux/amd64` and `linux/arm64`, to ensure broad compatibility.
- Kubernetes compatibility: Images are tested to run seamlessly within
Kubernetes clusters, ensuring they meet the requirements for container
orchestration environments.
## Application functionality testing
Docker tests Docker Hardened Images to ensure they behave as expected in typical
usage scenarios. This includes verifying that:
- Applications start and run successfully in containerized environments.
- Runtime behavior aligns with upstream expectations.
- Build variants (like `-dev` images) support common development and build tasks.
The goal is to ensure that DHIs work out of the box for the most common use
cases while maintaining the hardened, minimal design.
## Automated testing and CI/CD integration
Docker integrates automated testing into its Continuous Integration/Continuous
Deployment (CI/CD) pipelines:
- Automated scans: Each image build triggers automated scans for vulnerabilities
and compliance checks.
- Reproducible builds: Build processes are designed to be reproducible, ensuring
consistency across different environments.
- Continuous monitoring: Docker continuously monitors for new vulnerabilities
and updates images accordingly to maintain security standards.
## Testing attestation
Docker provides a test attestation that details the testing and validation
processes each DHI has undergone.
### View and verify the test attestation
You can view and verify this attestation using the Docker Scout CLI.
1. Use the `docker scout attest get` command with the test predicate type:
```console
$ docker scout attest get \
--predicate-type https://scout.docker.com/tests/v0.1 \
--predicate \
<your-namespace>/dhi-<image>:<tag> --platform <platform>
```
For example:
```console
$ docker scout attest get \
--predicate-type https://scout.docker.com/tests/v0.1 \
--predicate \
docs/dhi-python:3.13 --platform linux/amd64
```
This contains a list of tests and their results.
Example output:
```console
v SBOM obtained from attestation, 101 packages found
v Provenance obtained from attestation
{
"reportFormat": "CTRF",
"results": {
"summary": {
"failed": 0,
"passed": 1,
"skipped": 0,
"start": 1749216533,
"stop": 1749216574,
"tests": 1
},
"tests": [
{
...
```
2. Verify the test attestation signature. To ensure the attestation is authentic
and signed by Docker, run:
```console
docker scout attest get \
--predicate-type https://scout.docker.com/tests/v0.1 \
--verify \
<your-namespace>/dhi-<image>:<tag> --platform <platform>
```
Example output:
```console
v SBOM obtained from attestation, 101 packages found
v Provenance obtained from attestation
v cosign verify registry.scout.docker.com/docker/dhi-python@sha256:70c8299c4d3cb4d5432734773c45ae58d8acc2f2f07803435c65515f662136d5 \
--key https://registry.scout.docker.com/keyring/dhi/latest.pub --experimental-oci11
Verification for registry.scout.docker.com/docker/dhi-python@sha256:70c8299c4d3cb4d5432734773c45ae58d8acc2f2f07803435c65515f662136d5 --
The following checks were performed on each of these signatures:
- The cosign claims were validated
- Existence of the claims in the transparency log was verified offline
- The signatures were verified against the specified public key
i Signature payload
...
```
If the attestation is valid, Docker Scout will confirm the signature and show
the matching Cosign verify-attestation command.
To view other attestations, such as SBOMs or vulnerability reports, see [Verify
an image](../how-to/verify.md).
content/manuals/dhi/about/what.md
+94
View File
@@ -0,0 +1,94 @@
---
title: What are hardened images and why use them?
linktitle: Hardened images
description: Learn what a hardened image is, why it matters, and how Docker Hardened Images offer stronger security, compliance, and operational efficiency.
keywords: hardened container image, docker hardened images, distroless container, slsa build level 3, signed sbom, vulnerability scan, compliance-ready container
weight: 5
---
In today’s diverse software environments, container images are often designed
for flexibility and broad compatibility. While that makes them ideal for many
use cases, it can also result in images that include more components than needed
for specific workloads. Docker Hardened Images take a minimal-by-design approach
to help reduce image size, limit the attack surface, and streamline security and
compliance workflows.
Hardened images solve this by minimizing what's in the container image. Less
software means fewer vulnerabilities, faster deployments, and fewer red
dashboards to chase down every week.
For platform engineers and security teams, hardened images offer a way out of
the CVE triage cycle, letting you focus on delivering secure, compliant
infrastructure without constant firefighting.
## What is a hardened image?
A hardened image is a container image that has been deliberately minimized and
secured to reduce vulnerabilities and meet stringent security and compliance
requirements. Unlike standard images, which may include non-essential components
that increase risk, hardened images are streamlined to include only what’s
needed to run your application securely.
## Benefits of hardened images
- Reduced attack surface: By removing non-essential components, hardened images
limit potential entry points for attackers.
- Improved security posture: Regular updates and vulnerability scans help ensure
hardened images remain secure over time.
- Compliance facilitation: Inclusion of signed metadata like SBOMs supports
meeting regulatory and organizational compliance standards.
- Operational efficiency: Smaller image sizes lead to faster pulls, lower runtime overhead, and reduced cloud resource costs.
## What is a Docker Hardened Image?
Docker Hardened Images (DHIs) take hardened images even further by combining
minimal, secure design with enterprise-grade support and tooling. Built with
security at the core, these images are continuously maintained, tested, and
validated to meet today’s toughest software supply chain and compliance
standards.
Docker Hardened Images are secure by default, minimal by design, and maintained
so you don’t have to.
## How Docker Hardened Images differ from generic hardened images
- SLSA-compliant builds: Docker Hardened Images are built to meet [SLSA Build
Level 3](../core-concepts/slsa.md), ensuring a tamper-resistant, verifiable,
and auditable build process that protects against supply chain threats.
- Distroless approach: Unlike traditional base images that bundle an entire OS
with shells and package managers, [distroless
images](../core-concepts/distroless.md) exclude the OS layer and include only
your app and its runtime dependencies, reducing the attack surface by up to 95
percent and improving performance.
- Continuous maintenance: All DHIs are continuously monitored and updated to
maintain near-zero known exploitable [CVEs](../core-concepts/cves.md), helping
your teams avoid patch fatigue and surprise alerts.
- Compliance-ready: Each image includes cryptographically signed metadata:
- [SBOMs](../core-concepts/sbom.md) that show what's in the image
- [VEX documents](../core-concepts/vex.md) to identify which vulnerabilities
are actually exploitable
- [Build provenance](../core-concepts/provenance.md) that proves how and where
the image was built
- Compatibility-focused design: Docker Hardened Images provide a minimal runtime
environment while maintaining compatibility with common Linux distributions.
They remove non-essential components like shells and package managers to
enhance security, yet retain a small base layer built on familiar distribution
standards. You can choose between Alpine-based images (using musl libc) and
Debian-based images (using glibc) to suit your application's compatibility
requirements.
## Why use Docker Hardened Images?
Docker Hardened Images (DHIs) are secure by default, minimal by design, and
maintained so you don't have to. They offer:
- Images built for peace of mind: Ultra-minimal and distroless, DHIs eliminate up to 95 percent of the traditional container attack surface.
- No more patch panic: With continuous CVE scanning and SLA-backed remediation, Docker helps you stay ahead of threats.
- Audit-ready images: All DHIs include signed SBOMs, VEX, and provenance that support security and compliance workflows.
- Images that work with your stack: Available in Alpine and Debian flavors, DHIs drop into your existing Dockerfiles and pipelines.
- Images backed by enterprise support: Get peace of mind with Docker's support and rapid response to critical vulnerabilities.
content/manuals/dhi/core-concepts/_index.md
+93
View File
@@ -0,0 +1,93 @@
---
title: Core concepts
description: Learn the core concepts behind Docker Hardened Images, including security metadata, vulnerability management, image structure, and verification.
weight: 30
params:
grid_concepts_metadata:
- title: Attestations
description: Review the full set of signed attestations included with each Docker Hardened Image, such as SBOMs, VEX, build provenance, and scan results.
icon: assignment
link: /dhi/core-concepts/attestations/
- title: Software Bill of Materials (SBOMs)
description: Learn what SBOMs are, why they matter, and how Docker Hardened Images include signed SBOMs to support transparency and compliance.
icon: list_alt
link: /dhi/core-concepts/sbom/
- title: Supply-chain Levels for Software Artifacts (SLSA)
description: Learn how Docker Hardened Images comply with SLSA Build Level 3 and how to verify provenance for secure, tamper-resistant builds.
icon: fact_check
link: /dhi/core-concepts/slsa/
- title: Image provenance
description: Learn how build provenance metadata helps trace the origin of Docker Hardened Images and support compliance with SLSA.
icon: track_changes
link: /dhi/core-concepts/provenance/
grid_concepts_risk:
- title: Common Vulnerabilities and Exposures (CVEs)
description: Understand what CVEs are, how Docker Hardened Images reduce exposure, and how to scan images for vulnerabilities using popular tools.
icon: error
link: /dhi/core-concepts/cves/
- title: Vulnerability Exploitability eXchange (VEX)
description: Learn how VEX helps you prioritize real risks by identifying which vulnerabilities in Docker Hardened Images are actually exploitable.
icon: warning
link: /dhi/core-concepts/vex/
- title: Software Supply Chain Security
description: Learn how Docker Hardened Images help secure every stage of your software supply chain with signed metadata, provenance, and minimal attack surface.
icon: shield
link: /dhi/core-concepts/sscs/
- title: Secure Software Development Lifecycle (SSDLC)
description: See how Docker Hardened Images support a secure SDLC by integrating with scanning, signing, and debugging tools.
icon: build_circle
link: /dhi/core-concepts/ssdlc/
grid_concepts_structure:
- title: Distroless images
description: Learn how Docker Hardened Images use distroless variants to minimize attack surface and remove unnecessary components.
icon: layers_clear
link: /dhi/core-concepts/distroless/
- title: glibc and musl support in Docker Hardened Images
description: Compare glibc and musl variants of DHIs to choose the right base image for your application’s compatibility, size, and performance needs.
icon: swap_vert
link: /dhi/core-concepts/glibc-musl/
- title: Image immutability
description: Understand how image digests, read-only containers, and signed metadata ensure Docker Hardened Images are tamper-resistant and immutable.
icon: do_not_disturb_on
link: /dhi/core-concepts/immutability/
- title: Image hardening
description: Learn how Docker Hardened Images are designed for security, with minimal components, nonroot execution, and secure-by-default configurations.
icon: security
link: /dhi/core-concepts/hardening/
grid_concepts_verification:
- title: Digests
description: Learn how to use immutable image digests to guarantee consistency and verify the exact Docker Hardened Image you're running.
icon: fingerprint
link: /dhi/core-concepts/digests/
- title: Code signing
description: Understand how Docker Hardened Images are cryptographically signed using Cosign to verify authenticity, integrity, and secure provenance.
icon: key
link: /dhi/core-concepts/signatures/
---
Docker Hardened Images (DHIs) are built on a foundation of secure software
supply chain practices. This section explains the core concepts behind that
foundation, from signed attestations and immutable digests to standards like SLSA
and VEX.
Start here if you want to understand how Docker Hardened Images support compliance,
transparency, and security.
## Security metadata and attestations
{{< grid items="grid_concepts_metadata" >}}
## Vulnerability and risk management
{{< grid items="grid_concepts_risk" >}}
## Image structure and behavior
{{< grid items="grid_concepts_structure" >}}
## Verification and traceability
{{< grid items="grid_concepts_verification" >}}
content/manuals/dhi/core-concepts/attestations.md
+100
View File
@@ -0,0 +1,100 @@
---
title: Attestations
description: Review the full set of signed attestations included with each Docker Hardened Image, such as SBOMs, VEX, build provenance, and scan results.
keywords: container image attestations, signed sbom, build provenance, slsa compliance, vex document
---
Docker Hardened Images (DHIs) include comprehensive, signed security
attestations that verify the image's build process, contents, and security
posture. These attestations are a core part of secure software supply chain
practices and help users validate that an image is trustworthy and
policy-compliant.
## What is an attestation?
An attestation is a signed statement that provides verifiable information
about an image, such as how it was built, what's inside it, and what security
checks it has passed. Attestations are typically signed using Sigstore tooling
(such as Cosign), making them tamper-evident and cryptographically verifiable.
Attestations follow standardized formats (like [in-toto](https://in-toto.io/),
[CycloneDX](https://cyclonedx.org/), and [SLSA](https://slsa.dev/)) and are
attached to the image as OCI-compliant metadata. They can be generated
automatically during image builds or added manually to document extra tests,
scan results, or custom provenance.
## Why are attestations important?
Attestations provide critical visibility into the software supply chain by:
- Documenting *what* went into an image (e.g., SBOMs)
- Verifying *how* it was built (e.g., build provenance)
- Capturing *what security scans* it has passed or failed (e.g., CVE reports,
secrets scans, test results)
- Helping organizations enforce compliance and security policies
- Supporting runtime trust decisions and CI/CD policy gates
They are essential for meeting industry standards such as SLSA,
and help teams reduce the risk of supply chain attacks by making build and
security data transparent and verifiable.
## How Docker Hardened Images use attestations
All DHIs are built using [SLSA Build Level
3](https://slsa.dev/spec/latest/levels) practices, and each image variant is
published with a full set of signed attestations. These attestations allow users
to:
- Verify that the image was built from trusted sources in a secure environment
- View SBOMs in multiple formats to understand component-level details
- Review scan results to check for vulnerabilities or embedded secrets
- Confirm the build and deployment history of each image
Attestations are automatically published and associated with each mirrored DHI
in your Docker Hub organization. They can be inspected using tools like [Docker
Scout](../how-to/verify.md) or
[Cosign](https://docs.sigstore.dev/cosign/overview), and are consumable by CI/CD
tooling or security platforms.
## Available attestations
The following attestations are available for each image variant.
| Attestation type | Description | Predicate type URI |
|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|
| CycloneDX SBOM | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing components, libraries, and versions. | `https://cyclonedx.org/bom/v1.5` |
| SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, widely adopted in open-source ecosystems. | `https://spdx.dev/Document` |
| Scout SBOM | An SBOM generated and signed by Docker Scout, including additional Docker-specific metadata. | `https://scout.docker.com/sbom/v0.1` |
| CVEs (in-toto format) | A list of known vulnerabilities (CVEs) affecting the image's components, based on package and distro scanning. | `https://in-toto.io/attestation/vulns/v0.1` |
| CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data. | `https://scout.docker.com/vulnerabilities/v0.1` |
| VEX | A [Vulnerability Exploitability eXchange (VEX)](https://openvex.dev/) document that identifies vulnerabilities that do not apply to the image and explains why (e.g., not reachable or not present). | `https://openvex.dev/ns/v0.2.0` |
| Secrets Scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys. | `https://scout.docker.com/secrets/v0.1` |
| Virus Scan | Results of antivirus scans performed on the image layers. | `https://scout.docker.com/virus/v0.1` |
| Tests | A record of automated tests run against the image, such as functional checks or validation scripts. | `https://scout.docker.com/tests/v0.1` |
| Scout Health Score | A signed attestation from Docker Scout that summarizes the overall security and quality posture of the image. | `https://scout.docker.com/health/v0.1` |
| Build Provenance (Scout) | Provenance metadata generated by Docker Scout, including the source Git commit, build parameters, and environment details. | `https://scout.docker.com/provenance/v0.1` |
| SLSA Provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the image was built, including build tool, parameters, and source. | `https://slsa.dev/provenance/v0.2` |
| SLSA Verification Summary | A summary attestation indicating the image's compliance with SLSA requirements. | `https://slsa.dev/verification_summary/v1` |
## View and verify attestations
To view and verify attestations for an image, see [Verify a Docker Hardened
Image](../how-to/verify.md).
## Add your own attestations
In addition to the comprehensive attestations provided by Docker Hardened
Images, you can add your own signed attestations when building derivative
images. This is especially useful if you’re building new applications on top of
a DHI and want to maintain transparency, traceability, and trust in your
software supply chain.
By attaching attestations such as SBOMs, build provenance, or custom metadata,
you can meet compliance requirements, pass security audits, and support policy
evaluation tools like Docker Scout.
These attestations can then be verified downstream using tools
like Cosign or Docker Scout.
To learn how to attach custom attestations during the build process, see [Build
attestations](/manuals/build/metadata/attestations.md).
content/manuals/dhi/core-concepts/cves.md
+179
View File
@@ -0,0 +1,179 @@
---
title: Common Vulnerabilities and Exposures (CVEs)
linktitle: CVEs
description: Understand what CVEs are, how Docker Hardened Images reduce exposure, and how to scan images for vulnerabilities using popular tools.
keywords: docker cve scan, grype vulnerability scanner, trivy image scan, vex attestation, secure container images
---
## What are CVEs?
CVEs are publicly disclosed cybersecurity flaws in software or hardware. Each
CVE is assigned a unique identifier (e.g., CVE-2024-12345) and includes a
standardized description, allowing organizations to track and address
vulnerabilities consistently.
In the context of Docker, CVEs often pertain to issues within base images, or
application dependencies. These vulnerabilities can range from minor bugs to
critical security risks, such as remote code execution or privilege escalation.
## Why are CVEs important?
Regularly scanning and updating Docker images to mitigate CVEs is crucial for
maintaining a secure and compliant environment. Ignoring CVEs can lead to severe
security breaches, including:
- Unauthorized access: Exploits can grant attackers unauthorized access to
systems.
- Data breaches: Sensitive information can be exposed or stolen.
- Service disruptions: Vulnerabilities can be leveraged to disrupt services or
cause downtime.
- Compliance violations: Failure to address known vulnerabilities can lead to
non-compliance with industry regulations and standards.
## How Docker Hardened Images help mitigate CVEs
Docker Hardened Images (DHIs) are crafted to minimize the risk of CVEs from the
outset. By adopting a security-first approach, DHIs offer several advantages in
CVE mitigation:
- Reduced attack surface: DHIs are built using a distroless approach, stripping
away unnecessary components and packages. This reduction in image size, up to
95% smaller than traditional images, limits the number of potential
vulnerabilities, making it harder for attackers to exploit unneeded software.
- Faster CVE remediation: Maintained by Docker with an enterprise-grade SLA,
DHIs are continuously updated to address known vulnerabilities. Critical and
high-severity CVEs are patched quickly, ensuring that your containers remain
secure without manual intervention.
- Proactive vulnerability management: By utilizing DHIs, organizations can
proactively manage vulnerabilities. The images come with CVE and Vulnerability
Exposure (VEX) feeds, enabling teams to stay informed about potential threats
and take necessary actions promptly.
## Scan images for CVEs
Regularly scanning Docker images for CVEs is essential for maintaining a secure
containerized environment. While Docker Scout is integrated into Docker Desktop
and the Docker CLI, tools like Grype and Trivy offer alternative scanning
capabilities. The following are instructions for using each tool to scan Docker
images for CVEs.
### Docker Scout
Docker Scout is integrated into Docker Desktop and the Docker CLI. It provides
vulnerability insights, CVE summaries, and direct links to remediation guidance.
#### Scan a DHI using Docker Scout
To scan a Docker Hardened Image using Docker Scout, run the following
command:
```console
$ docker scout cves <your-namespace>/dhi-<image>:<tag>
```
Example output:
```plaintext
v SBOM obtained from attestation, 101 packages found
v Provenance obtained from attestation
v VEX statements obtained from attestation
v No vulnerable package detected
...
```
For more detailed filtering and JSON output, see [Docker Scout CLI reference](../../../reference/cli/docker/scout/_index.md).
### Grype
[Grype](https://github.com/anchore/grype) is an open-source scanner that checks
container images against vulnerability databases like the NVD and distro
advisories.
#### Scan a DHI using Grype
After installing Grype, you can scan a Docker Hardened Image by pulling
the image and running the scan command:
```console
$ docker pull <your-namespace>/dhi-<image>:<tag>
$ grype <your-namespace>/dhi-<image>:<tag>
```
Example output:
```plaintext
NAME INSTALLED FIXED-IN TYPE VULNERABILITY SEVERITY EPSS% RISK
libperl5.36 5.36.0-7+deb12u2 (won't fix) deb CVE-2023-31484 High 79.45 1.1
perl 5.36.0-7+deb12u2 (won't fix) deb CVE-2023-31484 High 79.45 1.1
perl-base 5.36.0-7+deb12u2 (won't fix) deb CVE-2023-31484 High 79.45 1.1
...
```
### Trivy
[Trivy](https://github.com/aquasecurity/trivy) is an open-source vulnerability
scanner for containers and other artifacts. It detects vulnerabilities in OS
packages and application dependencies.
#### Scan a DHI using Trivy
After installing Trivy, you can scan a Docker Hardened Image by pulling
the image and running the scan command:
```console
$ docker pull <your-namespace>/dhi-<image>:<tag>
$ trivy image <your-namespace>/dhi-<image>:<tag>
```
Example output:
```plaintext
Report Summary
┌──────────────────────────────────────────────────────────────────────────────┬────────────┬─────────────────┬─────────┐
│ Target │ Type │ Vulnerabilities │ Secrets │
├──────────────────────────────────────────────────────────────────────────────┼────────────┼─────────────────┼─────────┤
│ <namespace>/dhi-<image>:<tag> (debian 12.11) │ debian │ 66 │ - │
├──────────────────────────────────────────────────────────────────────────────┼────────────┼─────────────────┼─────────┤
│ opt/python-3.13.4/lib/python3.13/site-packages/pip-25.1.1.dist-info/METADATA │ python-pkg │ 0 │ - │
└──────────────────────────────────────────────────────────────────────────────┴────────────┴─────────────────┴─────────┘
```
## Use VEX to filter known non-exploitable CVEs
Docker Hardened Images include signed [VEX (Vulnerability Exploitability
eXchange)](./vex.md) attestations that identify vulnerabilities not relevant to the image’s
runtime behavior.
When using Docker Scout, these VEX statements are automatically applied and no
manual configuration needed.
To manually retrieve the VEX attestation for tools that support it:
```console
$ docker scout attest get \
--predicate-type https://openvex.dev/ns/v0.2.0 \
--predicate \
<your-namespace>/dhi-<image>:<tag> --platform <platform> > vex.json
```
For example:
```console
$ docker scout attest get \
--predicate-type https://openvex.dev/ns/v0.2.0 \
--predicate \
docs/dhi-python:3.13 --platform linux/amd64 > vex.json
```
This creates a `vex.json` file containing the VEX statements for the specified
image. You can then use this file with tools that support VEX to filter out known non-exploitable CVEs.
For example, with Grype and Trivy, you can use the `--vex` flag to apply the VEX
statements during the scan:
```console
$ grype <your-namespace>/dhi-<image>:<tag> --vex vex.json
```
content/manuals/dhi/core-concepts/digests.md
+126
View File
@@ -0,0 +1,126 @@
---
title: Digests
description: Learn how Docker Hardened Images help secure every stage of your software supply chain with signed metadata, provenance, and minimal attack surface.
keywords: docker image digest, pull image by digest, immutable container image, secure container reference, multi-platform manifest
---
## What are Docker image digests?
A Docker image digest is a unique, cryptographic identifier (SHA-256 hash)
representing the content of a Docker image. Unlike tags, which can be reused or
changed, a digest is immutable and ensures that the exact same image is pulled
every time. This guarantees consistency across different environments and
deployments.
For example, the digest for the `nginx:latest` image might look like:
```text
sha256:94a00394bc5a8ef503fb59db0a7d0ae9e1110866e8aee8ba40cd864cea69ea1a
```
This digest uniquely identifies the specific version of the `nginx:latest` image,
ensuring that any changes to the image content result in a different digest.
## Why are digests important?
Using digests instead of tags offers several advantages:
- Immutability: Once an image is built and its digest is generated, the content
tied to that digest cannot change. This means that if you pull an image using
its digest, you can be confident that you are retrieving exactly the same
image that was originally built.
- Security: Digests help prevent supply chain attacks by ensuring that the image
content has not been tampered with. Even a small change in the image content
will result in a completely different digest.
- Consistency: Using digests ensures that the same image is used across
different environments, reducing the risk of discrepancies between
development, staging, and production environments.
## Docker Hardened Image digests
By using digests to reference DHIs, you can ensure that your applications are
always using the exact same secure image version, enhancing security and
compliance
## View an image digest
### Use the Docker CLI
To view the digest of a Docker image, you can use the following command. Replace
`<image-name>:<tag>` with the image name and tag.
```console
$ docker buildx imagetools inspect <image-name>:<tag>
```
### Use the Docker Hub UI
1. Go to [Docker Hub](https://hub.docker.com/) and sign in.
2. Navigate to your organization's namespace and open the mirrored DHI repository.
3. Select the **Tags** tab to view image variants.
4. Each tag in the list includes a **Digest** field showing the image's SHA-256 value.
## Pull an image by digest
Pulling an image by digest ensures that you are pulling the exact image version
identified by the specified digest.
To pull a Docker image using its digest, use the following command. Replace
`<image-name>` with the image name and `<digest>` with the image digest.
```console
$ docker pull <image-name>@sha256:<digest>
```
For example, to pull a `docs/dhi-python:3.13` image using its digest of
`94a00394bc5a8ef503fb59db0a7d0ae9e1110866e8aee8ba40cd864cea69ea1a`, you would
run:
```console
$ docker pull docs/dhi-python@sha256:94a00394bc5a8ef503fb59db0a7d0ae9e1110866e8aee8ba40cd864cea69ea1a
```
## Multi-platform images and manifests
Docker Hardened Images are published as multi-platform images, which means
a single image tag (like `docs/dhi-python:3.13`) can support multiple operating
systems and CPU architectures, such as `linux/amd64`, `linux/arm64`, and more.
Instead of pointing to a single image, a multi-platform tag points to a manifest
list (also called an index), which is a higher-level object that references
multiple image digests, one for each supported platform.
When you inspect a multi-platform image using `docker buildx imagetools inspect`, you'll see something like this:
```text
Name: docs/dhi-python:3.13
MediaType: application/vnd.docker.distribution.manifest.list.v2+json
Digest: sha256:6e05...d231
Manifests:
Name: docs/dhi-python:3.13@sha256:94a0...ea1a
Platform: linux/amd64
...
Name: docs/dhi-python:3.13@sha256:7f1d...bc43
Platform: linux/arm64
...
```
- The manifest list digest (`sha256:6e05...d231`) identifies the overall
multi-platform image.
- Each platform-specific image has its own digest (e.g., `sha256:94a0...ea1a`
for `linux/amd64`).
### Why this matters
- Reproducibility: If you're building or running containers on different
architectures, using a tag alone will resolve to the appropriate image digest
for your platform.
- Verification: You can pull and verify a specific image digest for your
platform to ensure you're using the exact image version, not just the manifest
list.
- Poliqcy enforcement: When enforcing digest-based policies with Docker Scout,
each platform variant is evaluated individually using its digest.
content/manuals/dhi/core-concepts/distroless.md
+68
View File
@@ -0,0 +1,68 @@
---
title: Minimal or distroless images
linktitle: Distroless images
description: Learn how Docker Hardened Images use distroless variants to minimize attack surface and remove unnecessary components.
keywords: distroless container image, minimal docker image, secure base image, no shell container, reduced attack surface
---
Minimal images, sometimes called distroless images, are container images
stripped of unnecessary components such as package managers, shells, or even the
underlying operating system distribution. Docker Hardened Images (DHI) embrace
this minimal approach to reduce vulnerabilities and enforce secure software
delivery.
### What are minimal or distroless images?
Traditional container images include a full OS, often more than what is needed
to run an application. In contrast, minimal or distroless images include only:
- The application binary
- Its runtime dependencies (e.g., libc, Java, Python)
- Any explicitly required configuration or metadata
They typically exclude:
- OS tools (e.g., `ls`, `ps`, `cat`)
- Shells (e.g., `sh`, `bash`)
- Package managers (e.g., `apt`, `apk`)
- Debugging utilities (e.g., `curl`, `wget`, `strace`)
Docker Hardened Images are based on this model, ensuring a smaller and more
secure runtime surface.
### What you gain
| Benefit | Description |
|------------------------|-------------------------------------------------------------------------------|
| Smaller attack surface | Fewer components mean fewer vulnerabilities and less exposure to CVEs |
| Faster startup | Smaller image sizes result in faster pull and start times |
| Improved security | Lack of shell and package manager limits what attackers can do if compromised |
| Better compliance | Easier to audit and verify, especially with SBOMs and attestations |
### Addressing common tradeoffs
Minimal and distroless images offer strong security benefits, but they can
change how you work with containers. Docker Hardened Images are designed to
maintain productivity while enhancing security.
| Concern | How Docker Hardened Images help |
|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Debuggability | Hardened images exclude shells and CLI tools by default. Use [Docker Debug](../../../reference/cli/docker/debug.md) to temporarily attach a debug sidecar for troubleshooting without modifying the original container. |
| Familiarity | DHI supports multiple base images, including Alpine and Debian variants, so you can choose a familiar environment while still benefiting from hardening practices. |
| Flexibility | Runtime immutability helps secure your containers. Use multi-stage builds and CI/CD to control changes, and optionally use dev-focused base images during development. |
By balancing minimalism with practical tooling, Docker Hardened Images support
modern development workflows without compromising on security or reliability.
### Best practices for using minimal images
- Use multi-stage builds to separate build-time and runtime environments
- Validate image behavior using CI pipelines, not interactive inspection
- Include runtime-specific dependencies explicitly in your Dockerfile
- Use Docker Scout to continuously monitor for CVEs, even in minimal images
By adopting minimal or distroless images through Docker Hardened Images, you
gain a more secure, predictable, and production-ready container environment
that's designed for automation, clarity, and reduced risk.
content/manuals/dhi/core-concepts/glibc-musl.md
+58
View File
@@ -0,0 +1,58 @@
---
title: glibc and musl support in Docker Hardened Images
linktitle: glibc and musl
description: Compare glibc and musl variants of DHIs to choose the right base image for your application’s compatibility, size, and performance needs.
keywords: glibc vs musl, alpine musl image, debian glibc container, docker hardened images compatibility, c library in containers
---
Docker Hardened Images (DHI) are built to prioritize security without
sacrificing compatibility with the broader open source and enterprise software
ecosystem. A key aspect of this compatibility is support for common Linux
standard libraries: `glibc` and `musl`.
## What are glibc and musl?
When you run Linux-based containers, the image's C library plays a key role in
how applications interact with the operating system. Most modern Linux
distributions rely on one of the following standard C libraries:
- `glibc` (GNU C Library): The standard C library on mainstream distributions
like Debian, Ubuntu, and Red Hat Enterprise Linux. It is widely supported and
typically considered the most compatible option across languages, frameworks,
and enterprise software.
- `musl`: A lightweight alternative to `glibc`, commonly used in minimal
distributions like Alpine Linux. While it offers smaller image sizes and
performance benefits, `musl` is not always fully compatible with software that
expects `glibc`.
## DHI compatibility
DHI images are available in both `glibc`-based (e.g., Debian) and `musl`-based
(e.g., Alpine) variants. For enterprise applications and language runtimes where
compatibility is critical, we recommend using DHI images based on glibc.
## What to choose, glibc or musl?
Docker Hardened Images are available in both glibc-based (Debian) and musl-based
(Alpine) variants, allowing you to choose the best fit for your workload.
Choose Debian-based (`glibc`) images if:
- You need broad compatibility with enterprise workloads, language runtimes, or
proprietary software.
- You're using ecosystems like .NET, Java, or Python with native extensions that
depend on `glibc`.
- You want to minimize the risk of runtime errors due to library
incompatibilities.
Choose Alpine-based (`musl`) images if:
- You want a minimal footprint with smaller image sizes and reduced surface
area.
- You're building a custom or tightly controlled application stack where
dependencies are known and tested.
- You prioritize startup speed and lean deployments over maximum compatibility.
If you're unsure, start with a Debian-based image to ensure compatibility, and
evaluate Alpine once you're confident in your application's dependencies.
content/manuals/dhi/core-concepts/hardening.md
+74
View File
@@ -0,0 +1,74 @@
---
title: Base image hardening
linktitle: Hardening
description: Learn how Docker Hardened Images are designed for security, with minimal components, nonroot execution, and secure-by-default configurations.
keywords: hardened base image, minimal container image, non-root containers, secure container configuration, remove package manager
---
## What is base image hardening?
Base image hardening is the process of securing the foundational layers of a
container image by minimizing what they include and configuring them with
security-first defaults. A hardened base image removes unnecessary components,
like shells, compilers, and package managers, which limits the available attack
surface, making it more difficult for an attacker to gain control or escalate
privileges inside the container.
Hardening also involves applying best practices like running as a non-root user,
reducing writable surfaces, and ensuring consistency through immutability.
## Why is it important?
Most containers inherit their security posture from the base image they use. If
the base image includes unnecessary tools or runs with elevated privileges,
every container built on top of it is exposed to those risks.
Hardening the base image:
- Reduces the attack surface by removing tools and libraries that could be exploited
- Enforces least privilege by dropping root access and restricting what the container can do
- Improves reliability and consistency by avoiding runtime changes and drift
- Aligns with secure software supply chain practices and helps meet compliance standards
Using hardened base images is a critical first step in securing the software you
build and run in containers.
## What's removed and why
Hardened images typically exclude common components that are risky or unnecessary in secure production environments:
| Removed component | Reason |
|--------------------------------------------------|----------------------------------------------------------------------------------|
| Shells (e.g., `sh`, `bash`) | Prevents users or attackers from executing arbitrary commands inside containers |
| Package managers (e.g., `apt`, `apk`) | Disables the ability to install software post-build, reducing drift and exposure |
| Compilers and interpreters | Avoids introducing tools that could be used to run or inject malicious code |
| Debugging tools (e.g., `strace`, `curl`, `wget`) | Reduces risk of exploitation or information leakage |
| Unused libraries or locales | Shrinks image size and minimizes attack vectors |
## How Docker Hardened Images apply base image hardening
Docker Hardened Images (DHIs) apply base image hardening principles by design.
Each image is constructed to include only what is necessary for its specific
purpose, whether that’s building applications (with `-dev` or `-sdk` tags) or
running them in production.
### Docker Hardened Image traits
Docker Hardened Images are built to be:
- Minimal: Only essential libraries and binaries are included
- Immutable: Images are fixed at build time—no runtime installations
- Non-root by default: Containers run as an unprivileged user unless configured otherwise
- Purpose-scoped: Different tags are available for development (`-dev`), SDK-based builds (`-sdk`), and production runtime
These characteristics help enforce consistent, secure behavior across development, testing, and production environments.
### Docker Hardened Image compatibility considerations
Because Docker Hardened Images strip out many common tools, they may not work out of the box for all use cases. You may need to:
- Use multi-stage builds to compile code or install dependencies in a `-dev` image and copy the output into a hardened runtime image
- Replace shell scripts with equivalent entrypoint binaries or explicitly include a shell if needed
- Use [Docker Debug](../../../reference/cli/docker/debug.md) to temporarily inspect or troubleshoot containers without altering the base image
These trade-offs are intentional and help support best practices for building secure, reproducible, and production-ready containers.
content/manuals/dhi/core-concepts/immutability.md
+57
View File
@@ -0,0 +1,57 @@
---
title: Immutable infrastructure
linktitle: Immutability
description: Understand how image digests, read-only containers, and signed metadata ensure Docker Hardened Images are tamper-resistant and immutable.
keywords: immutable container image, read-only docker image, configuration drift prevention, secure redeployment, image digest verification
---
Immutable infrastructure is a security and operations model where components
such as servers, containers, and images are never modified after deployment.
Instead of patching or reconfiguring live systems, you replace them entirely
with new versions.
When using Docker Hardened Images, immutability is a best practice that
reinforces the security posture of your software supply chain.
## Why immutability matters
Mutable systems are harder to secure and audit. Live patching or manual updates
introduce risks such as:
- Configuration drift
- Untracked changes
- Inconsistent environments
- Increased attack surface
Immutable infrastructure solves this by making changes only through controlled,
repeatable builds and deployments.
## How Docker Hardened Images support immutability
Docker Hardened Images are built to be minimal, locked-down, and
non-interactive, which discourages in-place modification. For example:
- Many DHI images exclude shells, package managers, and debugging tools
- DHI images are designed to be scanned and signed before deployment
- DHI users are encouraged to rebuild and redeploy images rather than patch running containers
This design aligns with immutable practices and ensures that:
- Updates go through the CI/CD pipeline
- All changes are versioned and auditable
- Systems can be rolled back or reproduced consistently
## Immutable patterns in practice
Some common patterns that leverage immutability include:
- Container replacement: Instead of logging into a container to fix a bug or
apply a patch, rebuild the image and redeploy it.
- Infrastructure as Code (IaC): Define your infrastructure and image
configurations in version-controlled files.
- Blue/Green or Canary deployments: Roll out new images alongside old ones and
gradually shift traffic to the new version.
By combining immutable infrastructure principles with hardened images, you
create a predictable and secure deployment workflow that resists tampering and
minimizes long-term risk.
content/manuals/dhi/core-concepts/provenance.md
+71
View File
@@ -0,0 +1,71 @@
---
title: Image provenance
description: Learn how build provenance metadata helps trace the origin of Docker Hardened Images and support compliance with SLSA.
keywords: image provenance, container build traceability, slsa compliance, signed container image, software supply chain trust
---
## What is image provenance?
Image provenance refers to metadata that traces the origin, authorship, and
integrity of a container image. It answers critical questions such as:
- Where did this image come from?
- Who built it?
- Has it been tampered with?
Provenance establishes a chain of custody, helping you verify that the image
you're using is the result of a trusted and verifiable build process.
## Why image provenance matters
Provenance is foundational to securing your software supply chain. Without it, you risk:
- Running unverified or malicious images
- Failing to meet internal or regulatory compliance requirements
- Losing visibility into the components and workflows that produce your containers
With reliable provenance, you gain:
- Trust: Know that your images are authentic and unchanged.
- Traceability: Understand the full build process and source inputs.
- Auditability: Provide verifiable evidence of compliance and build integrity.
Provenance also supports automated policy enforcement and is a key requirement
for frameworks like SLSA (Supply-chain Levels for Software Artifacts).
## How Docker Hardened Images support provenance
Docker Hardened Images (DHIs) are designed with built-in provenance to help you
adopt secure-by-default practices and meet supply chain security standards.
### Attestations
DHIs include [attestations](./attestations.md)—machine-readable metadata that
describe how, when, and where the image was built. These are generated using
industry standards such as [in-toto](https://in-toto.io/) and align with [SLSA
provenance](https://slsa.dev/spec/v1.0/provenance/).
Attestations allow you to:
- Validate that builds followed the expected steps
- Confirm that inputs and environments meet policy
- Trace the build process across systems and stages
### Code signing
Each Docker Hardened Image is cryptographically [signed](./signatures.md) and
stored in the registry alongside its digest. These signatures are verifiable
proofs of authenticity and are compatible with tools like `cosign`, Docker
Scout, and Kubernetes admission controllers.
With image signatures, you can:
- Confirm that the image was published by Docker
- Detect if an image has been modified or republished
- Enforce signature validation in CI/CD or production deployments
## Additional resources
- [Provenance attestations](/build/metadata/attestations/slsa-provenance/)
- [Image signatures](./signatures.md)
- [Attestations overview](./attestations.md)
content/manuals/dhi/core-concepts/sbom.md
+96
View File
@@ -0,0 +1,96 @@
---
title: Software Bill of Materials (SBOMs)
linktitle: SBOMs
description: Learn what SBOMs are, why they matter, and how Docker Hardened Images include signed SBOMs to support transparency and compliance.
keywords: sbom docker image, software bill of materials, signed sbom, container sbom verification, sbom compliance
---
## What is an SBOM?
An SBOM is a detailed inventory that lists all components, libraries, and
dependencies used in building a software application. It provides transparency
into the software supply chain by documenting each component's version, origin,
and relationship to other components. Think of it as a "recipe" for your
software, detailing every ingredient and how they come together.
Metadata included in an SBOM for describing software artifacts may include:
- Name of the artifact
- Version
- License type
- Authors
- Unique package identifier
## Why are SBOMs important?
In today's software landscape, applications often comprise numerous components
from various sources, including open-source libraries, third-party services, and
proprietary code. This complexity can obscure visibility into potential
vulnerabilities and complicate compliance efforts. SBOMs address these
challenges by providing a detailed inventory of all components within an
application.
The significance of SBOMs is underscored by several key factors:
- Enhanced transparency: SBOMs offer a comprehensive view of all components that
constitute an application, enabling organizations to identify and assess risks
associated with third-party libraries and dependencies.
- Proactive vulnerability management: By maintaining an up-to-date SBOM,
organizations can swiftly identify and address vulnerabilities in software
components, reducing the window of exposure to potential exploits.
- Regulatory compliance: Many regulations and industry standards now require
organizations to maintain control over the software components they use. An
SBOM facilitates compliance by providing a clear and accessible record.
- Improved incident response: In the event of a security breach, an SBOM
enables organizations to quickly identify affected components and take
appropriate action, minimizing potential damage.
## Docker Hardened Image SBOMs
Docker Hardened Images come with built-in SBOMs, ensuring that every component
in the image is documented and verifiable. These SBOMs are cryptographically
signed, providing a tamper-evident record of the image's contents. This
integration simplifies audits and enhances trust in the software supply chain.
## View SBOMs in Docker Hardened Images
To view the SBOM of a Docker Hardened Image, you can use the `docker scout sbom`
command. Replace `<image-name>:<tag>` with the image name and tag.
```console
$ docker scout sbom <image-name>:<tag>
```
## Verify the SBOM of a Docker Hardened Image
Since Docker Hardened Images come with signed SBOMs, you can use Cosign to
verify the authenticity and integrity of the SBOM attached to the image. This
ensures that the SBOM has not been tampered with and that the image's contents
are trustworthy.
To verify the SBOM of a Docker Hardened Image using Cosign, use the following command:
```console
$ cosign verify-attestation \
--key https://registry.scout.docker.com/keyring/dhi/latest.pub \
--type sbom \
<image-reference>
```
For example, to verify the SBOM attestation for the dhi/node image:
```console
$ cosign verify-attestation \
--key https://registry.scout.docker.com/keyring/dhi/latest.pub \
--type sbom \
registry.scout.docker.com/dhi/node@sha256:6de8ac9c07367652496bf926675425a22bf93e487cc2690d6778a82dd0159c4f
```
## Resources
For more details about SBOM attestations and Docker Build, see [SBOM
attestations](/build/metadata/attestations/sbom/).
content/manuals/dhi/core-concepts/signatures.md
+95
View File
@@ -0,0 +1,95 @@
---
title: Code signing
description: Understand how Docker Hardened Images are cryptographically signed using Cosign to verify authenticity, integrity, and secure provenance.
keywords: container image signing, cosign docker image, verify image signature, signed container image, sigstore cosign
---
## What is code signing?
Code signing is the process of applying a cryptographic signature to software
artifacts, such as Docker images, to verify their integrity and authenticity. By
signing an image, you ensure that it has not been altered since it was signed
and that it originates from a trusted source.
In the context of Docker Hardened Images (DHIs), code signing is achieved using
[Cosign](https://docs.sigstore.dev/), a tool developed by the Sigstore project.
Cosign enables secure and verifiable signing of container images, enhancing
trust and security in the software supply chain.
## Why is code signing important?
Code signing plays a crucial role in modern software development and
cybersecurity:
- Authenticity: Verifies that the image was created by a trusted source.
- Integrity: Ensures that the image has not been tampered with since it was
signed.
- Compliance: Helps meet regulatory and organizational security requirements.
## Docker Hardened Image code signing
Each DHI is cryptographically signed using Cosign, ensuring that the images have
not been tampered with and originate from a trusted source.
## Why sign your own images?
Docker Hardened Images are signed by Docker to prove their origin and integrity,
but if you're building application images that extend or use DHIs as a base, you
should sign your own images as well.
By signing your own images, you can:
- Prove the image was built by your team or pipeline
- Ensure your build hasn't been tampered with after it's pushed
- Support software supply chain frameworks like SLSA
- Enable image verification in deployment workflows
This is especially important in CI/CD environments where you build and push
images frequently, or in any scenario where image provenance must be auditable.
## How to view and use code signatures
### View signatures
You can verify that a Docker Hardened Image is signed and trusted using either Docker Scout or Cosign.
To lists all attestations, including signature metadata, attached to the image, use the following command:
```console
$ docker scout attest list <image-name>:<tag> --platform <platform>
```
To verify a specific signed attestation (e.g., SBOM, VEX, provenance):
```console
$ docker scout attest get \
--predicate-type <predicate-uri> \
--verify \
<image-name>:<tag> --platform <platform>
```
For example:
```console
$ docker scout attest get \
--predicate-type https://openvex.dev/ns/v0.2.0 \
--verify \
docs/dhi-python:3.13 --platform linux/amd64
```
If valid, Docker Scout will confirm the signature and display signature payload, as well as the equivalent Cosign command to verify the image.
### Sign images
To sign a Docker image, use [Cosign](https://docs.sigstore.dev/). Replace
`<image-name>:<tag>` with the image name and tag.
```console
$ cosign sign <image-name>:<tag>
```
This command will prompt you to authenticate via an OIDC provider (such as
GitHub, Google, or Microsoft). Upon successful authentication, Cosign will
generate a short-lived certificate and sign the image. The signature will be
stored in a transparency log and associated with the image in the registry.
content/manuals/dhi/core-concepts/slsa.md
+102
View File
@@ -0,0 +1,102 @@
---
title: Supply-chain Levels for Software Artifacts (SLSA)
linktitle: SLSA
description: Learn how Docker Hardened Images comply with SLSA Build Level 3 and how to verify provenance for secure, tamper-resistant builds.
keywords: slsa docker compliance, slsa build level 3, supply chain security, verified build provenance, secure container build
---
## What is SLSA?
Supply-chain Levels for Software Artifacts (SLSA) is a security framework
designed to enhance the integrity and security of software supply chains.
Developed by Google and maintained by the Open Source Security Foundation
(OpenSSF), SLSA provides a set of guidelines and best practices to prevent
tampering, improve integrity, and secure packages and infrastructure in software
projects.
SLSA defines [four build levels (0–3)](https://slsa.dev/spec/latest/levels) of
increasing security rigor, focusing on areas such as build provenance, source
integrity, and build environment security. Each level builds upon the previous
one, offering a structured approach to achieving higher levels of software
supply chain security.
## Why is SLSA important?
SLSA is crucial for modern software development due to the increasing complexity
and interconnectedness of software supply chains. Supply chain attacks, such as
the SolarWinds breach, have highlighted the vulnerabilities in software
development processes. By implementing SLSA, organizations can:
- Ensure artifact integrity: Verify that software artifacts have not been
tampered with during the build and deployment processes.
- Enhance build provenance: Maintain verifiable records of how and when software
artifacts were produced, providing transparency and accountability.
- Secure build environments: Implement controls to protect build systems from
unauthorized access and modifications.
- Mitigate supply chain risks: Reduce the risk of introducing vulnerabilities or
malicious code into the software supply chain.
## What is SLSA Build Level 3?
SLSA Build Level 3, Hardened Builds, is the highest of four progressive levels in
the SLSA framework. It introduces strict requirements to ensure that software
artifacts are built securely and traceably. To meet Level 3, a build must:
- Be fully automated and scripted to prevent manual tampering
- Use a trusted build service that enforces source and builder authentication
- Generate a signed, tamper-resistant provenance record describing how the artifact was built
- Capture metadata about the build environment, source repository, and build steps
This level provides strong guarantees that the software was built from the
expected source in a controlled, auditable environment, which significantly
reduces the risk of supply chain attacks.
## Docker Hardened Images and SLSA
Docker Hardened Images (DHIs) are secure-by-default container images
purpose-built for modern production environments. Each DHI is cryptographically
signed and complies with the [SLSA Build Level 3
standard](https://slsa.dev/spec/latest/levels#build-l3-hardened-builds), ensuring
verifiable build provenance and integrity.
By integrating SLSA-compliant DHIs into your development and deployment processes, you can:
- Achieve higher security levels: Utilize images that meet stringent security
standards, reducing the risk of vulnerabilities and attacks.
- Simplify compliance: Leverage built-in features like signed Software Bills of
Materials (SBOMs) and vulnerability exception (VEX) statements to facilitate
compliance with regulations such as FedRAMP.
- Enhance transparency: Access detailed information about the components and
build process of each image, promoting transparency and trust.
- Streamline audits: Utilize verifiable build records and signatures to simplify
security audits and assessments.
## How to verify SLSA compliance
Each DHI is cryptographically signed and complies with the SLSA framework,
ensuring verifiable build provenance and integrity.
To evaluate whether a DHI complies with SLSA standards, you can use the
[slsa-verifier tool](https://github.com/slsa-framework/slsa-verifier). This tool
verifies the SLSA provenance of an image, ensuring that it was built according
to the specified security levels.
To use the slsa-verifier tool after installation, run the following command.
Replace `<your-namespace>/dhi-<image>:<tag>` with the image name and tag.
```console
$ slsa-verifier verify-image <your-namespace>/dhi-<image>:<tag>
```
This command will verify the SLSA provenance of the image, checking that it
meets the specified security levels.
## Resources
For more details about SLSA definitions and Docker Build, see [SLSA definitions](/build/metadata/attestations/slsa-definitions/).
content/manuals/dhi/core-concepts/sscs.md
+52
View File
@@ -0,0 +1,52 @@
---
title: Software Supply Chain Security
linktitle: Software Supply Chain Security
description: Learn how Docker Hardened Images help secure every stage of your software supply chain with signed metadata, provenance, and minimal attack surface.
keywords: software supply chain security, secure container images, signed image provenance, docker sbom, distroless security
---
## What is Software Supply Chain Security (SSCS)?
SSCS encompasses practices and strategies designed to safeguard the entire
lifecycle of software development from initial code creation to deployment and
maintenance. It focuses on securing all components. This includes code,
dependencies, build processes, and distribution channels in order to prevent
malicious actors from compromising the software supply chain. Given the
increasing reliance on open-source libraries and third-party components,
ensuring the integrity and security of these elements is paramount
## Why is SSCS important?
The significance of SSCS has escalated due to the rise in sophisticated
cyberattacks targeting software supply chains. Recent incidents and the
exploitation of vulnerabilities in open-source components have underscored the
critical need for robust supply chain security measures. Compromises at any
stage of the software lifecycle can lead to widespread vulnerabilities, data
breaches, and significant financial losses.
## How Docker Hardened Images contribute to SSCS
Docker Hardened Images (DHI) are purpose-built container images designed with
security at their core, addressing the challenges of modern software supply
chain security. By integrating DHI into your development and deployment
pipelines, you can enhance your organization's SSCS posture through the
following features:
- Minimal attack surface: DHIs are engineered to be ultra-minimal, stripping
away unnecessary components and reducing the attack surface by up to 95%. This
distroless approach minimizes potential entry points for malicious actors.
- Cryptographic signing and provenance: Each DHI is cryptographically signed,
ensuring authenticity and integrity. Build provenance is maintained, providing
verifiable evidence of the image's origin and build process, aligning with
standards like SLSA (Supply-chain Levels for Software Artifacts).
- Software Bill of Materials (SBOM): DHIs include a comprehensive SBOM,
detailing all components and dependencies within the image. This transparency
aids in vulnerability management and compliance tracking, enabling teams to
assess and mitigate risks effectively.
- Continuous maintenance and rapid CVE remediation: Docker maintains DHIs with
regular updates and security patches, backed by an SLA for addressing critical
and high-severity vulnerabilities. This proactive approach helps ensure that
images remain secure and compliant with enterprise standards.
content/manuals/dhi/core-concepts/ssdlc.md
+113
View File
@@ -0,0 +1,113 @@
---
title: Secure Software Development Lifecycle
linktitle: SSDLC
description: See how Docker Hardened Images support a secure SDLC by integrating with scanning, signing, and debugging tools.
keywords: secure software development, ssdlc containers, slsa compliance, docker scout integration, secure container debugging
---
## What is a Secure Software Development Lifecycle?
A Secure Software Development Lifecycle (SSDLC) integrates security practices
into every phase of software delivery, from design and development to deployment
and monitoring. It’s not just about writing secure code, but about embedding
security throughout the tools, environments, and workflows used to build and
ship software.
SSDLC practices are often guided by compliance frameworks, organizational
policies, and supply chain security standards such as SLSA (Supply-chain Levels
for Software Artifacts) or NIST SSDF.
## Why SSDLC matters
Modern applications depend on fast, iterative development, but rapid delivery
often introduces security risks if protections aren’t built in early. An SSDLC
helps:
- Prevent vulnerabilities before they reach production
- Ensure compliance through traceable and auditable workflows
- Reduce operational risk by maintaining consistent security standards
- Enable secure automation in CI/CD pipelines and cloud-native environments
By making security a first-class citizen in each stage of software delivery,
organizations can shift left and reduce both cost and complexity.
## How Docker supports a secure SDLC
Docker provides tools and secure content that make SSDLC practices easier to
adopt across the container lifecycle. With [Docker Hardened
Images](../_index.md) (DHIs), [Docker
Debug](../../../reference/cli/docker/debug.md), and [Docker
Scout](../../../manuals/scout/_index.md), teams can add security without losing
velocity.
### Plan and design
During planning, teams define architectural constraints, compliance goals, and
threat models. Docker Hardened Images help at this stage by providing:
- Secure-by-default base images for common languages and runtimes
- Verified metadata including SBOMs, provenance, and VEX documents
- Support for both glibc and musl across multiple Linux distributions
You can use DHI metadata and attestations to support design reviews, threat
modeling, or architecture sign-offs.
### Develop
In development, security should be transparent and easy to apply. Docker
Hardened Images support secure-by-default development:
- Dev variants include shells, package managers, and compilers for convenience
- Minimal runtime variants reduce attack surface in final images
- Multi-stage builds let you separate build-time tools from runtime environments
[Docker Debug](../../../reference/cli/docker/debug.md) helps developers:
- Temporarily inject debugging tools into minimal containers
- Avoid modifying base images during troubleshooting
- Investigate issues securely, even in production-like environments
### Build and test
Build pipelines are an ideal place to catch issues early. Docker Scout
integrates with Docker Hub and the CLI to:
- Scan for known CVEs using multiple vulnerability databases
- Trace vulnerabilities to specific layers and dependencies
- Interpret signed VEX data to suppress known-irrelevant issues
- Export JSON scan reports for CI/CD workflows
Build pipelines that use Docker Hardened Images benefit from:
- Reproducible, signed images
- Minimal build surfaces to reduce exposure
- Built-in compliance with SLSA Build Level 3 standards
### Release and deploy
Security automation is critical as you release software at scale. Docker
supports this phase by enabling:
- Signature verification and provenance validation before deployment
- Policy enforcement gates using Docker Scout
- Safe, non-invasive container inspection using Docker Debug
DHIs ship with the metadata and signatures required to automate image
verification during deployment.
### Monitor and improve
Security continues after release. With Docker tools, you can:
- Continuously monitor image vulnerabilities through Docker Hub
- Get CVE remediation guidance and patch visibility using Docker Scout
- Receive updated DHI images with rebuilt and re-signed secure layers
- Debug running workloads with Docker Debug without modifying the image
## Summary
Docker helps teams embed security throughout the SSDLC by combining secure
content (DHIs) with developer-friendly tooling (Docker Scout and Docker Debug).
These integrations promote secure practices without introducing friction, making
it easier to adopt compliance and supply chain security across your software
delivery lifecycle.
content/manuals/dhi/core-concepts/vex.md
+90
View File
@@ -0,0 +1,90 @@
---
title: Vulnerability Exploitability eXchange (VEX)
linktitle: VEX
description: Learn how VEX helps you prioritize real risks by identifying which vulnerabilities in Docker Hardened Images are actually exploitable.
keywords: vex container security, vulnerability exploitability, filter false positives, docker scout vex, cve prioritization
---
## What is VEX?
Vulnerability Exploitability eXchange (VEX) is a standardized framework
developed by the U.S. Cybersecurity and Infrastructure Security Agency (CISA) to
document the exploitability of vulnerabilities within software components.
Unlike traditional CVE (Common Vulnerabilities and Exposures) databases, VEX
provides contextual assessments, indicating whether a vulnerability is
exploitable in a given environment. This approach helps organizations prioritize
remediation efforts by distinguishing between vulnerabilities that are
exploitable and those that are not relevant to their specific use cases.
## Why is VEX important?
VEX enhances traditional vulnerability management by:
- Reducing false positives: By providing context-specific assessments, VEX helps
in filtering out vulnerabilities that do not pose a threat in a particular
environment.
- Prioritizing remediation: Organizations can focus resources on addressing
vulnerabilities that are exploitable in their specific context, improving
efficiency in vulnerability management.
- Enhancing compliance: VEX reports provide detailed information that can assist
in meeting regulatory requirements and internal security standards.
This approach is particularly beneficial in complex environments where numerous
components and configurations exist, and traditional CVE-based assessments may
lead to unnecessary remediation efforts.
## How Docker Hardened Images integrate VEX
To enhance vulnerability management, Docker Hardened Images (DHI) incorporate
VEX reports, providing context-specific assessments of known vulnerabilities.
This integration allows you to:
- Assess exploitability: Determine whether known vulnerabilities in the image's
components are exploitable in their specific environment.
- Prioritize actions: Focus remediation efforts on vulnerabilities that pose
actual risks, optimizing resource allocation.
- Streamline audits: Utilize the detailed information provided by VEX reports to
simplify compliance audits and reporting.
By combining the security features of DHI with the contextual insights of VEX,
organizations can achieve a more effective and efficient approach to
vulnerability management.
## Use VEX to filter known non-exploitable CVEs
When using Docker Scout, VEX statements are automatically applied and no
manual configuration is needed.
To manually retrieve the VEX attestation for tools that support it:
```console
$ docker scout attest get \
--predicate-type https://openvex.dev/ns/v0.2.0 \
--predicate \
<your-namespace>/dhi-<image>:<tag> --platform <platform> > vex.json
```
For example:
```console
$ docker scout attest get \
--predicate-type https://openvex.dev/ns/v0.2.0 \
--predicate \
docs/dhi-python:3.13 --platform linux/amd64 > vex.json
```
This creates a `vex.json` file containing the VEX statements for the specified
image. You can then use this file with tools that support VEX to filter out
known non-exploitable CVEs.
For example, with Grype and Trivy, you can use the `--vex` flag to apply the VEX
statements during the scan:
```console
$ grype <your-namespace>/dhi-<image>:<tag> --vex vex.json
```
content/manuals/dhi/features/_index.md
+39
View File
@@ -0,0 +1,39 @@
---
title: Features
description: Explore the core features of Docker Hardened Images, including hardened defaults, secure metadata, and ecosystem compatibility.
weight: 10
params:
grid_features:
- title: Hardened, secure images
description: Learn how Docker Hardened Images reduce vulnerabilities, enforce non-root execution, and include SLSA-compliant metadata for supply chain security.
icon: lock
link: /dhi/features/secure/
- title: Seamless integration
description: See how Docker Hardened Images integrate with CI/CD pipelines, vulnerability scanners, and container registries across your toolchain.
icon: hub
link: /dhi/features/integration/
- title: Enterprise support
description: Learn about enterprise support and SLA-driven updates.
icon: settings
link: /dhi/features/support/
- title: Continuous patching and secure maintenance
description: Learn how Docker Hardened Images are continuously updated with security patches, ensuring your images remain secure over time.
icon: dashboard
link: /dhi/features/patching/
- title: Flexible, repository-based pricing
description: Learn how Docker Hardened Images offer repository-based flexibility with no per-image or per-pull limitations.
icon: wallet
link: /dhi/features/flexible/
---
Docker Hardened Images (DHIs) go beyond minimal base and application images by
incorporating hardened defaults, signed metadata, and broad ecosystem
compatibility. Whether you're securing a single service or rolling out
compliance controls at scale, this section covers the key features that make
DHIs production-ready.
## Explore core features
{{< grid
items="grid_features"
>}}
content/manuals/dhi/features/flexible.md
+44
View File
@@ -0,0 +1,44 @@
---
title: Flexible, repository-based pricing
linktitle: Flexibility
description: Understand how Docker Hardened Images give you cost control by charging only for what you mirror and use.
keywords: docker hardened images pricing, per repo billing, flexible pricing model, mirror image pricing, container pricing model
weight: 30
---
Docker Hardened Images are designed not only for security and compliance, but
also for operational and financial efficiency. With a model that charges per
repository, you get precise control over what you use and what you pay for.
## Repository mirroring on your terms
With Docker Hardened Images, you mirror entire repositories, each giving you
access to all supported tags, variants, and versions. You can choose which
repositories to mirror based on your needs.
This flexibility allows your organization to adapt as projects evolve, whether
you're spinning up new environments, consolidating runtimes, or managing costs
over time, without worrying about per-image or per-pull fees.
## Access all variants and versions
When you mirror a Docker Hardened Image repository, you gain access to all
supported tags in that repository, including multiple versions, base
distributions (such as Alpine and Debian), and dev/runtime variants. You can
freely choose the best tag for each use case without incurring additional cost.
This flexibility allows teams to adopt secure images without being limited by
billing complexity or image count.
## Share access across your team
Once a repository is mirrored, anyone in your organization can pull, verify,
scan, and run images from it. There are no extra charges based on usage volume.
You mirror what you need, and your teams use it freely.
## Cost efficiency for platform teams
This model simplifies budgeting for platform and security teams. Rather than
tracking usage at the individual image or tag level, you manage your spend
through the repositories you control, aligning security enforcement, team access,
and cost in one place.
content/manuals/dhi/features/integration.md
+81
View File
@@ -0,0 +1,81 @@
---
title: Seamless integration
description: Learn how Docker Hardened Images integrate into your existing development and deployment workflows for enhanced security without compromising usability.
description_short: See how Docker Hardened Images integrate with CI/CD pipelines, vulnerability scanners, and container registries across your toolchain
keywords: ci cd containers, vulnerability scanning, slsa build level 3, signed sbom, oci compliant registry
---
Docker Hardened Images (DHI) are designed to integrate effortlessly into your
existing development and deployment workflows, ensuring that enhanced security
does not come at the cost of usability.
## Explore images in Docker Hub
After your organization [signs
up](https://www.docker.com/products/hardened-images/#getstarted), teams can
explore the full DHI catalog directly on Docker Hub. There, developers and
security teams can:
- Review available images and language/framework variants
- Understand supported distros
- Compare development vs. runtime variants
Each repository includes metadata like supported tags, base image
configurations, and image-specific documentation, helping you choose the right variant
for your project.
## Use DHIs in CI/CD workflows
You can use DHIs as the same base image in any CI/CD pipeline that is built
using a Dockerfile. They integrate easily into platforms like GitHub Actions,
GitLab CI/CD, Jenkins, CircleCI, and other automation systems your team already
uses.
## Built to fit your DevSecOps stack
Docker Hardened Images are designed to work seamlessly with your existing
DevSecOps toolchain. They integrate with scanning tools, registries, CI/CD
systems, and policy engines that teams already use.
Docker has partnered with a broad range of ecosystem providers in order to
ensure that DHIs work out of the box with your existing workflows and tools.
These partners help deliver enhanced scanning, metadata validation, and
compliance insights directly into your pipelines.
All DHIs include:
- Signed Software Bill of Materials (SBOMs)
- CVE data
- Vulnerability Exploitability eXchange (VEX) documents
- SLSA Build Level 3 provenance
Because the metadata is signed and structured, you can feed it into policy
engines and dashboards for auditing or compliance workflows.
## Distribute through your preferred registry
DHIs are mirrored to your organization's namespace on Docker Hub. From there,
you can optionally push them to any OCI-compliant registry, such as:
- Amazon ECR
- Google Artifact Registry
- GitHub Container Registry
- Azure Container Registry
- Harbor
- JFrog Artifactory
- Other OCI-compliant on-premises or cloud registries
Mirroring ensures teams can pull images from their preferred location without
breaking policies or build systems.
## Summary
Docker Hardened Images integrate with the tools you already use, from development
and CI to scanning and deployment. They:
- Work with standard Docker tooling and pipelines
- Support popular scanners and registries
- Include security metadata that plugs into your existing compliance systems
This means you can adopt stronger security controls without disrupting your
engineering workflows.
content/manuals/dhi/features/patching.md
+42
View File
@@ -0,0 +1,42 @@
---
title: Continuous patching and secure maintenance
linktitle: Continuous patching
description: Learn how Docker Hardened Images are automatically rebuilt, tested, and updated to stay in sync with upstream security patches.
keywords: docker hardened images, secure base image, automatic patching, CVE updates, compatibility, dev containers, runtime containers, image maintenance
---
Docker Hardened Images (DHI) offer a secure and enterprise-ready foundation for
containerized applications, backed by a robust, automated patching process that
helps maintain compliance and reduce vulnerability exposure.
## Secure base images with strong compatibility
DHI includes a curated set of minimal base images designed to work across a
broad range of environments and language ecosystems. These images provide secure
building blocks with high compatibility, making it easier to integrate into your
existing infrastructure and development workflows without sacrificing security.
## Development and runtime variants
To support different stages of the software lifecycle, DHI provides two key
variants:
- Development images: Include essential tools and libraries required to build
and test applications securely.
- Runtime images: Contain only the core components needed to run applications,
offering a smaller attack surface and improved runtime efficiency.
This variant structure supports multi-stage builds, enabling developers to
compile code in secure development containers and deploy with lean runtime
images in production.
## Automated patching and secure updates
Docker monitors upstream open-source packages and security advisories for
vulnerabilities (CVEs) and other updates. When changes are detected, affected
Docker Hardened Images are automatically rebuilt and tested.
Updated images are published with cryptographic provenance attestations to
support verification and compliance workflows. This automated process reduces
the operational burden of manual patching and helps teams stay aligned with
secure software development practices.
content/manuals/dhi/features/secure.md
+48
View File
@@ -0,0 +1,48 @@
---
title: Hardened, secure images
description: Learn how Docker Hardened Images reduce vulnerabilities, enforce non-root execution, and include SLSA-compliant metadata for supply chain security.
keywords: non-root containers, slsa build level 3, signed sbom, vex document, hardened container image
---
Docker Hardened Images (DHI) are engineered to provide a robust security
foundation for containerized applications, addressing the evolving challenges of
software supply chain security.
## Near-zero vulnerabilities and non-root execution
Each DHI is meticulously built to eliminate known vulnerabilities, achieving
near-zero Common Vulnerabilities and Exposures (CVEs) through continuous
scanning and updates. By adhering to the principle of least privilege, DHI
images run as non-root by default, reducing the risk of privilege escalation
attacks in production environments.
## Comprehensive supply chain security
DHI incorporates multiple layers of security metadata to ensure transparency and
trust:
- SLSA Level 3 compliance: Each image includes detailed build provenance,
meeting the standards set by the Supply-chain Levels for Software Artifacts
(SLSA) framework.
- Software Bill of Materials (SBOMs): Comprehensive SBOMs are provided,
detailing all components within the image to facilitate vulnerability
management and compliance audits.
- Vulnerability Exploitability eXchange (VEX) statements: VEX documents
accompany each image, providing context about known vulnerabilities and their
exploitability status.
- Cryptographic signing and attestations: All images and associated metadata are
cryptographically signed, ensuring integrity and authenticity.
## Minimal and developer-friendly options
DHI provides both minimal and development-friendly image variants:
- Minimal images: Built using a distroless approach, these images remove
unnecessary components, reducing the attack surface by up to 95% and improving
startup times.
- Development images: Equipped with essential development tools and libraries,
these images facilitate secure application building and testing.
content/manuals/dhi/features/support.md
+28
View File
@@ -0,0 +1,28 @@
---
title: Enterprise support
description: Get enterprise-grade support and SLA-backed security updates for Docker Hardened Images (DHI), including 24x7x365 access to Docker’s support team and guaranteed CVE patching for critical and high vulnerabilities.
keywords: enterprise container support, sla-backed security, cve patching, secure container image, docker enterprise support
---
Docker Hardened Images (DHI) are designed to provide flexibility and robust
support for enterprise environments, allowing teams to tailor images to their
specific needs while ensuring security and compliance.
## Enterprise-grade support and SLA-backed security updates
Docker provides comprehensive enterprise support for DHI users, ensuring rapid
response to security threats and operational issues:
- Enterprise support: Access to Docker's support team, with
response times designed to safeguard mission-critical applications and
maintain operational continuity.
- SLA-backed CVE mitigation: Docker aims to address Critical and High severity
Common Vulnerabilities and Exposures (CVEs) within 7 working days of an
upstream fix becoming available, with some exceptions. Faster than typical
industry response times and backed by an enterprise-grade SLA, so your teams
can rely on timely fixes to keep workloads secure.
This level of support ensures that organizations can rely on DHI for their
mission-critical applications, with the assurance that security and stability
are maintained proactively.
content/manuals/dhi/get-started.md
+121
View File
@@ -0,0 +1,121 @@
---
linktitle: Quickstart
title: Docker Hardened Images quickstart
description: Follow a quickstart guide to explore, mirror, and run a Docker Hardened Image.
weight: 2
keywords: docker hardened images quickstart, mirror container image, run secure image
---
{{< summary-bar feature_name="Docker Hardened Images" >}}
This guide shows you how to go from zero to running a Docker Hardened Image
(DHI) using a real example. While the steps use a specific image as an
example, they can be applied to any DHI.
## Step 1: Sign up and subscribe to DHI for access
To access Docker Hardened Images, your organization must [sign
up](https://www.docker.com/products/hardened-images/#getstarted) and subscribe.
## Step 2: Find an image to use
Once subscribed, Docker Hardened Images will appear under your organization's
namespace on Docker Hub.
1. Go to [Docker Hub](https://hub.docker.com) and sign in.
2. Select **My Hub** in the top navigation.
3. In the left sidebar, choose your organization that has DHI access.
4. In the left sidebar, select **DHI catalog**.
![Docker Hub sidebar showing DHI catalog](./images/dhi-catalog.png)
5. Use the search bar or filters to find an image (e.g., `python`, `node`,
`golang`). For this guide, use the Python image as an example.
![DHI catalog with Python repository shown](./images/dhi-python-search.png)
6. Select the Python repository to view its details.
Continue to the next step to mirror the image. To dive deeper into exploring
images see [Explore Docker Hardened Images](./how-to/explore.md).
## Step 3: Mirror the image
To use a Docker Hardened Image, you must mirror it to your organization. Only
organization owners can perform this action. Mirroring creates a copy of the
image in your organization's namespace, allowing team members to pull and use
it.
1. In the image repository page, select **Mirror to repository**.
![An image of the Python page with the Mirror to repository button showing](./images/dhi-mirror-button.png)
> [!NOTE]
>
> If you don't see the **Mirror to repository** button, the repository may
> already be mirrored to your organization. In this case, you can select
> **View in repository** to see the mirrored image's location or mirror it to
> another repository.
2. Follow the on-screen instructions to choose a name. For this guide, the
example uses the name `dhi-python`. Note that the name must start with
`dhi-`.
![Mirror a repository page](./images/dhi-mirror-screen.png)
3. Select **Create repository** to start the mirroring process.
It may take a few minutes for all the tags to finish mirroring. Once
mirrored, the image repository appears in your organization's namespace. For
example, in [Docker Hub](https://hub.docker.com), go to **My Hub** > ***YOUR_ORG*** > **Repositories**,
and you should see `dhi-python` listed. You can now pull it
like any other image.
![Repository list with mirrored repository showing](./images/dhi-python-mirror.png)
Continue to the next step to pull and run the image. To dive deeper into
mirroring images see [Mirror a Docker Hardened Image
repository](./how-to/mirror.md).
## Step 4: Pull and run the image
Once you've mirrored the image to your organization, you can pull and run it
like any other Docker image. Note that Docker Hardened Images are designed to be
minimal and secure, so they may not include all the tools or libraries you
expect in a typical image. You can view the typical differences in
[Considerations when adopting
DHIs](./how-to/use.md#considerations-when-adopting-dhis).
The following example demonstrates that you can run the Python image and execute
a simple Python command just like you would with any other Docker image:
1. Pull the mirrored image. Open a terminal and run the following command,
replacing `<your-namespace>` with your organization's namespace:
```console
$ docker pull <your-namespace>/dhi-python:3.13
```
2. Run the image to confirm everything works:
```console
$ docker run --rm <your-namespace>/dhi-python:3.13 python -c "print('Hello from DHI')"
```
This starts a container from the `dhi-python:3.13` image and runs a simple
Python script that prints `Hello from DHI`.
To dive deeper into using images see [Use a Docker Hardened Image](./how-to/use.md).
## What's next
You've pulled and run your first Docker Hardened Image. Here are a few ways to keep going:
- [Migrate existing applications to DHIs](./how-to/migrate.md): Learn how to
update your Dockerfiles to use Docker Hardened Images as the base.
- [Verify DHIs](./how-to/verify.md): Use tools like [Docker Scout](/scout/) or
Cosign to inspect and verify signed attestations, like SBOMs and provenance.
- [Scan DHIs](./how-to/scan.md): Analyze the image with Docker
Scout or other scanners to identify known CVEs.
content/manuals/dhi/how-to/_index.md
+67
View File
@@ -0,0 +1,67 @@
---
title: How-tos
description: Step-by-step guidance for working with Docker Hardened Images, from discovery to debugging.
weight: 20
params:
grid_howto:
- title: Explore Docker Hardened Images
description: Learn how to find and evaluate image repositories, variants, metadata, and attestations in the DHI catalog on Docker Hub.
icon: travel_explore
link: /dhi/how-to/explore/
- title: Mirror a Docker Hardened Image repository
description: Learn how to mirror an image into your organization's namespace and optionally push it to another private registry.
icon: compare_arrows
link: /dhi/how-to/mirror/
- title: Use a Docker Hardened Image
description: Learn how to pull, run, and reference Docker Hardened Images in Dockerfiles, CI pipelines, and standard development workflows.
icon: play_arrow
link: /dhi/how-to/use/
- title: Migrate an existing application to use Docker Hardened Images
description: Follow a step-by-step guide to update your Dockerfiles and adopt Docker Hardened Images for secure, minimal, and production-ready builds.
icon: directions_run
link: /dhi/how-to/migrate/
- title: Verify a Docker Hardened Image
description: Use Docker Scout or cosign to verify signed attestations like SBOMs, provenance, and vulnerability data for Docker Hardened Images.
icon: check_circle
link: /dhi/how-to/verify/
- title: Scan a Docker Hardened Image
description: Learn how to scan Docker Hardened Images for known vulnerabilities using Docker Scout, Grype, or Trivy.
icon: bug_report
link: /dhi/how-to/scan/
- title: Enforce Docker Hardened Image usage with policies
description: Learn how to use image policies with Docker Scout for Docker Hardened Images.
icon: policy
link: /dhi/how-to/policies/
- title: Debug a Docker Hardened Image
description: Use Docker Debug to inspect a running container based on a hardened image without modifying it.
icon: terminal
link: /dhi/how-to/debug/
---
This section provides practical, step-by-step guidance for working with Docker
Hardened Images (DHIs). Whether you're evaluating DHIs for the first time or
integrating them into a production CI/CD pipeline, these topics walk you
through each phase of the adoption journey, from discovery to debugging.
To help you get started and stay secure, the topics are organized around the
typical lifecycle of working with DHIs.
## Lifecycle flow
1. Explore available images and metadata in the DHI catalog.
2. Mirror trusted images into your namespace or registry.
3. Adopt DHIs in your workflows by pulling, using in development and CI, and
migrating existing applications to use secure, minimal base images.
4. Analyze images by verifying signatures, SBOMs, and provenance, and scanning
for vulnerabilities.
5. Enforce policies to maintain security and compliance.
6. Debug containers based on DHIs without modifying the image.
Each of the following topics aligns with a step in this lifecycle, so you can progress
confidently through exploration, implementation, and ongoing maintenance.
## Step-by-step topics
{{< grid
items="grid_howto"
>}}
content/manuals/dhi/how-to/debug.md
+77
View File
@@ -0,0 +1,77 @@
---
title: Debug a Docker Hardened Image container
linkTitle: Debug a container
weight: 60
keywords: debug, hardened images, DHI, troubleshooting, ephemeral container, docker debug
description: Learn how to use Docker Debug to troubleshoot Docker Hardened Images (DHI) locally or in production.
keywords: docker debug, ephemeral container, non-root containers, hardened container image, debug secure container
---
{{< summary-bar feature_name="Docker Hardened Images" >}}
Docker Hardened Images (DHI) prioritize minimalism and security, which means
they intentionally leave out many common debugging tools (like shells or package
managers). This makes direct troubleshooting difficult without introducing risk.
To address this, you can use [Docker
Debug](../../../reference/cli/docker/debug.md), a secure workflow that
temporarily attaches an ephemeral debug container to a running service or image
without modifying the original image.
This guide shows how to debug Docker Hardened Images locally during
development. You can also debug containers remotely using the `--host` option.
The following example uses a mirrored `dhi-python:3.13` image, but the same steps apply to any image.
## Step 1: Run a container from a Hardened Image
Start with a DHI-based container that simulates an issue:
```console
$ docker run -d --name myapp <YOUR_ORG>/dhi-python:3.13 python -c "import time; time.sleep(300)"
```
This container doesn't include a shell or tools like `ps`, `top`, or `cat`.
If you try:
```console
$ docker exec -it myapp sh
```
You'll see:
```console
exec: "sh": executable file not found in $PATH
```
## Step 2: Use Docker Debug to inspect the container
Use the `docker debug` command to attach a temporary, tool-rich debug container to the running instance.
```console
$ docker debug myapp
```
From here, you can inspect running processes, network status, or mounted files.
For example, to check running processes:
```console
$ ps aux
```
Exit the debug session with:
```console
$ exit
```
## What's next
Docker Debug helps you troubleshoot hardened containers without compromising the
integrity of the original image. Because the debug container is ephemeral and
separate, it avoids introducing security risks into production environments.
If you encounter issues related to permissions, ports, missing shells, or
package managers, see [Troubleshoot Docker Hardened Images](../troubleshoot.md)
for recommended solutions and workarounds.
content/manuals/dhi/how-to/explore.md
+140
View File
@@ -0,0 +1,140 @@
---
title: Explore Docker Hardened Images
linktitle: Explore images
description: Learn how to find and evaluate image repositories, variants, metadata, and attestations in the DHI catalog on Docker Hub.
keywords: explore docker images, image variants, docker hub catalog, container image metadata, signed attestations
weight: 10
---
{{< summary-bar feature_name="Docker Hardened Images" >}}
Docker Hardened Images (DHI) are a curated set of secure, production-ready
container images designed for enterprise use. This page explains how to explore
available DHI repositories, review image metadata, examine variant details, and
understand the security attestations provided. Use this information to evaluate
and select the right image variants for your applications before mirroring them
to your organization.
## Access Docker Hardened Images
Docker Hardened Images requires a subscription. [Sign
up](https://www.docker.com/products/hardened-images/#getstarted) to access
Docker Hardened Images.
## Explore Docker Hardened Images
To explore Docker Hardened Images (DHI):
1. Go to [Docker Hub](https://hub.docker.com) and sign in.
2. Select **My Hub**.
3. In the namespace drop-down, select your organization that has access to DHI.
4. Select **DHI catalog**.
On the DHI page, you can browse images, search images, or filter images by
category.
## View repository details
To view repository details:
1. Go to [Docker Hub](https://hub.docker.com) and sign in.
2. Select **My Hub**.
3. In the namespace drop-down, select your organization that has access to DHI.
4. Select **DHI catalog**.
5. Select a repository in the DHI catalog list.
The repository details page provides the following:
- Overview: A brief explanation of the image.
- Guides: Several guides on how to use the image and migrate your existing application.
- Tags: Select this option to [view image variants](#view-image-variants).
- Security summary: Select a tag name to view a quick security summary,
including package count, total known vulnerabilities, and Scout health score.
- Recently pushed tags: A list of recently updated image variants and when they
were last updated.
- Mirror to repository: Select this option to mirror the image to your
organization's repository in order to use it. Only organization owners can mirror a repository.
- View in repository: After a repository has been mirrored, you can select this
option to view where the repository has been mirrored, or mirror it to another repository.
## View image variants
Tags are used to identify image variants. Image variants are different builds of
the same application or framework tailored for different use-cases.
To explore image variants:
1. Go to [Docker Hub](https://hub.docker.com) and sign in.
2. Select **My Hub**.
3. In the namespace drop-down, select your organization that has access to DHI.
4. Select **DHI catalog**.
5. Select a repository in the DHI catalog list.
6. Select **Tags**.
The **Tags** page provides the following information:
- Tags: A list of all available tags, also known as image variants.
- Distribution: The distribution that the variant is based on. For example, `debian 12` or `alpine 3.21`.
- Package manager: The package manager that is available in the variant. For example, `apt`, `apk`, or `-` (no package manager).
- Shell: The shell that is available in the variant. For example, `bash`, `busybox`, or `-` (no shell).
- User: The user that the container runs as. For example, `root`, `nonroot (65532)`, or `node (1000)`.
- Last pushed: The amount of days ago that the image variant was last pushed.
- Vulnerabilities: The amount of vulnerabilities in the variant based on the severity.
- Health: The Scout health score for the variant. Select the score icon to get more details.
> [!NOTE]
>
> Unlike most images on Docker Hub, Docker Hardened Images do not use the
> `latest` tag. Each image variant is published with a full semantic version tag
> (for example, `3.13`, `3.13-dev`) and is kept up to date. If you need to pin
> to a specific image release for reproducibility, you can reference the image
> by its [digest](../core-concepts/digests.md).
## View image variant details
To explore the details of an image variant:
1. Go to [Docker Hub](https://hub.docker.com) and sign in.
2. Select **My Hub**.
3. In the namespace drop-down, select your organization that has access to DHI.
4. Select **DHI catalog**.
5. Select a repository in the DHI catalog list.
6. Select **Tags**.
7. Select the image variant's tag in the table.
The image variant details page provides the following information:
- Packages: A list of all packages included in the image variant. This section
includes details about each package, including its name, version,
distribution, and licensing information.
- Specifications: The specifications for the image variant include the following
key details:
- Source & Build Information: The image is built from the Dockerfile found
here and the Git commit.
- Build parameters
- Entrypoint
- CMD
- User
- Working directory
- Environment Variables
- Labels
- Platform
- Vulnerabilities: The vulnerabilities section provides a list of known CVEs for
the image variant, including:
- CVE
- Severity
- Package
- Fix version
- Last detected
- Status
- Suppressed CVEs
- Attestations: Variants include comprehensive security attestations to verify
the image's build process, contents, and security posture. These attestations
are signed and can be verified using cosign. For a list of available
attestations, see [Attestations](../core-concepts/attestations.md).
## What's next
After finding an image you need, you can [mirror the image to your
organization](./mirror.md). If the image is already mirrored, then you can start
[using the image](./use.md).
content/manuals/dhi/how-to/migrate.md
+242
View File
@@ -0,0 +1,242 @@
---
title: Migrate an existing application to use Docker Hardened Images
linktitle: Migrate an app
description: Follow a step-by-step guide to update your Dockerfiles and adopt Docker Hardened Images for secure, minimal, and production-ready builds.
weight: 50
keywords: migrate dockerfile, hardened base image, multi-stage build, non-root containers, secure container build
---
{{< summary-bar feature_name="Docker Hardened Images" >}}
This guide helps you migrate your existing Dockerfiles to use Docker Hardened
Images (DHIs). DHIs are minimal and security-focused, which may require
adjustments to your base images, build process, and runtime configuration.
This guide focuses on migrating framework images, such as images for building
applications from source using languages like Go, Python, or Node.js. If you're
migrating application images, such as databases, proxies, or other prebuilt
services, many of the same principles still apply.
## Migration considerations
DHIs omit common tools such as shells and package managers to
reduce the attack surface. They also default to running as a nonroot user. As a
result, migrating to DHI typically requires the following changes to your
Dockerfile:
| Item | Migration note |
|:-------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Base image | Replace your base images in your Dockerfile with a Docker Hardened Image. |
| Package management | Images intended for runtime, don't contain package managers. Use package managers only in images with a `dev` tag. Utilize multi-stage builds and copy necessary artifacts from the build stage to the runtime stage. |
| Non-root user | By default, images intended for runtime, run as the nonroot user. Ensure that necessary files and directories are accessible to the nonroot user. |
| Multi-stage build | Utilize images with a `dev` or `sdk` tags for build stages and non-dev images for runtime. |
| TLS certificates | DHIs contain standard TLS certificates by default. There is no need to install TLS certificates. |
| Ports | DHIs intented for runtime run as a nonroot user by default. As a result, applications in these images can't bind to privileged ports (below 1024) when running in Kubernetes or in Docker Engine versions older than 20.10. To avoid issues, configure your application to listen on port 1025 or higher inside the container. |
| Entry point | DHIs may have different entry points than images such as Docker Official Images. Inspect entry points for DHIs and update your Dockerfile if necessary. |
| No shell | DHIs intended for runtime don't contain a shell. Use dev images in build stages to run shell commands and then copy artifacts to the runtime stage. |
For more details and troubleshooting tips, see the [Troubleshoot](/manuals/dhi/troubleshoot.md).
## Migrate an existing application
The following steps outline the migration process.
### Step 1: Update the base image in your Dockerfile
Update the base image in your application’s Dockerfile to a hardened image. This
is typically going to be an image tagged as `dev` or `sdk` because it has the tools
needed to install packages and dependencies.
The following example diff snippet from a Dockerfile shows the old base image
replaced by the new hardened image.
```diff
- ## Original base image
- FROM golang:1.22
+ ## Updated to use hardened base image
+ FROM <your-namespace>/dhi-golang:1.22-dev
```
### Step 2: Update the runtime image in your Dockerfile
To ensure that your final image is as minimal as possible, you should use a
[multi-stage build](/manuals/build/building/multi-stage.md). All stages in your
Dockerfile should use a hardened image. While intermediary stages will typically
use images tagged as `dev` or `sdk`, your final runtime stage should use a runtime image.
Utilize the build stage to compile your application and copy the resulting
artifacts to the final runtime stage. This ensures that your final image is
minimal and secure.
See the [Example Dockerfile migrations](#example-dockerfile-migrations) section for
examples of how to update your Dockerfile.
## Example Dockerfile migrations
The following migration examples show a Dockerfile before the migration and
after the migration.
### Go example
{{< tabs >}}
{{< tab name="Before" >}}
```dockerfile
#syntax=docker/dockerfile:1
FROM golang:latest
WORKDIR /app
ADD . ./
RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" --installsuffix cgo -o main .
ENTRYPOINT ["/app/main"]
```
{{< /tab >}}
{{< tab name="After" >}}
```dockerfile
#syntax=docker/dockerfile:1
# === Build stage: Compile Go application ===
FROM <your-namespace>/dhi-golang:1-alpine3.21-dev AS builder
WORKDIR /app
ADD . ./
RUN CGO_ENABLED=0 GOOS=linux go build -a -ldflags="-s -w" --installsuffix cgo -o main .
# === Final stage: Create minimal runtime image ===
FROM <your-namespace>/dhi-golang:1-alpine3.21
WORKDIR /app
COPY --from=builder /app/main /app/main
ENTRYPOINT ["/app/main"]
```
{{< /tab >}}
{{< /tabs >}}
### Node.js example
{{< tabs >}}
{{< tab name="Before" >}}
```dockerfile
#syntax=docker/dockerfile:1
FROM node:latest
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY image.jpg ./image.jpg
COPY . .
CMD ["node", "index.js"]
```
{{< /tab >}}
{{< tab name="After" >}}
```dockerfile
#syntax=docker/dockerfile:1
#=== Build stage: Install dependencies and build application ===#
FROM <your-namespace>/dhi-node:23-alpine3.21-dev AS builder
WORKDIR /usr/src/app
COPY package*.json ./
RUN npm install
COPY image.jpg ./image.jpg
COPY . .
#=== Final stage: Create minimal runtime image ===#
FROM <your-namespace>/dhi-node:23-alpine3.21
ENV PATH=/app/node_modules/.bin:$PATH
COPY --from=builder --chown=node:node /usr/src/app /app
WORKDIR /app
CMD ["index.js"]
```
{{< /tab >}}
{{< /tabs >}}
### Python example
{{< tabs >}}
{{< tab name="Before" >}}
```dockerfile
#syntax=docker/dockerfile:1
FROM python:latest AS builder
ENV LANG=C.UTF-8
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"
WORKDIR /app
RUN python -m venv /app/venv
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
FROM python:latest
WORKDIR /app
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"
COPY image.py image.png ./
COPY --from=builder /app/venv /app/venv
ENTRYPOINT [ "python", "/app/image.py" ]
```
{{< /tab >}}
{{< tab name="After" >}}
```dockerfile
#syntax=docker/dockerfile:1
#=== Build stage: Install dependencies and create virtual environment ===#
FROM <your-namespace>/dhi-python:3.13-alpine3.21-dev AS builder
ENV LANG=C.UTF-8
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"
WORKDIR /app
RUN python -m venv /app/venv
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
#=== Final stage: Create minimal runtime image ===#
FROM <your-namespace>/dhi-python:3.13-alpine3.21
WORKDIR /app
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"
COPY image.py image.png ./
COPY --from=builder /app/venv /app/venv
ENTRYPOINT [ "python", "/app/image.py" ]
```
{{< /tab >}}
{{< /tabs >}}
content/manuals/dhi/how-to/mirror.md
+164
View File
@@ -0,0 +1,164 @@
---
title: Mirror a Docker Hardened Image repository
linktitle: Mirror an image
description: Learn how to mirror an image into your organization's namespace and optionally push it to another private registry.
weight: 20
keywords: mirror docker image, private container registry, docker hub automation, webhook image sync, secure image distribution
---
{{< summary-bar feature_name="Docker Hardened Images" >}}
Before you can use a Docker Hardened Image (DHI), you must mirror its repository
to your organization. Only organization owners can perform this action. Once
mirrored, the image becomes available in your organization's namespace, and
users with access can begin pulling and using it.
Mirrored repositories automatically stay up to date. Docker continues to sync
new tags and image updates from the upstream DHI catalog, so you always have
access to the latest secure version.
## Prerequisites
- To manage mirroring, you must be an [organization owner](/admin/).
- Your organization must be [signed
up](https://www.docker.com/products/hardened-images/#getstarted) to use
Docker Hardened Images.
## Mirror an image repository
To mirror a Docker Hardened Image repository:
1. Go to [Docker Hub](https://hub.docker.com) and sign in.
2. Select **My Hub**.
3. In the namespace drop-down, select your organization that has access to DHI.
4. Select **DHI catalog**.
5. Select a DHI repository to view its details.
6. Select **Mirror to repository** and follow the on-screen instructions.
It may take a few minutes for all the tags to finish mirroring. Once an image
has been mirrored, the **Mirror to repository** button changes to **View in
repository**. Selecting **View in repository** opens a drop-down list of
repositories that the image has already been mirrored to. From this drop-down,
you can:
- Select an existing mirrored repository to view its details
- Select **Mirror to repository** again to mirror the image to an additional
repository
After mirroring a repository, the repository appears in your organization's
repository list under the name you specified, prefixed by `dhi-`. It will
continue to receive updated images.
![Repository list with mirrored repository showing](../images/dhi-python-mirror.png)
> [!IMPORTANT]
>
> The mirrored repository's visibility must remain private. Changing its
> visibility to public will stop updates from being mirrored.
Once mirrored, the image repository works like any other private repository on
Docker Hub. Team members with access to the repository can now pull and use the
image. To learn how to manage access, view tags, or configure settings, see
[Repositories](/manuals/docker-hub/repos.md).
### Webhook integration for syncing and alerts
To keep external registries or systems in sync with your mirrored Docker
Hardened Images, and to receive notifications when updates occur, you can
configure a [webhook](/docker-hub/repos/manage/webhooks/) on the mirrored
repository in Docker Hub. A webhook sends a `POST` request to a URL you define
whenever a new image tag is pushed or updated.
For example, you might configure a webhook to call a CI/CD system at
`https://ci.example.com/hooks/dhi-sync` whenever a new tag is mirrored. The
automation triggered by this webhook can pull the updated image from Docker Hub
and push it to an internal registry such as Amazon ECR, Google Artifact
Registry, or GitHub Container Registry.
Other common webhook use cases include:
- Triggering validation or vulnerability scanning workflows
- Signing or promoting images
- Sending notifications to downstream systems
#### Example webhook payload
When a webhook is triggered, Docker Hub sends a JSON payload like the following:
```json
{
"callback_url": "https://registry.hub.docker.com/u/exampleorg/dhi-python/hook/abc123/",
"push_data": {
"pushed_at": 1712345678,
"pusher": "trustedbuilder",
"tag": "3.13-alpine3.21"
},
"repository": {
"name": "dhi-python",
"namespace": "exampleorg",
"repo_name": "exampleorg/dhi-python",
"repo_url": "https://hub.docker.com/r/exampleorg/dhi-python",
"is_private": true,
"status": "Active",
...
}
}
```
## Stop mirroring an image repository
Only organization owners can stop mirroring a repository. After you stop
mirroring, the repository remains, but it will
no longer receive updates. You can still pull the last image that was mirrored,
but the repository will not receive new tags or updates from the original
repository.
To stop mirroring an image repository:
1. Go to the mirrored repository in your organization's namespace.
2. Select **Stop mirroring**.
Once you have stopped mirroring a repository, you can choose another DHI
repository to mirror.
## Mirror from Docker Hub to another registry
After you've mirrored a Docker Hardened Image repository to your organization's
namespace on Docker Hub, you can optionally mirror it to another container
registry, such as Amazon ECR, Google Artifact Registry, GitHub Container
Registry, or a private Harbor instance.
You can use any standard workflow, including:
- [The Docker CLI](/reference/cli/docker/_index.md)
- [The Docker Hub Registry API](/reference/api/registry/latest/)
- Third-party registry tools or CI/CD automation
The following example shows how to use the Docker CLI to pull a mirrored DHI and
push it to another registry:
```console
# Authenticate to Docker Hub (if not already signed in)
$ docker login
# Pull the image from your organization's namespace on Docker Hub
$ docker pull <your-namespace>/dhi-<image>:<tag>
# Tag the image for your destination registry
$ docker tag <your-namespace>/dhi-<image>:<tag> registry.example.com/my-project/<image>:<tag>
# Push the image to the destination registry
# You will need to authenticate to the third-party registry before pushing
$ docker push registry.example.com/my-project/<image>:<tag>
```
> [!IMPORTANT]
>
> To continue receiving image updates and preserve access to Docker Hardened
> Images, ensure that any copies pushed to other registries remain private.
## What's next
After mirroring an image repository, you can you can start [using the
image](./use.md).
content/manuals/dhi/how-to/policies.md
+110
View File
@@ -0,0 +1,110 @@
---
title: Enforce Docker Hardened Image usage with policies
linktitle: Enforce image usage
description: Learn how to use image policies with Docker Scout for Docker Hardened Images.
weight: 50
keywords: docker scout policies, enforce image compliance, container security policy, image provenance, vulnerability policy check
---
{{< summary-bar feature_name="Docker Hardened Images" >}}
Mirroring a Docker Hardened Image (DHI) repository automatically enables [Docker
Scout](/scout/), allowing you to start enforcing security and compliance policies for your
images without additional setup. Using Docker Scout policies, you can define and
apply rules that ensure only approved and secure images, such as those based on
DHIs, are used across your environments.
With policy evaluation built into Docker Scout, you can monitor image compliance
in real time, integrate checks into your CI/CD workflows, and maintain
consistent standards for image security and provenance.
## View existing policies
To see the current policies applied to a mirrored DHI repository:
1. Go to the mirrored DHI repository in [Docker Hub](https://hub.docker.com).
2. Select **View on Scout**.
This opens the [Docker Scout dashboard](https://scout.docker.com), where you
can see which policies are currently active and whether your images meet the
policy criteria.
Docker Scout automatically evaluates policy compliance when new images are
pushed. Each policy includes a compliance result and a link to the affected
images and layers.
## Create policies for your DHI-based images
To ensure that the images you build using Docker Hardened Images remain secure,
you can create Docker Scout policies tailored to your requirements for your own
repositories. These policies help enforce security standards such as preventing
high-severity vulnerabilities, requiring up-to-date base images, or validating
the presence of key metadata.
Policies evaluate images when they are pushed to a repository, allowing you to
track compliance, get notified of deviations, and integrate policy checks into
your CI/CD pipeline.
### Example: Create a policy for DHI-based images
This example shows how to create a policy that requires all images in your
organization to use Docker Hardened Images as their base. This ensures that
your applications are built on secure, minimal, and production-ready images.
#### Step 1: Use a DHI base image in your Dockerfile
Create a Dockerfile that uses a Docker Hardened Image mirrored repository as the
base. For example:
```dockerfile
# Dockerfile
FROM ORG_NAME/dhi-python:3.13-alpine3.21
ENTRYPOINT ["python", "-c", "print('Hello from a DHI-based image')"]
```
#### Step 2: Build and push the image
Open a terminal and navigate to the directory containing your Dockerfile. Then,
build and push the image to your Docker Hub repository:
```console
$ docker build \
--push \
-t YOUR_ORG/my-dhi-app:v1 .
```
#### Step 3: Enable Docker Scout
To enable Docker Scout for your organization and the repository, run the
following commands in your terminal:
```console
$ docker login
$ docker scout enroll YOUR_ORG
$ docker scout repo enable --org YOUR_ORG YOUR_ORG/my-dhi-app
```
#### Step 4: Create a policy
1. Go to the [Docker Scout dashboard](https://scout.docker.com).
2. Select your organization and navigate to **Policies**.
3. Select **Add policy**.
4. Select **Configure** for **Approved Base Images Policy**.
5. Give the policy a compliant name, such as **Approved DHI Base Images**.
6. In **Approved base image sources**, delete the default item.
7. In **Approved base image sources**, add approved base image sources. For this
example, use the wildcard (`*`) to allow all mirrored DHI repositories,
`docker.io/ORG_NAME/dhi-*`. Replace `ORG_NAME` with your organization name.
8. Select **Save policy**.
#### Step 4: Evaluate policy compliance
1. Go to the [Docker Scout dashboard](https://scout.docker.com).
2. Select your organization and navigate to **Images**.
3. Find your image, `YOUR_ORG/my-dhi-app:v1`, and select the link in the **Compliance** column.
This shows the policy compliance results for your image, including whether it
meets the requirements of the **Approved DHI Base Images** policy.
You can now [evaluate policy compliance in your CI](/scout/policy/ci/).
content/manuals/dhi/how-to/scan.md
+220
View File
@@ -0,0 +1,220 @@
---
title: Scan Docker Hardened Images
linktitle: Scan an image
description: Learn how to scan Docker Hardened Images for known vulnerabilities using Docker Scout, Grype, or Trivy.
keywords: scan container image, docker scout cves, grype scanner, trivy container scanner, vex attestation
weight: 45
---
{{< summary-bar feature_name="Docker Hardened Images" >}}
Docker Hardened Images (DHIs) are designed to be secure by default, but like any
container image, it's important to scan them regularly as part of your
vulnerability management process.
You can scan DHIs using the same tools you already use for standard images, such
as Docker Scout, Grype, and Trivy. DHIs follow the same formats and standards
for compatibility across your security tooling. Before you scan an image, the image must
be mirrored into your organization on Docker Hub.
> [!NOTE]
>
> [Docker Scout](/manuals/scout/_index.md) is automatically enabled at no
> additional cost for all mirrored Docker Hardened Image repositories on Docker
> Hub. You can view scan results directly in the Docker Hub UI under your
> organization's repository.
## Docker Scout
Docker Scout is integrated into Docker Desktop and the Docker CLI. It provides
vulnerability insights, CVE summaries, and direct links to remediation guidance.
### Scan a DHI using Docker Scout
To scan a Docker Hardened Image using Docker Scout, run the following
command:
```console
$ docker scout cves <your-namespace>/dhi-<image>:<tag> --platform <platform>
```
Example output:
```plaintext
v SBOM obtained from attestation, 101 packages found
v Provenance obtained from attestation
v VEX statements obtained from attestation
v No vulnerable package detected
...
```
For more detailed filtering and JSON output, see [Docker Scout CLI reference](../../../reference/cli/docker/scout/_index.md).
### Automate DHI scanning in CI/CD with Docker Scout
Integrating Docker Scout into your CI/CD pipeline enables you to automatically
verify that images built from Docker Hardened Images remain free from known
vulnerabilities during the build process. This proactive approach ensures the
continued security integrity of your images throughout the development
lifecycle.
#### Example GitHub Actions workflow
The following is a sample GitHub Actions workflow that builds an image and scans
it using Docker Scout:
```yaml {collapse="true"}
name: DHI Vulnerability Scan
on:
push:
branches: [ main ]
pull_request:
branches: [ "**" ]
env:
REGISTRY: docker.io
IMAGE_NAME: ${{ github.repository }}
SHA: ${{ github.event.pull_request.head.sha || github.event.after }}
jobs:
scan:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
pull-requests: write
steps:
- name: Checkout repository
uses: actions/checkout@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to Docker Hub
uses: docker/login-action@v2
with:
username: ${{ secrets.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
- name: Build Docker image
run: |
docker build -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.SHA }} .
- name: Run Docker Scout CVE scan
uses: docker/scout-action@v1
with:
command: cves
image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.SHA }}
only-severities: critical,high
exit-code: true
```
The `exit-code: true` parameter ensures that the workflow fails if any critical or
high-severity vulnerabilities are detected, preventing the deployment of
insecure images.
For more details on using Docker Scout in CI, see [Integrating Docker
Scout with other systems](/manuals/scout/integrations/_index.md).
## Grype
[Grype](https://github.com/anchore/grype) is an open-source scanner that checks
container images against vulnerability databases like the NVD and distro
advisories.
### Scan a DHI using Grype
After installing Grype, you can scan a Docker Hardened Image by pulling
the image and running the scan command:
```console
$ docker pull <your-namespace>/dhi-<image>:<tag>
$ grype <your-namespace>/dhi-<image>:<tag>
```
Example output:
```plaintext
NAME INSTALLED FIXED-IN TYPE VULNERABILITY SEVERITY EPSS% RISK
libperl5.36 5.36.0-7+deb12u2 (won't fix) deb CVE-2023-31484 High 79.45 1.1
perl 5.36.0-7+deb12u2 (won't fix) deb CVE-2023-31484 High 79.45 1.1
perl-base 5.36.0-7+deb12u2 (won't fix) deb CVE-2023-31484 High 79.45 1.1
...
```
You should include the `--vex` flag to apply VEX statements during the scan,
which filter out known non-exploitable CVEs. For more information, see the [VEX
section](#use-vex-to-filter-known-non-exploitable-cves).
## Trivy
[Trivy](https://github.com/aquasecurity/trivy) is an open-source vulnerability
scanner for containers and other artifacts. It detects vulnerabilities in OS
packages and application dependencies.
### Scan a DHI using Trivy
After installing Trivy, you can scan a Docker Hardened Image by pulling
the image and running the scan command:
```console
$ docker pull <your-namespace>/dhi-<image>:<tag>
$ trivy image <your-namespace>/dhi-<image>:<tag>
```
Example output:
```plaintext
Report Summary
┌──────────────────────────────────────────────────────────────────────────────┬────────────┬─────────────────┬─────────┐
│ Target │ Type │ Vulnerabilities │ Secrets │
├──────────────────────────────────────────────────────────────────────────────┼────────────┼─────────────────┼─────────┤
│ <namespace>/dhi-<image>:<tag> (debian 12.11) │ debian │ 66 │ - │
├──────────────────────────────────────────────────────────────────────────────┼────────────┼─────────────────┼─────────┤
│ opt/python-3.13.4/lib/python3.13/site-packages/pip-25.1.1.dist-info/METADATA │ python-pkg │ 0 │ - │
└──────────────────────────────────────────────────────────────────────────────┴────────────┴─────────────────┴─────────┘
```
You should include the `--vex` flag to apply VEX statements during the scan,
which filter out known non-exploitable CVEs. For more information, see the [VEX
section](#use-vex-to-filter-known-non-exploitable-cves).
## Use VEX to filter known non-exploitable CVEs
Docker Hardened Images include signed VEX (Vulnerability Exploitability
eXchange) attestations that identify vulnerabilities not relevant to the image’s
runtime behavior.
When using Docker Scout, these VEX statements are automatically applied and no
manual configuration needed.
To manually create a JSON file VEX attestation for tools that support it:
```console
$ docker scout attest get \
--predicate-type https://openvex.dev/ns/v0.2.0 \
--predicate \
<your-namespace>/dhi-<image>:<tag> --platform <platform> > vex.json
```
For example:
```console
$ docker scout attest get \
--predicate-type https://openvex.dev/ns/v0.2.0 \
--predicate \
docs/dhi-python:3.13 --platform linux/amd64 > vex.json
```
This creates a `vex.json` file containing the VEX statements for the specified
image. You can then use this file with tools that support VEX to filter out known non-exploitable CVEs.
For example, with Grype and Trivy, you can use the `--vex` flag to apply the VEX
statements during the scan:
```console
$ grype <your-namespace>/dhi-<image>:<tag> --vex vex.json
```
content/manuals/dhi/how-to/use.md
+187
View File
@@ -0,0 +1,187 @@
---
title: Use a Docker Hardened Image
linktitle: Use an image
description: Learn how to pull, run, and reference Docker Hardened Images in Dockerfiles, CI pipelines, and standard development workflows.
keywords: use hardened image, docker pull secure image, non-root containers, multi-stage dockerfile, dev image variant
weight: 30
---
{{< summary-bar feature_name="Docker Hardened Images" >}}
You can use a Docker Hardened Image (DHI) just like any other image on Docker
Hub. DHIs follow the same familiar usage patterns. Pull them with `docker pull`,
reference them in your Dockerfile, and run containers with `docker run`.
The key difference is that DHIs are security-focused and intentionally minimal
to reduce the attack surface. This means some variants don't include a shell or
package manager, and may run as a nonroot user by default.
> [!NOTE]
>
> You don't need to change your existing workflows. Whether you're pulling
> images manually, referencing them in your Dockerfiles, or integrating them
> into CI pipelines, DHIs work just like the images you already use.
After [mirroring](./mirror.md) a DHI to your organization's namespace, the image
becomes available for use. To find your mirrored repository, go to the original
image's page in the Hardened Images catalog and select **View in repository**,
to show a list of mirrored repositories.
## Considerations when adopting DHIs
Docker Hardened Images are intentionally minimal to improve security. If you're updating existing Dockerfiles or frameworks to use DHIs, keep the following considerations in mind:
| Feature | Details |
|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| No shell or package manager | Runtime images don’t include a shell or package manager. Use `-dev` or `-sdk` variants in build stages to run shell commands or install packages, and then copy artifacts to a minimal runtime image. |
| Non-root runtime | Runtime DHIs default to running as a non-root user. Ensure your application doesn't require privileged access and that all needed files are readable and executable by a non-root user. |
| Ports | Applications running as non-root users can't bind to ports below 1024 in older versions of Docker or in some Kubernetes configurations. Use ports above 1024 for compatibility. |
| Entry point | DHIs may not include a default entrypoint or might use a different one than the original image you're familiar with. Check the image configuration and update your `CMD` or `ENTRYPOINT` directives accordingly. |
| Multi-stage builds | Always use multi-stage builds for frameworks: a `-dev` image for building or installing dependencies, and a minimal runtime image for the final stage. |
| TLS certificates | DHIs include standard TLS certificates. You do not need to manually install CA certs. |
If you're migrating an existing application, see [Migrate an existing
application to use Docker Hardened Images](./migrate.md).
## Use a DHI in a Dockerfile
To use a DHI as the base image for your container, specify it in the `FROM` instruction in your Dockerfile:
```dockerfile
FROM <your-namespace>/dhi-<image>:<tag>
```
Replace the image name and tag with the variant you want to use. For example,
use a `-dev` tag if you need a shell or package manager during build stages:
```dockerfile
FROM <your-namespace>/dhi-python:3.13-dev AS build
```
To learn how to explore available variants, see [Explore images](./explore.md).
> [!TIP]
>
> Use a multi-stage Dockerfile to separate build and runtime stages, using a
> `-dev` variant in build stages and a minimal runtime image in the final stage.
## Pull a DHI from Docker Hub
Just like any other image on Docker Hub, you can pull Docker Hardened Images
(DHIs) using tools such as the Docker CLI, the Docker Hub Registry API, or
within your CI pipelines.
The following example shows how to pull a DHI using the CLI:
```console
$ docker pull <your-namespace>/dhi-<image>:<tag>
```
You must have access to the image in your Docker Hub namespace. For more
information, see [Mirror a Docker Hardened Image](./mirror.md).
## Run a DHI
After pulling the image, you can run it using `docker run`. For example,
assuming the repository was mirrored to `dhi-python` in your organization
namespace, start a container and run a Python command:
```console
$ docker run --rm <your-namespace>/dhi-python:3.13 python -c "print('Hello from DHI')"
```
## Use a DHI in CI/CD pipelines
Docker Hardened Images work just like any other image in your CI/CD pipelines.
You can reference them in Dockerfiles, pull them as part of a pipeline step, or
run containers based on them during builds and tests.
Unlike typical container images, DHIs also include signed
[attestations](../core-concepts/attestations.md) such as SBOMs and provenance
metadata. You can incorporate these into your pipeline to support supply chain
security, policy checks, or audit requirements if your tooling supports it.
To strengthen your software supply chain, consider adding your own attestations
when building images from DHIs. This lets you document how the image was
built, verify its integrity, and enable downstream validation and [policy
enforcement](./policies.md) using tools like Docker Scout.
To learn how to attach attestations during the build process, see [Docker Build
Attestations](/manuals/build/metadata/attestations.md) .
## Use a static image for compiled executables
Docker Hardened Images include a `static` image repository designed specifically
for running compiled executables in an extremely minimal and secure runtime.
Use a `-dev` or other builder image in an earlier stage to compile your binary,
and copy the output into a `static` image.
The following example shows a multi-stage Dockerfile that builds a Go application
and runs it in a minimal static image:
```dockerfile
#syntax=docker/dockerfile:1
FROM <your-namespace>/dhi-golang:1.22-dev AS build
WORKDIR /app
COPY . .
RUN CGO_ENABLED=0 go build -o myapp
FROM <your-namespace>/dhi-static:20230311
COPY --from=build /app/myapp /myapp
ENTRYPOINT ["/myapp"]
```
This pattern ensures a hardened runtime environment with no unnecessary
components, reducing the attack surface to a bare minimum.
## Use dev variants for framework-based applications
If you're building applications with frameworks that require package managers or
build tools (such as Python, Node.js, or Go), use a `-dev` variant during the
development or build stage. These variants include essential utilities like
shells, compilers, and package managers to support local iteration and CI
workflows.
Use `-dev` images in your inner development loop or in isolated CI stages to
maximize productivity. Once you're ready to produce artifacts for production,
switch to a smaller runtime variant to reduce the attack surface and image size.
The following example shows how to build a Python app using a `-dev` variant and
run it using the smaller runtime variant:
```dockerfile
#syntax=docker/dockerfile:1
FROM <your-namespace>/dhi-python:3.13-alpine3.21-dev AS builder
ENV LANG=C.UTF-8
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"
WORKDIR /app
RUN python -m venv /app/venv
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
FROM <your-namespace>/dhi-python:3.13-alpine3.21
WORKDIR /app
ENV PYTHONUNBUFFERED=1
ENV PATH="/app/venv/bin:$PATH"
COPY image.py image.png ./
COPY --from=builder /app/venv /app/venv
ENTRYPOINT [ "python", "/app/image.py" ]
```
This pattern separates the build environment from the runtime environment,
helping reduce image size and improve security by removing unnecessary tooling
from the final image.
content/manuals/dhi/how-to/verify.md
+157
View File
@@ -0,0 +1,157 @@
---
title: Verify a Docker Hardened Image
linktitle: Verify an image
description: Use Docker Scout or cosign to verify signed attestations like SBOMs, provenance, and vulnerability data for Docker Hardened Images.
weight: 40
keywords: verify container image, docker scout attest, cosign verify, sbom validation, signed container attestations
---
{{< summary-bar feature_name="Docker Hardened Images" >}}
Docker Hardened Images (DHI) include signed attestations that verify the image’s
build process, contents, and security posture. These attestations are available
for each image variant and can be verified using
[cosign](https://docs.sigstore.dev/) or the Docker Scout CLI.
Docker's public key for DHI images is published at:
- https://registry.scout.docker.com/keyring/dhi/latest.pub
- https://github.com/docker-hardened-images/keyring
## Verify attestations with Docker Scout
You can use the Docker Scout CLI to list and retrieve attestations for Docker
Hardened Images, including images mirrored into your organization's namespace.
> [!NOTE]
>
> Before you run `docker scout attest` commands, ensure any image that you have
> pulled locally is up to date with the remote image. You can do this by running
> `docker pull`. If you don't do this, you may see `No attestation found`.
### Why use Docker Scout instead of cosign directly?
While you can use cosign to verify attestations manually, the Docker Scout CLI
offers several key advantages when working with Docker Hardened Images:
- Purpose-built experience: Docker Scout understands the structure of DHI
attestations and image naming conventions, so you don't have to construct full
image digests or URIs manually.
- Automatic platform resolution: With Scout, you can specify the platform (e.g.,
`--platform linux/amd64`), and it automatically verifies the correct image
variant. Cosign requires you to look up the digest yourself.
- Human-readable summaries: Scout returns summaries of attestation contents
(e.g., package counts, provenance steps), whereas cosign only returns raw
signature validation output.
- One-step validation: The `--verify` flag in `docker scout attest get` validates
the attestation and shows the equivalent cosign command, making it easier to
understand what's happening behind the scenes.
- Integrated with Docker Hub and DHI trust model: Docker Scout is tightly
integrated with Docker’s attestation infrastructure and public keyring,
ensuring compatibility and simplifying verification for users within the
Docker ecosystem.
In short, Docker Scout streamlines the verification process and reduces the chances of human error, while still giving you full visibility and the option to fall back to cosign when needed.
### List available attestations
To list attestations for a mirrored DHI:
```console
$ docker scout attest list <your-org-namespace>/dhi-<image>:<tag> --platform <platform>
```
This command shows all available attestations, including SBOMs, provenance, vulnerability reports, and more.
### Retrieve a specific attestation
To retrieve a specific attestation, use the `--predicate-type` flag with the full predicate type URI:
```console
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.5 \
<your-org-namespace>/dhi-<image>:<tag> --platform <platform>
```
For example:
```console
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.5 \
docs/dhi-python:3.13 --platform linux/amd64
```
To retrieve only the predicate body:
```console
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.5 \
--predicate \
<your-org-namespace>/dhi-<image>:<tag> --platform <platform>
```
For example:
```console
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.5 \
--predicate \
docs/dhi-python:3.13 --platform linux/amd64
```
### Validate and show the equivalent cosign command
You can use the `--verify` flag to validate the attestation and print the corresponding [cosign](https://docs.sigstore.dev/) command:
```console
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.5 \
--verify \
<your-org-namespace>/dhi-<image>:<tag> --platform <platform>
```
For example:
```console
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.5 \
--verify \
docs/dhi-python:3.13 --platform linux/amd64
```
If verification succeeds, Docker Scout prints the full `cosign verify` command.
Example output:
```console
v SBOM obtained from attestation, 101 packages found
v Provenance obtained from attestation
v cosign verify registry.scout.docker.com/docker/dhi-python@sha256:b5418da893ada6272add2268573a3d5f595b5c486fb7ec58370a93217a9785ae \
--key https://registry.scout.docker.com/keyring/dhi/latest.pub --experimental-oci11
...
```
## Available DHI attestations
See [available
attestations](../core-concepts/attestations.md#available-attestations) for list
of attestations available for each DHI.
## Explore attestations on Docker Hub
You can also browse attestations visually when [exploring an image
variant](./explore.md#view-image-variant-details). The **Attestations** section
lists each available attestation with its:
- Type (e.g. SBOM, VEX)
- Predicate type URI
- Digest reference for use with `cosign`
These attestations are generated and signed automatically as part of the Docker
Hardened Image build process.
content/manuals/dhi/images/dhi-catalog.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 44 KiB

content/manuals/dhi/images/dhi-mirror-button.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 96 KiB

content/manuals/dhi/images/dhi-mirror-screen.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 57 KiB

content/manuals/dhi/images/dhi-python-mirror.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 50 KiB

content/manuals/dhi/images/dhi-python-search.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 97 KiB

content/manuals/dhi/troubleshoot.md
+81
View File
@@ -0,0 +1,81 @@
---
title: Troubleshoot
description: Resolve common issues when building, running, or debugging Docker Hardened Images, such as non-root behavior, missing shells, and port access.
weight: 40
tags: [Troubleshooting]
keywords: troubleshoot hardened image, docker debug container, non-root permission issue, missing shell error, no package manager
---
The following are common issues you may encounter while migrating to or using
Docker Hardened Images (DHIs), along with recommended solutions.
## General debugging
Docker Hardened Images are optimized for security and runtime performance. As
such, they typically don't include a shell or standard debugging tools. The
recommended way to troubleshoot containers built on DHIs is by using [Docker
Debug](./how-to/debug.md).
Docker Debug allows you to:
- Attach a temporary debug container to your existing container.
- Use a shell and familiar tools such as `curl`, `ps`, `netstat`, and `strace`.
- Install additional tools as needed in a writable, ephemeral layer that
disappears after the session.
## Permissions
DHIs run as a nonroot user by default for enhanced security. This can result in
permission issues when accessing files or directories. Ensure your application
files and runtime directories are owned by the expected UID/GID or have
appropriate permissions.
To find out which user a DHI runs as, check the repository page for the image on
Docker Hub. See [View image variant
details](./how-to/explore.md#view-image-variant-details) for more information.
## Privileged ports
Nonroot containers cannot bind to ports below 1024 by default. This is enforced
by both the container runtime and the kernel (especially in Kubernetes and
Docker Engine < 20.10).
Inside the container, configure your application to listen on an unprivileged
port (1025 or higher). For example `docker run -p 80:8080 my-image` maps
port 8080 in the container to port 80 on the host, allowing you to access it
without needing root privileges.
## No shell
Runtime DHIs omit interactive shells like `sh` or `bash`. If your build or
tooling assumes a shell is present (e.g., for `RUN` instructions), use a `dev`
variant of the image in an earlier build stage and copy the final artifact into
the runtime image.
To find out which shell, if any, a DHI has, check the repository page for the
image on Docker Hub. See [View image variant
details](./how-to/explore.md#view-image-variant-details) for more information.
Also, use [Docker Debug](./how-to/debug.md) when you need shell
access to a running container.
## Entry point differences
DHIs may define different entry points compared to Docker Official Images (DOIs)
or other community images.
To find out the ENTRYPOINT or CMD for a DHI, check the repository page for the
image on Docker Hub. See [View image variant
details](./how-to/explore.md#view-image-variant-details) for more information.
## No package manager
Runtime Docker Hardened Images are stripped down for security and minimal attack
surface. As a result, they don't include a package manager such as `apk` or
`apt`. This means you can't install additional software directly in the runtime
image.
If your build or application setup requires installing packages (for example, to
compile code, install runtime dependencies, or add diagnostic tools), use a `dev`
variant of the image in a build stage. Then, copy only the necessary artifacts
into the final runtime image.
data/summary.yaml
+4 -2
View File
@@ -153,14 +153,16 @@ Docker Desktop CLI logs:
requires: Docker Desktop 4.39 and later
Docker GitHub Copilot:
availability: Early Access
Docker Hardened Images:
subscription: [Docker Hardened Images]
Docker Init:
requires: Docker Desktop [4.27](/manuals/desktop/release-notes.md#4270) and later
Docker Model Runner:
availability: Beta
requires: Docker Engine or Docker Desktop (Windows) 4.41+ or Docker Desktop (MacOS) 4.40+
for: Docker Desktop for Mac with Apple Silicon or Windows with NVIDIA GPUs
Docker Projects:
availability: Beta
Docker Init:
requires: Docker Desktop [4.27](/manuals/desktop/release-notes.md#4270) and later
Docker Scout exceptions:
availability: Experimental
requires: Docker Scout CLI [1.15.0](/manuals/scout/release-notes/cli.md#1150) and later
layouts/partials/icon.html
+20 -7
View File
@@ -1,8 +1,21 @@
{{- $svg := resources.Get (fmt.Printf "icons/%s-fill.svg" .) }}
{{- if not $svg }}
{{- errorf "Failed to get icon: %v\n\n" . }}
{{ end }}
{{- if not $svg.Content }}
{{- errorf "Failed to get icon: %v\n\n" . }}
{{- $icon := . -}}
{{- $svgPath := "" -}}
{{- if or (strings.HasSuffix $icon ".svg") (strings.HasPrefix $icon "icons/") }}
{{- $svgPath = $icon -}}
{{- else }}
{{- $svgPath = printf "icons/%s-fill.svg" $icon -}}
{{- end }}
{{- safe.HTML $svg.Content -}}
{{- $svg := resources.Get $svgPath -}}
{{- if not $svg }}
{{- errorf "Failed to get icon: %v (resolved path: %s)\n\n" $icon $svgPath }}
{{- end }}
{{- if not $svg.Content }}
{{- errorf "Empty content for icon: %v (resolved path: %s)\n\n" $icon $svgPath }}
{{- end }}
{{- $svg.Content | safeHTML -}}
layouts/shortcodes/summary-bar.html
+1
View File
@@ -10,6 +10,7 @@
"Pro" "person_add"
"Personal" "person"
"Available to all" "public"
"Docker Hardened Images" "/icons/dhi.svg"
}}
{{ $availabilityIcons := dict
"Experimental" "science"