build: explain provenance material policy checks

The policy guides omit metadata from dependencies recorded in provenance.
Describe nested material inputs and depth, and show how to check the Git
repository and commit used to build a base image.

Signed-off-by: CrazyMax <1951866+crazy-max@users.noreply.github.com>

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`