diff --git a/content/manuals/dhi/how-to/cli.md b/content/manuals/dhi/how-to/cli.md index 7d1618d0d84..4a416872c09 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,37 +147,50 @@ 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 ``` ### Enterprise package authentication @@ -164,8 +203,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 +213,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 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 ``` 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 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 ``` 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 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 ``` ### 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 my-org/dhi-golang "golang with git" --org my-org --json ``` ## Configuration diff --git a/content/manuals/dhi/how-to/customize.md b/content/manuals/dhi/how-to/customize.md index 47e9143f513..618e1978d8c 100644 --- a/content/manuals/dhi/how-to/customize.md +++ b/content/manuals/dhi/how-to/customize.md @@ -165,12 +165,17 @@ permissions. [Organization access tokens 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 @@ -183,17 +188,17 @@ $ 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 ``` {{< /tab >}} diff --git a/content/manuals/dhi/how-to/mirror.md b/content/manuals/dhi/how-to/mirror.md index e5cf2dad467..1bbf9dca349 100644 --- a/content/manuals/dhi/how-to/mirror.md +++ b/content/manuals/dhi/how-to/mirror.md @@ -75,15 +75,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 645aff470be..f1ae47d690a 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