From 635579312355740e36f8ddb5222c59896caac900 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Tue, 22 Sep 2026 15:30:37 -0700 Subject: [PATCH 1/2] ai-gov: add l7 local policy Signed-off-by: Craig Osterhout --- .../manuals/ai/sandboxes/governance/_index.md | 3 +- .../governance/access-controls/_index.md | 2 +- .../governance/access-controls/local.md | 91 +++++++++++++++++++ .../governance/access-controls/network.md | 20 +++- .../ai/sandboxes/governance/concepts.md | 49 ++++++++++ .../monitor-and-enforce/monitoring.md | 50 ++++++++-- 6 files changed, 206 insertions(+), 9 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 4db45c542720..589233e73a71 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -47,7 +47,8 @@ MCP policy basics, evaluation, and precedence. - [Organization policies](access-controls/organization.md): centrally manage sandbox policies across your organization. - [Network access policies](access-controls/network.md): control outbound network - access from sandboxes. + access from sandboxes. A local policy rule can match a host, or an HTTP + method and path. - [Filesystem access policies](access-controls/filesystem.md): control which host paths sandboxes can mount as workspaces. - [MCP access policies](access-controls/mcp.md): control MCP server registration, diff --git a/content/manuals/ai/sandboxes/governance/access-controls/_index.md b/content/manuals/ai/sandboxes/governance/access-controls/_index.md index a2d2e1ff1f3c..79a892b72fef 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/_index.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/_index.md @@ -20,7 +20,7 @@ and filesystem rule format. ## Access surfaces - [Network access policies](network.md): control outbound network access from - sandboxes. + sandboxes. A local policy rule can match a host, or an HTTP method and path. - [Filesystem access policies](filesystem.md): control which host paths sandboxes can mount as workspaces. - [MCP access policies](mcp.md): control MCP server registration, tool calls, diff --git a/content/manuals/ai/sandboxes/governance/access-controls/local.md b/content/manuals/ai/sandboxes/governance/access-controls/local.md index 4320f743ef5a..e23cbfd56bd4 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/local.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/local.md @@ -103,6 +103,11 @@ Available values are `allow-all`, `balanced`, and `deny-all`. ## Managing rules +A rule covers a destination host. It can also name HTTP methods and paths to +narrow the match to part of that host. + +### Network rules + Use [`sbx policy allow`](/reference/cli/sbx/policy/allow/) and [`sbx policy deny`](/reference/cli/sbx/policy/deny/) to add or restrict access on top of the active preset. Changes take effect immediately. Rules apply to @@ -152,6 +157,84 @@ To remove a sandbox-scoped rule, pass `--sandbox `: $ sbx policy rm network --sandbox my-sandbox --resource api.example.com ``` +### HTTP method and path rules + +Add `--method` to an allow or deny rule to match specific HTTP methods on a +host, and `--path` to restrict it to part of the host's URL space: + +```console +$ sbx policy allow network api.github.com --method GET --path '/repos/org/project/**' +``` + +Quote the path so your shell doesn't expand the wildcard. Pass several methods +as a comma-separated list: + +```console +$ sbx policy allow network api.github.com --method GET,HEAD +``` + +`--method ANY` matches every HTTP method, and `--path` defaults to `/**` when +you omit it: + +```console +$ sbx policy allow network api.github.com --method ANY +``` + +`ANY` can't be combined with specific methods, and a path without a method is +rejected. Pass a method, or use `ANY` when you mean every method. + +Method names are case-insensitive. The accepted values are `GET`, `HEAD`, +`POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `CONNECT`, and `TRACE`. + +A path must start with `/` and be canonical. It can't contain a query string, a +fragment, percent-encoding, control characters, surrounding whitespace, +repeated or trailing slashes, or dot segments such as `.` and `..`. Each rule +takes one path. + +Hosts follow the same patterns as network rules and can include a port. Write +the host on its own, without a scheme, so an HTTP rule takes `api.example.com` +rather than `https://api.example.com`. + +A local HTTP rule takes a hostname. To match an IP address or a CIDR range, +add a plain network rule for that destination instead. + +Deny rules take the same flags, which is the usual way to carve a method or +path out of a broader allow: + +```console +$ sbx policy allow network api.example.com +$ sbx policy deny network api.example.com --method POST --path '/admin/**' +``` + +For how the two layers combine, see +[HTTP rules](../concepts.md#http-method-and-path). + +Remove an HTTP rule by naming the same qualifiers you added it with, or by +rule ID: + +```console +$ sbx policy rm network --resource api.github.com --method GET --path '/repos/org/project/**' +$ sbx policy rm network --id 7f3a1c2e-4a73-4e05-bc9d-f2f9a4b50d67 +``` + +List HTTP rules with `--type http`, or see them alongside network rules in a +wide listing, where the `METHOD` and `PATH` columns are empty for rules that +match a whole host: + +```console +$ sbx policy ls --wide +TYPE METHOD PATH +network - - +http GET /repos/org/project/** +``` + +> [!NOTE] +> `sbx policy check network` and `sbx policy log` don't evaluate or display +> HTTP methods and paths. A check reports the decision for the host, which can +> differ from the decision for a specific method and path on that host. + +## Inspecting rules + To inspect which policies are active and where they come from, use `sbx policy ls`. Use `--source` to filter by origin (`local`, `org`, `kit`), `--decision` to filter by outcome (`allow`, `deny`), and `--wide` for @@ -228,3 +311,11 @@ a `Governance:` status line showing `Managed by `, it is. Add `--include-inactive` to confirm your rule shows an `inactive` status. If so, the block can only be lifted by updating the org policy in Docker Home or via the [API](/reference/api/ai-governance/). + +### An HTTP method or path is blocked on an allowed host + +A host that a network rule allows can still have individual methods or paths +denied by an HTTP rule. Run `sbx policy ls --type http` to see which HTTP rules +apply. `sbx policy check network` reports the decision for the host only, so it +shows a host as allowed even when the specific request is denied. See +[HTTP method and path rules](#http-method-and-path-rules). diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md index 3085f7aa14ce..c567d3e03125 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/network.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md @@ -8,7 +8,9 @@ keywords: docker sandboxes, network access, network rules, governance, local pol Network access policies control outbound connections from sandboxes. Each policy contains one or more rules that allow the domains, IP ranges, and ports a -workflow needs, or block destinations that should stay unavailable. +workflow needs, or block destinations that should stay unavailable. A local +policy rule can also match the HTTP method and path of a request, so it can +allow part of an API without allowing all of it. You can configure network access in two places: @@ -40,6 +42,22 @@ Examples: For exact wildcard behavior and CIDR support, see [Network rules](../concepts.md#network-rules). +## HTTP method and path rules + +A network rule matches a destination, so it allows or blocks everything a +sandbox sends there. An HTTP rule narrows the match to specific HTTP methods +and URL paths on that destination, which lets a policy allow reads from an API +without allowing writes to it. + +HTTP rules and network rules layer. A network allow is the baseline for a +destination and HTTP rules carve into it, while a network deny blocks the +destination outright and no HTTP allow can reopen it. For the pattern syntax +and the full matching table, see +[HTTP rules](../concepts.md#http-method-and-path). + +Add them to a local policy with `--method` and `--path` on `sbx policy`. See +[HTTP method and path rules](local.md#http-method-and-path-rules). + ## Local network rules Use `sbx policy allow network` and `sbx policy deny network` to manage local diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index 765b56d514e0..f1efd9182e72 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -99,6 +99,55 @@ need to match the root domain and its subdomains. Both IPv4 and IPv6 notation are supported: `10.0.0.0/8`, `192.168.1.0/24`, `2001:db8::/32`. +#### HTTP method and path + +A network rule matches a destination host on its own. An HTTP rule is a network +rule that also names an HTTP method and URL path, so a policy can allow reads +from an API without allowing writes to it. + +An HTTP rule names one or more methods, a destination, and a path pattern: + +| Part | Accepts | +| ----------- | ------------------------------------------------------------- | +| Method | One or more HTTP methods, or every method | +| Destination | A host, with an optional port | +| Path | An absolute path pattern, such as `/api/**` | + +A CIDR range isn't a valid HTTP destination. Use a network rule to cover one. + +A rule that names no method matches every method. For the methods you can +select individually, see +[HTTP method and path rules](access-controls/local.md#http-method-and-path-rules). + +Path patterns follow the same wildcard rules as filesystem paths, where `*` +matches within one path segment and `**` matches any depth. A pattern without a +wildcard matches that path exactly, so `/repos` matches `/repos` and nothing +below it. A pattern must start with `/` and be canonical, so it can't contain a +query string, a fragment, percent-encoding, control characters, repeated or +trailing slashes, or dot segments such as `.` and `..`. + +HTTP requests are evaluated against both layers. A network rule sets the +baseline for a host, and HTTP rules adjust individual methods and paths within +it: + +| Rules that cover the host | Result for an HTTP request | +| --------------------------- | ----------------------------------------------------------------------- | +| Network allow only | Allowed at any method and path | +| HTTP allow only | Allowed only where a rule matches the method and path. Anything else is denied | +| Network allow and HTTP deny | The denied methods and paths are blocked. The rest stay allowed | +| Network deny | Blocked. An HTTP allow can't reopen a denied host | + +A network deny is therefore a floor that HTTP rules can't raise, while a +network allow is a ceiling that HTTP rules can carve into. + +When a rule requires a method and path decision, the sandbox HTTP proxy +evaluates each request separately instead of deciding once per connection. + +Those requests have to go through the proxy. A connection it can't inspect, +such as one it handles transparently, is blocked rather than evaluated. +Traffic that isn't HTTP, such as SSH, carries no method or path, so HTTP rules +never match it. Control those destinations with network rules. + For local and organization policy configuration, see [Network access policies](access-controls/network.md). diff --git a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md index 700545187223..297c0cf38421 100644 --- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md @@ -34,8 +34,11 @@ The columns are: - `APPLIES TO`: which sandboxes the policy applies to. `all` means the policy is global. `sandbox:` scopes it to a single sandbox; a profile name scopes it to sandboxes using that profile. -- `SUMMARY`: a count of rules by type and decision — for example, - `network: 5 allow, 1 deny`. +- `SUMMARY`: a count of rule entries by type and decision, for example + `network: 5 allow, 1 deny`. A rule that names several destinations + contributes one entry per destination. When the listing includes rules that + match an HTTP method and path, the network count labels each part `(L4)` or + `(L7)`. See [HTTP rules](#http-rules). To see full rule-level detail including rule IDs and resources, pass `--wide`. To inspect a single policy or rule, use `sbx policy inspect`: @@ -100,10 +103,10 @@ while organization governance is active. Local and kit-defined deny rules stay active and aren't hidden, because a deny still applies on top of the organization policy. See [Precedence](../concepts.md#precedence). -Use `--type network` or `--type filesystem` to show only policies of that type. -Without a sandbox argument, `sbx policy ls` shows every policy across all -sandboxes. Pass a sandbox name to filter to global policies and those scoped to -that sandbox: +Use `--type network`, `--type filesystem`, or `--type http` to show only +policies of that type. Without a sandbox argument, `sbx policy ls` shows every +policy across all sandboxes. Pass a sandbox name to filter to global policies +and those scoped to that sandbox: ```console $ sbx policy ls my-sandbox @@ -127,6 +130,41 @@ default local policy allows read and write access to all paths, shown as the two `default-fs-*` rules above. For the rule syntax and path patterns, see [Policy concepts](../concepts.md#filesystem-rules). +### HTTP rules + +Rules that match an HTTP method and path are listed as type `http`. Pass +`--wide` to see the `METHOD` and `PATH` columns alongside network rules: + +```console +$ sbx policy ls --wide +TYPE METHOD PATH +network - - +http GET /repos/org/project/** +http POST /admin/** +``` + +Rules that match a whole destination show `-` in both columns. To list only +HTTP rules, pass `--type http`. + +HTTP rules are counted as network rules in the `SUMMARY` column, with each part +labeled by the network layer it matches on. `L4` counts entries that match a +whole destination, and `L7` counts those that also match an HTTP method and +path: + +```console +$ sbx policy ls +POLICY SOURCE APPLIES TO SUMMARY +local-policy local all network: 2 allow (L4), 1 deny (L7) +``` + +The labels appear when the current listing includes at least one HTTP rule. +Because filters and hidden inactive rules change what the listing contains, a +filtered listing with no HTTP rules shows an unlabeled count, such as +`network: 42 allow`. + +For the rule syntax, see +[HTTP method and path](../concepts.md#http-method-and-path). + ## Monitoring traffic Use `sbx policy log` to see which hosts your sandboxes have contacted and From 64c42b53955b56bdf2638bee507cd268dde64264 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Tue, 22 Sep 2026 15:46:08 -0700 Subject: [PATCH 2/2] tweak wording Signed-off-by: Craig Osterhout --- .../ai/sandboxes/governance/access-controls/network.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md index c567d3e03125..876ee8fcfce5 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/network.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md @@ -49,8 +49,8 @@ sandbox sends there. An HTTP rule narrows the match to specific HTTP methods and URL paths on that destination, which lets a policy allow reads from an API without allowing writes to it. -HTTP rules and network rules layer. A network allow is the baseline for a -destination and HTTP rules carve into it, while a network deny blocks the +HTTP rules layer on top of network rules. A network allow is the baseline for +a destination and HTTP rules carve into it, while a network deny blocks the destination outright and no HTTP allow can reopen it. For the pattern syntax and the full matching table, see [HTTP rules](../concepts.md#http-method-and-path).