diff --git a/content/manuals/dhi/core-concepts/attestations.md b/content/manuals/dhi/core-concepts/attestations.md index 0ab55829299..e41aebca1c7 100644 --- a/content/manuals/dhi/core-concepts/attestations.md +++ b/content/manuals/dhi/core-concepts/attestations.md @@ -4,22 +4,21 @@ description: Review the full set of signed attestations included with each Docke keywords: container image attestations, signed sbom, build provenance, slsa compliance, vex document --- -Docker Hardened Images (DHIs) include comprehensive, signed security -attestations that verify the image's build process, contents, and security -posture. These attestations are a core part of secure software supply chain -practices and help users validate that an image is trustworthy and -policy-compliant. +Docker Hardened Images (DHIs) and charts include comprehensive, signed security +attestations that verify the build process, contents, and security posture. +These attestations are a core part of secure software supply chain practices and +help users validate that images and charts are trustworthy and policy-compliant. ## What is an attestation? -An attestation is a signed statement that provides verifiable information -about an image, such as how it was built, what's inside it, and what security +An attestation is a signed statement that provides verifiable information about +an image or chart, such as how it was built, what's inside it, and what security checks it has passed. Attestations are typically signed using Sigstore tooling (such as Cosign), making them tamper-evident and cryptographically verifiable. Attestations follow standardized formats (like [in-toto](https://in-toto.io/), [CycloneDX](https://cyclonedx.org/), and [SLSA](https://slsa.dev/)) and are -attached to the image as OCI-compliant metadata. They can be generated +attached to the image or chart as OCI-compliant metadata. They can be generated automatically during image builds or added manually to document extra tests, scan results, or custom provenance. @@ -38,25 +37,26 @@ They are essential for meeting industry standards such as SLSA, and help teams reduce the risk of supply chain attacks by making build and security data transparent and verifiable. -## How Docker Hardened Images use attestations +## How Docker Hardened Images and charts use attestations -All DHIs are built using [SLSA Build Level +All DHIs and DHI charts are built using [SLSA Build Level 3](https://slsa.dev/spec/latest/levels) practices, and each image variant is published with a full set of signed attestations. These attestations allow users to: -- Verify that the image was built from trusted sources in a secure environment +- Verify that the image or chart was built from trusted sources in a secure + environment - View SBOMs in multiple formats to understand component-level details - Review scan results to check for vulnerabilities or embedded secrets -- Confirm the build and deployment history of each image +- Confirm the build and deployment history of each image or chart Attestations are automatically published and associated with each mirrored DHI -in your Docker Hub organization. They can be inspected using tools like [Docker -Scout](../how-to/verify.md) or +and chart in your Docker Hub organization. They can be inspected using tools +like [Docker Scout](../how-to/verify.md) or [Cosign](https://docs.sigstore.dev/cosign/overview), and are consumable by CI/CD tooling or security platforms. -## Available attestations +## Image attestations While every DHI variant includes a set of attestations, the attestations may vary based on the image variant. For example, some images may include a STIG @@ -83,10 +83,35 @@ details](../how-to/explore.md#view-image-variant-details) in Docker Hub. | SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, widely adopted in open-source ecosystems. | `https://spdx.dev/Document` | | FIPS compliance | An attestation that verifies the image uses FIPS 140-validated cryptographic modules. | `https://docker.com/dhi/fips/v0.1` | -## View and verify attestations +To view and verify attestations for an image, see [Verify image +attestations](../how-to/verify.md#verify-image-attestations-with-docker-scout). -To view and verify attestations for an image, see [Verify a Docker Hardened -Image](../how-to/verify.md). +## Helm chart attestations + +Docker Hardened Image (DHI) charts also include comprehensive signed attestations +that provide transparency and verification for your Kubernetes deployments. Like +DHI container images, these charts are built following SLSA Build Level 3 +practices and include extensive security metadata. + +DHI Helm charts include the following attestations: + +| Attestation type | Description | Predicate type URI | +|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------| +| CycloneDX SBOM | A software bill of materials in [CycloneDX](https://cyclonedx.org/) format, listing the chart itself and all container images and tools referenced by the chart. | `https://cyclonedx.org/bom/v1.6` | +| CVEs (In-Toto format) | A list of known vulnerabilities (CVEs) affecting the container images and components referenced by the chart. | `https://in-toto.io/attestation/vulns/v0.1` | +| Scout health score | A signed attestation from Docker Scout that summarizes the overall security and quality posture of the chart and its referenced images. | `https://scout.docker.com/health/v0.1` | +| Scout provenance | Provenance metadata generated by Docker Scout, including the chart source repository, build images used, and build parameters. | `https://scout.docker.com/provenance/v0.1` | +| Scout SBOM | An SBOM generated and signed by Docker Scout, including the chart and container images it references, with additional Docker-specific metadata. | `https://scout.docker.com/sbom/v0.1` | +| Secrets scan | Results of a scan for accidentally included secrets, such as credentials, tokens, or private keys, in the chart package. | `https://scout.docker.com/secrets/v0.1` | +| Tests | A record of automated tests run against the chart to validate functionality and compatibility with referenced images. | `https://scout.docker.com/tests/v0.1` | +| Virus scan | Results of antivirus scans performed on the chart package. | `https://scout.docker.com/virus/v0.1` | +| CVEs (Scout format) | A vulnerability report generated by Docker Scout, listing known CVEs and severity data for the chart's referenced images. | `https://scout.docker.com/vulnerabilities/v0.1` | +| SLSA provenance | A standard [SLSA](https://slsa.dev/) provenance statement describing how the chart was built, including build tool, source repository, referenced images, and build materials. | `https://slsa.dev/provenance/v0.2` | +| SPDX SBOM | An SBOM in [SPDX](https://spdx.dev/) format, listing the chart and all container images and tools it references. | `https://spdx.dev/Document` | + +For instructions on how to view and verify Helm chart attestations, see [Verify +Helm chart +attestations](../how-to/verify.md#verify-helm-chart-attestations-with-docker-scout). ## Add your own attestations diff --git a/content/manuals/dhi/features/helm.md b/content/manuals/dhi/features/helm.md index 7fb784d07a2..58c041c13f2 100644 --- a/content/manuals/dhi/features/helm.md +++ b/content/manuals/dhi/features/helm.md @@ -21,6 +21,9 @@ Like the hardened images, DHI charts incorporate multiple layers of security met authenticity. - Hardened configuration: Charts automatically reference Docker hardened images, ensuring security in deployments. +For a complete list of attestations included with DHI charts, see [Helm chart +attestations](../core-concepts/attestations.md#helm-chart-attestations). + ## Developer Friendly DHI charts are robustly tested after building to ensure they work out-of-the-box with Docker Hardened Images. This diff --git a/content/manuals/dhi/how-to/verify.md b/content/manuals/dhi/how-to/verify.md index f5818673794..723d26b17fa 100644 --- a/content/manuals/dhi/how-to/verify.md +++ b/content/manuals/dhi/how-to/verify.md @@ -1,24 +1,44 @@ --- -title: Verify a Docker Hardened Image -linktitle: Verify an image -description: Use Docker Scout or cosign to verify signed attestations like SBOMs, provenance, and vulnerability data for Docker Hardened Images. +title: Verify Docker Hardened Images and charts +linktitle: Verify images and charts +description: Use Docker Scout or cosign to verify signed attestations like SBOMs, provenance, and vulnerability data for Docker Hardened Images and Helm charts. weight: 40 -keywords: verify container image, docker scout attest, cosign verify, sbom validation, signed container attestations +keywords: verify container image, docker scout attest, cosign verify, sbom validation, signed container attestations, helm chart verification --- {{< summary-bar feature_name="Docker Hardened Images" >}} -Docker Hardened Images (DHI) include signed attestations that verify the image’s +Docker Hardened Images (DHI) and DHI Helm charts include signed attestations that verify the build process, contents, and security posture. These attestations are available -for each image variant and can be verified using +for each image variant and chart, and can be verified using [cosign](https://docs.sigstore.dev/) or the Docker Scout CLI. -Docker's public key for DHI images is published at: +Docker's public key for DHI images and charts is published at: - https://registry.scout.docker.com/keyring/dhi/latest.pub - https://github.com/docker-hardened-images/keyring -## Verify attestations with Docker Scout +## Available DHI attestations + +See [available image attestations](../core-concepts/attestations.md#image-attestations) for a list +of attestations available for each DHI, and [available Helm chart attestations](../core-concepts/attestations.md#helm-chart-attestations) +for attestations included with DHI charts. + +### Explore image attestations on Docker Hub + +You can also browse attestations visually when [exploring an image +variant](./explore.md#view-image-variant-details). The **Attestations** section +lists each available attestation with its: + +- Type (for example, SBOM or VEX) +- Predicate type URI +- Digest reference for use with `cosign` + +These attestations are generated and signed automatically as part of the Docker +Hardened Image build process. + + +## Verify image attestations with Docker Scout You can use the [Docker Scout](/scout/) CLI to list and retrieve attestations for Docker Hardened Images, including images mirrored into your organization's namespace. @@ -231,21 +251,40 @@ Example output: > --key https://registry.scout.docker.com/keyring/dhi/latest.pub --experimental-oci11 > ``` -## Available DHI attestations +## Verify Helm chart attestations with Docker Scout -See [available -attestations](../core-concepts/attestations.md#available-attestations) for list -of attestations available for each DHI. +You can use the Docker Scout CLI to list and retrieve attestations for DHI Helm +charts using the same commands as for images. -## Explore attestations on Docker Hub +### List available chart attestations -You can also browse attestations visually when [exploring an image -variant](./explore.md#view-image-variant-details). The **Attestations** section -lists each available attestation with its: +To list all attestations attached to a DHI Helm chart: -- Type (e.g. SBOM, VEX) -- Predicate type URI -- Digest reference for use with `cosign` +```console +$ docker scout attestation list /: +``` -These attestations are generated and signed automatically as part of the Docker -Hardened Image build process. \ No newline at end of file +For example, to view attestations for the Redis HA chart for the `docs` organization: + +```console +$ docker scout attestation list docs/dhi-redis-ha-chart:4.35.2 +``` + +This command displays an overview of the chart including its provenance source +and a detailed list of all available attestations with their predicate types and +digest information. + +### Retrieve a specific chart attestation + +To retrieve the full content of a specific attestation, use: + +```console +$ docker scout attestation get /: --predicate-type +``` + +For example, to view the SLSA provenance: + +```console +$ docker scout attestation get docs/dhi-redis-ha-chart:4.35.2 \ + --predicate-type https://slsa.dev/provenance/v0.2 +```