diff --git a/content/manuals/dhi/_index.md b/content/manuals/dhi/_index.md index e13ae1a7430d..5cc89afd7b9f 100644 --- a/content/manuals/dhi/_index.md +++ b/content/manuals/dhi/_index.md @@ -39,17 +39,18 @@ params: link: /dhi/resources/ --- -Docker Hardened Images (DHI) are minimal, secure, and production-ready container -base and application images maintained by Docker. Designed to reduce -vulnerabilities and simplify compliance, DHI integrates easily into your -existing Docker-based workflows with little to no retooling required. +Docker Hardened Images (DHI) provide minimal, secure, and production-ready +container images, Helm charts, and system packages maintained by Docker. +Designed to reduce vulnerabilities and simplify compliance, DHI integrates +easily into your existing Docker-based workflows with little to no retooling +required. -DHI is available in two tiers: **DHI Free** provides core security features at -no cost, while **DHI Enterprise** adds SLA-backed support, compliance variants, -customization, and Extended Lifecycle Support for organizations with advanced -requirements. +DHI is available in the following three subscriptions. -![DHI Subscription](./images/dhi-subscription.png) +![DHI Tiers](./images/dhi-tiers.png) + +For more details see the [Docker Hardened Images subscription +comparison](https://www.docker.com/products/hardened-images/#compare). 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. diff --git a/content/manuals/dhi/core-concepts/attestations.md b/content/manuals/dhi/core-concepts/attestations.md index b9218efa49d6..e5f93c39677f 100644 --- a/content/manuals/dhi/core-concepts/attestations.md +++ b/content/manuals/dhi/core-concepts/attestations.md @@ -90,6 +90,21 @@ For more details, see [Verify image attestations](../how-to/verify.md#verify-ima | FIPS compliance | An attestation that verifies the image uses FIPS 140-validated cryptographic modules. | | DHI Image Sources | Links to a corresponding source image containing all materials used to build the image, including package source code, Git repositories, and local files, ensuring compliance with open source license requirements. | +## Package attestations + +In addition to image-level attestations, Docker hardened packages also include +their own attestations. These package-level attestations provide provenance and +build information for individual packages within an image, allowing you to +trace the supply chain at a granular level. + +Package attestations include similar information as image attestations, such as +SLSA provenance, showing how each package was built and what materials were +used. You can extract package information from an image's attestations and then +retrieve the package's own attestations recursively. + +For detailed instructions on how to access and verify package attestations, see +[Package attestations](../how-to/hardened-packages.md#package-attestations). + ## Helm chart attestations Docker Hardened Image (DHI) charts also include comprehensive signed attestations diff --git a/content/manuals/dhi/core-concepts/fips.md b/content/manuals/dhi/core-concepts/fips.md index fba47e52470d..b63b215d8013 100644 --- a/content/manuals/dhi/core-concepts/fips.md +++ b/content/manuals/dhi/core-concepts/fips.md @@ -1,5 +1,5 @@ --- -title: 'FIPS DHI Enterprise' +title: 'FIPS DHI Select & Enterprise' linkTitle: FIPS description: Learn how Docker Hardened Images support FIPS 140 through validated cryptographic modules to help organizations meet compliance requirements. keywords: docker fips, fips 140 images, fips docker images, docker compliance, secure container images @@ -39,7 +39,7 @@ Using software components that rely on validated cryptographic modules can help ## How Docker Hardened Images support FIPS compliance While Docker Hardened Images are available to all, the FIPS variant requires a -Docker Hardened Images Enterprise subscription. +paid Docker Hardened Images subscription. Docker Hardened Images (DHIs) include variants that use cryptographic modules validated under FIPS 140. These images are intended to help organizations meet diff --git a/content/manuals/dhi/core-concepts/stig.md b/content/manuals/dhi/core-concepts/stig.md index fac4e90ed68d..48c3255b00cb 100644 --- a/content/manuals/dhi/core-concepts/stig.md +++ b/content/manuals/dhi/core-concepts/stig.md @@ -1,5 +1,5 @@ --- -title: 'STIG DHI Enterprise' +title: 'STIG DHI Select & Enterprise' linkTitle: STIG description: Learn how Docker Hardened Images provide STIG-ready container images with verifiable security scan attestations for government and enterprise compliance requirements. keywords: docker stig, stig-ready images, stig guidance, openscap docker, secure container images diff --git a/content/manuals/dhi/explore/available.md b/content/manuals/dhi/explore/available.md index d33265c3cba7..712a29fa5f44 100644 --- a/content/manuals/dhi/explore/available.md +++ b/content/manuals/dhi/explore/available.md @@ -12,6 +12,9 @@ Docker Hardened Images (DHI) is a comprehensive catalog of security-hardened container images built to meet diverse development and production needs. +You can explore the DHI catalog on [Docker Hub](https://hub.docker.com/search?q=&image_filter=store%2Cdhi) or use the [DHI CLI](../how-to/cli.md) to browse +available images, tags, and metadata from the command line. + ## Framework and application images DHI includes a selection of popular frameworks and application images, each @@ -76,7 +79,7 @@ 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 -## FIPs and STIG variants {tier="DHI Enterprise"} +## FIPs and STIG variants {tier="DHI Select & Enterprise"} {{< summary-bar feature_name="Docker Hardened Images" >}} diff --git a/content/manuals/dhi/explore/build-process.md b/content/manuals/dhi/explore/build-process.md index a572dbb7e47a..5154bd4b7c04 100644 --- a/content/manuals/dhi/explore/build-process.md +++ b/content/manuals/dhi/explore/build-process.md @@ -10,13 +10,13 @@ aliases: Docker Hardened Images are built through an automated pipeline that monitors upstream sources, applies security updates, and publishes signed artifacts. -This page explains the build process for both base DHI images and DHI Enterprise -customized images. +This page explains the build process for both base DHI images and customized +images available with DHI Select and DHI Enterprise subscriptions. -With a DHI Enterprise subscription, the automated security update pipeline for +With DHI Select or DHI Enterprise subscriptions, the automated security update pipeline for both base and customized images is backed by SLA commitments, including a 7-day -SLA for critical and high severity vulnerabilities. Only DHI Enterprise includes -SLAs. DHI Free offers a secure baseline but no guaranteed remediation timelines. +SLA for critical and high severity vulnerabilities. DHI Community offers a secure baseline +but no guaranteed remediation timelines. ## Build transparency @@ -72,14 +72,14 @@ dependencies. When a package update is detected (for example, a security patch for a library), Docker automatically identifies and rebuilds all images within the support window that use that package. -### Customization changes {tier="DHI Enterprise"} +### Customization changes {tier="DHI Select and Enterprise"} {{< summary-bar feature_name="Docker Hardened Images" >}} Updates to your OCI artifact customizations trigger rebuilds of your customized images. -When you customize a DHI image with DHI Enterprise, your changes are packaged as +When you customize a DHI image with DHI Select or DHI Enterprise, your changes are packaged as OCI artifacts that layer on top of the base image. Docker monitors your artifact repositories and automatically rebuilds your customized images whenever you push updates. @@ -149,11 +149,11 @@ The following diagram shows the base image build flow: '-------------------' '-------------------' '-------------------' '-------------------' ``` -### Customized image pipeline {tier="DHI Enterprise"} +### Customized image pipeline {tier="DHI Select and Enterprise"} {{< summary-bar feature_name="Docker Hardened Images" >}} -When you customize a DHI image with DHI Enterprise, the build process is simplified: +When you customize a DHI image with DHI Select or DHI Enterprise, the build process is simplified: 1. Monitoring: Docker monitors your OCI artifact repositories for changes. 2. Rebuild trigger: When you push updates to your OCI artifacts, or when the base diff --git a/content/manuals/dhi/explore/responsibility.md b/content/manuals/dhi/explore/responsibility.md index a5e6c97615b0..cd03c4b0de81 100644 --- a/content/manuals/dhi/explore/responsibility.md +++ b/content/manuals/dhi/explore/responsibility.md @@ -38,8 +38,8 @@ securely. - 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 - monitors for vulnerabilities and publishes updates to affected images. Only - DHI Enterprise includes SLAs. DHI Free offers a secure baseline but no + monitors for vulnerabilities and publishes updates to affected images. DHI Select + and DHI Enterprise include SLA commitments. DHI Community offers a secure baseline but no guaranteed remediation timelines. - You: Apply DHI updates in your environments and patch any software or dependencies you install on top of the base image. @@ -58,9 +58,9 @@ securely. - Docker: Publishes signed SBOMs, VEX documents, provenance data, and CVE scan results with each image to support compliance and supply chain security. - - For free DHI users: All security metadata and transparency features are + - For DHI Community users: All security metadata and transparency features are included at no cost. - - For DHI Enterprise users: Additional compliance variants (like FIPS and + - For DHI Select and Enterprise users: Additional compliance variants (like FIPS and STIG) and customization capabilities are available, with automatic rebuilds when base images are patched. - You: Integrate DHIs into your security and compliance workflows, including @@ -69,9 +69,9 @@ securely. ## Support - Docker: - - For free DHI users: Community support and public documentation are available. - - For DHI Enterprise users: Access to Docker's enterprise support team for - mission-critical applications. + - For DHI Community users: Community support and public documentation are available. + - For DHI Select and DHI Enterprise users: Access to Docker's enterprise + support team for mission-critical applications. - You: Monitor Docker's release notes, security advisories, and documentation for updates and best practices. diff --git a/content/manuals/dhi/features.md b/content/manuals/dhi/features.md index 0928ed5b32ab..4446da3d27a8 100644 --- a/content/manuals/dhi/features.md +++ b/content/manuals/dhi/features.md @@ -19,15 +19,15 @@ existing Docker-based workflows with little to no retooling required. DHI provides security for everyone: -- [DHI Free](#dhi-free-features) provides core security features available to - everyone with no licensing restrictions under Apache 2.0 -- [DHI Enterprise subscription - features](#dhi-enterprise-subscription-features) add - SLA-backed security updates, compliance variants (like FIPS and STIG), image - customization, and optional Extended Lifecycle Support (ELS) for post-EOL - coverage +- [DHI Community](#dhi-community-features) provides core security features available to + everyone with no licensing restrictions under Apache 2.0. +- [DHI Select and DHI Enterprise](#dhi-select-and-enterprise-features) add SLA-backed + security updates, FIPS/STIG compliance variants, and customization + capabilities, with DHI Enterprise offering unlimited customization, full + catalog access, and optional Extended Lifecycle Support (ELS) for post-EOL + coverage. -## DHI Free features +## DHI Community features DHI's core features are open and free to use, share, and build on with no licensing surprises, backed by an Apache 2.0 license. @@ -35,12 +35,27 @@ licensing surprises, backed by an Apache 2.0 license. ### Security by default - Near-zero CVEs: Continuously scanned and patched to maintain minimal known - exploitable vulnerabilities, with no SLA-backed time commitments for non-DHI - Enterprise users + exploitable vulnerabilities, with no SLA-backed time commitments for DHI Community users - Minimal attack surface: Distroless variants reduce attack surface by up to 95% by removing unnecessary components - Non-root execution: Run as non-root by default, following the principle of least privilege - Transparent vulnerability reporting: Every CVE is visible and assessed using public data—no suppressed feeds or proprietary scoring +### Hardened system packages + +Docker Hardened Images maintain supply chain integrity throughout the entire +image stack with hardened system packages: + +- Source-built packages: For supported distributions, system packages are built + from source code by Docker +- Cryptographic signatures: Every package is cryptographically signed and verified +- Supply chain security: Eliminates risk from potentially compromised public packages + +Hardened system packages are included in supported distributions of DHI images. +Community users can also configure their package manager to use Docker's public +hardened package repository in their own images for the same packages included +in the base images. See [Use hardened system packages](./how-to/hardened-packages.md) +for details. + ### Total transparency Every image includes complete, verifiable security metadata: @@ -87,27 +102,41 @@ metadata to ensure transparency and trust: - Hardened configuration: Charts automatically reference Docker hardened images, ensuring security in deployments. -## DHI Enterprise subscription features +## DHI Select and Enterprise features For organizations with strict security requirements, regulatory demands, or -operational needs, DHI Enterprise delivers additional capabilities. +operational needs, DHI Select and Enterprise deliver additional capabilities. -### Compliance variants {tier="DHI Enterprise"} +DHI Select offers customizations, compliance variants, and SLA-backed updates +for teams and organizations with production workloads. DHI Enterprise includes +everything in Select with unlimited customizations, plus an optional Extended +Lifecycle Support add-on and full catalog access for large enterprises with +advanced security needs. -- FIPS-enabled images: For regulated industries and government systems -- STIG-ready images: Meet DoD Security Technical Implementation Guide requirements +For a detailed comparison, see [Docker Hardened Images subscription +comparison](https://www.docker.com/products/hardened-images/#compare). -### SLA-backed security {tier="DHI Enterprise"} +### SLA-backed security {tier="DHI Select & DHI Enterprise"} -- CVE remediation SLA: 7-day SLA for critical and high severity vulnerabilities, - with SLA commitments for other severity levels -- ELS CVE remediation SLA: Extended Lifecycle Support images have SLA commitments - for CVE remediation, even after upstream end-of-life +- CVE remediation SLA: 7-day SLA for critical and high severity vulnerabilities +- Continuous patching: Regular security updates backed by SLA commitments - Enterprise support: Access to Docker's support team for mission-critical applications -### Customization and control {tier="DHI Enterprise"} +### Compliance variants {tier="DHI Select & DHI Enterprise"} + +- FIPS-enabled images: For regulated industries and government systems +- STIG-ready images: Meet DoD Security Technical Implementation Guide requirements + +### Customization and control {tier="DHI Select & DHI Enterprise"} - Build custom images: Add your own packages, tools, certificates, and configurations + - DHI Select: Up to 5 customizations + - DHI Enterprise: Unlimited customizations +- Hardened packages: Access to additional compliance-specific packages (such as + FIPS variants) and Docker-patched packages not available in the public repository + - DHI Select: Add these packages through the customization UI when customizing hardened images + - DHI Enterprise: Add these packages through the customization UI, or configure + your package manager to use the enterprise package repository in your own images - Secure build infrastructure: Customizations built on Docker's trusted infrastructure - Full chain of trust: Customized images maintain provenance and cryptographic signing - Automatic updates: Custom images are automatically rebuilt when base images are patched diff --git a/content/manuals/dhi/get-started.md b/content/manuals/dhi/get-started.md index 3481552d9a28..338ec2da1774 100644 --- a/content/manuals/dhi/get-started.md +++ b/content/manuals/dhi/get-started.md @@ -11,10 +11,11 @@ This guide shows you how to go from zero to running a Docker Hardened Image Docker image to better understand the differences. While the steps use a specific image as an example, they can be applied to any DHI. + Docker Hardened Images are freely available to everyone with no subscription required, no usage restrictions, and no vendor lock-in. This quickstart covers -free DHI images pulled from `dhi.io`. If you have a DHI Enterprise subscription -or have started a trial and need compliance variants (FIPS), customization +free DHI images pulled from `dhi.io`. If you have a paid DHI subscription or +have started a trial and need compliance variants (FIPS), customization capabilities, or SLA-backed updates, you must [mirror DHI repositories](./how-to/mirror.md) to your organization's namespace on Docker Hub. You then pull mirrored images from `docker.io` (not `dhi.io`) using your @@ -120,7 +121,7 @@ Example output: > This is example output. Your results may vary depending on newly discovered > CVEs and image updates. > -> Docker maintains near-zero CVEs in Docker Hardened Images. For DHI Enterprise +> Docker maintains near-zero CVEs in Docker Hardened Images. For paid DHI > subscriptions, when new CVEs are discovered, the CVEs are remediated within > the industry-leading SLA timeframe. Learn more about the [SLA-backed security > features](./features.md#sla-backed-security). @@ -142,12 +143,12 @@ You've pulled and run your first Docker Hardened Image. Here are a few ways to k as the base. - [Start a trial](https://hub.docker.com/hardened-images/start-free-trial) to - explore the benefits of a DHI Enterprise subscription, such as access to FIPS + explore the benefits of a paid DHI subscription, such as access to FIPS and STIG variants, customized images, and SLA-backed updates. -- [Mirror a repository](./how-to/mirror.md): After subscribing to DHI Enterprise - or starting a trial, learn how to mirror a DHI repository to enable - customization, access compliance variants, and get SLA-backed updates. +- [Mirror a repository](./how-to/mirror.md): After subscribing to a paid DHI + subscription or starting a trial, learn how to mirror a DHI repository to + enable customization, access compliance variants, and get SLA-backed updates. - [Verify DHIs](./how-to/verify.md): Use tools like [Docker Scout](/scout/) or Cosign to inspect and verify signed attestations, like SBOMs and provenance. diff --git a/content/manuals/dhi/how-to/_index.md b/content/manuals/dhi/how-to/_index.md index 16c43febf431..02f58e0803cb 100644 --- a/content/manuals/dhi/how-to/_index.md +++ b/content/manuals/dhi/how-to/_index.md @@ -9,6 +9,10 @@ params: icon: travel_explore link: /dhi/how-to/explore/ grid_adopt: + - title: Use the DHI CLI + description: Use the dhictl command-line tool to manage and interact with Docker Hardened Images. + icon: terminal + link: /dhi/how-to/cli/ - title: Mirror a Docker Hardened Image repository description: Learn how to mirror an image into your organization's namespace and optionally push it to another private registry. icon: compare_arrows @@ -17,6 +21,10 @@ params: description: Learn how to customize Docker Hardened Images and charts. icon: settings link: /dhi/how-to/customize/ + - title: Use hardened system packages + description: Learn how to use Docker's hardened system packages in your images. + icon: inventory_2 + link: /dhi/how-to/hardened-packages/ - 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 diff --git a/content/manuals/dhi/how-to/cli.md b/content/manuals/dhi/how-to/cli.md new file mode 100644 index 000000000000..dd0ce546f931 --- /dev/null +++ b/content/manuals/dhi/how-to/cli.md @@ -0,0 +1,190 @@ +--- +title: Use the DHI CLI +linkTitle: Use the CLI +weight: 50 +keywords: dhictl, CLI, command line, docker hardened images +description: Learn how to install and use dhictl, the command-line interface for managing Docker Hardened Images. +--- + +`dhictl` is a command-line interface (CLI) tool for managing Docker Hardened Images: +- Browse the catalog of available DHI images and their metadata +- Mirror DHI images to your Docker Hub organization +- Create and manage customizations of DHI images +- Generate authentication for enterprise package repositories +- Monitor customization builds + +## Installation + +`dhictl` will be available by default on [Docker Desktop](https://docs.docker.com/desktop/) soon. +In the meantime, you can install `dhictl` manually as a Docker CLI plugin or as a standalone binary. + +### Docker CLI Plugin + +1. Download the `dhictl` binary for your platform from the [releases](https://github.com/docker-hardened-images/dhictl/releases) page. +2. Rename the binary: + - `docker-dhi` on _Linux_ and _macOS_ + - `docker-dhi.exe` on _Windows_ +3. Copy it to the CLI plugins directory: + - `$HOME/.docker/cli-plugins` on _Linux_ and _macOS_ + - `%USERPROFILE%\.docker\cli-plugins` on _Windows_ +4. Make it executable on _Linux_ and _macOS_: + - `chmod +x $HOME/.docker/cli-plugins/docker-dhi` +5. Run `docker dhi` to verify the installation. + +### Standalone Binary + +1. Download the `dhictl` binary for your platform from the + [releases](https://github.com/docker-hardened-images/dhictl/releases) page. +2. Move it to a directory in your `PATH`: + - `mv dhictl /usr/local/bin/` on _Linux_ and _macOS_ + - Move `dhictl.exe` to a directory in your `PATH` on _Windows_ + +## Usage + +> [!NOTE] +> +> The following examples use `dhictl` to reference the CLI tool. Depending on +> your installation, you may need to replace `dhictl` with `docker dhi`. + +Every command has built-in help accessible with the `--help` flag: + +```bash +dhictl --help +dhictl catalog list --help +``` + +### Browse the DHI Catalog + +List all available DHI images: + +```bash +dhictl catalog list +``` + +Filter by type, name, or compliance: + +```bash +dhictl catalog list --type image +dhictl catalog list --filter golang +dhictl catalog list --fips +``` + +Get details of a specific image, including available tags and CVE counts: + +```bash +dhictl catalog get +``` + +### Mirror DHI Images + +Start mirroring one or more DHI images to your Docker Hub organization: + +```bash +dhictl mirror start --org my-org \ + -r dhi/golang,my-org/dhi-golang \ + -r dhi/nginx,my-org/dhi-nginx \ + -r dhi/prometheus-chart,my-org/dhi-prometheus-chart +``` + +List mirrored images in your organization: + +```bash +dhictl mirror list --org my-org +``` + +Stop mirroring an image: + +```bash +dhictl mirror stop --org my-org dhi-golang +``` + +### Customize DHI Images {tier="DHI Select & DHI Enterprise"} + +The CLI can be used to create and manage DHI image customizations. For detailed +instructions on creating customizations, including the YAML syntax and +available options, see [Customize a Docker Hardened Image](./customize.md). + +Quick reference for CLI commands: + +```bash +# Prepare a customization scaffold +dhictl customization prepare --org my-org golang 1.25 \ + --destination my-org/dhi-golang \ + --name "golang with git" \ + --tag-suffix "_git" \ + --output my-customization.yaml + +# Create a customization +dhictl customization create --org my-org my-customization.yaml + +# List customizations +dhictl customization list --org my-org + +# Get a customization +dhictl customization get --org my-org my-org/dhi-golang "golang with git" --output my-customization.yaml + +# Update a customization +dhictl customization edit --org my-org my-customization.yaml + +# Delete a customization +dhictl customization delete --org my-org my-org/dhi-golang "golang with git" +``` + +### Enterprise Package Authentication {tier="DHI Enterprise"} + +Generate authentication credentials for accessing the enterprise hardened +package repository. This is used when configuring your package manager to +install compliance-specific packages in your own images. For detailed +instructions, see [Enterprise +repository](./hardened-packages.md#enterprise-repository). + +```bash +dhictl auth apk +``` + +### Monitor Customization Builds {tier="DHI Select & DHI Enterprise"} + +List builds for a customization: + +```bash +dhictl customization build list --org my-org my-org/dhi-golang "golang with git" +``` + +Get details of a specific build: + +```bash +dhictl customization build get --org my-org my-org/dhi-golang "golang with git" +``` + +View build logs: + +```bash +dhictl customization build logs --org my-org my-org/dhi-golang "golang with git" +``` + +### JSON Output + +Most list and get commands support a `--json` flag for machine-readable output: + +```bash +dhictl catalog list --json +dhictl mirror list --org my-org --json +dhictl customization list --org my-org --json +``` + +## Configuration + +`dhictl` can be configured with a YAML file located at: +- `$HOME/.config/dhictl/config.yaml` on _Linux_ and _macOS_ +- `%USERPROFILE%\.config\dhictl\config.yaml` on _Windows_ + +If `$XDG_CONFIG_HOME` is set, the configuration file is located at `$XDG_CONFIG_HOME/dhictl/config.yaml` (see the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/spec/latest/)). + +Available configuration options: + +| Option | Environment Variable | Description | +|-------------|----------------------|---------------------------------------------------------------------------------------------------------------------------| +| `org` | `DHI_ORG` | Default Docker Hub organization for mirror and customization commands. | +| `api_token` | `DHI_API_TOKEN` | Docker token for authentication. You can generate a token in your [Docker Hub account settings](https://hub.docker.com/). | + +Environment variables take precedence over configuration file values. diff --git a/content/manuals/dhi/how-to/customize.md b/content/manuals/dhi/how-to/customize.md index 186d8983eee3..aa01b8643d52 100644 --- a/content/manuals/dhi/how-to/customize.md +++ b/content/manuals/dhi/how-to/customize.md @@ -1,5 +1,5 @@ --- -title: 'Customize a Docker Hardened Image or chart DHI Enterprise' +title: 'Customize a Docker Hardened Image or chart DHI Select & Enterprise' linkTitle: Customize an image or chart weight: 25 keywords: hardened images, DHI, customize, certificate, artifact, helm chart @@ -8,12 +8,13 @@ description: Learn how to customize Docker Hardened Images (DHI) and charts. {{< summary-bar feature_name="Docker Hardened Images" >}} -When you have a Docker Hardened Images subscription, you can customize Docker +When you have a DHI Select or DHI Enterprise subscription, you can customize Docker Hardened Images (DHI) and charts to suit your specific needs using the Docker Hub web interface. For images, this lets you select a base image, add packages, add OCI artifacts (such as custom certificates or additional tools), and configure settings. For charts, this lets you customize the image references. + Your customizations stay secure automatically. When the base Docker Hardened Image or chart receives a security patch or your OCI artifacts are updated, Docker automatically rebuilds your customizations in the background. This @@ -29,9 +30,37 @@ owner must first [mirror](./mirror.md) the DHI repository to your organization on Docker Hub. Once the repository is mirrored, any user with access to the mirrored DHI repository can create a customized image. -### Create an image customization +You can create customizations using either the DHI CLI or the Docker Hub web interface. + +### Customize using the DHI CLI + +The DHI CLI provides a command-line interface for managing Docker Hardened Image +customizations. For installation instructions and usage details, see [Use +the DHI CLI](./cli.md#customize-dhi-images). + +#### Monitor customization builds + +List builds for a customization: + +```console +$ docker dhi customization build list --org my-org my-org/dhi-golang "golang with git" +``` + +Get details of a specific build: + +```console +$ docker dhi customization build get --org my-org my-org/dhi-golang "golang with git" +``` + +View build logs: + +```console +$ docker dhi customization build logs --org my-org my-org/dhi-golang "golang with git" +``` + +### Customize using the Docker Hub web interface -To customize a Docker Hardened Image, follow these steps: +To customize a Docker Hardened Image using the web interface, follow these steps: 1. Sign in to [Docker Hub](https://hub.docker.com). 1. Select **My Hub**. @@ -48,13 +77,15 @@ To customize a Docker Hardened Image, follow these steps: 1. Select the image version you want to customize. 1. Optional. Add packages. - 1. In the **Packages** drop-down, select the packages you want to add to the - image. + 1. In the packages drop-down (labeled **Hardened packages** for Alpine + distributions or **Packages** for Debian distributions), select the + packages you want to add to the image. The packages available in the drop-down are OS system packages for the - selected image variant. For example, if you are customizing the Alpine - variant of the Python DHI, the list will include all Alpine system - packages. + selected image variant. For Alpine-based images, these are hardened + packages that have been built from source by Docker with cryptographic + signatures and full supply chain security. For Debian-based images, + these are standard Debian system packages. 1. In the **OCI artifacts** drop-down, first, select the repository that contains the OCI artifact image. Then, select the tag you want to use from diff --git a/content/manuals/dhi/how-to/hardened-packages.md b/content/manuals/dhi/how-to/hardened-packages.md new file mode 100644 index 000000000000..c2251bb2d011 --- /dev/null +++ b/content/manuals/dhi/how-to/hardened-packages.md @@ -0,0 +1,288 @@ +--- +title: Use Hardened System Packages +linkTitle: Use hardened packages +weight: 30 +keywords: hardened images, DHI, hardened packages, packages, alpine +description: Learn how to use and verify Docker's hardened system packages in your images. +--- + +Docker Hardened System Packages are built from source by Docker. This ensures +supply chain integrity throughout your entire image stack by eliminating risks +from potentially compromised public packages. + +Access to hardened packages varies by subscription: + +- **DHI Community**: Includes hardened packages in base images. Can configure the + public package repository to access the same packages in custom images. +- **DHI Select**: Includes all Community packages, plus access to additional + compliance-specific packages (such as FIPS variants) and Docker-patched + packages through the image customization UI. +- **DHI Enterprise**: Includes all Select packages, plus the ability to configure + the enterprise package repository directly in your own images for full access + to compliance and security-patched packages. + +## Built-in packages + +Supported distributions of Docker Hardened Images (DHI) automatically include +hardened system packages. No additional configuration is required. Simply pull +and use the images as normal. + +All packages in these images are built by Docker from source, maintaining +the same security standards as the base images themselves. + +## Add hardened packages to your images + +You can add hardened packages to your own images in the following two ways. + +### Add packages through image customization {tier="DHI Select & DHI Enterprise"} + +When customizing Docker Hardened Images with DHI Select or DHI Enterprise, you +can add hardened packages for Alpine-based images through the customization +interface. Follow the steps to [create an image +customization](./customize.md#create-an-image-customization) and select hardened +packages during the customization process. + +### Configure the package manager + +You can configure your package manager to pull from Docker's hardened package +repositories. This lets you install hardened packages in your own images. + +#### Public repository + +To use Docker's public hardened package repository in your own images, configure +the Alpine package manager in your Dockerfile. + +The configuration process involves three steps: + +1. Install the [signing key](https://github.com/docker-hardened-images/keyring) +2. Configure the package repository +3. Update and install packages + +The following example shows how to configure the Alpine package manager in your +Dockerfile to use Docker's public hardened package repository: + +```dockerfile +FROM alpine:3.23 + +# Install the signing key +RUN cd /etc/apk/keys && \ + wget https://dhi.io/keyring/dhi-apk@docker-0F81AD7700D99184.rsa.pub + +# Replace the default repositories with the hardened package repository +RUN echo "https://dhi.io/apk/alpine/v3.23/main" > /etc/apk/repositories + +# Update and install packages +RUN apk update && \ + apk add libpng +``` + +Replace `3.23` with your Alpine version in both the base image tag and repository URL. + +To verify the configuration, build and run the image: + +```console +$ docker build -t myapp:latest . +$ docker run -it myapp:latest sh +``` + +Inside the container, check the configured repositories: + +```console +/ # cat /etc/apk/repositories +https://dhi.io/apk/alpine/v3.23/main +``` + +This ensures all packages are installed from Docker's hardened repository. + +All packages installed from the Docker Hardened Images repository are built from +source by Docker and include full provenance. + +#### Enterprise repository {tier="DHI Enterprise"} + +With DHI Enterprise, you have access to an additional package +repository that includes hardened packages for compliance variants such as FIPS, +as well as additional security patches. + +The configuration process involves five steps: + +1. Install the [signing key](https://github.com/docker-hardened-images/keyring) +2. Configure the base package repository +3. Install the enterprise configuration package +4. Configure package installation with authentication +5. Build the image passing credentials as a secret using the DHI CLI + + > [!NOTE] + > + > You must have the Docker Hardened Images CLI installed and configured. For + > more information, see [Use the DHI CLI](./cli.md). + +The following example shows how to configure the Alpine package manager in your +Dockerfile to use Docker's enterprise hardened package repository: + +```dockerfile +FROM alpine:3.23 + +# Install the signing key +RUN cd /etc/apk/keys && \ + wget https://dhi.io/keyring/dhi-apk@docker-0F81AD7700D99184.rsa.pub + +# Replace the default repositories with the hardened package repository +RUN echo "https://dhi.io/apk/alpine/v3.23/main" > /etc/apk/repositories + +# Update and install the enterprise configuration package to add the security repository +RUN apk update && \ + apk add dhi-enterprise-conf + +# Install packages from the security repository with authentication +RUN --mount=type=secret,id=http_auth \ + HTTP_AUTH="$(cat /run/secrets/http_auth)" \ + apk update && \ + apk add openssl-fips +``` + +Build the image with authentication passed securely as a build secret: + +```console +$ dhictl auth apk > http_auth.txt +$ docker build --secret id=http_auth,src=http_auth.txt -t myapp-enterprise:latest . +$ rm http_auth.txt +``` + +The `--secret` flag securely mounts the authentication credentials during build +without storing them in the image layers or metadata. + +## Verify packages + +Every hardened package is cryptographically signed and includes metadata that +proves its provenance and build integrity. You can verify the signatures and +view the metadata to ensure your packages come from Docker's trusted build +infrastructure. + +### View package metadata + +To view information about a hardened package, including its provenance: + +```console +$ apk info -L +``` + +This shows the files included in the package and its metadata. + +### Verify package signatures + +Hardened packages are cryptographically signed by Docker. When you install the +signing keys and configure your package manager as described previously, the +package manager automatically verifies signatures during installation. + +If a package fails signature verification, the package manager will refuse to +install it, protecting you from tampered or compromised packages. + +### Build provenance and cryptographic verification + +Docker hardened packages are built by Docker's trusted infrastructure and include +verifiable metadata and cryptographic signatures. + +To view this metadata for an installed package: + +```console +$ apk info -a +``` + +Or to view metadata for a package before installing: + +```console +$ apk fetch --stdout | tar -xzO .PKGINFO +``` + +The package signing keys ensure that packages haven't been tampered with after +being built. When you install the signing key and configure your package manager, +all packages are automatically verified before installation. + +### Package attestations + +Each hardened package includes its own attestations, similar to [image +attestations](./verify.md). These attestations provide provenance and build +information for individual packages, allowing you to trace the supply chain down +to the package level. + +You can retrieve package attestations by first extracting package information +from the image's SLSA provenance, then using the package digest to access its +attestations. + +#### Extract package information from image attestations + +To get provenance information for a specific package from an image's SLSA +provenance attestation, you first need to retrieve the image's provenance and +then filter for the specific package you're interested in. + +The SLSA provenance attestation includes a `materials` array that lists all +build inputs, including packages. You can use `jq` to filter this array for a +specific package: + +```console +$ docker scout attest get dhi.io/golang:1.26-alpine3.23 \ + --predicate-type https://slsa.dev/provenance/v0.2 | \ + jq '.predicate.materials[] | select( .uri == "https://dhi.io/apk/alpine/v3.23/main/aarch64/golang-1.26-1.26.0-r0.apk" )' +``` + +Replace the package URI in the `select()` filter with the specific package +you're looking for. You can find available packages by first running the command +without the `select()` filter to see all materials. + +This returns the package URI and its SHA-256 digest: + +```json +{ + "uri": "https://dhi.io/apk/alpine/v3.23/main/aarch64/golang-1.26-1.26.0-r0.apk", + "digest": { + "sha256": "4082a2500abc2e7b8435f9398d3514d760044fa52ca3d10cf80015469124a838" + } +} +``` + +#### List attestations for a package + +Using the package digest from the previous section, you can list all available +attestations for that package: + +```console +$ curl -s https://dhi.io/apk/alpine/v3.23/main/sha256:4082a2500abc2e7b8435f9398d3514d760044fa52ca3d10cf80015469124a838/attestations/list | jq . +``` + +This returns information about the package and its available attestations: + +```json +{ + "subject": { + "name": "pkg:apk/alpine/golang-1.26@1.26.0-r0?os_name=&os_version=", + "digest": { + "sha256": "4082a2500abc2e7b8435f9398d3514d760044fa52ca3d10cf80015469124a838" + } + }, + "attestations": [ + { + "predicate_type": "https://slsa.dev/provenance/v1", + "digest": { + "sha256": "97c919cf0edb27087739bbabeea4c1ef88d069cd41791476ba64b69280d63a32" + }, + "url": "https://dhi.io/apk/alpine/v3.23/main/sha256:4082a2500abc2e7b8435f9398d3514d760044fa52ca3d10cf80015469124a838/attestations/sha256:97c919cf0edb27087739bbabeea4c1ef88d069cd41791476ba64b69280d63a32" + } + ] +} +``` + +#### Retrieve package attestations + +To retrieve the actual attestation content, use the URL provided in the +attestation list: + +```console +$ curl -s https://dhi.io/apk/alpine/v3.23/main/sha256:4082a2500abc2e7b8435f9398d3514d760044fa52ca3d10cf80015469124a838/attestations/sha256:97c919cf0edb27087739bbabeea4c1ef88d069cd41791476ba64b69280d63a32 | jq . +``` + +This returns the full SLSA provenance attestation for the package, which +includes information about how the package was built, its dependencies, and +other build materials. + +You can continue this process recursively to trace the supply chain all the way +down to the compiler and other build tools used to create the package. diff --git a/content/manuals/dhi/how-to/manage.md b/content/manuals/dhi/how-to/manage.md index 8c73e96d85bc..8bb99f635c52 100644 --- a/content/manuals/dhi/how-to/manage.md +++ b/content/manuals/dhi/how-to/manage.md @@ -12,6 +12,9 @@ On the **Manage** screen in Docker Hub, you can manage your mirrored Docker Hardened Image (DHI) repositories, mirrored DHI chart repositories, and customizations in your organization. +Alternatively, you can use the [DHI CLI](./cli.md) to manage mirrored +repositories and customizations from the command line. + Mirrored DHI repositories are standard Docker Hub repositories in your organization's namespace. They behave exactly like any other Hub repository, which means you can manage access and permissions, configure webhooks, and use diff --git a/content/manuals/dhi/how-to/mirror.md b/content/manuals/dhi/how-to/mirror.md index c3144d1f07f6..f44fcd0bd177 100644 --- a/content/manuals/dhi/how-to/mirror.md +++ b/content/manuals/dhi/how-to/mirror.md @@ -8,9 +8,9 @@ keywords: mirror docker image, private container registry, docker hub automation {{< summary-bar feature_name="Docker Hardened Images" >}} -Mirroring requires a DHI Enterprise subscription. Without a DHI Enterprise +Mirroring requires a DHI Select or Enterprise subscription. Without a subscription, you can pull Docker Hardened Images directly from `dhi.io` without -mirroring. With a DHI Enterprise subscription, you must mirror to get: +mirroring. With a DHI Select or Enterprise subscription, you must mirror to get: - Compliance variants (FIPS-enabled or STIG-ready images) - Extended Lifecycle Support (ELS) variants (requires add-on) @@ -55,7 +55,25 @@ Only organization owners can perform mirroring. Once mirrored, the repository becomes available in your organization's namespace, and you can customize it as needed. -To mirror a Docker Hardened Image repository: +You can mirror repositories using either the Docker Hub web interface or the DHI CLI. + +### Mirror using the DHI CLI + +The DHI CLI provides a command-line interface for managing Docker Hardened +Images, including mirroring operations. For installation instructions and usage +details, see [Use the DHI CLI](./cli.md#mirror-dhi-images). + +### Stop mirroring with the CLI + +```console +$ docker dhi mirror stop --org my-org dhi-golang +``` + +After stopping mirroring, the repository remains but will no longer receive updates. + +### Mirror using the Docker Hub web interface + +To mirror a Docker Hardened Image repository using the web interface: 1. Go to [Docker Hub](https://hub.docker.com) and sign in. 2. Select **My Hub**. diff --git a/content/manuals/dhi/how-to/use.md b/content/manuals/dhi/how-to/use.md index f0779de4ed64..a46f88459291 100644 --- a/content/manuals/dhi/how-to/use.md +++ b/content/manuals/dhi/how-to/use.md @@ -241,11 +241,11 @@ 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. -## Use compliance variants {tier="DHI Enterprise"} +## Use compliance variants {tier="DHI Select & Enterprise"} {{< summary-bar feature_name="Docker Hardened Images" >}} -When you have a Docker Hardened Images Enterprise subscription, you can access +When you have a DHI Select or DHI Enterprise subscription, you can access compliance variants such as FIPS-enabled and STIG-ready images. These variants help meet regulatory and compliance requirements for secure deployments. diff --git a/content/manuals/dhi/how-to/verify.md b/content/manuals/dhi/how-to/verify.md index 4cc51ae41947..35aeb9e00e56 100644 --- a/content/manuals/dhi/how-to/verify.md +++ b/content/manuals/dhi/how-to/verify.md @@ -294,6 +294,16 @@ Example output: > $ cosign verify ... > ``` +## Verify package attestations + +In addition to image attestations, individual hardened packages have their own +attestations. These package-level attestations allow you to verify the +provenance and build information for specific packages within an image. + +For instructions on how to extract package information from image attestations +and retrieve package-level attestations, see [Package +attestations](./hardened-packages.md#package-attestations). + ## Verify Helm chart attestations with Docker Scout Docker Hardened Image Helm charts include the same comprehensive attestations diff --git a/content/manuals/dhi/images/dhi-subscription.png b/content/manuals/dhi/images/dhi-subscription.png deleted file mode 100644 index b3cf48a7c563..000000000000 Binary files a/content/manuals/dhi/images/dhi-subscription.png and /dev/null differ diff --git a/content/manuals/dhi/images/dhi-tiers.png b/content/manuals/dhi/images/dhi-tiers.png new file mode 100644 index 000000000000..43e568caaaef Binary files /dev/null and b/content/manuals/dhi/images/dhi-tiers.png differ diff --git a/content/manuals/dhi/resources.md b/content/manuals/dhi/resources.md index 2191328fbf23..f25b3f0b16ab 100644 --- a/content/manuals/dhi/resources.md +++ b/content/manuals/dhi/resources.md @@ -54,20 +54,22 @@ organization: keys and verification tools - [Log](https://github.com/docker-hardened-images/log): Log of references (tag > digest) for Docker Hardened Images +- [dhictl](https://github.com/docker-hardened-images/dhictl): Command-line + interface for managing and interacting with Docker Hardened Images - [Discussions](https://github.com/orgs/docker-hardened-images/discussions): Community forum and product discussions ## Additional resources - [Start a free trial](https://hub.docker.com/hardened-images/start-free-trial): - Explore DHI Enterprise features including FIPS/STIG variants, customization, + Explore DHI Select and Enterprise features including FIPS/STIG variants, customization, and SLA-backed support - [Request a demo](https://www.docker.com/products/hardened-images/#getstarted): Get a - personalized demo and information about DHI Enterprise subscriptions + personalized demo and information about DHI Select and Enterprise subscriptions - [Request an image](https://github.com/docker-hardened-images/catalog/issues): Submit a request for a specific Docker Hardened Image - [Contact Sales](https://www.docker.com/pricing/contact-sales/): Connect with Docker sales team for enterprise inquiries - [Docker Support](https://www.docker.com/support/): Access support resources - for DHI Enterprise customers + for DHI Select and Enterprise customers diff --git a/data/cli/dhi/docker_dhi.yaml b/data/cli/dhi/docker_dhi.yaml new file mode 100644 index 000000000000..73b4aa2457ce --- /dev/null +++ b/data/cli/dhi/docker_dhi.yaml @@ -0,0 +1,24 @@ +command: docker dhi +short: CLI for managing Docker Hardened Images +long: |- + command-line interface for administering Docker Hardened Images. + It provides commands to browse the DHI catalog, mirror images into your organisations and manage customizations. +pname: docker +plink: docker.yaml +cname: + - docker dhi auth + - docker dhi catalog + - docker dhi customization + - docker dhi mirror +clink: + - docker_dhi_auth.yaml + - docker_dhi_catalog.yaml + - docker_dhi_customization.yaml + - docker_dhi_mirror.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_auth.yaml b/data/cli/dhi/docker_dhi_auth.yaml new file mode 100644 index 000000000000..59412ee6a634 --- /dev/null +++ b/data/cli/dhi/docker_dhi_auth.yaml @@ -0,0 +1,16 @@ +command: docker dhi auth +short: Authenticate with Docker Hub +long: Commands to authenticate with Docker Hub +pname: docker dhi +plink: docker_dhi.yaml +cname: + - docker dhi auth apk +clink: + - docker_dhi_auth_apk.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_auth_apk.yaml b/data/cli/dhi/docker_dhi_auth_apk.yaml new file mode 100644 index 000000000000..6eed620942a0 --- /dev/null +++ b/data/cli/dhi/docker_dhi_auth_apk.yaml @@ -0,0 +1,13 @@ +command: docker dhi auth apk +short: Create authentication details for DHI APK repositories +long: Create authentication details for DHI APK repositories +usage: docker dhi auth apk +pname: docker dhi auth +plink: docker_dhi_auth.yaml +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_catalog.yaml b/data/cli/dhi/docker_dhi_catalog.yaml new file mode 100644 index 000000000000..ab3c3b720501 --- /dev/null +++ b/data/cli/dhi/docker_dhi_catalog.yaml @@ -0,0 +1,28 @@ +command: docker dhi catalog +short: Browse the Docker Hardened Images catalog +long: Commands to browse available Docker Hardened Images and Helm charts +pname: docker dhi +plink: docker_dhi.yaml +cname: + - docker dhi catalog get + - docker dhi catalog list +clink: + - docker_dhi_catalog_get.yaml + - docker_dhi_catalog_list.yaml +options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_catalog_get.yaml b/data/cli/dhi/docker_dhi_catalog_get.yaml new file mode 100644 index 000000000000..9bbdd17ca611 --- /dev/null +++ b/data/cli/dhi/docker_dhi_catalog_get.yaml @@ -0,0 +1,35 @@ +command: docker dhi catalog get +short: Get details of a Docker Hardened Image +long: | + Get detailed information about a Docker Hardened Image or Helm chart, including available tags and CVE counts +usage: docker dhi catalog get +pname: docker dhi catalog +plink: docker_dhi_catalog.yaml +options: + - option: json + value_type: bool + default_value: "false" + description: Output in JSON format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_catalog_list.yaml b/data/cli/dhi/docker_dhi_catalog_list.yaml new file mode 100644 index 000000000000..a98e2625d1e6 --- /dev/null +++ b/data/cli/dhi/docker_dhi_catalog_list.yaml @@ -0,0 +1,73 @@ +command: docker dhi catalog list +short: List available Docker Hardened Images +long: List all available Docker Hardened Images and Helm charts in the catalog +usage: docker dhi catalog list +pname: docker dhi catalog +plink: docker_dhi_catalog.yaml +options: + - option: filter + shorthand: f + value_type: string + description: Filter by name (case-insensitive substring match) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: fips + value_type: bool + default_value: "false" + description: Filter to FIPS compliant images (use --fips=false to exclude) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: json + value_type: bool + default_value: "false" + description: Output in JSON format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: stig + value_type: bool + default_value: "false" + description: Filter to STIG certified images (use --stig=false to exclude) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: type + value_type: string + description: Filter by type (image, helm, chart, or helm-chart) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_customization.yaml b/data/cli/dhi/docker_dhi_customization.yaml new file mode 100644 index 000000000000..a710aaa284f0 --- /dev/null +++ b/data/cli/dhi/docker_dhi_customization.yaml @@ -0,0 +1,39 @@ +command: docker dhi customization +short: Manage Docker Hardened Images customizations +long: | + Commands to list, create, edit, and delete Docker Hardened Images customizations +pname: docker dhi +plink: docker_dhi.yaml +cname: + - docker dhi customization build + - docker dhi customization create + - docker dhi customization delete + - docker dhi customization edit + - docker dhi customization get + - docker dhi customization list + - docker dhi customization prepare +clink: + - docker_dhi_customization_build.yaml + - docker_dhi_customization_create.yaml + - docker_dhi_customization_delete.yaml + - docker_dhi_customization_edit.yaml + - docker_dhi_customization_get.yaml + - docker_dhi_customization_list.yaml + - docker_dhi_customization_prepare.yaml +options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_customization_build.yaml b/data/cli/dhi/docker_dhi_customization_build.yaml new file mode 100644 index 000000000000..5cab2fd36f7b --- /dev/null +++ b/data/cli/dhi/docker_dhi_customization_build.yaml @@ -0,0 +1,30 @@ +command: docker dhi customization build +short: Manage customization builds +long: Commands to manage Docker Hardened Images customization builds +pname: docker dhi customization +plink: docker_dhi_customization.yaml +cname: + - docker dhi customization build get + - docker dhi customization build list + - docker dhi customization build logs +clink: + - docker_dhi_customization_build_get.yaml + - docker_dhi_customization_build_list.yaml + - docker_dhi_customization_build_logs.yaml +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_customization_build_get.yaml b/data/cli/dhi/docker_dhi_customization_build_get.yaml new file mode 100644 index 000000000000..60a2dab345b2 --- /dev/null +++ b/data/cli/dhi/docker_dhi_customization_build_get.yaml @@ -0,0 +1,35 @@ +command: docker dhi customization build get +short: Get details of a build +long: | + Get detailed information about a Docker Hardened Images customization build +usage: docker dhi customization build get +pname: docker dhi customization build +plink: docker_dhi_customization_build.yaml +options: + - option: json + value_type: bool + default_value: "false" + description: Output in JSON format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_customization_build_list.yaml b/data/cli/dhi/docker_dhi_customization_build_list.yaml new file mode 100644 index 000000000000..7933657c3919 --- /dev/null +++ b/data/cli/dhi/docker_dhi_customization_build_list.yaml @@ -0,0 +1,35 @@ +command: docker dhi customization build list +short: List builds of a customization +long: | + List all builds of a Docker Hardened Images customization by repository and name +usage: docker dhi customization build list +pname: docker dhi customization build +plink: docker_dhi_customization_build.yaml +options: + - option: json + value_type: bool + default_value: "false" + description: Output in JSON format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_customization_build_logs.yaml b/data/cli/dhi/docker_dhi_customization_build_logs.yaml new file mode 100644 index 000000000000..3a5afe133545 --- /dev/null +++ b/data/cli/dhi/docker_dhi_customization_build_logs.yaml @@ -0,0 +1,34 @@ +command: docker dhi customization build logs +short: Get logs of a build +long: Get the logs of a Docker Hardened Images customization build +usage: docker dhi customization build logs +pname: docker dhi customization build +plink: docker_dhi_customization_build.yaml +options: + - option: json + value_type: bool + default_value: "false" + description: Output in JSON format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_customization_create.yaml b/data/cli/dhi/docker_dhi_customization_create.yaml new file mode 100644 index 000000000000..43921a97317f --- /dev/null +++ b/data/cli/dhi/docker_dhi_customization_create.yaml @@ -0,0 +1,24 @@ +command: docker dhi customization create +short: Create a new customization from YAML file +long: | + Create a new Docker Hardened Images customization using a YAML file as input. The file should contain the complete customization structure without an 'id' field. +usage: docker dhi customization create +pname: docker dhi customization +plink: docker_dhi_customization.yaml +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_customization_delete.yaml b/data/cli/dhi/docker_dhi_customization_delete.yaml new file mode 100644 index 000000000000..cd0f98668470 --- /dev/null +++ b/data/cli/dhi/docker_dhi_customization_delete.yaml @@ -0,0 +1,35 @@ +command: docker dhi customization delete +short: Delete a customization +long: Delete a Docker Hardened Images customization by repository and name +usage: docker dhi customization delete +pname: docker dhi customization +plink: docker_dhi_customization.yaml +options: + - option: "yes" + shorthand: "y" + value_type: bool + default_value: "false" + description: Skip confirmation prompt + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_customization_edit.yaml b/data/cli/dhi/docker_dhi_customization_edit.yaml new file mode 100644 index 000000000000..ca05bc1703a2 --- /dev/null +++ b/data/cli/dhi/docker_dhi_customization_edit.yaml @@ -0,0 +1,25 @@ +command: docker dhi customization edit +aliases: docker dhi customization edit, docker dhi customization update +short: Edit an existing customization from YAML file +long: | + Edit an existing Docker Hardened Images customization using a YAML file as input. The file should contain the complete customization structure with an 'id' field to identify which customization to update. +usage: docker dhi customization edit +pname: docker dhi customization +plink: docker_dhi_customization.yaml +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_customization_get.yaml b/data/cli/dhi/docker_dhi_customization_get.yaml new file mode 100644 index 000000000000..3c9c2484cc0d --- /dev/null +++ b/data/cli/dhi/docker_dhi_customization_get.yaml @@ -0,0 +1,35 @@ +command: docker dhi customization get +short: Get details of a specific customization +long: | + Get detailed information about a Docker Hardened Images customization by repository and name. Outputs YAML to stdout by default, or to file if --output is specified. +usage: docker dhi customization get +pname: docker dhi customization +plink: docker_dhi_customization.yaml +options: + - option: output + shorthand: o + value_type: string + description: Output file path (if not specified, outputs to stdout) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_customization_list.yaml b/data/cli/dhi/docker_dhi_customization_list.yaml new file mode 100644 index 000000000000..c9879525a147 --- /dev/null +++ b/data/cli/dhi/docker_dhi_customization_list.yaml @@ -0,0 +1,64 @@ +command: docker dhi customization list +short: List all customizations +long: List all Docker Hardened Images customizations +usage: docker dhi customization list +pname: docker dhi customization +plink: docker_dhi_customization.yaml +options: + - option: filter + shorthand: f + value_type: string + description: Filter by customization name (case-insensitive substring match) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: json + value_type: bool + default_value: "false" + description: Output in JSON format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: repo + shorthand: r + value_type: string + description: | + Filter by destination repository (case-insensitive substring match) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: source + value_type: string + description: Filter by DHI source repository (case-insensitive substring match) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_customization_prepare.yaml b/data/cli/dhi/docker_dhi_customization_prepare.yaml new file mode 100644 index 000000000000..555645b32078 --- /dev/null +++ b/data/cli/dhi/docker_dhi_customization_prepare.yaml @@ -0,0 +1,72 @@ +command: docker dhi customization prepare +short: Prepare a new customization YAML file from a DHI base image tag +long: |- + Prepare a new customization YAML file by fetching tag details from a Docker Hardened Images repository. + This creates a scaffold YAML file that can be used with the create command. + + The repository argument must be a DHI source repository name, not a mirrored destination repository. + Supported formats: + - golang + - dhi/golang + - dhi.io/golang +usage: docker dhi customization prepare +pname: docker dhi customization +plink: docker_dhi_customization.yaml +options: + - option: destination + shorthand: d + value_type: string + description: Destination repository (e.g. myorg/dhi-golang) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: name + shorthand: "n" + value_type: string + description: Name for the customization + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: output + shorthand: o + value_type: string + description: Output file path (if not specified, outputs to stdout) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: tag-suffix + shorthand: t + value_type: string + description: Tag suffix for the customized image + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_mirror.yaml b/data/cli/dhi/docker_dhi_mirror.yaml new file mode 100644 index 000000000000..2df250c938c4 --- /dev/null +++ b/data/cli/dhi/docker_dhi_mirror.yaml @@ -0,0 +1,30 @@ +command: docker dhi mirror +short: Mirror Docker Hardened Images to your organization +long: Commands to mirror Docker Hardened Images to your organization's registry +pname: docker dhi +plink: docker_dhi.yaml +cname: + - docker dhi mirror list + - docker dhi mirror start + - docker dhi mirror stop +clink: + - docker_dhi_mirror_list.yaml + - docker_dhi_mirror_start.yaml + - docker_dhi_mirror_stop.yaml +options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_mirror_list.yaml b/data/cli/dhi/docker_dhi_mirror_list.yaml new file mode 100644 index 000000000000..58d3f93f2b11 --- /dev/null +++ b/data/cli/dhi/docker_dhi_mirror_list.yaml @@ -0,0 +1,72 @@ +command: docker dhi mirror list +short: List all mirrored Docker Hardened Images +long: |- + List all Docker Hardened Images currently being mirrored to your organization's registry. + + Shows the source repositories, destination repositories, and mirroring status. + + Examples: + # List all mirrored repositories + dhictl mirror list --org myorg + + # List only image repositories + dhictl mirror list --org myorg --type image + + # List only helm chart repositories + dhictl mirror list --org myorg --type helm-chart + + # Search for a specific repository by name + dhictl mirror list --org myorg --filter dhi-python + + # Output in JSON format + dhictl mirror list --org myorg --json +usage: docker dhi mirror list +pname: docker dhi mirror +plink: docker_dhi_mirror.yaml +options: + - option: filter + shorthand: f + value_type: string + description: Filter by repository name (partial match) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: json + value_type: bool + default_value: "false" + description: Output in JSON format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: type + value_type: string + description: Filter by repository type (image or helm-chart) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_mirror_start.yaml b/data/cli/dhi/docker_dhi_mirror_start.yaml new file mode 100644 index 000000000000..cc9cda4ff702 --- /dev/null +++ b/data/cli/dhi/docker_dhi_mirror_start.yaml @@ -0,0 +1,77 @@ +command: docker dhi mirror start +short: Start mirroring Docker Hardened Images +long: |- + Start mirroring one or more Docker Hardened Images to your organization's registry. + + Repository mappings are specified using the -r flag. The following formats are supported: + + source Only the source repository; destination is auto-generated as + /dhi- + source,destination Source and destination; namespaces are filled from config if omitted + ns/source,ns/dest Fully qualified source and destination + + The source namespace defaults to "dhi" when not specified. + The destination namespace defaults to the configured organization (--org or config). + + Examples: + # These are all equivalent (assuming --org myorg): + dhictl mirror start --org myorg -r dhi/golang,myorg/dhi-golang + dhictl mirror start --org myorg -r golang,dhi-golang + dhictl mirror start --org myorg -r golang + + # Mirror multiple repositories + dhictl mirror start --org myorg -r golang -r python +usage: docker dhi mirror start +pname: docker dhi mirror +plink: docker_dhi_mirror.yaml +options: + - option: dependencies + shorthand: d + value_type: bool + default_value: "false" + description: Mirrors any existing dependencies + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: json + value_type: bool + default_value: "false" + description: Output in JSON format + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false + - option: repo + shorthand: r + value_type: stringArray + default_value: '[]' + description: | + Repository mapping in format source,destination (can be specified multiple times) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/cli/dhi/docker_dhi_mirror_stop.yaml b/data/cli/dhi/docker_dhi_mirror_stop.yaml new file mode 100644 index 000000000000..555bb7e4114f --- /dev/null +++ b/data/cli/dhi/docker_dhi_mirror_stop.yaml @@ -0,0 +1,49 @@ +command: docker dhi mirror stop +short: Stop mirroring a Docker Hardened Image +long: |- + Stop mirroring a Docker Hardened Image repository. + + The repository can be specified as: + - Just the repository name (e.g., dhi-python) - uses --org flag or config + - Full path with org (e.g., myorg/dhi-python) - org must match --org flag or config + + Examples: + # Stop mirroring using --org flag + dhictl mirror stop dhi-python --org myorg + + # Stop mirroring with full path (org must match) + dhictl mirror stop myorg/dhi-python --org myorg + + # Stop mirroring and delete the repository + dhictl mirror stop dhi-python --org myorg --delete +usage: docker dhi mirror stop +pname: docker dhi mirror +plink: docker_dhi_mirror.yaml +options: + - option: delete + value_type: bool + default_value: "false" + description: Delete the repository after stopping mirroring + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +inherited_options: + - option: org + value_type: string + description: Docker Hub organization (overrides config) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +deprecated: false +hidden: false +experimental: false +experimentalcli: false +kubernetes: false +swarm: false + diff --git a/data/summary.yaml b/data/summary.yaml index 89d2f36c767d..372286c657fe 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -172,7 +172,7 @@ Docker Desktop CLI kubernetes: Docker Desktop CLI diagnose: requires: Docker Desktop 4.60 and later Docker Hardened Images: - subscription: [Docker Hardened Images Enterprise] + subscription: [Docker Hardened Images Select or Enterprise] Docker Init: requires: Docker Desktop [4.27](/manuals/desktop/release-notes.md#4270) and later Docker Model Runner: diff --git a/layouts/_shortcodes/summary-bar.html b/layouts/_shortcodes/summary-bar.html index d0cfe213254f..6a0c5b60f45f 100644 --- a/layouts/_shortcodes/summary-bar.html +++ b/layouts/_shortcodes/summary-bar.html @@ -11,6 +11,7 @@ "Personal" "person" "Available to all" "public" "Docker Hardened Images Enterprise" "/icons/dhi.svg" + "Docker Hardened Images Select or Enterprise" "/icons/dhi.svg" }} {{ $availabilityIcons := dict "Experimental" "science"