From 8ac30aaec4decf14aa7565c229a17473777ea246 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 13 Oct 2026 12:48:09 +0200
Subject: [PATCH] docs: document URL blocking in build steps (#26312)

## Summary

The build policy docs covered HTTP downloads through `ADD` but did not
explain how to block URLs requested by `RUN` steps. Add a tested
allowlist example using `"caps": {"exec.proxy": true}` in the policy
file and update the HTTP input reference, with a brief builder flag
example for CI.

Verified that Debian package downloads pass and the blocked URL returns
HTTP 403 and fails the build. Scoped Markdown and Vale checks passed,
with one existing Vale warning on unchanged text.

@netlify /build/policies/usage/

Generated by Codex
---
 content/manuals/build/policies/inputs.md |  4 +-
 content/manuals/build/policies/usage.md  | 74 +++++++++++++++++++++++-
 2 files changed, 74 insertions(+), 4 deletions(-)

diff --git a/content/manuals/build/policies/inputs.md b/content/manuals/build/policies/inputs.md
index 43aad88629..096f486e30 100644
--- a/content/manuals/build/policies/inputs.md
+++ b/content/manuals/build/policies/inputs.md
@@ -19,6 +19,7 @@ Build inputs correspond to Dockerfile instructions:
 | `FROM alpine:latest`                    | Image      | `input.image`  |
 | `COPY --from=builder /app /app`         | Image      | `input.image`  |
 | `ADD https://example.com/file.tar.gz /` | HTTP       | `input.http`   |
+| `RUN curl https://example.com/`        | HTTP       | `input.http`   |
 | `ADD git@github.com:user/repo.git /src` | Git        | `input.git`    |
 | Build context (`.`)                     | Local      | `input.local`  |
 
@@ -27,7 +28,8 @@ Each input type has specific fields available for policy evaluation.
 ## HTTP inputs
 
 HTTP inputs represent files downloaded over HTTP or HTTPS using the `ADD`
-instruction.
+instruction, or requests from `RUN` instructions when BuildKit's proxy is
+enabled. See [Block URLs in build steps](./usage.md#block-urls-in-build-steps).
 
 ### Example Dockerfile
 
diff --git a/content/manuals/build/policies/usage.md b/content/manuals/build/policies/usage.md
index 08935b6354..7f195241fd 100644
--- a/content/manuals/build/policies/usage.md
+++ b/content/manuals/build/policies/usage.md
@@ -6,9 +6,9 @@ keywords: build policies, policy eval, docker buildx, policy development, debugg
 weight: 20
 ---
 
-Build policies validate inputs before builds execute. This guide covers how to
-develop policies iteratively and apply them to real builds with `docker buildx
-build` and `docker buildx bake`.
+Build policies validate build inputs and can check HTTP(S) requests during build
+steps. This guide covers how to develop policies iteratively and apply them to
+builds with `docker buildx build` and `docker buildx bake`.
 
 ## Prerequisites
 
@@ -223,6 +223,74 @@ Use only your specified policy:
 $ docker buildx build --policy reset=true,filename=strict.rego .
 ```
 
+## Block URLs in build steps
+
+To check HTTP(S) requests from `RUN` instructions, add
+`"caps": {"exec.proxy": true}` to the policy's `decision` object. This enables
+BuildKit's proxy, which checks requests against your `input.http` rules.
+By default, these rules only apply to `ADD` downloads.
+
+Save this policy as `Dockerfile.rego` alongside your Dockerfile to allow Debian
+package downloads and block requests to other hosts:
+
+```rego {title="Dockerfile.rego"}
+package docker
+
+default allow := false
+
+allow if input.local
+
+allow if {
+    input.image.repo == "debian"
+}
+
+allow if {
+    input.http.host == "deb.debian.org"
+}
+
+decision := {
+    "allow": allow,
+    "caps": {"exec.proxy": true},
+}
+```
+
+Test it with this Dockerfile:
+
+```dockerfile {title="Dockerfile"}
+FROM debian:trixie
+RUN apt-get update && apt-get install -y curl
+RUN curl -f http://example.com/
+```
+
+```console
+$ docker buildx build --no-cache --progress=plain .
+```
+
+The package downloads from `deb.debian.org` succeed. The proxy denies the request
+to `example.com` with HTTP 403, and `curl -f` fails the build. Use `--no-cache`
+when testing to run the steps again.
+
+To restrict individual URLs, use `input.http.url` or match both `input.http.host`
+and `input.http.path`. See the [HTTP input reference](./inputs.md#http-inputs).
+
+The proxy supports Linux build steps. Applications must use the injected proxy
+environment variables and trust BuildKit's certificate for HTTPS. BuildKit adds
+the certificate to the system trust store. Traffic that bypasses the proxy is
+blocked.
+
+### Enable the proxy for a CI builder
+
+For a dedicated CI builder, enable the proxy for all builds with
+`--buildkitd-flags '--proxy-network'`:
+
+```console
+$ docker buildx create --name ci-policy --driver docker-container \
+    --buildkitd-flags '--proxy-network' --use --bootstrap
+```
+
+This replaces the `exec.proxy` opt-in in each policy file. You still need a
+policy to restrict URLs.
+
 ## Using policies with bake
 
 [Bake](/build/bake/) supports automatic policy loading just like `docker buildx