diff --git a/content/manuals/dhi/how-to/_index.md b/content/manuals/dhi/how-to/_index.md index 9d7324bf4f9a..9a5ffaeb94e9 100644 --- a/content/manuals/dhi/how-to/_index.md +++ b/content/manuals/dhi/how-to/_index.md @@ -2,6 +2,8 @@ title: How-tos description: Step-by-step guidance for working with Docker Hardened Images, from discovery to governance. weight: 20 +aliases: + - /dhi/how-to/manage/ params: grid_discover: - title: Search and evaluate Docker Hardened Images @@ -37,10 +39,6 @@ params: description: Learn how to use a Docker Hardened Image chart. icon: leaderboard link: /dhi/how-to/helm/ - - title: Manage Docker Hardened Images and charts - description: Learn how to manage your mirrored and customized Docker Hardened Images in your organization. - icon: reorder - link: /dhi/how-to/manage/ grid_verify: - title: Verify a Docker Hardened Image or chart description: Use Docker Scout or cosign to verify signed attestations like SBOMs, provenance, and vulnerability data for Docker Hardened Images and charts. diff --git a/content/manuals/dhi/how-to/cli.md b/content/manuals/dhi/how-to/cli.md index 9021add863ac..59365e905010 100644 --- a/content/manuals/dhi/how-to/cli.md +++ b/content/manuals/dhi/how-to/cli.md @@ -76,7 +76,7 @@ docker dhi mirror start --org my-org \ Mirror with dependencies: ```bash -docker dhi mirror start --org my-org -r golang --dependencies +docker dhi mirror start --org my-org -r dhi/golang,my-org/dhi-golang --dependencies ``` List mirrored images in your organization: diff --git a/content/manuals/dhi/how-to/customize.md b/content/manuals/dhi/how-to/customize.md index 82aa14b154b5..c35749576088 100644 --- a/content/manuals/dhi/how-to/customize.md +++ b/content/manuals/dhi/how-to/customize.md @@ -2,7 +2,7 @@ title: Customize a Docker Hardened Image or chart linkTitle: Customize an image or chart weight: 25 -keywords: hardened images, DHI, customize, certificate, artifact, helm chart +keywords: hardened images, DHI, customize, certificate, artifact, helm chart, terraform, infrastructure as code description: Learn how to customize Docker Hardened Images (DHI) and charts. --- @@ -14,7 +14,6 @@ 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 @@ -32,35 +31,8 @@ mirrored DHI repository can create a customized image. 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 using the web interface, follow these steps: +{{< tabs >}} +{{< tab name="Docker Hub" >}} 1. Sign in to [Docker Hub](https://hub.docker.com). 1. Select **My Hub**. @@ -158,6 +130,130 @@ To customize a Docker Hardened Image using the web interface, follow these steps to build. Once built, it will appear in the **Tags** tab of the repository, and your team members can pull it like any other image. +{{< /tab >}} +{{< tab name="CLI" >}} + +Authenticate with `docker login` using your Docker credentials or a [personal +access token (PAT)](../../security/access-tokens.md) with **Read & Write** +permissions. [Organization access tokens +(OATs)](../../enterprise/security/access-tokens.md) are not supported. + +Use the [`docker dhi customization`](/reference/cli/docker/dhi/customization/) command: + +```console +# Prepare a 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 + +# Create a customization +$ docker dhi customization create my-customization.yaml --org my-org + +# List customizations +$ 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 + +# Get a customization +$ docker dhi customization get my-org/dhi-golang "golang with git" --org my-org --output my-customization.yaml + +# 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 without confirmation prompt +$ docker dhi customization delete my-org/dhi-golang "golang with git" --org my-org --yes +``` + +{{< /tab >}} +{{< tab name="Terraform" >}} + +You can manage DHI customizations as infrastructure-as-code using the [DHI +Terraform +provider](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs). +If you haven't configured the provider yet, see the Terraform tab in [Mirror a +repository](./mirror.md) for setup instructions. + +Define a `dhi_customization` resource for each customization: + +```hcl +resource "dhi_customization" "golang_with_git" { + repository = "dhi-golang" + name = "golang with git" + + contents { + packages = ["git", "curl"] + } + + platform { + os = "linux" + architecture = "amd64" + } +} +``` + +The `dhi_customization` resource also supports optional configuration blocks +for `accounts`, `files`, `labels`, `annotations`, `environment`, `entrypoint`, +`cmd`, `user`, `workdir`, and `stop_signal`. + +Run `terraform apply` to create the customization. + +To edit a customization, update the resource configuration and run `terraform +apply`. To delete a customization, remove the resource and run `terraform apply`. + +For the full list of resource attributes, see the [Terraform Registry +documentation](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs/resources/customization). + +> [!NOTE] +> +> Monitoring customization builds is not available through the Terraform +> provider. Use the Docker Hub web interface or the DHI CLI to monitor builds. + +{{< /tab >}} +{{< /tabs >}} + +### Monitor customization builds + +{{< 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 my-org/dhi-golang "golang with git" --org my-org +``` + +Get details of a specific build: + +```console +$ docker dhi customization build get my-org/dhi-golang "golang with git" --org my-org +``` + +View build logs: + +```console +$ docker dhi customization build logs my-org/dhi-golang "golang with git" --org my-org +``` + +{{< /tab >}} +{{< /tabs >}} + ### Create an OCI artifact image for image customization An OCI artifact image is a Docker image that contains files or directories that diff --git a/content/manuals/dhi/how-to/manage.md b/content/manuals/dhi/how-to/manage.md deleted file mode 100644 index 1a02cf22fa14..000000000000 --- a/content/manuals/dhi/how-to/manage.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Manage Docker Hardened Images and charts -linktitle: Manage images and charts -description: Learn how to manage your mirrored and customized Docker Hardened Images in your organization. -keywords: manage docker hardened images, custom hardened images -weight: 35 ---- - -{{< summary-bar feature_name="Docker Hardened Images" >}} - -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 -other standard Hub features. See [Docker Hub -repositories](/manuals/docker-hub/repos/_index.md) for details. The **Manage** -screen provides DHI-specific actions like customizing images and stopping -mirroring. - -## Manage mirrored Docker Hardened Image repositories - -To manage your mirrored DHI repositories: - -1. Go to the [Docker Hub](https://hub.docker.com) and sign in. -2. Select **My Hub**. -3. In the namespace drop-down, select your organization. -4. Select **Hardened Images** > **Manage**. -5. Select **Mirrored Images** -6. Select the menu icon in the far right column of the repository you want to manage. - - From here, you can: - - - **Customize**: Create a customized image based on the source repository. - - **Stop mirroring**: Stop mirroring the DHI repository. - -## Manage customized Docker Hardened Image repositories - -To manage your customized DHI repositories: - -1. Go to [Docker Hub](https://hub.docker.com) and sign in. -2. Select **My Hub**. -3. In the namespace drop-down, select your organization. -4. Select **Hardened Images** > **Manage**. -5. Select **Customizations**. - - On this page, you can view your customized DHI - repositories. - -6. Select the menu icon in the far right column of the repository you want to manage. - - From here, you can: - - - **Edit**: Edit the customized image. - - **Create new**: Create a new customized image based on the source repository. - - **Delete**: Delete the customized image. \ No newline at end of file diff --git a/content/manuals/dhi/how-to/mirror.md b/content/manuals/dhi/how-to/mirror.md index c94ae8277945..e5cf2dad4675 100644 --- a/content/manuals/dhi/how-to/mirror.md +++ b/content/manuals/dhi/how-to/mirror.md @@ -3,14 +3,15 @@ title: Mirror a Docker Hardened Image repository linktitle: Mirror a repository description: Learn how to mirror an image into your organization's namespace and optionally push it to another private registry. weight: 20 -keywords: mirror docker image, private container registry, docker hub automation, webhook image sync, secure image distribution, internal registry, jfrog artifactory, harbor registry, amazon ecr, google artifact registry, github container registry +keywords: mirror docker image, private container registry, docker hub automation, webhook image sync, secure image distribution, internal registry, jfrog artifactory, harbor registry, amazon ecr, google artifact registry, github container registry, terraform, infrastructure as code --- {{< summary-bar feature_name="Docker Hardened Images" >}} 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 Select or Enterprise subscription, you must mirror to get: +mirroring. With a DHI Select or Enterprise subscription, you must mirror to your +organization to get: - Compliance variants (FIPS-enabled or STIG-ready images) - Extended Lifecycle Support (ELS) variants (requires add-on) @@ -23,22 +24,17 @@ mirroring. With a DHI Select or Enterprise subscription, you must mirror to get: This topic covers two types of mirroring for Docker Hardened Image (DHI) repositories: -- [Mirror to Docker Hub](#mirror-a-dhi-repository-to-docker-hub): Mirror a DHI - repository to your organization's namespace on Docker Hub. This requires a DHI - Enterprise subscription and is used to [customize an image or - chart](./customize.md) and access compliance variants and ELS variants - (requires add-on). This must be done through the Docker Hub web interface. +- [Mirror to your organization](#mirror-a-dhi-repository-to-your-organization): + Mirror a DHI repository to your organization's namespace on Docker Hub. - [Mirror to a third-party registry](#mirror-a-dhi-repository-to-a-third-party-registry): Mirror a repository to another container registry, such as Amazon ECR, Google Artifact Registry, or a private Harbor instance. -## Mirror a DHI repository to Docker Hub +## Mirror a DHI repository to your organization -Mirroring a repository to Docker Hub requires a DHI Enterprise subscription and -enables access to compliance variants, Extended Lifecycle Support (ELS) variants -(requires add-on), and customization capabilities: +You must be an organization owner or editor to mirror repositories. - Image repositories: Mirroring lets you customize images by adding packages, OCI artifacts (such as custom certificates or additional tools), environment @@ -51,29 +47,8 @@ enables access to compliance variants, Extended Lifecycle Support (ELS) variants reference those custom locations. For more details, see [Customize a Docker Hardened Helm chart](./customize.md#customize-a-docker-hardened-helm-chart). -Only organization owners can perform mirroring. Once mirrored, the repository -becomes available in your organization's namespace, and you can customize it as -needed. - -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: +{{< tabs >}} +{{< tab name="Docker Hub" >}} 1. Go to [Docker Hub](https://hub.docker.com) and sign in. 2. Select **My Hub**. @@ -88,76 +63,125 @@ To mirror a Docker Hardened Image repository using the web interface: It may take a few minutes for all the tags to finish mirroring. -After mirroring a repository, the repository appears in your organization's -repository list, prefixed by `dhi-`. It will continue to receive updated images. +{{< /tab >}} +{{< tab name="CLI" >}} -Once mirrored, the repository is a standard Docker Hub repository in your -organization's namespace. It behaves exactly like any other Hub repository, -which means you can manage access and permissions, configure webhooks, and use -other standard Hub features. See [Docker Hub -repositories](/manuals/docker-hub/repos/_index.md) for details. +Authenticate with `docker login` using your Docker credentials or a [personal +access token (PAT)](../../security/access-tokens.md) with **Read & Write** +permissions. [Organization access tokens +(OATs)](../../enterprise/security/access-tokens.md) are not supported. -Additionally, mirrored DHI repositories let you customize images and charts. To -learn more, see [Customize a Docker Hardened Image or chart](./customize.md). +Use the [`docker dhi mirror`](/reference/cli/docker/dhi/mirror/) command: -### Webhook integration for syncing and alerts +```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 +``` -To keep external registries or systems in sync with your mirrored Docker -Hardened Images, and to receive notifications when updates occur, you can -configure a [webhook](/docker-hub/repos/manage/webhooks/) on the mirrored -repository in Docker Hub. A webhook sends a `POST` request to a URL you define -whenever a new image tag is pushed or updated. +Mirror with dependencies: -For example, you might configure a webhook to call a CI/CD system at -`https://ci.example.com/hooks/dhi-sync` whenever a new tag is mirrored. The -automation triggered by this webhook can pull the updated image from Docker Hub -and push it to an internal registry such as Amazon ECR, Google Artifact -Registry, or GitHub Container Registry. +```console +$ docker dhi mirror start --org my-org -r dhi/golang,my-org/dhi-golang --dependencies +``` -Other common webhook use cases include: +List mirrored images in your organization: -- Triggering validation or vulnerability scanning workflows -- Signing or promoting images -- Sending notifications to downstream systems +```console +$ docker dhi mirror list --org my-org +``` -#### Example webhook payload +Filter mirrored images by name or type: -When a webhook is triggered, Docker Hub sends a JSON payload like the following: +```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 +``` -```json -{ - "callback_url": "https://registry.hub.docker.com/u/exampleorg/dhi-python/hook/abc123/", - "push_data": { - "pushed_at": 1712345678, - "pusher": "trustedbuilder", - "tag": "3.13-alpine3.21" - }, - "repository": { - "name": "dhi-python", - "namespace": "exampleorg", - "repo_name": "exampleorg/dhi-python", - "repo_url": "https://hub.docker.com/r/exampleorg/dhi-python", - "is_private": true, - "status": "Active", - ... +{{< /tab >}} +{{< tab name="Terraform" >}} + +You can manage DHI mirrors as infrastructure-as-code using the [DHI Terraform +provider](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs). + +First, install and configure the provider: + +```hcl +terraform { + required_providers { + dhi = { + source = "docker-hardened-images/dhi" + } } } + +provider "dhi" { + docker_hub_username = var.docker_username + docker_hub_password = var.docker_password + organization = var.org_name +} +``` + +> [!NOTE] +> +> Instead of specifying credentials in the provider block, you can set the +> `DOCKER_USERNAME`, `DOCKER_PASSWORD`, and `DHI_ORG` environment variables. + +Then, define a `dhi_mirror` resource for each repository you want to mirror: + +```hcl +resource "dhi_mirror" "golang" { + source_namespace = "dhi" + source_name = "golang" + destination_name = "dhi-golang" +} + +resource "dhi_mirror" "nginx" { + source_namespace = "dhi" + source_name = "nginx" + destination_name = "dhi-nginx" +} ``` +To enable Extended Lifecycle Support (ELS) variants, set the `els` attribute: + +```hcl +resource "dhi_mirror" "golang" { + source_namespace = "dhi" + source_name = "golang" + destination_name = "dhi-golang" + els = true +} +``` + +Run `terraform apply` to create the mirrors. + +For the full list of resource attributes, see the [Terraform Registry +documentation](https://registry.terraform.io/providers/docker-hardened-images/dhi/latest/docs/resources/mirror). + +{{< /tab >}} +{{< /tabs >}} + +After mirroring, the repository appears in your organization's repository list, +prefixed by `dhi-`, and continues to receive updated images. It behaves like any +other Docker Hub repository, so you can manage access and permissions, configure +webhooks, and use other standard Hub features. See [Docker Hub +repositories](/manuals/docker-hub/repos/_index.md) for details. + ### Stop mirroring a repository -Only organization owners can stop mirroring a repository. After you stop -mirroring, the repository remains, but it will -no longer receive updates. You can still use the last images or charts that were mirrored, -but the repository will not receive new tags or updates from the original -repository. +After you stop mirroring, the repository remains, but it no longer receives +updates. You can still use the last images or charts that were mirrored. > [!NOTE] > -> If you only want to stop mirroring ELS versions, clear the **Mirror -> end-of-life images** option in the mirrored repository's **Settings** tab. +> If you only want to stop mirroring ELS versions, you can clear the ELS +> option in the mirrored repository's **Settings** tab. - To stop mirroring a repository: +{{< tabs >}} +{{< tab name="Docker Hub" >}} 1. Go to [Docker Hub](https://hub.docker.com) and sign in. 2. Select **My Hub**. @@ -167,11 +191,35 @@ repository. 6. In the far right column of the repository you want to stop mirroring, select the menu icon. 7. Select **Stop mirroring**. +{{< /tab >}} +{{< tab name="CLI" >}} + +Authenticate with `docker login` using your Docker credentials or a [personal +access token (PAT)](../../security/access-tokens.md) with **Read & Write** +permissions. [Organization access tokens +(OATs)](../../enterprise/security/access-tokens.md) are not supported. + +Use the [`docker dhi mirror`](/reference/cli/docker/dhi/mirror/) command: + +```console +$ docker dhi mirror stop --org my-org dhi-golang +``` + +{{< /tab >}} +{{< tab name="Terraform" >}} + +To stop mirroring, remove the `dhi_mirror` resource from your Terraform +configuration and run `terraform apply`. The repository remains in your +organization but no longer receives updates. + +{{< /tab >}} +{{< /tabs >}} + ## Mirror a DHI repository to a third-party registry -You can optionally mirror a DHI repository to another container registry, such as Amazon -ECR, Google Artifact Registry, GitHub Container Registry, or a private Harbor -instance. +After mirroring a DHI repository to your organization on Docker Hub, you can +optionally mirror it to another container registry, such as Amazon ECR, Google +Artifact Registry, GitHub Container Registry, or a private Harbor instance. You can use any standard workflow to mirror the image, such as the [Docker CLI](/reference/cli/docker/), [Docker Hub Registry @@ -188,55 +236,49 @@ OCI-aware CLI that supports mirroring images along with attached artifacts such as SBOMs, vulnerability reports, and SLSA provenance. For ongoing synchronization, you can use [`regsync`](https://regclient.org/cli/regsync/). -### Authenticate to `dhi.io` with an organization access token - -You can authenticate to `dhi.io` using an [organization access token -(OAT)](../../enterprise/security/access-tokens.md) instead of a personal access -token (PAT). OATs are owned by the organization rather than an individual user, -which makes them better suited for CI/CD pipelines and automated workflows. - -> [!NOTE] -> -> When using an OAT, use your organization name as the username, not your -> personal Docker ID. OATs are org-scoped and will return a `401 Unauthorized` -> error if presented under an individual user's username. - -To authenticate using an OAT: +### Automate syncing with webhooks -1. Sign in to [Docker Home](https://app.docker.com) and select your organization. -2. Select **Admin Console**, then **Access tokens**. -3. Select **Generate access token**. -4. Give the token a descriptive name, for example `dhi-pull-automation`. -5. Expand the **Repository** drop-down and select **Read public repositories**. -6. Select **Generate token**, then copy and save the token. You won't be able - to retrieve it after closing the screen. -7. Sign in to `dhi.io` using your organization name as the username and the OAT - as the password: - - ```console - $ oras login dhi.io -u - ``` +To keep external registries or systems in sync with your mirrored Docker +Hardened Images, and to receive notifications when updates occur, you can +configure a [webhook](/docker-hub/repos/manage/webhooks/) on the mirrored +repository in Docker Hub. A webhook sends a `POST` request to a URL you define +whenever a new image tag is pushed or updated. - Or non-interactively in a CI/CD pipeline: +For example, you might configure a webhook to call a CI/CD system at +`https://ci.example.com/hooks/dhi-sync` whenever a new tag is mirrored. The +automation triggered by this webhook can pull the updated image from Docker Hub +and push it to an internal registry such as Amazon ECR, Google Artifact +Registry, or GitHub Container Registry. - ```console - $ echo $OAT | oras login dhi.io -u "$DOCKER_ORG" --password-stdin - ``` +Other common webhook use cases include: -8. Verify access by discovering attestations on a DHI image: +- Triggering validation or vulnerability scanning workflows +- Signing or promoting images +- Sending notifications to downstream systems - ```console - $ oras discover dhi.io/node:24-dev --platform linux/amd64 - ``` +#### Example webhook payload - > [!NOTE] - > - > The `--platform` flag is required. Without it, `oras discover` resolves to - > the multi-arch image index, which returns only an index-level signature - > rather than the full set of per-platform attestations. +When a webhook is triggered, Docker Hub sends a JSON payload like the following: - A successful response lists the attestations attached to the image, - including SBOMs, provenance, vulnerability reports, and changelog metadata. +```json{collapse=true} +{ + "callback_url": "https://registry.hub.docker.com/u/exampleorg/dhi-python/hook/abc123/", + "push_data": { + "pushed_at": 1712345678, + "pusher": "trustedbuilder", + "tag": "3.13-alpine3.21" + }, + "repository": { + "name": "dhi-python", + "namespace": "exampleorg", + "repo_name": "exampleorg/dhi-python", + "repo_url": "https://hub.docker.com/r/exampleorg/dhi-python", + "is_private": true, + "status": "Active", + ... + } +} +``` ### Example mirroring with `regctl` @@ -263,6 +305,14 @@ same steps to a non-mirrored image by updating the `SRC_ATT_REPO` and workflow requires authenticating to the Scout registry, use a personal access token (PAT) for that step. + > [!WARNING] + > + > The following examples export credentials directly on the command line for + > demonstration purposes. This exposes sensitive tokens in your shell history + > and process list. In production environments, use secure methods such as + > reading from files with restricted permissions, environment files loaded + > at runtime, or secret management tools. + ```console $ export DOCKER_USERNAME="YOUR_DOCKER_USERNAME" $ export DOCKER_PAT="YOUR_DOCKER_PAT" @@ -326,7 +376,7 @@ reads a YAML configuration file and can filter tags. The following example uses a `regsync.yaml` file that syncs Node 24 and Python 3.12 Debian 13 variants, excluding Alpine and Debian 12. -```yaml{title="regsync.yaml"} +```yaml{title="regsync.yaml",collapse=true} version: 1 # Optional: inline creds if not relying on prior CLI logins # creds: diff --git a/content/manuals/dhi/how-to/use.md b/content/manuals/dhi/how-to/use.md index 548bcfc15f55..82b2f8603e53 100644 --- a/content/manuals/dhi/how-to/use.md +++ b/content/manuals/dhi/how-to/use.md @@ -102,6 +102,66 @@ using tools like Docker Scout. To learn how to attach attestations during the build process, see [Docker Build Attestations](/manuals/build/metadata/attestations.md). +### Discover attestations with ORAS + +You can use [ORAS](https://oras.land/) to discover and inspect the attestations +attached to Docker Hardened Images. This is particularly useful in CI/CD +pipelines for supply chain security validation and compliance checks. + +For automated workflows, authenticate using an [organization access token +(OAT)](../../enterprise/security/access-tokens.md). OATs are owned by the +organization rather than an individual user, making them better suited for CI/CD +pipelines. + +To discover attestations with ORAS: + +1. [Generate an organization access + token](../../enterprise/security/access-tokens.md) with **Read public + repositories** scope. + + The following example shows how to discover attestations on DHI community + images from `dhi.io`. If you're discovering attestations on images mirrored to + your organization, generate an OAT scoped to read from your mirrored repository + instead of **Read public repositories**. + +2. Sign in to `dhi.io` using your organization name as the username and the OAT + as the password. + + > [!WARNING] + > + > The following examples export credentials directly on the command line for + > demonstration purposes. This exposes sensitive tokens in your shell history + > and process list. In production environments, use secure methods such as + > reading from files with restricted permissions, environment files loaded + > at runtime, or secret management tools. + + ```console + $ oras login dhi.io -u + ``` + + Or non-interactively in a CI/CD pipeline, set your organization name and token: + + ```console + $ export DOCKER_ORG="YOUR_ORGANIZATION_NAME" + $ export OAT="YOUR_ORGANIZATION_ACCESS_TOKEN" + $ echo $OAT | oras login dhi.io -u "$DOCKER_ORG" --password-stdin + ``` + +3. Discover attestations on a DHI image: + + ```console + $ oras discover dhi.io/node:24-dev --platform linux/amd64 + ``` + + > [!NOTE] + > + > The `--platform` flag is required. Without it, `oras discover` resolves to + > the multi-arch image index, which returns only an index-level signature + > rather than the full set of per-platform attestations. + + A successful response lists the attestations attached to the image, + including SBOMs, provenance, vulnerability reports, and changelog metadata. + ## Use a static image for compiled executables Docker Hardened Images include a `static` image repository designed specifically diff --git a/content/manuals/dhi/how-to/verify.md b/content/manuals/dhi/how-to/verify.md index 6a7adeb058d4..1d4e94ae99fa 100644 --- a/content/manuals/dhi/how-to/verify.md +++ b/content/manuals/dhi/how-to/verify.md @@ -63,6 +63,14 @@ This command shows all available attestations, including SBOMs, provenance, vuln First, authenticate to both registries. Prepare a [personal access token (PAT)](../../security/access-tokens.md) for your user with `read only` access: +> [!WARNING] +> +> The following examples export credentials directly on the command line for +> demonstration purposes. This exposes sensitive tokens in your shell history +> and process list. In production environments, use secure methods such as +> reading from files with restricted permissions, environment files loaded +> at runtime, or secret management tools. + ```console $ export DOCKER_USERNAME="YOUR_DOCKER_USERNAME" $ export DOCKER_PAT="YOUR_DOCKER_PAT"