[WIP] build: rego source policies

_vale/config/vocabularies/Docker/accept.txt

@@ -169,6 +169,7 @@ Qualcomm
 Quickview
 rebalance
 reimplement
+Rego
 Rekor
 rollback
 rootful
@@ -179,6 +180,7 @@ scrollable
 SELinux
 Slack
 snapshotters?
+Sigstore
 Snyk
 Solr
 SonarQube
@@ -290,4 +292,3 @@ Zsh
 [Vv]irtiofs
 [Vv]irtualize
 [Ww]alkthrough
-

content/manuals/build/checks.md

@@ -1,12 +1,7 @@
 ---
 title: Checking your build configuration
 linkTitle: Build checks
-params:
-  sidebar:
-    badge:
-      color: green
-      text: New
-weight: 30
+weight: 20
 description: Learn how to use build checks to validate your build configuration.
 keywords: build, buildx, buildkit, checks, validate, configuration, lint
 ---

content/manuals/build/policies/_index.md

@@ -0,0 +1,122 @@
+---
+title: Validating build inputs with policies
+linkTitle: Validating builds
+description: ""
+weight: 10
+params:
+  sidebar:
+    badge:
+      color: green
+      text: New
+---
+
+<!-- diataxis explanation -->
+
+Building with Docker often involves downloading remote resources of some kind.
+These external dependencies are called **build inputs**: Docker images, Git
+repositories, remote files, and other artifacts your build pulls in.
+
+For example:
+
+- Pulling images from a registry
+- Cloning a source code repository
+- Fetching files from a server over HTTPS
+
+When consuming build inputs, it's a good idea to verify the contents are what
+you expect them to be. One way to do this is to use the `--checksum` option for
+the `ADD` Dockerfile instruction. This lets you verify the SHA256 checksum of a
+remote resource when pulling it into a build:
+
+```dockerfile
+ADD --checksum=sha256:c0ff3312345… https://example.com/archive.tar.gz /
+```
+
+If the remote `archive.tar.gz` file does not match the checksum that the
+Dockerfile expects, the build fails.
+
+Checksums verify that content matches what you expect, but only for the `ADD`
+instruction. They don't tell you anything about where the content came from or
+how it was produced. You can't use checksums to enforce constraints like
+"images must be signed" or "dependencies must come from approved sources."
+
+## Build policies
+
+Buildx version 0.31.0 added support for **build policies**. Build policies are
+rules for securing your Docker build supply chain, and help protect against
+upstream compromises, malicious dependencies, and unauthorized modifications to
+your build inputs.
+
+With build policies, you can perform extended verifications on inputs, such as:
+
+- Docker images must use digest references (not tags alone)
+- Images must have provenance attestations and cosign signatures
+- Git tags are signed by maintainers with a PGP public key
+- All remote artifacts must use HTTPS and include a checksum for verification
+
+Build policies are defined in a declarative policy language, called Rego,
+created for the [Open Policy Agent (OPA)](https://www.openpolicyagent.org/).
+The following example shows a minimal build policy in Rego.
+
+```rego {title="Dockerfile.rego"}
+package docker
+
+default allow := false
+
+# Allow any local inputs for this build
+allow if input.local
+
+# Allow images, but only if they have provenance attestations
+allow if {
+    input.image.hasProvenance
+}
+
+decision := {"allow": allow}
+```
+
+If the Dockerfile associated with this policy references an image with no
+provenance attestation in a `FROM` instruction, the policy would be violated
+and the build would fail.
+
+## Use cases
+
+Build policies help you enforce security and compliance requirements on your
+Docker builds. Common scenarios where policies provide value:
+
+### Enforce base image standards
+
+Require all production Dockerfiles to use specific, approved base images with
+digest references. Prevent developers from using arbitrary images that haven't
+been vetted by your security team.
+
+### Validate third-party dependencies
+
+When your build downloads files, libraries, or tools from the internet, verify
+they come from trusted sources and match expected checksums or signatures. This
+protects against supply chain attacks where an upstream dependency is
+compromised.
+
+### Ensure signed releases
+
+Require that all dependencies - whether container images or downloaded files -
+have valid signatures from trusted parties. Use GPG signatures, Sigstore
+attestations, or GitHub attestations to verify authenticity.
+
+### Meet compliance requirements
+
+Some regulatory frameworks require evidence that you validate your build
+inputs. Build policies give you an auditable, declarative way to demonstrate
+you're checking dependencies against security standards.
+
+### Separate development and production rules
+
+Apply stricter validation for production builds while allowing more flexibility
+during development. The same policy file can contain conditional rules based on
+build context or target.
+
+## Get started
+
+Ready to start writing policies? The [Introduction](./intro.md) tutorial walks
+you through creating your first policy and teaches the Rego basics you need.
+
+For practical examples you can copy and adapt, see the [Example
+policies](./examples.md) library.