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