diff --git a/content/guides/dhi-backstage.md b/content/guides/dhi-backstage.md index ec1b7e06049f..fa2626fdd880 100644 --- a/content/guides/dhi-backstage.md +++ b/content/guides/dhi-backstage.md @@ -430,7 +430,7 @@ docker exec -it sh OCI runtime exec failed: exec failed: unable to start container process: ... ``` -Use [Docker Debug](/dhi/troubleshoot/#general-debugging) if you need to troubleshoot a running distroless container. +Use [Docker Debug](/dhi/how-to/troubleshoot/#general-debugging) if you need to troubleshoot a running distroless container. > [!NOTE] > @@ -479,5 +479,5 @@ Different scanners detect different issues. Running all three gives you the most - [Create and build a DHI](/dhi/how-to/build/) — learn how to write a DHI definition file, build images locally. - [Use the DHI CLI](/dhi/how-to/cli/) — manage DHI images, mirrors, and customizations from the command line. - [Migrate to DHI](/dhi/migration/) — for applications that work with standard DHI images without additional packages. -- [Compare images](/dhi/how-to/explore/#compare-and-evaluate-images) — evaluate security improvements between your original and hardened images. -- [Docker Debug](/dhi/troubleshoot/#general-debugging) — troubleshoot distroless containers that have no shell. +- [Compare images](/dhi/how-to/search-evaluate/#compare-and-evaluate-images) — evaluate security improvements between your original and hardened images. +- [Docker Debug](/dhi/how-to/troubleshoot/#general-debugging) — troubleshoot distroless containers that have no shell. diff --git a/content/guides/dhi-openshift.md b/content/guides/dhi-openshift.md index 2885d0985ab0..c588f81d00a0 100644 --- a/content/guides/dhi-openshift.md +++ b/content/guides/dhi-openshift.md @@ -620,6 +620,6 @@ and use `COPY --chown` to transfer results. - [Use an image in Kubernetes](/dhi/how-to/k8s/) — general DHI Kubernetes deployment guide. - [Customize an image](/dhi/how-to/customize/) — add packages to DHI images using Enterprise customization. -- [Debug a container](/dhi/troubleshoot/#general-debugging) — troubleshoot distroless containers with Docker Debug (local development). +- [Debug a container](/dhi/how-to/troubleshoot/#general-debugging) — troubleshoot distroless containers with Docker Debug (local development). - [Managing SCCs](https://docs.openshift.com/container-platform/4.14/authentication/managing-security-context-constraints.html) — Red Hat’s reference documentation on Security Context Constraints. - [Creating images for OpenShift](https://docs.openshift.com/container-platform/4.14/openshift_images/create-images.html) — Red Hat’s guidelines for building OpenShift-compatible container images. diff --git a/content/guides/dhi-vex-walkthrough.md b/content/guides/dhi-vex-walkthrough.md index 9f113265173b..89ceed00b706 100644 --- a/content/guides/dhi-vex-walkthrough.md +++ b/content/guides/dhi-vex-walkthrough.md @@ -282,7 +282,7 @@ The justification codes have precise meanings: that addresses the CVE in this image. For the full list of justification codes, see [VEX status -reference](/manuals/dhi/core-concepts/vex.md#not_affected-justification-codes). +reference](/manuals/dhi/explore/security-concepts/vex.md#not_affected-justification-codes). Every suppression is documented, auditable, and verifiable with any VEX-enabled scanner. @@ -357,7 +357,7 @@ $ curl -s https://raw.githubusercontent.com/docker-hardened-images/advisories/ma ``` For status definitions and justification codes, see the [VEX status -reference](/manuals/dhi/core-concepts/vex.md#vex-status-reference). +reference](/manuals/dhi/explore/security-concepts/vex.md#vex-status-reference). ## What's next @@ -369,7 +369,7 @@ reference](/manuals/dhi/core-concepts/vex.md#vex-status-reference). VEX](/manuals/scout/how-tos/create-exceptions-vex.md). - VEX status reference: For status definitions, justification codes, and why DHI does not use `fixed`, see [Vulnerability Exploitability eXchange - (VEX)](/manuals/dhi/core-concepts/vex.md#vex-status-reference). + (VEX)](/manuals/dhi/explore/security-concepts/vex.md#vex-status-reference). - Browse the VEX feed directly: The raw VEX data is published at [github.com/docker-hardened-images/advisories](https://github.com/docker-hardened-images/advisories/tree/main/vex), organized by image name. diff --git a/content/manuals/dhi/_index.md b/content/manuals/dhi/_index.md index 274c2e2e71ca..0e7d4386c7ef 100644 --- a/content/manuals/dhi/_index.md +++ b/content/manuals/dhi/_index.md @@ -2,6 +2,14 @@ title: Docker Hardened Images description: Secure, minimal, and production-ready base images weight: 8 +aliases: + - /dhi/features/ + - /dhi/features/secure/ + - /dhi/features/integration/ + - /dhi/features/support/ + - /dhi/features/patching/ + - /dhi/features/flexible/ + - /dhi/features/helm/ params: sidebar: group: Supply chain security @@ -14,24 +22,20 @@ params: description: Learn what Docker Hardened Images are, how they're built, and what sets them apart from typical base images. icon: information-circle link: /dhi/explore/ - - title: Features - description: Discover the security, compliance, and enterprise-readiness features built into Docker Hardened Images. - icon: lock-closed - link: /dhi/features/ - title: How-tos description: Step-by-step guides for using, verifying, scanning, and migrating to Docker Hardened Images. icon: play link: /dhi/how-to/ - - title: Core concepts + - title: Security concepts description: Understand the secure supply chain principles that make Docker Hardened Images production-ready. icon: clipboard-document-check - link: /dhi/core-concepts/ - - title: Troubleshoot - description: Resolve common issues with building, running, or debugging Docker Hardened Images. - icon: question-mark-circle - link: /dhi/troubleshoot/ - - title: Additional resources - description: Guides, Docker Hub catalog, GitHub repositories, and more. + link: /dhi/explore/security-concepts/ + - title: Tools + description: Browse and manage Docker Hardened Images using Docker Hub, the CLI, MCP server, or Terraform. + icon: wrench-screwdriver + link: /dhi/tools/ + - title: Resources and feedback + description: Guides, GitHub repositories, community channels, and how to give feedback. icon: link link: /dhi/resources/ - title: Release notes @@ -68,9 +72,48 @@ DHI is available in the following three subscriptions. For pricing and more details, see the [Docker Hardened Images subscription comparison](https://www.docker.com/products/hardened-images/#compare). +## Community features + +DHI's core features are free to use, share, and build on under Apache 2.0. + +- [Near-zero CVEs](/dhi/explore/security-concepts/cves/): continuously scanned and patched + to maintain minimal known vulnerabilities +- [Distroless variants](/dhi/explore/security-concepts/distroless/): remove unnecessary + components, reducing attack surface by up to 95% +- Non-root execution: containers run as non-root by default +- [Hardened system packages](/dhi/how-to/hardened-packages/): system packages + built from source, cryptographically signed, and verified by Docker +- [SLSA Build Level 3 provenance](/dhi/explore/security-concepts/slsa/), [signed + SBOMs](/dhi/explore/security-concepts/sbom/), [VEX statements](/dhi/explore/security-concepts/vex/), + and [cryptographic signatures](/dhi/explore/security-concepts/signatures/) on every image +- Built on Alpine and Debian with [glibc and musl + variants](/dhi/explore/security-concepts/glibc-musl/); dev and runtime image variants + available +- Works with existing Docker workflows, CI/CD pipelines, and tools with no + retooling required +- [Helm charts](/dhi/how-to/helm/): Docker-provided charts built from upstream + sources, tested for compatibility with DHI, and available as OCI artifacts in + the DHI catalog; include SLSA Level 3 provenance, SBOMs, and cryptographic + signing + +## Select and Enterprise features + +For organizations with strict security or compliance requirements: + +- [7-day SLA](https://docs.docker.com/go/dhi-sla/) for critical and high + severity CVE remediation +- [FIPS-enabled](/dhi/explore/security-concepts/fips/) and + [STIG-ready](/dhi/explore/security-concepts/stig/) compliance variants +- [Customization](/dhi/how-to/customize/): add packages, tools, certificates, + and configurations (up to 5 with Select, unlimited with Enterprise) +- [Enterprise package repository](/dhi/how-to/hardened-packages/) access and + full catalog access (Enterprise) +- Extended Lifecycle Support: post-EOL security patches, updated SBOMs, + provenance, and signing (Enterprise add-on) + +## Get started + 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" ->}} +{{< grid items="grid_sections" >}} diff --git a/content/manuals/dhi/explore/_index.md b/content/manuals/dhi/explore/_index.md index bc5ade0beecc..8336abaa8159 100644 --- a/content/manuals/dhi/explore/_index.md +++ b/content/manuals/dhi/explore/_index.md @@ -33,10 +33,11 @@ params: description: Understand Docker's role and your responsibilities when using Docker Hardened Images as part of your secure software supply chain. icon: user-group link: /dhi/explore/responsibility/ - - title: Give feedback - icon: question-mark-circle - description: Docker welcomes all contributions and feedback. - link: /dhi/explore/feedback + - title: Security concepts + description: Learn the core concepts behind Docker Hardened Images — signed attestations, immutable digests, SLSA, VEX, and more. + icon: clipboard-document-check + link: /dhi/explore/security-concepts/ + aliases: - /dhi/about/ --- @@ -48,8 +49,7 @@ existing Docker-based workflows with little to no retooling required. This section helps you understand what Docker Hardened Images are, how they're built and tested, the different types available, and how responsibility is -shared between Docker and you as a user. For a complete list of DHI features and -capabilities, see [Features](/dhi/features/). +shared between Docker and you as a user. ## Learn more about Docker Hardened Images diff --git a/content/manuals/dhi/explore/available.md b/content/manuals/dhi/explore/available.md index e8540691d8f1..3db9c8c5c539 100644 --- a/content/manuals/dhi/explore/available.md +++ b/content/manuals/dhi/explore/available.md @@ -12,7 +12,7 @@ Docker Hardened Images (DHI) is a comprehensive catalog of security-hardened container images built to meet diverse development and production needs. -You can explore the DHI catalog on [Docker Hub](https://hub.docker.com/hardened-images/catalog) or use the [DHI CLI](../how-to/cli.md) to browse +You can explore the DHI catalog on [Docker Hub](https://hub.docker.com/hardened-images/catalog) or use the [DHI CLI](../tools/cli.md) to browse available images, tags, and metadata from the command line. ## Framework and application images @@ -85,7 +85,7 @@ For example, you might find tags like the following in a DHI repository: Some Docker Hardened Images include a `-fips` variant. These variants use cryptographic modules that have been validated under [FIPS -140](../core-concepts/fips.md), a U.S. government standard for secure +140](security-concepts/fips.md), a U.S. government standard for secure cryptographic operations. FIPS variants are designed to help organizations meet regulatory and compliance diff --git a/content/manuals/dhi/explore/build-process.md b/content/manuals/dhi/explore/build-process.md index 01cd6541eb7c..e2bcd2930ee4 100644 --- a/content/manuals/dhi/explore/build-process.md +++ b/content/manuals/dhi/explore/build-process.md @@ -35,7 +35,7 @@ contents, build pipeline steps, security configurations, and runtime settings. Every Docker Hardened Image includes a SLSA Build Level 3 attestation that provides verifiable build provenance. For details on SLSA attestations and how to -verify them, see [SLSA](../core-concepts/slsa.md). +verify them, see [SLSA](security-concepts/slsa.md). ## Build triggers diff --git a/content/manuals/dhi/explore/feedback.md b/content/manuals/dhi/explore/feedback.md deleted file mode 100644 index 48fa91833689..000000000000 --- a/content/manuals/dhi/explore/feedback.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: Give feedback -linkTitle: Feedback -description: How to interact with the DHI team -keywords: software supply chain security, feedback, bugs, discussion, questions -weight: 999 -aliases: - - /dhi/about/feedback/ ---- - -Committed to maintaining the quality, security, and reliability of the Docker Hardened Images (DHI) -a repository has been created as a point of contact to encourage the community to collaborate -in improving the Hardened Images ecosystem. - -## Questions or discussions - -You can use the [GitHub Discussions -board](https://github.com/orgs/docker-hardened-images/discussions) to engage -with the DHI team for: - -- General questions about DHIs -- Best practices and recommendations -- Security tips and advice -- Show and tell your implementations -- Community announcements - -## Reporting bugs or issues - -You can [open a new issue](https://github.com/docker-hardened-images/catalog/issues) for topics such as: - -- Bug reports -- Feature requests -- Documentation improvements -- Security vulnerabilities (see security policy) - -It's encouraged to first search existing issues to see if it’s already been reported. -The DHI team reviews reports regularly and appreciates clear, actionable feedback. - -## Responsible security disclosure - -It is forbidden to post details of vulnerabilities before coordinated disclosure and resolution. - -If you discover a security vulnerability, report it responsibly by following Docker’s [security disclosure](https://www.docker.com/trust/vulnerability-disclosure-policy/). diff --git a/content/manuals/dhi/explore/responsibility.md b/content/manuals/dhi/explore/responsibility.md index e4e816dd0321..92663ce716cf 100644 --- a/content/manuals/dhi/explore/responsibility.md +++ b/content/manuals/dhi/explore/responsibility.md @@ -50,7 +50,7 @@ securely. 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. + attestation](security-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. diff --git a/content/manuals/dhi/explore/scanner-integrations.md b/content/manuals/dhi/explore/scanner-integrations.md index 5cb23b92afe9..a2928ccde516 100644 --- a/content/manuals/dhi/explore/scanner-integrations.md +++ b/content/manuals/dhi/explore/scanner-integrations.md @@ -39,7 +39,7 @@ the minimum requirements for VEX defined by CISA (Cybersecurity and Infrastructure Security Agency), the U.S. government agency responsible for cybersecurity guidance. These attestations document which vulnerabilities don't apply to the image and why, helping you focus on real risks. To understand what -VEX is and how it works, see the [VEX core concept](/manuals/dhi/core-concepts/vex.md). +VEX is and how it works, see the [VEX core concept](/manuals/dhi/explore/security-concepts/vex.md). Because OpenVEX is an open standard with government backing, it has strong industry momentum and any tool can implement it without vendor-specific diff --git a/content/manuals/dhi/core-concepts/_index.md b/content/manuals/dhi/explore/security-concepts/_index.md similarity index 83% rename from content/manuals/dhi/core-concepts/_index.md rename to content/manuals/dhi/explore/security-concepts/_index.md index 677498cdf0fd..03b7c1e1c6bd 100644 --- a/content/manuals/dhi/core-concepts/_index.md +++ b/content/manuals/dhi/explore/security-concepts/_index.md @@ -1,85 +1,88 @@ --- -title: Core concepts +aliases: + - /dhi/core-concepts/ +title: Security concepts +linkTitle: Security concepts description: Learn the core concepts behind Docker Hardened Images, including security metadata, vulnerability management, image structure, and verification. -weight: 30 +weight: 60 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: clipboard-document-list - link: /dhi/core-concepts/attestations/ + link: /dhi/explore/security-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-bullet - link: /dhi/core-concepts/sbom/ + link: /dhi/explore/security-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: clipboard-document-check - link: /dhi/core-concepts/slsa/ + link: /dhi/explore/security-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: pencil-square - link: /dhi/core-concepts/provenance/ + link: /dhi/explore/security-concepts/provenance/ grid_concepts_compliance: - title: FIPS description: Learn how Docker Hardened Images support FIPS 140 by using validated cryptographic modules and providing signed attestations for compliance audits. icon: check-badge - link: /dhi/core-concepts/fips/ + link: /dhi/explore/security-concepts/fips/ - title: STIG description: Learn how Docker Hardened Images provide STIG-ready container images with verifiable security scan attestations for government and enterprise compliance requirements. icon: shield-check - link: /dhi/core-concepts/stig/ + link: /dhi/explore/security-concepts/stig/ - title: CIS Benchmarks description: Learn how Docker Hardened Images help you meet Center for Internet Security (CIS) Docker Benchmark requirements for secure container configuration and deployment. icon: check-circle - link: /dhi/core-concepts/cis/ + link: /dhi/explore/security-concepts/cis/ 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: exclamation-circle - link: /dhi/core-concepts/cves/ + link: /dhi/explore/security-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: exclamation-triangle - link: /dhi/core-concepts/vex/ + link: /dhi/explore/security-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-check - link: /dhi/core-concepts/sscs/ + link: /dhi/explore/security-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: wrench-screwdriver - link: /dhi/core-concepts/ssdlc/ + link: /dhi/explore/security-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: squares-2x2 - link: /dhi/core-concepts/distroless/ + link: /dhi/explore/security-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: arrows-up-down - link: /dhi/core-concepts/glibc-musl/ + link: /dhi/explore/security-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: minus-circle - link: /dhi/core-concepts/immutability/ + link: /dhi/explore/security-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: shield-check - link: /dhi/core-concepts/hardening/ + link: /dhi/explore/security-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: finger-print - link: /dhi/core-concepts/digests/ + link: /dhi/explore/security-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/ + link: /dhi/explore/security-concepts/signatures/ --- Docker Hardened Images (DHIs) are built on a foundation of secure software diff --git a/content/manuals/dhi/core-concepts/attestations.md b/content/manuals/dhi/explore/security-concepts/attestations.md similarity index 95% rename from content/manuals/dhi/core-concepts/attestations.md rename to content/manuals/dhi/explore/security-concepts/attestations.md index c9a3b47e5d56..5e4ffbef6c37 100644 --- a/content/manuals/dhi/core-concepts/attestations.md +++ b/content/manuals/dhi/explore/security-concepts/attestations.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/attestations/ 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 @@ -52,7 +54,7 @@ to: Attestations are automatically published and associated with each DHI and chart. They can be inspected using tools like [Docker -Scout](../how-to/verify.md) or +Scout](../../how-to/verify.md) or [Cosign](https://docs.sigstore.dev/cosign/overview), and are consumable by CI/CD tooling or security platforms. @@ -69,7 +71,7 @@ use Docker Scout: $ docker scout attest list dhi.io/: ``` -For more details, see [Verify image attestations](../how-to/verify.md#verify-image-attestations). +For more details, see [Verify image attestations](../../how-to/verify.md#verify-image-attestations). | Attestation type | Description | |----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -81,7 +83,7 @@ For more details, see [Verify image attestations](../how-to/verify.md#verify-ima | Scout SBOM | An SBOM generated and signed by Docker Scout, including additional Docker-specific metadata. | | Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys. | | Tests | A record of automated tests run against the image, such as functional checks or validation scripts. | -| Virus scan | Results of antivirus scans performed on the image layers. For details, see [Malware scanning](../explore/malware-scanning.md). | +| Virus scan | Results of antivirus scans performed on the image layers. For details, see [Malware scanning](../malware-scanning.md). | | CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data. | | SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the image was built, including build tool, parameters, and source. | | SLSA verification summary | A summary attestation indicating the image's compliance with SLSA requirements. | @@ -102,7 +104,7 @@ used. You can extract package information from an image's attestations and then retrieve the package's own attestations recursively. For detailed instructions on how to access and verify package attestations, see -[Package attestations](../how-to/hardened-packages.md#package-attestations). +[Package attestations](../../how-to/hardened-packages.md#package-attestations). ## Helm chart attestations @@ -118,7 +120,7 @@ type URIs for these attestations, use Docker Scout: $ docker scout attest list dhi.io/: ``` -For more details, see [Verify Helm chart attestations](../how-to/verify.md#verify-helm-chart-attestations-with-docker-scout). +For more details, see [Verify Helm chart attestations](../../how-to/verify.md#verify-helm-chart-attestations-with-docker-scout). | Attestation type | Description | |----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -128,7 +130,7 @@ For more details, see [Verify Helm chart attestations](../how-to/verify.md#verif | Scout SBOM | An SBOM generated and signed by Docker Scout, including the chart and container images it references, with additional Docker-specific metadata. | | Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys, in the chart package. | | Tests | A record of automated tests run against the chart to validate functionality and compatibility with referenced images. | -| Virus scan | Results of antivirus scans performed on the chart package. For details, see [Malware scanning](../explore/malware-scanning.md). | +| Virus scan | Results of antivirus scans performed on the chart package. For details, see [Malware scanning](../malware-scanning.md). | | CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data for the chart's referenced images. | | SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the chart was built, including build tool, source repository, referenced images, and build materials. | | SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, listing the chart and all container images and tools it references. | @@ -136,7 +138,7 @@ For more details, see [Verify Helm chart attestations](../how-to/verify.md#verif ## View and verify attestations To view and verify attestations, see [Verify a Docker Hardened -Image](../how-to/verify.md). +Image](../../how-to/verify.md). ## Add your own attestations diff --git a/content/manuals/dhi/core-concepts/cis.md b/content/manuals/dhi/explore/security-concepts/cis.md similarity index 91% rename from content/manuals/dhi/core-concepts/cis.md rename to content/manuals/dhi/explore/security-concepts/cis.md index 0298a140655e..a4aa644c4aa4 100644 --- a/content/manuals/dhi/core-concepts/cis.md +++ b/content/manuals/dhi/explore/security-concepts/cis.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/cis/ title: CIS Benchmark description: Learn how Docker Hardened Images comply with the CIS Docker Benchmark to help organizations harden container images for secure deployments. keywords: docker cis benchmark, cis docker compliance, cis docker images, docker hardened images, secure container images @@ -31,7 +33,7 @@ configuration. CIS-compliant DHIs are compliant with all controls in Section 4, with the sole exception of the control requiring Docker Content Trust (DCT), which [Docker officially retired](https://www.docker.com/blog/retiring-docker-content-trust/). -Instead, DHIs are [signed](/manuals/dhi/core-concepts/signatures.md) using +Instead, DHIs are [signed](/manuals/dhi/explore/security-concepts/signatures.md) using Cosign, providing an even higher level of authenticity and integrity. By starting from a CIS-compliant DHI, teams can adopt image-level best practices from the benchmark more quickly and confidently. @@ -46,7 +48,7 @@ from the benchmark more quickly and confidently. ## Identify CIS-compliant images CIS-compliant images are labeled as **CIS** in the Docker Hardened Images catalog. -To find them, [search the catalog](../how-to/explore.md) and look for the **CIS** +To find them, [search the catalog](../../how-to/search-evaluate.md) and look for the **CIS** designation on individual listings. ## Get the benchmark diff --git a/content/manuals/dhi/core-concepts/cves.md b/content/manuals/dhi/explore/security-concepts/cves.md similarity index 99% rename from content/manuals/dhi/core-concepts/cves.md rename to content/manuals/dhi/explore/security-concepts/cves.md index da7a1140cb6d..1d7f0576a22e 100644 --- a/content/manuals/dhi/core-concepts/cves.md +++ b/content/manuals/dhi/explore/security-concepts/cves.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/cves/ 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. diff --git a/content/manuals/dhi/core-concepts/digests.md b/content/manuals/dhi/explore/security-concepts/digests.md similarity index 99% rename from content/manuals/dhi/core-concepts/digests.md rename to content/manuals/dhi/explore/security-concepts/digests.md index 27bdc244b45d..fe31aafd7c28 100644 --- a/content/manuals/dhi/core-concepts/digests.md +++ b/content/manuals/dhi/explore/security-concepts/digests.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/digests/ title: Image 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 diff --git a/content/manuals/dhi/core-concepts/distroless.md b/content/manuals/dhi/explore/security-concepts/distroless.md similarity index 95% rename from content/manuals/dhi/core-concepts/distroless.md rename to content/manuals/dhi/explore/security-concepts/distroless.md index c5b8a5d0b698..e886b5e6e388 100644 --- a/content/manuals/dhi/core-concepts/distroless.md +++ b/content/manuals/dhi/explore/security-concepts/distroless.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/distroless/ 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. @@ -11,9 +13,9 @@ 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. [Docker Official -Images](../../docker-hub/image-library/trusted-content.md#docker-official-images) +Images](../../../docker-hub/image-library/trusted-content.md#docker-official-images) and [Docker Verified Publisher -Images](../../docker-hub/image-library/trusted-content.md#verified-publisher-images) +Images](../../../docker-hub/image-library/trusted-content.md#verified-publisher-images) follow similar best practices for minimalism and security but may not be as stripped down to ensure compatibility with a wider range of use cases. diff --git a/content/manuals/dhi/core-concepts/fips.md b/content/manuals/dhi/explore/security-concepts/fips.md similarity index 96% rename from content/manuals/dhi/core-concepts/fips.md rename to content/manuals/dhi/explore/security-concepts/fips.md index 3e425e645513..1929b5959dc0 100644 --- a/content/manuals/dhi/core-concepts/fips.md +++ b/content/manuals/dhi/explore/security-concepts/fips.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/fips/ title: FIPS description: Learn how Docker Hardened Images support FIPS 140 through validated cryptographic modules to help organizations meet compliance requirements. keywords: docker fips, fips 140 images, fips docker images, docker compliance, secure container images @@ -66,7 +68,7 @@ compliance requirements by incorporating components that meet the standard. Docker Hardened Images that support FIPS are marked as **FIPS** compliant in the Docker Hardened Images catalog. -To find DHI repositories with FIPS image variants, [search the catalog](../how-to/explore.md) and: +To find DHI repositories with FIPS image variants, [search the catalog](../../how-to/search-evaluate.md) and: - Use the **FIPS** filter on the catalog page - Look for **FIPS** compliant on individual image listings @@ -77,7 +79,7 @@ ending with `-fips`, such as `3.13-fips`. ## Use a FIPS variant -To use a FIPS variant, you must [mirror](../how-to/mirror.md) the repository +To use a FIPS variant, you must [mirror](../../how-to/mirror.md) the repository and then pull the FIPS image from your mirrored repository. ## View the FIPS attestation diff --git a/content/manuals/dhi/core-concepts/glibc-musl.md b/content/manuals/dhi/explore/security-concepts/glibc-musl.md similarity index 98% rename from content/manuals/dhi/core-concepts/glibc-musl.md rename to content/manuals/dhi/explore/security-concepts/glibc-musl.md index 1ef7cdfa45f4..9a6a865c32b5 100644 --- a/content/manuals/dhi/core-concepts/glibc-musl.md +++ b/content/manuals/dhi/explore/security-concepts/glibc-musl.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/glibc-musl/ 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. diff --git a/content/manuals/dhi/core-concepts/hardening.md b/content/manuals/dhi/explore/security-concepts/hardening.md similarity index 95% rename from content/manuals/dhi/core-concepts/hardening.md rename to content/manuals/dhi/explore/security-concepts/hardening.md index 105b527eff66..ddf6c7fb7067 100644 --- a/content/manuals/dhi/core-concepts/hardening.md +++ b/content/manuals/dhi/explore/security-concepts/hardening.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/hardening/ 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. @@ -17,9 +19,9 @@ 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. While [Docker Official -Images](../../docker-hub/image-library/trusted-content.md#docker-official-images) +Images](../../../docker-hub/image-library/trusted-content.md#docker-official-images) and [Docker Verified Publisher -Images](../../docker-hub/image-library/trusted-content.md#verified-publisher-images) +Images](../../../docker-hub/image-library/trusted-content.md#verified-publisher-images) follow best practices for security, they may not be as hardened as Docker Hardened Images, as they are designed to support a broader range of use cases. diff --git a/content/manuals/dhi/core-concepts/immutability.md b/content/manuals/dhi/explore/security-concepts/immutability.md similarity index 98% rename from content/manuals/dhi/core-concepts/immutability.md rename to content/manuals/dhi/explore/security-concepts/immutability.md index c6cfb1144684..f03f3261fc6c 100644 --- a/content/manuals/dhi/core-concepts/immutability.md +++ b/content/manuals/dhi/explore/security-concepts/immutability.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/immutability/ 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. diff --git a/content/manuals/dhi/core-concepts/provenance.md b/content/manuals/dhi/explore/security-concepts/provenance.md similarity index 98% rename from content/manuals/dhi/core-concepts/provenance.md rename to content/manuals/dhi/explore/security-concepts/provenance.md index 5c8adcb425e4..7db3c9e72917 100644 --- a/content/manuals/dhi/core-concepts/provenance.md +++ b/content/manuals/dhi/explore/security-concepts/provenance.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/provenance/ 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 diff --git a/content/manuals/dhi/core-concepts/sbom.md b/content/manuals/dhi/explore/security-concepts/sbom.md similarity index 97% rename from content/manuals/dhi/core-concepts/sbom.md rename to content/manuals/dhi/explore/security-concepts/sbom.md index 40b99f153b11..07360ee072d6 100644 --- a/content/manuals/dhi/core-concepts/sbom.md +++ b/content/manuals/dhi/explore/security-concepts/sbom.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/sbom/ 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. @@ -91,4 +93,4 @@ $ docker scout attest get dhi.io/node:20.19-debian12 \ For more details about SBOM attestations and Docker Build, see [SBOM attestations](/build/metadata/attestations/sbom/). -To learn more about Docker Scout and working with SBOMs, see [Docker Scout SBOMs](../../scout/how-tos/view-create-sboms.md). \ No newline at end of file +To learn more about Docker Scout and working with SBOMs, see [Docker Scout SBOMs](../../../scout/how-tos/view-create-sboms.md). \ No newline at end of file diff --git a/content/manuals/dhi/core-concepts/signatures.md b/content/manuals/dhi/explore/security-concepts/signatures.md similarity index 98% rename from content/manuals/dhi/core-concepts/signatures.md rename to content/manuals/dhi/explore/security-concepts/signatures.md index 6922f3507cf2..d766d850ae2d 100644 --- a/content/manuals/dhi/core-concepts/signatures.md +++ b/content/manuals/dhi/explore/security-concepts/signatures.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/signatures/ 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 diff --git a/content/manuals/dhi/core-concepts/slsa.md b/content/manuals/dhi/explore/security-concepts/slsa.md similarity index 99% rename from content/manuals/dhi/core-concepts/slsa.md rename to content/manuals/dhi/explore/security-concepts/slsa.md index ad4b254bdab7..303da61f8ad0 100644 --- a/content/manuals/dhi/core-concepts/slsa.md +++ b/content/manuals/dhi/explore/security-concepts/slsa.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/slsa/ 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. diff --git a/content/manuals/dhi/core-concepts/sscs.md b/content/manuals/dhi/explore/security-concepts/sscs.md similarity index 98% rename from content/manuals/dhi/core-concepts/sscs.md rename to content/manuals/dhi/explore/security-concepts/sscs.md index 8606b6c377ba..fab3f1dafe5c 100644 --- a/content/manuals/dhi/core-concepts/sscs.md +++ b/content/manuals/dhi/explore/security-concepts/sscs.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/sscs/ 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. diff --git a/content/manuals/dhi/core-concepts/ssdlc.md b/content/manuals/dhi/explore/security-concepts/ssdlc.md similarity index 97% rename from content/manuals/dhi/core-concepts/ssdlc.md rename to content/manuals/dhi/explore/security-concepts/ssdlc.md index c1d2c864c166..88221ae0f3fd 100644 --- a/content/manuals/dhi/core-concepts/ssdlc.md +++ b/content/manuals/dhi/explore/security-concepts/ssdlc.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/ssdlc/ 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. @@ -37,7 +39,7 @@ 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/), and [Docker -Scout](../../../manuals/scout/_index.md), teams can add security without losing +Scout](../../../scout/_index.md), teams can add security without losing velocity. ### Plan and design diff --git a/content/manuals/dhi/core-concepts/stig.md b/content/manuals/dhi/explore/security-concepts/stig.md similarity index 95% rename from content/manuals/dhi/core-concepts/stig.md rename to content/manuals/dhi/explore/security-concepts/stig.md index 632654054637..95349728ebc7 100644 --- a/content/manuals/dhi/core-concepts/stig.md +++ b/content/manuals/dhi/explore/security-concepts/stig.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/stig/ title: STIG description: Learn how Docker Hardened Images provide STIG-ready container images with verifiable security scan attestations for government and enterprise compliance requirements. keywords: docker stig, stig-ready images, stig guidance, openscap docker, secure container images @@ -58,7 +60,7 @@ Docker Hardened Images that include STIG scan results are labeled as **STIG** in the Docker Hardened Images catalog. To find DHI repositories with STIG image variants, [explore -images](../how-to/explore.md#image-variants) and: +images](../../tools/hub.md#images-page) and: - Use the **STIG** filter on the catalog page - Look for **STIG** labels on individual image listings @@ -68,13 +70,13 @@ repository, and find images labeled with **STIG** in the **Compliance** column. ## Use a STIG variant -To use a STIG variant, you must [mirror](../how-to/mirror.md) the repository +To use a STIG variant, you must [mirror](../../how-to/mirror.md) the repository and then pull the STIG image from your mirrored repository. ## View and verify STIG scan results Docker provides a signed [STIG scan -attestation](../core-concepts/attestations.md) for each STIG-ready image. +attestation](attestations.md) for each STIG-ready image. These attestations include: - A summary of the scan results, including the number of passed, failed, and not diff --git a/content/manuals/dhi/core-concepts/vex.md b/content/manuals/dhi/explore/security-concepts/vex.md similarity index 98% rename from content/manuals/dhi/core-concepts/vex.md rename to content/manuals/dhi/explore/security-concepts/vex.md index d83f8f991b71..531f90858650 100644 --- a/content/manuals/dhi/core-concepts/vex.md +++ b/content/manuals/dhi/explore/security-concepts/vex.md @@ -1,4 +1,6 @@ --- +aliases: + - /dhi/core-concepts/vex/ 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. diff --git a/content/manuals/dhi/explore/what.md b/content/manuals/dhi/explore/what.md index b834f88113a2..962276f8858e 100644 --- a/content/manuals/dhi/explore/what.md +++ b/content/manuals/dhi/explore/what.md @@ -29,7 +29,8 @@ 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. +needed to run your application securely. For a deeper look at the techniques +involved, see [Base image hardening](security-concepts/hardening.md). ## Benefits of hardened images @@ -55,25 +56,25 @@ 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, + Level 3](security-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, package managers, and debugging tools, [distroless - images](../core-concepts/distroless.md) retain only the minimal OS components + images](security-concepts/distroless.md) retain only the minimal OS components required to run your application. By excluding unnecessary tooling and libraries, they reduce the attack surface by up to 95% and can improve performance and image size. - Continuous maintenance: All DHIs are continuously monitored and updated to - maintain near-zero known exploitable [CVEs](../core-concepts/cves.md), helping + maintain near-zero known exploitable [CVEs](security-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 + - [SBOMs](security-concepts/sbom.md) that show what's in the image + - [VEX documents](security-concepts/vex.md) to identify which vulnerabilities are actually exploitable - - [Build provenance](../core-concepts/provenance.md) that proves how and where + - [Build provenance](security-concepts/provenance.md) that proves how and where the image was built - Compatibility-focused design: Docker Hardened Images provide a minimal runtime diff --git a/content/manuals/dhi/features.md b/content/manuals/dhi/features.md deleted file mode 100644 index f08b4d782414..000000000000 --- a/content/manuals/dhi/features.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: Docker Hardened Images features -linktitle: Features -description: Docker Hardened Images provide total transparency, minimal attack surface, and enterprise-grade security for every application—free and open source. -weight: 5 -aliases: - - /dhi/features/secure/ - - /dhi/features/integration/ - - /dhi/features/support/ - - /dhi/features/patching/ - - /dhi/features/flexible/ - - /dhi/features/helm/ ---- - -Docker Hardened Images (DHI) are minimal, secure, and production-ready container -base and application images maintained by Docker. Designed to reduce -vulnerabilities and simplify compliance, DHI integrates easily into your -existing Docker-based workflows with little to no retooling required. - -DHI provides security for everyone: - -- [DHI Community](#dhi-community-features) provides core security features available to - everyone with no licensing restrictions under Apache 2.0. -- [DHI Select and DHI Enterprise](#dhi-select-and-enterprise-features) add SLA-backed - security updates, FIPS/STIG compliance variants, and customization - capabilities, with DHI Enterprise offering unlimited customization, full - catalog access, and optional Extended Lifecycle Support (ELS) for post-EOL - coverage. - -## DHI Community features - -DHI's core features are open and free to use, share, and build on with no -licensing surprises, backed by an Apache 2.0 license. - -### Security by default - -- Near-zero CVEs: Continuously scanned and patched to maintain minimal known - exploitable vulnerabilities, with no SLA-backed time commitments for DHI Community users -- Minimal attack surface: Distroless variants reduce attack surface by up to 95% by removing unnecessary components -- Non-root execution: Run as non-root by default, following the principle of least privilege -- Transparent vulnerability reporting: Every CVE is visible and assessed using public data—no suppressed feeds or proprietary scoring - -### Hardened system packages - -Docker Hardened Images maintain supply chain integrity throughout the entire -image stack with hardened system packages: - -- Source-built packages: For supported distributions, system packages are built - from source code by Docker -- Cryptographic signatures: Every package is cryptographically signed and verified -- Supply chain security: Eliminates risk from potentially compromised public packages - -Hardened system packages are included in supported distributions of DHI images. -Community users can also configure their package manager to use Docker's public -hardened package repository in their own images for the same packages included -in the base images. See [Use hardened system packages](./how-to/hardened-packages.md) -for details. - -### Total transparency - -Every image includes complete, verifiable security metadata: - -- SLSA Build Level 3 provenance: Verifiable, tamper-resistant builds that meet supply chain security standards -- Signed SBOMs: Complete Software Bill of Materials for every component -- VEX statements: Vulnerability Exploitability eXchange documents provide context about known CVEs -- Cryptographic signatures: All images and metadata are signed for authenticity - -### Built for developers - -- Familiar foundations: Built on Alpine and Debian, requiring minimal changes to adopt -- glibc and musl support: Available in both variants for broad application compatibility -- Development and runtime variants: Use dev images for building, minimal runtime images for production -- Drop-in compatibility: Works seamlessly with existing Docker workflows, CI/CD pipelines, and tools - -### Continuous maintenance - -- Automatic patching: Images are rebuilt and updated when upstream security - patches become available, with no SLA-backed time commitments for DHI - Community users -- Scanner integration: Direct integration with scanners and other security platforms - -### Kubernetes and Helm chart support - -Docker Hardened Image (DHI) charts are Docker-provided Helm charts built from -upstream sources, designed for compatibility with Docker Hardened Images. These -charts are available as OCI artifacts within the DHI catalog on Docker Hub. DHI -charts are robustly tested after building to ensure they work out-of-the-box -with Docker Hardened Images. This removes friction in migration and reduces -developer workload in implementing the charts, ensuring seamless compatibility. - -Like the hardened images, DHI charts incorporate multiple layers of security -metadata to ensure transparency and trust: - -- SLSA Level 3 compliance: Each chart is built with Docker's SLSA Build Level 3 - system, including a detailed build provenance, and 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 referenced within the chart to facilitate - vulnerability management and compliance audits. -- Cryptographic signing: All associated metadata is cryptographically signed by - Docker, ensuring integrity and authenticity. -- Hardened configuration: Charts automatically reference Docker hardened images, - ensuring security in deployments. - -## DHI Select and Enterprise features - -For organizations with strict security requirements, regulatory demands, or -operational needs, DHI Select and Enterprise deliver additional capabilities. - -DHI Select offers customizations, compliance variants, and SLA-backed updates -for teams and organizations with production workloads. DHI Enterprise includes -everything in Select with unlimited customizations, plus an optional Extended -Lifecycle Support add-on and full catalog access for large enterprises with -advanced security needs. - -For a detailed comparison, see [Docker Hardened Images subscription -comparison](https://www.docker.com/products/hardened-images/#compare). - -### SLA-backed security {tier="DHI Select or DHI Enterprise"} - -- CVE remediation SLA: 7-day SLA for critical and high severity vulnerabilities -- Continuous patching: Regular security updates backed by SLA commitments -- Enterprise support: Access to Docker's support team for mission-critical applications - -For complete details, see the [Support Service Level Agreement](https://docs.docker.com/go/dhi-sla/). - -### Compliance variants {tier="DHI Select or DHI Enterprise"} - -- FIPS-enabled images: For regulated industries and government systems -- STIG-ready images: Meet DoD Security Technical Implementation Guide requirements - -### Customization and control {tier="DHI Select or DHI Enterprise"} - -- Build custom images: Add your own packages, tools, certificates, and configurations - - DHI Select: Up to 5 customizations - - DHI Enterprise: Unlimited customizations -- Hardened packages: Access to additional compliance-specific packages (such as - FIPS variants) and Docker-patched packages not available in the public repository - - DHI Select: Add these packages through the customization UI when customizing hardened images - - DHI Enterprise: Add these packages through the customization UI, or configure - your package manager to use the enterprise package repository in your own images -- Secure build infrastructure: Customizations built on Docker's trusted infrastructure -- Full chain of trust: Customized images maintain provenance and cryptographic signing -- Automatic updates: Custom images are automatically rebuilt when base images are patched - -### Extended Lifecycle Support {tier="DHI Enterprise add-on"} - -- Post-EOL security coverage: Continue receiving patches for years after upstream support ends -- Continuous compliance: Updated SBOMs, provenance, and signing for audit requirements -- Production continuity: Keep production running securely without forced migrations - -## Learn more - -- [Explore how DHI images are built and more](/dhi/explore/) -- [Get started using DHIs](/dhi/get-started/) -- Contact Docker for DHI Enterprise diff --git a/content/manuals/dhi/get-started.md b/content/manuals/dhi/get-started.md index 9ad8d9981bc6..00cedadc7135 100644 --- a/content/manuals/dhi/get-started.md +++ b/content/manuals/dhi/get-started.md @@ -31,7 +31,7 @@ Docker account, pull and run an image, and compare it with a Docker Official Ima 3. Select the Python repository to view its details. Continue to the next step to pull and run the image. To dive deeper into searching -and evaluating images, see [Search and evaluate Docker Hardened Images](./how-to/explore.md). +and evaluating images, see [Search and evaluate Docker Hardened Images](./how-to/search-evaluate.md). ## Step 2: Pull and run the image @@ -121,7 +121,7 @@ The `## Overview` section of the output looks similar to the following: Docker maintains near-zero CVEs in Docker Hardened Images. For DHI Select and Enterprise subscriptions, when new CVEs are discovered, the CVEs are remediated within the industry-leading SLA time frame. Learn more about the [SLA-backed -security features](./features.md#sla-backed-security). +security features](./_index.md#sla-backed-security). This comparison shows that the Docker Hardened Image: @@ -129,7 +129,7 @@ This comparison shows that the Docker Hardened Image: - Reduces size: From 412 MB down to 35 MB (91% reduction) - Minimizes packages: From 610 packages down to 80 (87% reduction) -To dive deeper into comparing images see [Search and evaluate Docker Hardened Images](./how-to/explore.md#compare-and-evaluate-images). +To dive deeper into comparing images see [Search and evaluate Docker Hardened Images](./how-to/search-evaluate.md#compare-and-evaluate-images). ## What's next diff --git a/content/manuals/dhi/how-to/_index.md b/content/manuals/dhi/how-to/_index.md index 2b1177955014..84e772ae01fb 100644 --- a/content/manuals/dhi/how-to/_index.md +++ b/content/manuals/dhi/how-to/_index.md @@ -7,18 +7,14 @@ aliases: params: grid_discover: - title: Search and evaluate Docker Hardened Images - description: Learn how to find and evaluate image repositories, variants, metadata, and attestations in the DHI catalog on Docker Hub. + description: Learn how to find and compare image repositories, variants, and metadata in the DHI catalog. icon: globe-alt - link: /dhi/how-to/explore/ + link: /dhi/how-to/search-evaluate/ grid_adopt: - title: Get started with DHI Select and Enterprise description: Learn how to mirror repositories, customize images, and access compliance variants with DHI Select and Enterprise subscriptions. icon: rocket-launch link: /dhi/how-to/select-enterprise/ - - title: Use the DHI CLI - description: Use the dhictl command-line tool to manage and interact with Docker Hardened Images. - icon: command-line - link: /dhi/how-to/cli/ - 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: arrows-right-left @@ -53,6 +49,11 @@ params: description: Learn how to use image policies with Docker Scout for Docker Hardened Images. icon: shield-check link: /dhi/how-to/policies/ + grid_troubleshoot: + - title: Troubleshoot + description: Resolve common issues when building, running, or debugging Docker Hardened Images, such as non-root behavior, missing shells, and port access. + icon: question-mark-circle + link: /dhi/how-to/troubleshoot/ --- This section provides practical, task-based guidance for working with Docker @@ -96,3 +97,9 @@ Enforce policies to maintain security and compliance. {{< grid items="grid_govern" >}} + +## Troubleshoot + +{{< grid + items="grid_troubleshoot" +>}} diff --git a/content/manuals/dhi/how-to/customize.md b/content/manuals/dhi/how-to/customize.md index fe52f9955ef2..fbb17a2d4f89 100644 --- a/content/manuals/dhi/how-to/customize.md +++ b/content/manuals/dhi/how-to/customize.md @@ -219,10 +219,9 @@ For a complete reference of all YAML fields, see {{< tab name="Terraform" >}} You can manage DHI customizations as infrastructure-as-code using the [DHI -Terraform -provider](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs). -If you haven't configured the provider yet, see the Terraform tab in [Mirror a -repository](./mirror.md) for setup instructions. +Terraform provider](/dhi/tools/terraform/). If you haven't configured the +provider yet, see [DHI Terraform provider](/dhi/tools/terraform/) for setup +instructions. Define a `dhi_customization` resource for each customization: diff --git a/content/manuals/dhi/how-to/explore.md b/content/manuals/dhi/how-to/explore.md deleted file mode 100644 index 7be6778b96e6..000000000000 --- a/content/manuals/dhi/how-to/explore.md +++ /dev/null @@ -1,199 +0,0 @@ ---- -title: Search and evaluate Docker Hardened Images -linktitle: Search and evaluate -description: Learn how to find, compare, and evaluate Docker Hardened Images using the catalog on Docker Hub and Docker Scout comparison tools. -keywords: search docker images, image variants, docker hub catalog, compare docker images, docker scout compare, image comparison, vulnerability comparison -weight: 10 -aliases: - - /dhi/how-to/compare/ ---- - -Docker Hardened Images (DHI) are a curated set of secure, production-ready -container images designed to provide enhanced security, minimized attack -surfaces, and production-ready foundations for your applications. - -This page explains how to search available DHI repositories, review image -metadata, examine variant details, and compare images to evaluate security -improvements and differences. - -## Search the catalog - -You can browse, search, or filter images by category in the [Hardened Image -catalog](https://hub.docker.com/hardened-images/catalog) on Docker Hub. - -Alternatively, use the [DHI CLI](/reference/cli/docker/dhi/), included in -[Docker Desktop](/desktop/), to browse the catalog from the command line: - -```console -$ docker dhi catalog list -``` - -Filter by image type, name, or compliance requirements: - -```console -$ docker dhi catalog list --type image -$ docker dhi catalog list --filter python -$ docker dhi catalog list --fips -$ docker dhi catalog list --stig -``` - -### Repository details - -When you select a repository from the catalog, 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. - - Images: Select this option to [view image variants](#image-variants). - - Security summary: Select a tag name to view a quick security summary, - including package count and total known vulnerabilities. - - Recently pushed tags: A list of recently updated image variants and when they - were last updated. - - Use this image: After selecting an image variant, you can select this option to - view instructions on how to pull and use the image variant. - -To view repository details from the command line, use the DHI CLI: - -```console -$ docker dhi catalog get python -``` - -This shows available tags, CVE counts, and other repository metadata. - -### 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. - -From the [repository details](#repository-details), select **Images** to view -the available image variants. - -The **Images** page provides a table with the following columns: - -- Image version: The image name with its base distribution (for example, `debian - 13`) and associated tags. -- Type: The support lifecycle status of the variant. -- Compliance: Relevant compliance designations. For example, `CIS`, `FIPS`, or - `STIG (100%)`. -- Package manager: Whether a package manager is available. A checkmark indicates - a package manager is present (for example, `apt` or `apk`), a dash indicates - none. -- Shell: Whether a shell is available. A checkmark indicates a shell is present - (for example, `bash` or `busybox`), a dash indicates none. -- User: The user that the container runs as. For example, `root` or `nonroot - (65532)`. -- Last pushed: When the image variant was last updated. -- Vulnerabilities: Vulnerability counts by severity level. - -### Image variant details - -On the [**Images** page](#image-variants), select an image version from the -table to view detailed information about that specific variant. - -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). - -## Compare and evaluate images - -Docker Scout lets you analyze the differences between two images. Comparing a -DHI to a standard image helps you understand the security improvements, package -differences, and overall benefits of adopting hardened images. - -Comparison is useful for: - -- Evaluating the security improvements when migrating from a standard image to a - DHI -- Understanding package and vulnerability differences between image variants -- Assessing the impact of customizations or updates - -### Prerequisites - -Before comparing images: - -- Install [Docker Desktop](/desktop/) to use Docker Scout comparison features. -- Sign in to the registries containing the images you want to compare. Sign in - to `dhi.io` for Docker Hardened Images: - - ```console - $ docker login dhi.io - ``` - -### Basic comparison - -To compare a Docker Hardened Image with another image, use the [`docker scout -compare`](/reference/cli/docker/scout/compare/) command: - -```console -$ docker scout compare dhi.io/: \ - --to : \ - --platform -``` - -For example, to compare a DHI Node.js image with the official Node.js image: - -```console -$ docker scout compare dhi.io/node:22-debian13 \ - --to node:22 \ - --platform linux/amd64 -``` - -The output shows an overview at the top with key comparison metrics, followed by -detailed package and vulnerability information. Example overview: - -```console - ## Overview - - │ Analyzed Image │ Comparison Image - ────────────────────┼───────────────────────────────────────────────────────┼───────────────────────────────────────────── - Target │ dhi.io/node:22-debian13 │ node:22 - digest │ 55d471f61608 │ 9ee3220f602f - platform │ linux/amd64 │ linux/amd64 - vulnerabilities │ 0C 0H 0M 0L │ 0C 1H 3M 153L 4? - │ -1 -3 -153 -4 │ - size │ 41 MB (-367 MB) │ 408 MB - packages │ 19 (-726) │ 745 -``` - -### Filter unchanged packages - -To focus only on the differences and ignore unchanged packages, use the -`--ignore-unchanged` flag: - -```console -$ docker scout compare dhi.io/node:22-debian13 \ - --to node:22 \ - --platform linux/amd64 \ - --ignore-unchanged -``` - -This output highlights only the packages and vulnerabilities that differ between -the two images, making it easier to identify the security improvements and -changes. diff --git a/content/manuals/dhi/how-to/mirror.md b/content/manuals/dhi/how-to/mirror.md index e67d252037f6..a8d157814b2d 100644 --- a/content/manuals/dhi/how-to/mirror.md +++ b/content/manuals/dhi/how-to/mirror.md @@ -118,37 +118,9 @@ $ docker dhi mirror list --org my-org --type helm-chart {{< tab name="Terraform" >}} You can manage DHI mirrors as infrastructure-as-code using the [DHI Terraform -provider](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs). +provider](/dhi/tools/terraform/). -First, install and configure the provider: - -```hcl -terraform { - required_providers { - dhi = { - source = "docker-hardened-images/dhi" - } - } -} - -provider "dhi" { - docker_hub_username = var.docker_username - docker_hub_password = var.docker_password - organization = var.org_name -} -``` - -> [!NOTE] -> -> Instead of specifying credentials in the provider block, you can set the -> `DOCKER_USERNAME`, `DOCKER_PASSWORD`, and `DHI_ORG` environment variables. You -> can also authenticate using an organization access token (OAT) in place of a -> password. Set `DOCKER_USERNAME` to your organization namespace and -> `DOCKER_PASSWORD` to the OAT. When using an OAT, the same permission scopes -> apply as with the CLI: read (pull) access is required to list mirrors, and -> push access is required to create or delete them. - -Then, define a `dhi_mirror` resource for each repository you want to mirror: +Define a `dhi_mirror` resource for each repository you want to mirror: ```hcl resource "dhi_mirror" "golang" { diff --git a/content/manuals/dhi/how-to/scan.md b/content/manuals/dhi/how-to/scan.md index 3f18a5e00d41..3f325b0fc552 100644 --- a/content/manuals/dhi/how-to/scan.md +++ b/content/manuals/dhi/how-to/scan.md @@ -13,7 +13,7 @@ vulnerability management process. ## Scan with OpenVEX-compliant scanners To get accurate vulnerability assessments, use scanners that support -[VEX](/manuals/dhi/core-concepts/vex.md) attestations. The following scanners can +[VEX](/manuals/dhi/explore/security-concepts/vex.md) attestations. The following scanners can read and apply the VEX statements included with Docker Hardened Images: - [Docker Scout](#docker-scout): Automatically applies VEX statements with zero configuration diff --git a/content/manuals/dhi/how-to/search-evaluate.md b/content/manuals/dhi/how-to/search-evaluate.md new file mode 100644 index 000000000000..f27de2c5cafa --- /dev/null +++ b/content/manuals/dhi/how-to/search-evaluate.md @@ -0,0 +1,112 @@ +--- +title: Search and evaluate Docker Hardened Images +linktitle: Search and evaluate +description: Learn how to find, compare, and evaluate Docker Hardened Images using the Docker Hub catalog, DHI CLI, and Docker Scout. +keywords: search docker images, image variants, docker hub catalog, compare docker images, docker scout compare, image comparison, vulnerability comparison +weight: 10 +aliases: + - /dhi/how-to/compare/ + - /dhi/how-to/explore/ +--- + +## Search the catalog + +You can browse, search, or filter images by category in the [Docker Hub +catalog](https://hub.docker.com/hardened-images/catalog). For details about +the catalog interface, see [Docker Hub](/dhi/tools/hub/). + +Alternatively, use the [DHI CLI](/dhi/tools/cli/) to browse the catalog from +the command line: + +```console +$ docker dhi catalog list +``` + +Filter by image type, name, or compliance requirements: + +```console +$ docker dhi catalog list --type image +$ docker dhi catalog list --filter python +$ docker dhi catalog list --fips +$ docker dhi catalog list --stig +``` + +To view repository details, including available tags and CVE counts: + +```console +$ docker dhi catalog get python +``` + +## Compare and evaluate images + +Docker Scout lets you analyze the differences between two images. Comparing a +DHI to a standard image helps you understand the security improvements, package +differences, and overall benefits of adopting hardened images. + +Comparison is useful for: + +- Evaluating the security improvements when migrating from a standard image to a DHI +- Understanding package and vulnerability differences between image variants +- Assessing the impact of customizations or updates + +### Prerequisites + +Before comparing images: + +- Install [Docker Desktop](/desktop/) to use Docker Scout comparison features. +- Sign in to `dhi.io` for Docker Hardened Images: + + ```console + $ docker login dhi.io + ``` + +### Basic comparison + +To compare a Docker Hardened Image with another image, use the [`docker scout +compare`](/reference/cli/docker/scout/compare/) command: + +```console +$ docker scout compare dhi.io/: \ + --to : \ + --platform +``` + +For example, to compare a DHI Node.js image with the official Node.js image: + +```console +$ docker scout compare dhi.io/node:22-debian13 \ + --to node:22 \ + --platform linux/amd64 +``` + +The output shows an overview at the top with key comparison metrics, followed by +detailed package and vulnerability information. Example overview: + +```console + ## Overview + + │ Analyzed Image │ Comparison Image + ────────────────────┼───────────────────────────────────────────────────────┼───────────────────────────────────────────── + Target │ dhi.io/node:22-debian13 │ node:22 + digest │ 55d471f61608 │ 9ee3220f602f + platform │ linux/amd64 │ linux/amd64 + vulnerabilities │ 0C 0H 0M 0L │ 0C 1H 3M 153L 4? + │ -1 -3 -153 -4 │ + size │ 41 MB (-367 MB) │ 408 MB + packages │ 19 (-726) │ 745 +``` + +### Filter unchanged packages + +To focus only on the differences and ignore unchanged packages, use the +`--ignore-unchanged` flag: + +```console +$ docker scout compare dhi.io/node:22-debian13 \ + --to node:22 \ + --platform linux/amd64 \ + --ignore-unchanged +``` + +This output highlights only the packages and vulnerabilities that differ between +the two images. diff --git a/content/manuals/dhi/how-to/select-enterprise.md b/content/manuals/dhi/how-to/select-enterprise.md index 8f53e52bde5b..e108079f0254 100644 --- a/content/manuals/dhi/how-to/select-enterprise.md +++ b/content/manuals/dhi/how-to/select-enterprise.md @@ -72,7 +72,7 @@ can use either interface. {{< /tabs >}} Continue to the next step to mirror the image. To dive deeper into exploring -images see [Search and evaluate Docker Hardened Images](explore.md). +images see [Search and evaluate Docker Hardened Images](search-evaluate.md). ## Step 2: Mirror the repository @@ -97,7 +97,7 @@ can mirror repositories. To use the following commands, you must authenticate or configure DHI CLI authentication using your Docker token. For details, see [Use the DHI -CLI](cli.md#configuration). +CLI](../tools/cli.md#configuration). 1. Start mirroring the repository to your organization namespace. Replace `` with your organization name. @@ -152,7 +152,7 @@ column to monitor the build status. To use the following commands, you must authenticate or configure DHI CLI authentication using your Docker token. For details, see [Use the DHI -CLI](cli.md#configuration). +CLI](../tools/cli.md#configuration). 1. Create a customization. Replace `` with your organization name. This creates a file called `my-customization.yaml` with the customization diff --git a/content/manuals/dhi/troubleshoot.md b/content/manuals/dhi/how-to/troubleshoot.md similarity index 95% rename from content/manuals/dhi/troubleshoot.md rename to content/manuals/dhi/how-to/troubleshoot.md index f3d86b07c823..42d2a51400b7 100644 --- a/content/manuals/dhi/troubleshoot.md +++ b/content/manuals/dhi/how-to/troubleshoot.md @@ -1,11 +1,12 @@ --- 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 +weight: 100 tags: [Troubleshooting] keywords: troubleshoot hardened image, docker debug container, non-root permission issue, missing shell error, no package manager, debug, hardened images, DHI, troubleshooting, ephemeral container, docker debug, non-root containers, hardened container image, debug secure container aliases: -- /dhi/how-to/debug/ + - /dhi/how-to/debug/ + - /dhi/troubleshoot/ --- This page covers debugging techniques and common issues you may encounter while @@ -137,7 +138,7 @@ 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#image-variant-details) for more information. +details](../tools/hub.md#image-variant-details-page) for more information. ### Privileged ports @@ -159,7 +160,7 @@ 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#image-variant-details) for more information. +details](../tools/hub.md#image-variant-details-page) for more information. Also, use Docker Debug when you need shell access to a running container. For more details, see [General debugging](#general-debugging). @@ -171,7 +172,7 @@ 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#image-variant-details) for more information. +details](../tools/hub.md#image-variant-details-page) for more information. ### No package manager diff --git a/content/manuals/dhi/how-to/use.md b/content/manuals/dhi/how-to/use.md index 329886801fb7..73bf38594ea0 100644 --- a/content/manuals/dhi/how-to/use.md +++ b/content/manuals/dhi/how-to/use.md @@ -81,7 +81,7 @@ For multi-stage builds: executables](#use-a-static-image-for-compiled-executables). To learn how to search for available variants, see [Search and evaluate -images](./explore.md). +images](./search-evaluate.md). ## Use a DHI in CI/CD pipelines @@ -90,7 +90,7 @@ 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 +[attestations](../explore/security-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. diff --git a/content/manuals/dhi/how-to/verify.md b/content/manuals/dhi/how-to/verify.md index 1a96cec7f18c..ab4602e0deb7 100644 --- a/content/manuals/dhi/how-to/verify.md +++ b/content/manuals/dhi/how-to/verify.md @@ -388,15 +388,15 @@ attestations when needed. ## Available DHI attestations See [available -attestations](../core-concepts/attestations.md#image-attestations) for a list +attestations](../explore/security-concepts/attestations.md#image-attestations) for a list of attestations available for each DHI image and [Helm chart -attestations](../core-concepts/attestations.md#helm-chart-attestations) for a +attestations](../explore/security-concepts/attestations.md#helm-chart-attestations) for a list of attestations available for each DHI chart. ## Explore attestations on Docker Hub You can also browse attestations visually when [exploring an image -variant](./explore.md#image-variant-details). The **Attestations** section +variant](./search-evaluate.md#image-variant-details). The **Attestations** section lists each available attestation with its: - Type (e.g. SBOM, VEX) diff --git a/content/manuals/dhi/migration/migrate-from-doi.md b/content/manuals/dhi/migration/migrate-from-doi.md index 521733545f86..13e8faf1dc79 100644 --- a/content/manuals/dhi/migration/migrate-from-doi.md +++ b/content/manuals/dhi/migration/migrate-from-doi.md @@ -102,7 +102,7 @@ ENTRYPOINT ["/app/myapp"] ``` After updating your Dockerfile, build and test your application. If you encounter -issues, see the [Troubleshoot](/manuals/dhi/troubleshoot.md) guide for common +issues, see the [Troubleshoot](/manuals/dhi/how-to/troubleshoot.md) guide for common problems and solutions. ## Language-specific examples diff --git a/content/manuals/dhi/migration/migrate-from-wolfi.md b/content/manuals/dhi/migration/migrate-from-wolfi.md index 5896451dba40..2d02ce60237a 100644 --- a/content/manuals/dhi/migration/migrate-from-wolfi.md +++ b/content/manuals/dhi/migration/migrate-from-wolfi.md @@ -10,7 +10,7 @@ Images (DHI). Generally, the migration process is straightforward since Wolfi is Alpine-like and DHI provides an Alpine-based hardened image. Like other hardened images, DHI provides comprehensive -[attestations](/dhi/core-concepts/attestations/) including SBOMs and provenance, +[attestations](/dhi/explore/security-concepts/attestations/) including SBOMs and provenance, allowing you to [verify](/manuals/dhi/how-to/verify.md) image signatures and [scan](/manuals/dhi/how-to/scan.md) for vulnerabilities to ensure the security and integrity of your images. @@ -83,7 +83,7 @@ ENTRYPOINT ["/app/myapp"] ``` After updating your Dockerfile, build and test your application. If you encounter -issues, see the [Troubleshoot](/manuals/dhi/troubleshoot.md) guide for common +issues, see the [Troubleshoot](/manuals/dhi/how-to/troubleshoot.md) guide for common problems and solutions. ## Language-specific examples diff --git a/content/manuals/dhi/release-notes/platform.md b/content/manuals/dhi/release-notes/platform.md index 9093e00c3869..49f36f994af6 100644 --- a/content/manuals/dhi/release-notes/platform.md +++ b/content/manuals/dhi/release-notes/platform.md @@ -11,6 +11,16 @@ This page contains information about the new features, improvements, and changes in the Docker Hardened Images (DHI) platform. Release notes are aggregated by quarter and include only notable product changes. +## Q3 2026 + +New features and enhancements released in the third quarter of 2026. + +- DHI MCP server: The DHI catalog is now accessible via a remote MCP server at + `https://dhi.io/mcp`. Connect any MCP-capable AI assistant to search + repositories, inspect image metadata, retrieve SBOMs, check CVEs, and manage + mirrors using plain language. For more information, see [Use the DHI MCP + server](/dhi/tools/mcp/). + ## Q2 2026 New features and enhancements released in the second quarter of 2026. diff --git a/content/manuals/dhi/resources.md b/content/manuals/dhi/resources.md index 6696e166c085..9f1bec1dc8cd 100644 --- a/content/manuals/dhi/resources.md +++ b/content/manuals/dhi/resources.md @@ -1,12 +1,16 @@ --- -title: Docker Hardened Images resources -linktitle: Additional resources -description: Additional resources including product information, guides, and GitHub repositories for Docker Hardened Images +title: Resources and feedback +linktitle: Resources and feedback +description: Additional resources, community links, GitHub repositories, and how to give feedback for Docker Hardened Images. +keywords: docker hardened images resources, dhi feedback, dhi github, dhi community, report issue, dhi support weight: 999 +aliases: + - /dhi/about/feedback/ + - /dhi/explore/feedback/ --- -This page provides links to additional resources related to Docker Hardened -Images (DHI), including guides, Docker Hub resources, and GitHub repositories. +This page provides links to additional resources, community channels, and ways +to give feedback on Docker Hardened Images (DHI). For product information and feature comparison, visit the [Docker Hardened Images product page](https://www.docker.com/products/hardened-images/). @@ -47,8 +51,6 @@ organization: - [Terraform Provider](https://github.com/docker-hardened-images/terraform-provider-dhi): Terraform provider for managing DHI resources ([Terraform Registry](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs)) -- [Discussions](https://github.com/orgs/docker-hardened-images/discussions): - Community forum and product discussions ## Additional resources @@ -70,3 +72,19 @@ organization: - [Docker Support](https://www.docker.com/support/): Access support resources for DHI Select and Enterprise customers +## Feedback and community + +Use the [GitHub Discussions board](https://github.com/orgs/docker-hardened-images/discussions) +to engage with the DHI team for general questions, best practices, security +tips, and community announcements. + +To report a bug, request a feature, or suggest a documentation improvement, +[open an issue](https://github.com/docker-hardened-images/catalog/issues) in +the catalog repository. + +## Security disclosure + +Do not post details of vulnerabilities before coordinated disclosure and +resolution. If you discover a security vulnerability, report it responsibly +by following Docker's [security disclosure +policy](https://www.docker.com/trust/vulnerability-disclosure-policy/). diff --git a/content/manuals/dhi/tools/_index.md b/content/manuals/dhi/tools/_index.md new file mode 100644 index 000000000000..c5addb8ae62a --- /dev/null +++ b/content/manuals/dhi/tools/_index.md @@ -0,0 +1,28 @@ +--- +title: Tools +description: Interfaces and tools for browsing, managing, and automating Docker Hardened Images. +weight: 25 +params: + grid_tools: + - title: Use Docker Hub + description: Browse the DHI catalog on Docker Hub to search repositories, inspect image metadata, and view SBOMs, CVEs, and attestations. + icon: squares-2x2 + link: /dhi/tools/hub/ + - title: CLI + description: Install and use the `docker dhi` command-line interface to browse the catalog, inspect images, and manage mirrors from your terminal. + icon: command-line + link: /dhi/tools/cli/ + - title: MCP server + description: Connect an AI assistant to the DHI catalog to search repositories, inspect images, retrieve SBOMs, and check CVEs using plain language. + icon: cpu-chip + link: /dhi/tools/mcp/ + - title: Use the DHI Terraform provider + description: Use the DHI Terraform provider to manage mirrors and automate DHI configuration as infrastructure as code. + icon: wrench-screwdriver + link: /dhi/tools/terraform/ +--- + +Docker Hardened Images can be accessed and managed through several interfaces. +Choose the tool that fits your workflow. + +{{< grid items="grid_tools" >}} diff --git a/content/manuals/dhi/how-to/cli.md b/content/manuals/dhi/tools/cli.md similarity index 98% rename from content/manuals/dhi/how-to/cli.md rename to content/manuals/dhi/tools/cli.md index 18a71245312c..e6a68d7638f5 100644 --- a/content/manuals/dhi/how-to/cli.md +++ b/content/manuals/dhi/tools/cli.md @@ -1,9 +1,11 @@ --- title: Use the DHI CLI -linkTitle: Use the CLI -weight: 50 +linkTitle: CLI +weight: 20 keywords: docker dhi, CLI, command line, docker hardened images description: Learn how to install and use docker dhi, the command-line interface for managing Docker Hardened Images. +aliases: + - /dhi/how-to/cli/ --- The `docker dhi` command-line interface (CLI) is a tool for managing Docker Hardened Images: @@ -141,7 +143,7 @@ $ docker dhi mirror stop dhi-golang --org my-org --delete --force The CLI can be used to create and manage DHI image customizations. For detailed instructions on creating customizations using the GUI, see [Customize a Docker -Hardened Image](./customize.md). +Hardened Image](../how-to/customize.md). The following is a quick reference for CLI commands. For complete details on all options and flags, see the @@ -204,7 +206,7 @@ Generate authentication credentials for accessing the enterprise hardened package repository. These credentials are used when configuring your package manager to install compliance and security-patched packages in your own images. For detailed instructions, see [Enterprise -repository](./hardened-packages.md#enterprise-repository). +repository](../how-to/hardened-packages.md#enterprise-repository). For Alpine-based images: diff --git a/content/manuals/dhi/tools/hub.md b/content/manuals/dhi/tools/hub.md new file mode 100644 index 000000000000..cab81039bfb5 --- /dev/null +++ b/content/manuals/dhi/tools/hub.md @@ -0,0 +1,103 @@ +--- +title: Use Docker Hub +linktitle: Docker Hub +description: Browse the DHI catalog on Docker Hub to search repositories, inspect image metadata, and view SBOMs, CVEs, and attestations. +weight: 10 +keywords: docker hub dhi catalog, hardened images hub, dhi repository details, image variants hub +--- + +The [Docker Hardened Images catalog](https://hub.docker.com/hardened-images/catalog) +on Docker Hub is the primary web interface for browsing, searching, and inspecting +DHI repositories and their metadata. + +## Catalog page + +The catalog lists all available DHI repositories. You can filter by name, +image type, or compliance requirements (FIPS, STIG) to find the image you need. + +## Repository details page + +When you select a repository from the catalog, 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. +- Images: Select this option to [view image variants](#images-page). +- Security summary: Select a tag name to view a quick security summary, + including package count and total known vulnerabilities. +- Recently pushed tags: A list of recently updated image variants and when they + were last updated. +- Use this image: After selecting an image variant, you can select this option to + view instructions on how to pull and use the image variant, or select **Mirror + repository** to mirror it to your organization. + +## Images page + +From the repository details page, select **Images** to see all available image +variants for that repository. The table includes: + +- Image version: The image name with its base distribution (for example, `debian + 13`) and associated tags. +- Type: The support lifecycle status of the variant. +- Compliance: Relevant compliance designations, for example `CIS`, `FIPS`, or + `STIG (100%)`. +- Package manager: Whether a package manager is available. A checkmark indicates + a package manager is present (for example, `apt` or `apk`), a dash indicates + none. +- Shell: Whether a shell is available. A checkmark indicates a shell is present + (for example, `bash` or `busybox`), a dash indicates none. +- User: The user that the container runs as, for example `root` or `nonroot + (65532)`. +- Last pushed: When the image variant was last updated. +- Vulnerabilities: Vulnerability counts by severity level. + +## Image variant details page + +Select an image version from the Images table to view detailed information about +that specific variant: + +- Packages: A list of all packages included in the image variant, with each + package's name, version, distribution, and licensing information. +- Specifications: + - Source and build information: The Dockerfile and Git commit used to build the image. + - Build parameters, entrypoint, CMD, user, working directory, environment + variables, labels, and platform. +- Vulnerabilities: A list of known CVEs for the image variant, including CVE ID, + severity, affected package, fix version, last detected date, status, and + suppressed CVEs. +- Attestations: Signed security attestations covering the image's build process, + contents, and security posture. For the full list, see + [Attestations](/dhi/explore/security-concepts/attestations/). + +## Manage page + +The Manage page (**My Hub** > **Hardened Images** > **Manage**) is the central +place for administering your organization's mirrored DHI repositories. It has +two tabs: + +- Mirrored Images: Lists all image repositories currently mirrored to your + organization, with their source DHI repository, destination repository name, + and mirroring status. From here you can stop mirroring or open a repository's + settings. +- Mirrored Helm charts: The same view for Helm chart repositories. + +Selecting a mirrored repository opens its settings, where you can enable or +disable Extended Lifecycle Support (ELS) and access customizations. + +For step-by-step instructions, see [Mirror a Docker Hardened Image +repository](/dhi/how-to/mirror/). + +## Customizations + +Customizations are accessible from **My Hub** > **Hardened Images** > **Manage** > **Mirrored Images**. +Select the menu icon next to a mirrored repository and +then **Customize**. Each customization defines +additional packages, OCI artifacts, environment variables, or labels to layer +onto the base DHI during a rebuild. + +The customizations view shows each customization's name, status, and last build +time. Selecting a customization opens its configuration, where you can edit the +definition, trigger a rebuild, or delete it. + +For step-by-step instructions, see [Customize a Docker Hardened +Image](/dhi/how-to/customize/). diff --git a/content/manuals/dhi/tools/mcp.md b/content/manuals/dhi/tools/mcp.md new file mode 100644 index 000000000000..bc71dae76de6 --- /dev/null +++ b/content/manuals/dhi/tools/mcp.md @@ -0,0 +1,211 @@ +--- +title: Use the DHI MCP server +linktitle: MCP server +description: Connect an AI assistant to the Docker Hardened Images catalog using the DHI MCP server to search repositories, inspect images, view SBOMs, and check CVEs. +weight: 30 +keywords: docker hardened images mcp, ai assistant dhi, mcp server docker, dhi catalog ai, claude cursor docker images, sbom mcp, cve mcp +aliases: + - /dhi/how-to/mcp/ +--- + +The Docker Hardened Images (DHI) MCP server exposes the DHI catalog through the +Model Context Protocol (MCP), letting you query repositories, inspect image +metadata, retrieve SBOMs, and check CVEs directly from your AI assistant in +plain language. + +The MCP server is: + +- Remote. No local binary to install. Your AI assistant connects directly to + `https://dhi.io/mcp`. +- Compatible with any MCP-capable AI assistant, including Claude, + Cursor, and others. + +Most tools are public and require no credentials. The mirror management tools +(`dhi_list_mirrors`, `dhi_create_mirror`, `dhi_remove_mirror`) require a Docker +Hub username and personal access token (PAT) with owner access to the target +organization. Credentials are passed as an HTTP Basic auth header in the MCP +client configuration — they are never passed as tool arguments. + +## Connect your AI assistant + +Configuration varies by client. Select the tab for your AI assistant. + +{{< tabs >}} +{{< tab name="Claude Desktop" >}} + +Add the following to your Claude Desktop configuration file: + +```json +{ + "mcpServers": { + "dhi": { + "url": "https://dhi.io/mcp" + } + } +} +``` + +The configuration file is located at: +- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` +- Windows: `%APPDATA%\Claude\claude_desktop_config.json` + +{{< /tab >}} +{{< tab name="Cursor" >}} + +Add the following to `.cursor/mcp.json` in your project, or +`~/.cursor/mcp.json` globally: + +```json +{ + "mcpServers": { + "dhi": { + "url": "https://dhi.io/mcp" + } + } +} +``` + +{{< /tab >}} +{{< tab name="Claude Code" >}} + +Run the following command to add the DHI MCP server: + +```console +$ claude mcp add dhi --url https://dhi.io/mcp +``` + +Or add it manually to `.claude/mcp.json` in your project: + +```json +{ + "mcpServers": { + "dhi": { + "url": "https://dhi.io/mcp" + } + } +} +``` + +{{< /tab >}} +{{< tab name="Docker Agent" >}} + +In your [Docker Agent](/manuals/ai/docker-agent/_index.md) YAML configuration, add the +DHI MCP server as a remote toolset: + +```yaml +toolsets: + - type: mcp + remote: + url: "https://dhi.io/mcp" + transport_type: streamable +``` + +For example, to create an agent that can answer questions about the DHI catalog: + +```yaml +agents: + root: + model: anthropic/claude-sonnet-4-5 + description: DHI catalog assistant + instruction: | + Help me find and evaluate Docker Hardened Images. + Search the DHI catalog, inspect image details, check CVEs, + and retrieve SBOMs and attestations as needed. + toolsets: + - type: mcp + remote: + url: "https://dhi.io/mcp" + transport_type: streamable +``` + +Run the agent with: + +```console +$ docker agent run dhi-agent.yaml +``` + +{{< /tab >}} +{{< /tabs >}} + +## Available tools + +The DHI MCP server provides ten tools that your AI assistant calls automatically +based on what you ask: + +| Tool | What it does | +|------|-------------| +| `dhi_list_repositories` | Search and filter the DHI catalog by name, type, category, FIPS, or STIG compliance | +| `dhi_get_repository` | Get full details for a repository: tag definitions, build config, platforms, and per-manifest vulnerability counts | +| `dhi_get_tag_definition` | Get the deep view of a single tag definition | +| `dhi_get_image_details` | Get per-digest details: tags, platform, size, layer and package counts, vulnerability severity counts, and attestation types | +| `dhi_get_image_packages` | Retrieve the full software bill of materials (SBOM): package name, version, type, purl, licenses, and file locations | +| `dhi_get_image_cves` | List CVEs with severity, CVSS score, fix version, EPSS score, and CISA-exploited flag; filter by minimum severity or fixable-only | +| `dhi_get_image_attestations` | List SBOM, provenance, signature, and other attestations for a specific image digest | +| `dhi_list_mirrors` | List mirrored DHI repositories for a Docker Hub organization — requires authentication | +| `dhi_create_mirror` | Start mirroring a DHI repository into a Docker Hub organization — requires authentication | +| `dhi_remove_mirror` | Stop mirroring a repository by its mirror ID — requires authentication | + +## Authenticate for mirror tools + +The mirror tools require a Docker Hub username and [personal access token +(PAT)](/security/access-tokens/) with owner access to the target organization, +passed as an HTTP Basic auth header. Generate the value with: + +```console +$ printf 'USERNAME:dckr_pat_...' | base64 | tr -d '\n' +``` + +Then add it to your MCP client configuration: + +> [!WARNING] +> Base64 encoding is not encryption. The value in your configuration file +> is effectively a plaintext password. Do not commit this file to version +> control or share it. + +```json +{ + "mcpServers": { + "dhi": { + "url": "https://dhi.io/mcp", + "headers": { + "Authorization": "Basic " + } + } + } +} +``` + +Without credentials, the read-only catalog tools work normally and the mirror +tools return an authentication error. + +## What the tools return + +Each tool returns structured data that your AI assistant can summarize, +compare, or act on: + +- `dhi_list_repositories` returns a list of repositories with display + name, distributions, platforms, FIPS/STIG flags, included tools, and category. +- `dhi_get_repository` returns the full repository record, including all tag + definitions with their tags, build configuration, image indexes, and + per-platform manifest digests with vulnerability counts. +- `dhi_get_tag_definition` returns tags, build parameters, entrypoint, + environment variables, run-as user, and per-platform manifests for a single + tag definition. +- `dhi_get_image_details` returns the image platform, compressed size, layer + count, package count, vulnerability severity counts by level, labels, and + a list of attestation predicate types. +- `dhi_get_image_packages` returns each package in the image with its name, + version, type (`deb`, `rpm`, `apk`, etc.), purl, licenses, and the file paths where + it was found. +- `dhi_get_image_cves` returns each CVE affecting the image with its + severity, CVSS score and vector, affected package, fix version (if any), EPSS + probability score, and a flag indicating whether CISA lists it as + actively exploited. +- `dhi_get_image_attestations` returns the predicate type and OCI reference + for each attestation attached to the image digest. +- `dhi_list_mirrors` returns each mirror's ID, source DHI repository, + destination repository, and mirroring status for the given organization. +- `dhi_create_mirror` starts mirroring a DHI source repository into the + specified organization and destination repository name. +- `dhi_remove_mirror` stops mirroring for the given mirror ID. It does not + delete the destination repository — only stops new images from being synced. diff --git a/content/manuals/dhi/tools/terraform.md b/content/manuals/dhi/tools/terraform.md new file mode 100644 index 000000000000..176ad2f0ccd6 --- /dev/null +++ b/content/manuals/dhi/tools/terraform.md @@ -0,0 +1,65 @@ +--- +title: Use the DHI Terraform provider +linktitle: Terraform +description: Use the DHI Terraform provider to manage mirrors and customizations as infrastructure as code. +weight: 40 +keywords: dhi terraform, docker hardened images terraform, infrastructure as code, dhi mirror terraform, dhi provider +--- + +The [DHI Terraform provider](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs) +lets you manage Docker Hardened Image mirrors and customizations as +infrastructure as code. + +## Install and configure the provider + +Add the provider to your Terraform configuration: + +```hcl +terraform { + required_providers { + dhi = { + source = "docker-hardened-images/dhi" + } + } +} + +provider "dhi" { + docker_hub_username = var.docker_username + docker_hub_password = var.docker_password + organization = var.org_name +} +``` + +Instead of specifying credentials in the provider block, you can set environment +variables: + +| Variable | Description | +|----------|-------------| +| `DOCKER_USERNAME` | Docker Hub username or organization namespace | +| `DOCKER_PASSWORD` | Docker Hub password or personal/organization access token | +| `DHI_ORG` | Target organization namespace | + +You can authenticate using a personal access token (PAT) or an organization +access token (OAT) in place of a password. When using an OAT, permission scopes +apply: + +- Read (pull) access is required to list mirrors. +- Push access is required to create or delete mirrors. + +## Resources + +### `dhi_mirror` + +Manages a mirrored DHI repository in your organization. See [Mirror a Docker +Hardened Image repository](/dhi/how-to/mirror/) for task-based examples. + +For the full list of resource attributes, see the [Terraform Registry +documentation](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs/resources/mirror). + +### `dhi_customization` + +Manages image customizations applied to a mirrored repository. See [Customize a +Docker Hardened Image](/dhi/how-to/customize/) for task-based examples. + +For the full list of resource attributes, see the [Terraform Registry +documentation](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs/resources/customization).