dhi: initial draft

Signed-off-by: Craig <[email protected]>

Author: craig-osterhout

.vscode/docker.code-snippets

@@ -54,4 +54,4 @@
     "body": ["{{< button url=\"$1\" text=\"$2\" >}}"],
     "description": "Insert a Hugo button",
   },
-}
+}

content/manuals/_index.md

@@ -49,6 +49,10 @@ params:
     description: Your command center for container development.
     icon: /icons/Whale.svg
     link: /desktop/
+  - title: Docker Hardened Images
+    description: Secure, minimal base images for trusted software delivery.
+    icon: verified_user
+    link: /docker-hardened-images/
   - title: Build Cloud
     description: Build your images faster in the cloud.
     icon: /icons/logo-build-cloud.svg

content/manuals/dhi/_index.md

@@ -0,0 +1,50 @@
+---
+title: Docker Hardened Images
+description: Secure, minimal, and production-ready base images
+weight: 13
+params:
+  sidebar:
+    badge:
+      color: green
+      text: New
+    group: Products
+  grid_sections:
+    - title: Quickstart
+      description: Follow a step-by-step guide to explore, mirror, and run a Docker Hardened Image.
+      icon: rocket_launch
+      link: /dhi/get-started/
+    - title: About
+      description: Learn what Docker Hardened Images are, how they're built, and what sets them apart from typical base images.
+      icon: info
+      link: /dhi/about/
+    - title: Features
+      description: Discover the security, compliance, and enterprise-readiness features built into Docker Hardened Images.
+      icon: lock
+      link: /dhi/features/
+    - title: How-tos
+      description: Step-by-step guides for using, verifying, scanning, and migrating to Docker Hardened Images.
+      icon: play_arrow
+      link: /dhi/how-to/
+    - title: Core concepts
+      description: Understand the secure supply chain principles that make Docker Hardened Images production-ready.
+      icon: fact_check
+      link: /dhi/core-concepts/
+    - title: Troubleshoot
+      description: Resolve common issues with building, running, or debugging Docker Hardened Images.
+      icon: help_center
+      link: /dhi/troubleshoot/
+---
+
+{{< summary-bar feature_name="Docker Hardened Images" >}}
+
+Docker Hardened Images (DHIs) are minimal, secure, and production-ready
+container base and application images maintained by Docker. Designed to reduce
+vulnerabilities and simplify compliance, DHIs integrate easily into your
+existing Docker-based workflows with little to no retooling required.
+
+Explore the sections below to get started with Docker Hardened Images, integrate
+them into your workflow, and learn what makes them secure and enterprise-ready.
+
+{{< grid
+  items="grid_sections"
+>}}

content/manuals/dhi/about/_index.md

@@ -0,0 +1,35 @@
+---
+title: About
+description: dhi description
+weight: 5
+params:
+  grid_about:
+    - title: What are hardened images and why use them?
+      description: Learn what a hardened image is, how Docker Hardened Images are built, what sets them apart from typical base and application images, and why you should use them.
+      icon: info
+      link: /dhi/about/what/
+    - title: Image testing
+      description: See how Docker Hardened Images are automatically tested for standards compliance, functionality, and security.
+      icon: science
+      link: /dhi/about/test/
+    - title: Responsibility overview
+      description: Understand Docker's role and your responsibilities when using Docker Hardened Images as part of your secure software supply chain.
+      icon: group
+      link: /dhi/about/responsibility/
+    - title: Image types
+      description: Learn about the different image types, distributions, and variants offered in the Docker Hardened Images catalog.
+      icon: view_module
+      link: /dhi/about/available/
+---
+
+Docker Hardened Images (DHIs) are purpose-built for security, compliance, and
+reliability in modern software supply chains. This section explains what makes
+these images different from standard base and application images, how they're
+built and tested, and how Docker and users share responsibility in securing
+containerized workloads.
+
+## Learn about Docker Hardened Images
+
+{{< grid
+  items="grid_about"
+>}}

content/manuals/dhi/about/available.md

@@ -0,0 +1,73 @@
+---
+linktitle: Image types
+title: Available types of Docker Hardened Images
+description: Learn about the different image types, distributions, and variants offered in the Docker Hardened Images catalog.
+keywords: docker hardened images, distroless containers, distroless images, docker distroless, alpine base image, debian base image, development containers, runtime containers, secure base image, multi-stage builds
+weight: 20
+---
+
+Docker Hardened Images (DHI) is a comprehensive catalog of
+security-hardened container images built to meet diverse
+development and production needs.
+
+## Framework and application images
+
+DHI includes a selection of popular frameworks and application images, each
+hardened and maintained to ensure security and compliance. These images
+integrate seamlessly into existing workflows, allowing developers to focus on
+building applications without compromising on security.
+
+For example, you might find repositories like the following in the DHI catalog:
+
+- `node`: framework for Node.js applications
+- `python`: framework for Python applications
+- `nginx`: web server image
+
+## Compatibility options
+
+Docker Hardened Images are available in different base image options, giving you
+flexibility to choose the best match for your environment and workload
+requirements:
+
+- Debian-based images: A good fit if you're already working in glibc-based
+  environments. Debian is widely used and offers strong compatibility across
+  many language ecosystems and enterprise systems.
+
+- Alpine-based images: A smaller and more lightweight option using musl libc.
+  These images are faster to pull and have a reduced footprint, though you may
+  need to account for musl-glibc differences in some applications.
+
+Each image maintains a minimal and secure runtime layer by removing
+non-essential components like shells, package managers, and debugging tools.
+This helps reduce the attack surface while retaining compatibility with common
+runtime environments.
+
+Example tags include:
+
+- `3.9.23-alpine3.21`: Alpine-based image for Python 3.9.23
+- `3.9.23-debian12`: Debian-based image for Python 3.9.23
+
+If you're not sure which to choose, start with the base you're already familiar
+with. Debian tends to offer the broadest compatibility.
+
+## Development and runtime variants
+
+To accommodate different stages of the application lifecycle, DHI offers images
+in several variants:
+
+- Development (dev) images: Equipped with necessary development tools and
+libraries, these images facilitate the building and testing of applications in a
+secure environment. They include a shell, package manager, a root user, and
+other tools needed for development.
+
+- Runtime images: Stripped of development tools, these images contain only the
+essential components needed to run applications, ensuring a minimal attack
+surface in production.
+
+This separation supports multi-stage builds, enabling developers to compile code
+in a secure build environment and deploy it using a lean runtime image.
+
+For example, you might find tags like the following in a DHI repository:
+
+- `3.9.23-debian12`: runtime image for Python 3.9.23
+- `3.9.23-debian12-dev`: development image for Python 3.9.23

content/manuals/dhi/about/responsibility.md

@@ -0,0 +1,66 @@
+---
+title: Understanding roles and responsibilities for Docker Hardened Images
+linkTitle: Responsibility overview
+description: Understand the division of responsibilities between Docker, upstream projects, and you when using Docker Hardened Images.
+keywords: software supply chain security, signed sbom, vex document, container provenance, image attestation
+weight: 46
+---
+
+Docker Hardened Images (DHIs) are curated and maintained by Docker, and built
+using upstream open source components. To deliver security, reliability, and
+compliance, responsibilities are shared among three groups:
+
+- Upstream maintainers: the developers and communities responsible for the
+  open source software included in each image.
+- Docker: the provider of hardened, signed, and maintained container images.
+- You (the customer): the consumer who runs and, optionally, customizes DHIs
+  in your environment.
+
+This topic outlines who handles what, so you can use DHIs effectively and
+securely.
+
+## Releases
+
+- Upstream: Publishes and maintains official releases of the software
+  components included in DHIs. This includes versioning, changelogs, and
+  deprecation notices.
+- Docker: Builds, hardens, and signs Docker Hardened Images based on
+  upstream versions. Docker maintains these images in line with upstream release
+  timelines and internal policies.
+- You: Ensure you're staying on supported versions of DHIs and upstream
+  projects. Using outdated or unsupported components can introduce security
+  risk.
+
+## Patching
+
+- Upstream: Maintains and updates the source code for each component,
+  including fixing vulnerabilities in libraries and dependencies.
+- Docker: Rebuilds and re-releases images with upstream patches applied.
+  Docker also monitors for vulnerabilities and rapidly publishes updates to
+  affected images.
+- You: Apply DHI updates in your environments and patch any software or
+  dependencies you install on top of the base image.
+
+## Testing
+
+- Upstream: Defines the behavior and functionality of the original software,
+  and is responsible for validating core features.
+- Docker: Validates that DHIs start, run, and behave consistently with
+  upstream expectations. Docker also runs security scans and includes a [testing
+  attestation](../core-concepts/attestations.md) with each image.
+- You: Test your application on top of DHIs and validate that any changes or
+  customizations function as expected in your environment.
+
+## Security and compliance
+
+- Docker: Publishes signed SBOMs, VEX documents, provenance data, and CVE
+  scan results with each image to support compliance and supply chain security.
+- You: Integrate DHIs into your security and compliance workflows, including
+  vulnerability management and auditing.
+
+## Summary
+
+Docker Hardened Images give you a secure foundation, complete with signed
+metadata and upstream transparency. Your role is to make informed use of these
+images, apply updates promptly, and validate that your configurations and
+applications meet your internal requirements.

content/manuals/dhi/about/test.md

@@ -0,0 +1,148 @@
+---
+title: How Docker Hardened Images are tested
+linktitle: Image testing
+description: See how Docker Hardened Images are automatically tested for standards compliance, functionality, and security.
+keywords: docker scout, test attestation, cosign verify, image testing, vulnerability scan
+weight: 45
+---
+
+Docker Hardened Images (DHIs) are designed to be secure, minimal, and
+production-ready. To ensure their reliability and security, Docker employs a
+comprehensive testing strategy, which you can independently verify using signed
+attestations and open tooling.
+
+Every image is tested for standards compliance, functionality, and security. The
+results of this testing are embedded as signed attestations, which can be
+[inspected and verified](#view-and-verify-the-test-attestation) programmatically
+using the Docker Scout CLI.
+
+## Testing strategy overview
+
+The testing process for DHIs focuses on two main areas:
+
+- Image standards compliance: Ensuring that each image adheres to strict size,
+  security, and compatibility standards.
+- Application functionality: Verifying that applications within the images
+  function correctly and meet expected performance benchmarks.
+
+## Image standards compliance
+
+Each DHI undergoes rigorous checks to meet the following standards:
+
+- Minimal attack surface: Images are built to be as small as possible, removing
+  unnecessary components to reduce potential vulnerabilities.
+- Near-zero known CVEs: Images are scanned using tools like Docker Scout to
+  ensure they are free from known Common Vulnerabilities and Exposures (CVEs).
+- Multi-architecture support: DHIs are built for multiple architectures,
+  including `linux/amd64` and `linux/arm64`, to ensure broad compatibility.
+- Kubernetes compatibility: Images are tested to run seamlessly within
+  Kubernetes clusters, ensuring they meet the requirements for container
+  orchestration environments.
+
+## Application functionality testing
+
+Docker tests Docker Hardened Images to ensure they behave as expected in typical
+usage scenarios. This includes verifying that:
+
+- Applications start and run successfully in containerized environments.
+- Runtime behavior aligns with upstream expectations.
+- Build variants (like `-dev` images) support common development and build tasks.
+
+The goal is to ensure that DHIs work out of the box for the most common use
+cases while maintaining the hardened, minimal design.
+
+## Automated testing and CI/CD integration
+
+Docker integrates automated testing into its Continuous Integration/Continuous
+Deployment (CI/CD) pipelines:
+
+- Automated scans: Each image build triggers automated scans for vulnerabilities
+  and compliance checks.
+- Reproducible builds: Build processes are designed to be reproducible, ensuring
+  consistency across different environments.
+- Continuous monitoring: Docker continuously monitors for new vulnerabilities
+  and updates images accordingly to maintain security standards.
+
+## Testing attestation
+
+Docker provides a test attestation that details the testing and validation
+processes each DHI has undergone.
+
+### View and verify the test attestation
+
+You can view and verify this attestation using the Docker Scout CLI.
+
+1. Use the `docker scout attest get` command with the test predicate type:
+
+   ```console
+   $ docker scout attest get \
+     --predicate-type https://scout.docker.com/tests/v0.1 \
+     --predicate \
+     <your-namespace>/dhi-<image>:<tag> --platform <platform>
+   ```
+
+   For example:
+
+   ```console
+   $ docker scout attest get \
+     --predicate-type https://scout.docker.com/tests/v0.1 \
+     --predicate \
+     docs/dhi-python:3.13 --platform linux/amd64
+   ```
+
+   This contains a list of tests and their results.
+
+   Example output:
+
+    ```console
+        v SBOM obtained from attestation, 101 packages found
+        v Provenance obtained from attestation
+        {
+          "reportFormat": "CTRF",
+          "results": {
+            "summary": {
+              "failed": 0,
+              "passed": 1,
+              "skipped": 0,
+              "start": 1749216533,
+              "stop": 1749216574,
+              "tests": 1
+            },
+            "tests": [
+              {
+                ...
+   ```
+
+2. Verify the test attestation signature. To ensure the attestation is authentic
+   and signed by Docker, run:
+
+   ```console
+   docker scout attest get \
+     --predicate-type https://scout.docker.com/tests/v0.1 \
+     --verify \
+     <your-namespace>/dhi-<image>:<tag> --platform <platform>
+   ```
+
+   Example output:
+   
+   ```console
+    v SBOM obtained from attestation, 101 packages found
+    v Provenance obtained from attestation
+    v cosign verify registry.scout.docker.com/docker/dhi-python@sha256:70c8299c4d3cb4d5432734773c45ae58d8acc2f2f07803435c65515f662136d5 \
+        --key https://registry.scout.docker.com/keyring/dhi/latest.pub --experimental-oci11
+
+      Verification for registry.scout.docker.com/docker/dhi-python@sha256:70c8299c4d3cb4d5432734773c45ae58d8acc2f2f07803435c65515f662136d5 --
+      The following checks were performed on each of these signatures:
+        - The cosign claims were validated
+        - Existence of the claims in the transparency log was verified offline
+        - The signatures were verified against the specified public key
+
+    i Signature payload
+    ...
+    ```
+
+If the attestation is valid, Docker Scout will confirm the signature and show
+the matching Cosign verify-attestation command.
+
+To view other attestations, such as SBOMs or vulnerability reports, see [Verify
+an image](../how-to/verify.md).