diff --git a/content/manuals/dhi/how-to/cli.md b/content/manuals/dhi/how-to/cli.md index 7d1618d0d84..9cec3948681 100644 --- a/content/manuals/dhi/how-to/cli.md +++ b/content/manuals/dhi/how-to/cli.md @@ -8,6 +8,7 @@ description: Learn how to install and use docker dhi, the command-line interface The `docker dhi` command-line interface (CLI) is a tool for managing Docker Hardened Images: - Browse the catalog of available DHI images and their metadata +- View attestations for DHI images, including SBOMs and provenance - Mirror DHI images to your Docker Hub organization - Create and manage customizations of DHI images - Generate authentication for enterprise package repositories @@ -34,32 +35,57 @@ The `docker dhi` command is included in Docker Desktop 4.65 and later. No additi Every command has built-in help accessible with the `--help` flag: -```bash -docker dhi --help -docker dhi catalog list --help +```console +$ docker dhi --help +$ docker dhi catalog list --help ``` ### Browse the DHI catalog List all available DHI images: -```bash -docker dhi catalog list +```console +$ docker dhi catalog list ``` Filter by type, name, or compliance: -```bash -docker dhi catalog list --type image -docker dhi catalog list --filter golang -docker dhi catalog list --fips -docker dhi catalog list --stig +```console +$ docker dhi catalog list --type image +$ docker dhi catalog list --filter golang +$ docker dhi catalog list --fips +$ docker dhi catalog list --stig ``` Get details of a specific image, including available tags and CVE counts: -```bash -docker dhi catalog get +```console +$ docker dhi catalog get +``` + +### View attestations + +List all attestations attached to a DHI image: + +```console +$ docker dhi attestation list dhi/nginx:1.27 +$ docker dhi attestation list dhi/nginx:1.27 --platform linux/amd64 +$ docker dhi attestation list dhi/nginx:1.27 --predicate-type https://slsa.dev/provenance/v1 +$ docker dhi attestation list dhi/nginx:1.27 --json +``` + +Get a specific attestation by its referrer digest: + +```console +$ docker dhi attestation get dhi/nginx:1.27 sha256: +$ docker dhi attestation get dhi/nginx:1.27 sha256: -o provenance.json +``` + +Display the SPDX SBOM for an image: + +```console +$ docker dhi attestation sbom dhi/nginx:1.27 +$ docker dhi attestation sbom dhi/nginx:1.27 --platform linux/amd64 ``` ### Mirror DHI images @@ -68,45 +94,45 @@ docker dhi catalog get Start mirroring one or more DHI images to your Docker Hub organization: -```bash -docker dhi 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 +```console +$ docker dhi mirror start --org my-org \ + dhi/golang,my-org/dhi-golang \ + dhi/nginx,my-org/dhi-nginx \ + dhi/prometheus-chart,my-org/dhi-prometheus-chart ``` Mirror with dependencies: -```bash -docker dhi mirror start --org my-org -r dhi/golang,my-org/dhi-golang --dependencies +```console +$ docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang --dependencies ``` List mirrored images in your organization: -```bash -docker dhi mirror list --org my-org +```console +$ docker dhi mirror list --org my-org ``` Filter mirrored images by name or type: -```bash -docker dhi mirror list --org my-org --filter python -docker dhi mirror list --org my-org --type image -docker dhi mirror list --org my-org --type helm-chart +```console +$ docker dhi mirror list --org my-org --filter python +$ docker dhi mirror list --org my-org --type image +$ docker dhi mirror list --org my-org --type helm-chart ``` Stop mirroring one or more images: -```bash -docker dhi mirror stop dhi-golang --org my-org -docker dhi mirror stop dhi-python dhi-golang --org my-org +```console +$ docker dhi mirror stop dhi-golang --org my-org +$ docker dhi mirror stop dhi-python dhi-golang --org my-org ``` Stop mirroring and delete the repositories: -```bash -docker dhi mirror stop dhi-golang --org my-org --delete -docker dhi mirror stop dhi-golang --org my-org --delete --force +```console +$ docker dhi mirror stop dhi-golang --org my-org --delete +$ docker dhi mirror stop dhi-golang --org my-org --delete --force ``` ### Customize DHI images @@ -121,39 +147,55 @@ The following is a quick reference for CLI commands. For complete details on all options and flags, see the [CLI reference](/reference/cli/docker/dhi/). -```bash -# Prepare a customization scaffold -docker dhi customization prepare golang 1.25 \ +```console +# Prepare a single customization scaffold +$ docker dhi customization prepare golang 1.25 \ --org my-org \ --destination my-org/dhi-golang \ --name "golang with git" \ - --output my-customization.yaml + > my-customization.yaml + +# Prepare a bulk customization scaffold (pipe JSON array via stdin) +$ echo '[{"destination":"my-org/dhi-golang","tag-definition-id":"golang/alpine-3.23/1.24-dev"}]' \ + | docker dhi customization prepare --name "golang with git" --org my-org \ + > my-customization.yaml # Create a customization -docker dhi customization create my-customization.yaml --org my-org +$ docker dhi customization create my-customization.yaml --org my-org + +# Create with flag overrides (flags take precedence over the YAML file) +$ docker dhi customization create my-customization.yaml --org my-org \ + --destination my-org/dhi-golang \ + --name "golang with git" # List customizations -docker dhi customization list --org my-org +$ docker dhi customization list --org my-org # Filter customizations by name, repository, or source -docker dhi customization list --org my-org --filter git -docker dhi customization list --org my-org --repo dhi-golang -docker dhi customization list --org my-org --source golang +$ docker dhi customization list --org my-org --filter git +$ docker dhi customization list --org my-org --repo dhi-golang +$ docker dhi customization list --org my-org --source golang -# Get a customization -docker dhi customization get my-org/dhi-golang "golang with git" --org my-org --output my-customization.yaml +# Get a customization by ID +$ docker dhi customization get --org my-org # Update a customization # The YAML file must include the 'id' field to identify the customization to update -docker dhi customization edit my-customization.yaml --org my-org +$ docker dhi customization edit my-customization.yaml --org my-org + +# Delete a customization by ID +$ docker dhi customization delete --org my-org -# Delete a customization -docker dhi customization delete my-org/dhi-golang "golang with git" --org my-org +# Delete multiple customizations +$ docker dhi customization delete --org my-org # Delete without confirmation prompt -docker dhi customization delete my-org/dhi-golang "golang with git" --org my-org --yes +$ docker dhi customization delete --org my-org --force ``` +For a complete reference of all YAML fields, see +[Image customization YAML file](/dhi/how-to/customize/#image-customization-yaml-file). + ### Enterprise package authentication {{< summary-bar feature_name="Docker Hardened Images Enterprise" >}} @@ -164,8 +206,8 @@ install compliance-specific packages in your own images. For detailed instructions, see [Enterprise repository](./hardened-packages.md#enterprise-repository). -```bash -docker dhi auth apk +```console +$ docker dhi auth apk ``` ### Monitor customization builds @@ -174,36 +216,37 @@ docker dhi auth apk List builds for a customization: -```bash -docker dhi customization build list my-org/dhi-golang "golang with git" --org my-org -docker dhi customization build list my-org/dhi-golang "golang with git" --org my-org --json +```console +$ docker dhi customization build list --org my-org +$ docker dhi customization build list --org my-org --json ``` Get details of a specific build: -```bash -docker dhi customization build get my-org/dhi-golang "golang with git" --org my-org -docker dhi customization build get my-org/dhi-golang "golang with git" --org my-org --json +```console +$ docker dhi customization build get --org my-org +$ docker dhi customization build get --org my-org --json ``` View build logs: -```bash -docker dhi customization build logs my-org/dhi-golang "golang with git" --org my-org -docker dhi customization build logs my-org/dhi-golang "golang with git" --org my-org --json +```console +$ docker dhi customization build logs --org my-org +$ docker dhi customization build logs --org my-org --json ``` ### JSON output Most list and get commands support a `--json` flag for machine-readable output: -```bash -docker dhi catalog list --json -docker dhi catalog get golang --json -docker dhi mirror list --org my-org --json -docker dhi mirror start --org my-org -r golang --json -docker dhi customization list --org my-org --json -docker dhi customization build list my-org/dhi-golang "golang with git" --org my-org --json +```console +$ docker dhi catalog list --json +$ docker dhi catalog get golang --json +$ docker dhi attestation list dhi/nginx:1.27 --json +$ docker dhi mirror list --org my-org --json +$ docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang --json +$ docker dhi customization list --org my-org --json +$ docker dhi customization build list --org my-org --json ``` ## Configuration diff --git a/content/manuals/dhi/how-to/customize.md b/content/manuals/dhi/how-to/customize.md index 79795d15f60..0f6e2374bb0 100644 --- a/content/manuals/dhi/how-to/customize.md +++ b/content/manuals/dhi/how-to/customize.md @@ -4,6 +4,7 @@ linkTitle: Customize an image or chart weight: 25 keywords: hardened images, DHI, customize, certificate, artifact, helm chart, terraform, infrastructure as code description: Learn how to customize Docker Hardened Images (DHI) and charts. +toc_max: 4 --- {{< summary-bar feature_name="Docker Hardened Images" >}} @@ -81,7 +82,7 @@ You can create customizations using either the DHI CLI or the Docker Hub web int DHI. For example, you can add a custom root CA certificate or another image that contains a tool you need, like adding Python to a Node.js image. For more details on how to create an OCI artifact image, see - [Create an OCI artifact image](#create-an-oci-artifact-image-for-image-customization). + [Create an OCI artifact image](#create-an-oci-artifact-image). You can add multiple OCI artifact images to a single customization. When you add more than one, they're applied in the order you add them in the @@ -158,7 +159,7 @@ You can create customizations using either the DHI CLI or the Docker Hub web int {{< /tab >}} {{< tab name="CLI" >}} -Authenticate with `docker login` using your Docker credentials, a [personal +Authenticate with `docker login` using your Docker credentials or a [personal access token (PAT)](../../security/access-tokens.md) with **Read & Write** permissions, or an [organization access token (OAT)](../../enterprise/security/access-tokens.md). When using an OAT, the @@ -174,12 +175,17 @@ available operations depend on the token's permission scope: Use the [`docker dhi customization`](/reference/cli/docker/dhi/customization/) command: ```console -# Prepare a customization scaffold +# Prepare a single customization scaffold $ docker dhi customization prepare golang 1.25 \ --org my-org \ --destination my-org/dhi-golang \ --name "golang with git" \ - --output my-customization.yaml + > my-customization.yaml + +# Prepare a bulk customization scaffold (pipe JSON array via stdin) +$ echo '[{"destination":"my-org/dhi-golang","tag-definition-id":"golang/alpine-3.23/1.24-dev"}]' \ + | docker dhi customization prepare --name "golang with git" --org my-org \ + > my-customization.yaml # Create a customization $ docker dhi customization create my-customization.yaml --org my-org @@ -192,19 +198,22 @@ $ docker dhi customization list --org my-org --filter git $ docker dhi customization list --org my-org --repo dhi-golang $ docker dhi customization list --org my-org --source golang -# Get a customization -$ docker dhi customization get my-org/dhi-golang "golang with git" --org my-org --output my-customization.yaml +# Get a customization by ID +$ docker dhi customization get --org my-org # Update a customization $ docker dhi customization edit my-customization.yaml --org my-org -# Delete a customization -$ docker dhi customization delete my-org/dhi-golang "golang with git" --org my-org +# Delete a customization by ID +$ docker dhi customization delete --org my-org # Delete without confirmation prompt -$ docker dhi customization delete my-org/dhi-golang "golang with git" --org my-org --yes +$ docker dhi customization delete --org my-org --force ``` +For a complete reference of all YAML fields, see +[Image customization YAML file](#image-customization-yaml-file). + {{< /tab >}} {{< tab name="Terraform" >}} @@ -252,42 +261,227 @@ documentation](https://registry.terraform.io/providers/docker-hardened-images/dh {{< /tab >}} {{< /tabs >}} -### Monitor customization builds +### Image customization YAML file -{{< tabs >}} -{{< tab name="Docker Hub" >}} +When using the CLI, customizations are defined in a YAML file. Use +`docker dhi customization prepare` to generate a scaffold with all available +fields and commented-out examples. Edit the file to describe what you want, +then pass it to `docker dhi customization create`. -1. Sign in to [Docker Hub](https://hub.docker.com). -2. Select **My Hub**. -3. In the namespace drop-down, select your organization. -4. Select **Hardened Images** > **Manage**. -5. Select the **Customizations** tab. +The file has two parts: a preamble that identifies the customization and +its targets, and a configuration section that specifies what to change. -{{< /tab >}} -{{< tab name="CLI" >}} +#### About the `id` field -List builds for a customization: +The `id` field is assigned automatically by Docker Hub when you run +`docker dhi customization create`. When creating a new customization, omit +`id` entirely. It is read-only. + +To find the ID of an existing customization, run: ```console -$ docker dhi customization build list my-org/dhi-golang "golang with git" --org my-org +$ docker dhi customization list --org my-org ``` -Get details of a specific build: +The `id` appears in the output and in files retrieved with +`docker dhi customization get --org my-org`. It lets +`docker dhi customization edit` identify which customization to update. +Scaffolds from `docker dhi customization prepare` do not include `id`, and +that is expected. -```console -$ docker dhi customization build get my-org/dhi-golang "golang with git" --org my-org +#### Set targets + +The `name` and `targets` fields are required in every customization file. The +`targets` array specifies which image versions the customization applies to. +Use a single entry for a single-image customization, or multiple entries for a +bulk customization that applies the same configuration to several images at +once. + +```yaml +name: golang with git + +targets: + - destination: my-org/dhi-golang + tag_definition_id: golang/alpine-3.23/1.25 ``` -View build logs: +| Field | Description | +|:---|:---| +| `name` | Human-readable name. Converted to lowercase and hyphenated, it becomes the image tag suffix. For example, `golang with git` produces tags ending in `_golang-with-git`. | +| `targets[].destination` | Destination repository in Docker Hub, such as `my-org/dhi-golang`. | +| `targets[].tag_definition_id` | Tag definition to customize, such as `golang/alpine-3.23/1.25`. Use `docker dhi customization prepare` with tab completion to find valid values. | -```console -$ docker dhi customization build logs my-org/dhi-golang "golang with git" --org my-org +> [!NOTE] +> +> When `targets` has more than one entry, the fields `accounts`, `entrypoint`, +> and `cmd` are not supported. Including them causes `docker dhi customization +> create` to return an error. + +#### Add packages + +To install additional OS packages in your customized image, list them under +`contents.packages`. Available packages depend on the base image variant. + +```yaml +contents: + packages: + - git + - curl ``` -{{< /tab >}} -{{< /tabs >}} +#### Add OCI artifacts + +To layer additional files into your customized image, such as custom +certificates, internal tools, or configuration files, list OCI artifact +images under `contents.artifacts`. + +```yaml +contents: + artifacts: + - name: my-org/my-certs:latest + includes: + - etc/ssl/certs + excludes: + - etc/ssl/certs/old +``` + +| Field | Description | +|:---|:---| +| `name` | Image reference of the OCI artifact. Must be in the same Docker Hub namespace as the mirrored DHI. | +| `includes` | Paths to copy from the artifact. No files are included by default. You must list at least one path. | +| `excludes` | Paths to exclude after applying `includes`. | + +For instructions on building an OCI artifact image, see +[Create an OCI artifact image](#create-an-oci-artifact-image). + +#### Inject files into the image + +To add static files at build time, such as configuration files or startup +scripts, use the `paths` field. Files are added as static content and are not +executed during the build. + +```yaml +paths: + - path: /etc/myconfig + contents: | + key=value + mode: "0644" + uid: 0 + gid: 0 +``` + +| Field | Description | +|:---|:---| +| `path` | Absolute path where the file will be placed in the image. | +| `contents` | File content. Use a YAML block scalar (`\|`) for multi-line content. | +| `mode` | Octal file permissions, such as `"0644"`. Quote the value to prevent YAML from treating the leading zero as octal notation. | +| `uid` | User ID of the file owner. | +| `gid` | Group ID of the file owner. | + +#### Configure user accounts + +To add users or groups to the image, or to change which user the container +runs as, use the `accounts` field. + +> [!NOTE] +> +> Not supported for bulk customizations (multiple `targets`). + +```yaml +accounts: + root: true + runs-as: nonroot + users: + - name: nonroot + uid: 65532 + gid: 65532 + groups: + - name: nonroot + gid: 65532 + members: + - nonroot +``` + +| Field | Description | +|:---|:---| +| `root` | Whether to enable the root user. Default is `false`. Required if `runs-as` is set to `root`. | +| `runs-as` | The default user the container runs as. | +| `users[].name` | Username. | +| `users[].uid` | User ID. | +| `users[].gid` | Primary group ID. Optional. | +| `groups[].name` | Group name. | +| `groups[].gid` | Group ID. | +| `groups[].members` | Usernames to add to this group. Optional. | + +#### Set environment variables + +To add or override environment variables in the image, use the `environment` +field. These are merged with the base image's existing environment and do not +replace it. + +```yaml +environment: + MY_VAR: my_value + DEBUG: "false" +``` + +Quote values that a YAML parser would interpret as non-string types, for +example `"false"`, `"0"`, and `"null"`. + +#### Set labels and annotations + +To add OCI metadata to the image, use `labels` and `annotations`. Labels are +stored in the image config; annotations are stored in the image manifest. Use +[OCI standard keys](https://specs.opencontainers.org/image-spec/annotations/) +where applicable. + +```yaml +labels: + org.opencontainers.image.authors: your-email@example.com + org.opencontainers.image.version: "1.0.0" + +annotations: + org.opencontainers.image.title: Custom hardened image + org.opencontainers.image.description: Customized Docker Hardened Image +``` + +#### Override entrypoint and command + +To change how the container starts, use `entrypoint` and `cmd`. These arguments +are appended to the base image's existing entrypoint and command. + +> [!NOTE] +> +> Not supported for bulk customizations (multiple `targets`). + +```yaml +entrypoint: + - /docker-entrypoint.sh + +cmd: + - /bin/bash +``` + +#### Set platforms and compression + +To build for multiple architectures, list them under `platforms`. At least one +platform is required. + +```yaml +platforms: + - linux/amd64 + - linux/arm64 +``` + +To control layer compression, set `compression`. `ZSTD` (the default) offers +better compression and faster pulls. Use `GZIP` for compatibility with older +tooling. -### Create an OCI artifact image for image customization +```yaml +compression: ZSTD +``` + +### Create an OCI artifact image An OCI artifact image is a Docker image that contains files or directories that you want to include in your customized Docker Hardened Image (DHI). This can @@ -417,9 +611,74 @@ To customize a Docker Hardened Image Helm chart after it has been mirrored: At this point, the on-screen instructions will guide you through the customization process. +### Helm chart customization YAML file + +When using the CLI, Helm chart customizations use the same `prepare` / `create` +workflow as image customizations, but the configuration section uses +`reference_mappings` instead of image fields. + +Use `reference_mappings` to substitute image references within the chart, for +example to point a chart's image references at your mirrored DHIs. + +```yaml +name: use mirrored images + +targets: + - destination: my-org/dhi-haproxy-chart + tag_definition_id: haproxy/helm/1 + +reference_mappings: + - from: dhi/haproxy + to: my-org/dhi-haproxy +``` + +| Field | Description | +|:---|:---| +| `reference_mappings[].from` | The image reference in the chart to replace. | +| `reference_mappings[].to` | The replacement image reference, typically a mirrored DHI in your organization. | + +## Monitor customization builds + +After creating a customization, you can track build status and view logs +through Docker Hub or the DHI CLI. + +{{< tabs >}} +{{< tab name="Docker Hub" >}} + +1. Sign in to [Docker Hub](https://hub.docker.com). +2. Select **My Hub**. +3. In the namespace drop-down, select your organization. +4. Select **Hardened Images** > **Manage**. +5. Select the **Customizations** tab. + +{{< /tab >}} +{{< tab name="CLI" >}} + +List builds for a customization: + +```console +$ docker dhi customization build list --org my-org +``` + +Get details of a specific build: + +```console +$ docker dhi customization build get --org my-org +``` + +View build logs: + +```console +$ docker dhi customization build logs --org my-org +``` + +{{< /tab >}} +{{< /tabs >}} + ## Edit or delete a customization -To edit or delete a DHI or chart customization, follow these steps: +{{< tabs >}} +{{< tab name="Docker Hub" >}} 1. Sign in to [Docker Hub](https://hub.docker.com). 2. Select **My Hub**. @@ -434,4 +693,28 @@ To edit or delete a DHI or chart customization, follow these steps: - **Create new**: Create a new customization based on the source repository. - **Delete**: Delete the customization. -7. Follow the on-screen instructions to complete the edit or deletion. \ No newline at end of file +7. Follow the on-screen instructions to complete the edit or deletion. + +{{< /tab >}} +{{< tab name="CLI" >}} + +To edit a customization, update your YAML file and run: + +```console +$ docker dhi customization edit my-customization.yaml --org my-org +``` + +The YAML file must include the `id` field to identify which customization to +update. To find the ID, run `docker dhi customization list --org my-org`. + +To delete a customization by ID: + +```console +$ docker dhi customization delete --org my-org +$ docker dhi customization delete --org my-org --force +``` + +The `--force` flag skips the confirmation prompt. + +{{< /tab >}} +{{< /tabs >}} diff --git a/content/manuals/dhi/how-to/mirror.md b/content/manuals/dhi/how-to/mirror.md index d217c00d453..792606fdf06 100644 --- a/content/manuals/dhi/how-to/mirror.md +++ b/content/manuals/dhi/how-to/mirror.md @@ -89,15 +89,15 @@ Use the [`docker dhi mirror`](/reference/cli/docker/dhi/mirror/) command: ```console $ docker dhi 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 + dhi/golang,my-org/dhi-golang \ + dhi/nginx,my-org/dhi-nginx \ + dhi/prometheus-chart,my-org/dhi-prometheus-chart ``` Mirror with dependencies: ```console -$ docker dhi mirror start --org my-org -r dhi/golang,my-org/dhi-golang --dependencies +$ docker dhi mirror start --org my-org dhi/golang,my-org/dhi-golang --dependencies ``` List mirrored images in your organization: diff --git a/content/manuals/dhi/how-to/select-enterprise.md b/content/manuals/dhi/how-to/select-enterprise.md index 8c97665516f..05fce50f513 100644 --- a/content/manuals/dhi/how-to/select-enterprise.md +++ b/content/manuals/dhi/how-to/select-enterprise.md @@ -103,8 +103,7 @@ CLI](cli.md#configuration). `` with your organization name. ```console - $ docker dhi mirror start --org \ - -r dhi/python,/dhi-python + $ docker dhi mirror start --org dhi/python,/dhi-python ``` 2. Wait for images to finish mirroring. This can take a few minutes. @@ -163,7 +162,7 @@ CLI](cli.md#configuration). $ docker dhi customization prepare --org python 3-alpine3.23 \ --destination /dhi-python \ --name "python with curl" \ - --output my-customization.yaml + > my-customization.yaml ``` 2. Add the `curl` package to the customization. You can edit the file with any