Merge pull request #26472 from crazy-max/docs/buildx-3662-provenance-materials

build: explain provenance material policy checks

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.

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`