[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,159 @@
+---
+title: Validating build inputs with policies
+linkTitle: Validating builds
+description: ""
+weight: 10
+params:
+  sidebar:
+    badge:
+      color: green
+      text: New
+---
+
+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."
+
+## Prerequisites
+
+Build policies require:
+
+- **Buildx 0.31.0 or later** - Check your version: `docker buildx version`
+- **BuildKit 0.26.0 or later** - Verify with: `docker buildx inspect
+  --bootstrap`
+
+If you're using Docker Desktop, ensure you're on a version that includes these
+updates.
+
+## 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.
+
+## How policies work
+
+When you run `docker buildx build`, buildx:
+
+1. Resolves all build inputs (images, Git repos, HTTP downloads)
+2. Looks for a policy file matching your Dockerfile name (e.g.,
+   `Dockerfile.rego`)
+3. Evaluates each input against the policy before the build starts
+4. Allows the build to proceed only if all inputs pass the policy
+
+Policies are written in Rego (Open Policy Agent's policy language). You don't
+need to be a Rego expert - the [Introduction](./intro.md) tutorial teaches you
+everything needed.
+
+Policy files live alongside your Dockerfile:
+
+```text
+project/
+├── Dockerfile
+├── Dockerfile.rego
+└── src/
+```
+
+No additional configuration is needed - buildx automatically finds and loads
+the policy when you build.
+
+## 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 usage guidance, see [Using build policies](./usage.md).
+
+For practical examples you can copy and adapt, see the [Example
+policies](./examples.md) library.

content/manuals/build/policies/built-ins.md

@@ -0,0 +1,200 @@
+---
+title: Built-in functions
+description: Buildx includes built-in helper functions to make writing policies easier
+weight: 40
+---
+
+Buildx provides built-in functions to extend Rego policies with Docker-specific
+operations like loading local files, verifying Git signatures, and pinning
+image digests.
+
+> [!NOTE]
+> These are Buildx-specific functions, distinct from [Rego's standard built-in
+> functions](https://www.openpolicyagent.org/docs/latest/policy-reference/#built-in-functions).
+> Use both Buildx functions (documented here) and Rego built-ins (like
+> `startswith`, `regex.match`) together in your policies.
+
+## Available built-in functions
+
+Buildx provides four custom built-in functions for policy development:
+
+### `print(...)`
+
+Outputs debug information during policy evaluation.
+
+**Parameters:**
+
+- Any number of values to print
+
+**Returns:** The values (pass-through)
+
+**Example:**
+
+```rego
+allow if {
+    input.image.repo == "alpine"
+    print("Allowing alpine image:", input.image.tag)
+}
+```
+
+Debug output appears when using `BUILDX_POLICY_DEBUG=1` with
+`--progress=plain`.
+
+---
+
+### `load_json(filename)`
+
+Loads and parses JSON data from local files in the build context.
+
+**Parameters:**
+
+- `filename` (string) - Path to JSON file relative to policy directory
+
+**Returns:** Parsed JSON data as Rego value
+
+**Example:**
+
+```rego
+# Load approved versions from external file
+approved_versions = load_json("versions.json")
+
+allow if {
+    input.image.repo == "alpine"
+    some version in approved_versions.alpine
+    input.image.tag == version
+}
+```
+
+**File structure:**
+
+```text
+project/
+├── Dockerfile
+├── Dockerfile.rego
+└── versions.json
+```
+
+**versions.json:**
+
+```json
+{
+  "alpine": ["3.19", "3.20"],
+  "golang": ["1.21", "1.22"]
+}
+```
+
+The JSON file must be in the same directory as the policy or in a
+subdirectory accessible from the policy location.
+
+---
+
+### `verify_git_signature(git_object, keyfile)`
+
+Verifies PGP signatures on Git commits or tags.
+
+**Parameters:**
+
+- `git_object` (object) - Either `input.git.commit` or `input.git.tag`
+- `keyfile` (string) - Path to PGP public key file (relative to policy
+  directory)
+
+**Returns:** Boolean - `true` if signature is valid, `false` otherwise
+
+**Example:**
+
+```rego
+# Require signed Git tags
+allow if {
+    input.git.tagName != ""
+    verify_git_signature(input.git.tag, "maintainer.asc")
+}
+
+# Require signed commits
+allow if {
+    input.git.commit
+    verify_git_signature(input.git.commit, "keys/team.asc")
+}
+```
+
+**Directory structure:**
+
+```text
+project/
+├── Dockerfile.rego
+└── maintainer.asc          # PGP public key
+```
+
+Or with subdirectory:
+
+```text
+project/
+├── Dockerfile.rego
+└── keys/
+    ├── maintainer.asc
+    └── team.asc
+```
+
+**Obtaining public keys:**
+
+```console
+$ gpg --export --armor [email protected] > maintainer.asc
+```
+
+---
+
+### `pin_image(image_object, digest)`
+
+Pins an image to a specific digest, overriding the tag-based reference. Use
+this to force builds to use specific image versions.
+
+**Parameters:**
+
+- `image_object` (object) - Must be `input.image` (the current image being
+  evaluated)
+- `digest` (string) - Target digest in format `sha256:...`
+
+**Returns:** Boolean - `true` if pinning succeeds
+
+**Example:**
+
+```rego
+# Pin alpine 3.19 to specific digest
+alpine_3_19_digest = "sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412"
+
+allow if {
+    input.image.repo == "alpine"
+    input.image.tag == "3.19"
+    pin_image(input.image, alpine_3_19_digest)
+}
+```
+
+**Automatic digest replacement:**
+
+```rego
+# Replace old digests with patched versions
+replace_map = {
+  "3.22.0": "3.22.2",
+  "3.22.1": "3.22.2",
+}
+
+alpine_digests = {
+  "3.22.0": "sha256:8a1f59ffb675680d47db6337b49d22281a139e9d709335b492be023728e11715",
+  "3.22.2": "sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412",
+}
+
+allow if {
+    input.image.repo == "alpine"
+    some old_version, new_version in replace_map
+    input.image.checksum == alpine_digests[old_version]
+    print("Replacing", old_version, "with", new_version)
+    pin_image(input.image, alpine_digests[new_version])
+}
+```
+
+This pattern automatically upgrades old image versions to patched releases.
+
+## Next steps
+
+- Browse complete examples: [Example policies](./examples.md)
+- Learn policy development workflow: [Using build policies](./usage.md)
+- Reference input fields: [Input reference](./inputs.md)