diff --git a/content/manuals/build/policies/inputs.md b/content/manuals/build/policies/inputs.md index 2792afdb69..1dad093764 100644 --- a/content/manuals/build/policies/inputs.md +++ b/content/manuals/build/policies/inputs.md @@ -343,6 +343,40 @@ allow if { } ``` +### Provenance materials + +`input.image.provenance.materials` contains the build dependencies recorded in +an image's provenance. Each entry is an input object with the same `image`, +`git`, or `http` fields used for direct build inputs. + +For example, inspect the Git repository used to build a base image: + +```rego +allow if { + some material in input.image.provenance.materials + material.git.host == "github.com" + material.git.remote == "https://github.com/myorg/base.git" +} +``` + +An image material can have its own `image.provenance.materials` array. Access +nested fields to resolve metadata for those dependencies as needed. Buildx +supports image, Git, and HTTP material sources; unsupported material URIs +are skipped with a warning. Checking a parent image doesn't automatically +apply your rules to every material. Write explicit conditions for the +dependencies you need to validate. + +To inspect a nested field without evaluating a policy, use `--fields`: + +```console +$ docker buildx policy eval --print \ + --fields 'image.provenance.materials[0].git.commitChecksum' \ + docker-image://registry.example.com/team/base:latest +``` + +The example requests Git metadata for the first material. Choose the index +and field for the material you want to inspect. + ## Git inputs Git inputs represent Git repositories referenced in `ADD` instructions or used @@ -567,6 +601,13 @@ allow if { } ``` +#### `input.env.depth` + +The input's depth in the provenance material tree. A direct build input has +depth `0`, its materials have depth `1`, and each nested material increases +the depth by one. For example, access `material.env.depth` when iterating +over `input.image.provenance.materials`. + #### `input.env.args` Build arguments passed with `--build-arg`. Access specific arguments by key. diff --git a/content/manuals/build/policies/validate-images.md b/content/manuals/build/policies/validate-images.md index 0c01f41b15..e646e3cb0d 100644 --- a/content/manuals/build/policies/validate-images.md +++ b/content/manuals/build/policies/validate-images.md @@ -391,6 +391,37 @@ signing. The signature metadata provides cryptographic proof of the build's origin. For complete signature verification examples, see [Example policies](./examples.md). +## Validate provenance materials + +An image's provenance can expose metadata about its own build dependencies +through `input.image.provenance.materials`. Use this to check the source of a +base image, rather than only checking the base image's registry and tag. + +The following policy requires the base image's provenance to include a Git +material with an approved repository and commit: + +```rego +package docker + +default allow := false + +allow if input.local + +allow if { + some material in input.image.provenance.materials + material.git.remote == "https://github.com/myorg/base.git" + material.git.commitChecksum == "0123456789abcdef0123456789abcdef01234567" +} + +decision := {"allow": allow} +``` + +Replace the repository and commit with your approved source. This checks for +at least one matching material; it doesn't restrict other dependencies. +For image materials, you can also inspect their provenance and nested +materials. See the [material input reference](./inputs.md#provenance-materials) +for supported sources and metadata resolution. + ## Combine multiple checks Real policies often combine several checks. Multiple conditions in one `allow`