diff --git a/content/manuals/dhi/about/test.md b/content/manuals/dhi/about/test.md index 8dc3aa625ef2..4e86bef60750 100644 --- a/content/manuals/dhi/about/test.md +++ b/content/manuals/dhi/about/test.md @@ -78,16 +78,21 @@ You can view and verify this attestation using the Docker Scout CLI. $ docker scout attest get \ --predicate-type https://scout.docker.com/tests/v0.1 \ --predicate \ - /dhi-: --platform + /dhi-: ``` + > [!NOTE] + > + > If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use + > `registry://docs/dhi-python` instead of `docs/dhi-python`. + For example: ```console $ docker scout attest get \ --predicate-type https://scout.docker.com/tests/v0.1 \ --predicate \ - docs/dhi-python:3.13 --platform linux/amd64 + docs/dhi-python:3.13 ``` This contains a list of tests and their results. diff --git a/content/manuals/dhi/core-concepts/attestations.md b/content/manuals/dhi/core-concepts/attestations.md index 5fd03bfbbc17..0ab55829299e 100644 --- a/content/manuals/dhi/core-concepts/attestations.md +++ b/content/manuals/dhi/core-concepts/attestations.md @@ -67,7 +67,7 @@ details](../how-to/explore.md#view-image-variant-details) in Docker Hub. | Attestation type | Description | Predicate type URI | |----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------| -| CycloneDX SBOM | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing components, libraries, and versions. | `https://cyclonedx.org/bom/v1.5` | +| CycloneDX SBOM | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing components, libraries, and versions. | `https://cyclonedx.org/bom/v1.6` | | STIG scan | Results of a STIG scan, with output in HTML and XCCDF formats. | `https://docker.com/dhi/stig/v0.1` | | CVEs (In-Toto format) | A list of known vulnerabilities (CVEs) affecting the image's components, based on package and distribution scanning. | `https://in-toto.io/attestation/vulns/v0.1` | | VEX | A [Vulnerability Exploitability eXchange (VEX)](https://openvex.dev/) document that identifies vulnerabilities that do not apply to the image and explains why (e.g., not reachable or not present). | `https://openvex.dev/ns/v0.2.0` | diff --git a/content/manuals/dhi/core-concepts/cves.md b/content/manuals/dhi/core-concepts/cves.md index aaa40857926a..de5e5238c464 100644 --- a/content/manuals/dhi/core-concepts/cves.md +++ b/content/manuals/dhi/core-concepts/cves.md @@ -160,6 +160,9 @@ $ docker scout vex get /dhi-: --output vex.json > > The `docker scout vex get` command requires [Docker Scout > CLI](https://github.com/docker/scout-cli/) version 1.18.3 or later. +> +> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use +> `registry://docs/dhi-python:3.13` instead of `docs/dhi-python:3.13`. For example: diff --git a/content/manuals/dhi/core-concepts/signatures.md b/content/manuals/dhi/core-concepts/signatures.md index 4e2324ae4f7b..4396131837b5 100644 --- a/content/manuals/dhi/core-concepts/signatures.md +++ b/content/manuals/dhi/core-concepts/signatures.md @@ -56,28 +56,37 @@ You can verify that a Docker Hardened Image is signed and trusted using either D To lists all attestations, including signature metadata, attached to the image, use the following command: ```console -$ docker scout attest list : --platform +$ docker scout attest list : ``` +> [!NOTE] +> +> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use +> `registry://docs/dhi-python` instead of `docs/dhi-python`. + To verify a specific signed attestation (e.g., SBOM, VEX, provenance): ```console $ docker scout attest get \ --predicate-type \ --verify \ - : --platform + : ``` +> [!NOTE] +> +> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use +> `registry://docs/dhi-python:3.13` instead of `docs/dhi-python:3.13`. + For example: ```console $ docker scout attest get \ --predicate-type https://openvex.dev/ns/v0.2.0 \ --verify \ - docs/dhi-python:3.13 --platform linux/amd64 + docs/dhi-python:3.13 ``` - If valid, Docker Scout will confirm the signature and display signature payload, as well as the equivalent Cosign command to verify the image. ### Sign images diff --git a/content/manuals/dhi/core-concepts/vex.md b/content/manuals/dhi/core-concepts/vex.md index c172f1ad1624..8517806d9f18 100644 --- a/content/manuals/dhi/core-concepts/vex.md +++ b/content/manuals/dhi/core-concepts/vex.md @@ -60,6 +60,13 @@ vulnerability management. When using Docker Scout, VEX statements are automatically applied and no manual configuration is needed. +> [!NOTE] +> +> By default, VEX attestations are fetched from `registry.scout.docker.com`. Ensure that you can access this registry if +> your network has outbound restrictions. You can also mirror the attestations to an alternate registry. For more +> details, see [Mirror a Docker Hardened Image +> repository](../how-to/mirror.md#mirror-from-docker-hub-to-another-registry). + To manually retrieve the VEX attestation for tools that support it: ```console @@ -70,6 +77,9 @@ $ docker scout vex get /dhi-: --output vex.json > > The `docker scout vex get` command requires [Docker Scout > CLI](https://github.com/docker/scout-cli/) version 1.18.3 or later. +> +> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use +> `registry://docs/dhi-python:3.13` instead of `docs/dhi-python:3.13`. For example: diff --git a/content/manuals/dhi/how-to/scan.md b/content/manuals/dhi/how-to/scan.md index 76b6ed1fd1eb..0ef87e481a05 100644 --- a/content/manuals/dhi/how-to/scan.md +++ b/content/manuals/dhi/how-to/scan.md @@ -191,6 +191,12 @@ runtime behavior. When using Docker Scout, these VEX statements are automatically applied and no manual configuration needed. +> [!NOTE] +> +> By default, VEX attestations are fetched from `registry.scout.docker.com`. Ensure that you can access this registry +> if your network has outbound restrictions. You can also mirror the attestations to an alternate registry. For more +> details, see [Mirror a Docker Hardened Image repository](mirror.md#mirror-from-docker-hub-to-another-registry). + To manually create a JSON file of VEX attestations for tools that support it: ```console @@ -201,6 +207,9 @@ $ docker scout vex get /dhi-: --output vex.json > > The `docker scout vex get` command requires [Docker Scout > CLI](https://github.com/docker/scout-cli/) version 1.18.3 or later. +> +> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use +> `registry://docs/dhi-python:3.13` instead of `docs/dhi-python:3.13`. For example: @@ -217,4 +226,4 @@ statements during the scan: ```console $ grype /dhi-: --vex vex.json -``` \ No newline at end of file +``` diff --git a/content/manuals/dhi/how-to/verify.md b/content/manuals/dhi/how-to/verify.md index 55b9a2906cf1..f5818673794e 100644 --- a/content/manuals/dhi/how-to/verify.md +++ b/content/manuals/dhi/how-to/verify.md @@ -55,14 +55,20 @@ offers several key advantages when working with Docker Hardened Images: ensuring compatibility and simplifying verification for users within the Docker ecosystem. -In short, Docker Scout streamlines the verification process and reduces the chances of human error, while still giving you full visibility and the option to fall back to cosign when needed. +In short, Docker Scout streamlines the verification process and reduces the chances of human error, while still giving +you full visibility and the option to fall back to cosign when needed. ### List available attestations To list attestations for a mirrored DHI: +> [!NOTE] +> +> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use +> `registry://docs/dhi-python:3.13` instead of `docs/dhi-python:3.13`. + ```console -$ docker scout attest list /dhi-: --platform +$ docker scout attest list /dhi-: ``` This command shows all available attestations, including SBOMs, provenance, vulnerability reports, and more. @@ -73,34 +79,39 @@ To retrieve a specific attestation, use the `--predicate-type` flag with the ful ```console $ docker scout attest get \ - --predicate-type https://cyclonedx.org/bom/v1.5 \ - /dhi-: --platform + --predicate-type https://cyclonedx.org/bom/v1.6 \ + /dhi-: ``` +> [!NOTE] +> +> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use +> `registry://docs/dhi-python:3.13` instead of `docs/dhi-python:3.13`. + For example: ```console $ docker scout attest get \ - --predicate-type https://cyclonedx.org/bom/v1.5 \ - docs/dhi-python:3.13 --platform linux/amd64 + --predicate-type https://cyclonedx.org/bom/v1.6 \ + docs/dhi-python:3.13 ``` To retrieve only the predicate body: ```console $ docker scout attest get \ - --predicate-type https://cyclonedx.org/bom/v1.5 \ + --predicate-type https://cyclonedx.org/bom/v1.6 \ --predicate \ - /dhi-: --platform + /dhi-: ``` For example: ```console $ docker scout attest get \ - --predicate-type https://cyclonedx.org/bom/v1.5 \ + --predicate-type https://cyclonedx.org/bom/v1.6 \ --predicate \ - docs/dhi-python:3.13 --platform linux/amd64 + docs/dhi-python:3.13 ``` ### Validate the attestation with Docker Scout @@ -112,6 +123,13 @@ $ docker scout attest get : \ --predicate-type https://scout.docker.com/sbom/v0.1 --verify ``` +> [!NOTE] +> +> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use +> `registry://docs/dhi-node:20.19-debian12-fips-20250701182639` instead of +> `docs/dhi-node:20.19-debian12-fips-20250701182639`. + + For example, to verify the SBOM attestation for the `dhi/node:20.19-debian12-fips-20250701182639` image: ```console @@ -143,7 +161,7 @@ To skip the transparency log check and validate against Docker's key, use the ```console $ docker scout attest get \ --predicate-type https://cyclonedx.org/bom/v1.6 \ - /dhi-: --platform \ + /dhi-: \ --verify --skip-tlog ``` @@ -151,6 +169,10 @@ $ docker scout attest get \ > > The `--skip-tlog` flag is only available in Docker Scout CLI version 1.18.2 and > later. +> +> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use +> `registry://docs/dhi-python:3.13` instead of `docs/dhi-python:3.13`. + This is equivalent to using `cosign` with the `--insecure-ignore-tlog=true` flag, which validates the signature against Docker's published public key, but @@ -163,18 +185,23 @@ When using the `--verify` flag, it also prints the corresponding ```console $ docker scout attest get \ - --predicate-type https://cyclonedx.org/bom/v1.5 \ + --predicate-type https://cyclonedx.org/bom/v1.6 \ --verify \ - /dhi-: --platform + /dhi-: ``` +> [!NOTE] +> +> If the image exists locally on your device, you must prefix the image name with `registry://`. For example, use +> `registry://docs/dhi-python:3.13` instead of `docs/dhi-python:3.13`. + For example: ```console $ docker scout attest get \ - --predicate-type https://cyclonedx.org/bom/v1.5 \ + --predicate-type https://cyclonedx.org/bom/v1.6 \ --verify \ - docs/dhi-python:3.13 --platform linux/amd64 + docs/dhi-python:3.13 ``` If verification succeeds, Docker Scout prints the full `cosign verify` command.