From c9591713c62177fb6f6f432327108803d61fc3b7 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Fri, 25 Sep 2026 21:40:01 +0000 Subject: [PATCH] ai-gov: http and path rules for organization policies Co-Authored-By: Claude Opus 5.5 Signed-off-by: Craig Osterhout --- .../manuals/ai/sandboxes/governance/_index.md | 3 +- .../governance/access-controls/_index.md | 2 +- .../governance/access-controls/local.md | 3 +- .../governance/access-controls/network.md | 15 ++++-- .../access-controls/organization.md | 46 ++++++++++++++++--- .../ai/sandboxes/governance/concepts.md | 35 ++++++++------ .../monitor-and-enforce/monitoring.md | 4 ++ 7 files changed, 80 insertions(+), 28 deletions(-) diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 76e57efe7654..7c1fba061daf 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -51,8 +51,7 @@ 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. A local policy rule can match a host, or an HTTP - method and path. + access from sandboxes, by host or by 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 79a892b72fef..bcaabdd429a5 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. A local policy rule can match a host, or an HTTP method and path. + sandboxes, by host or by 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 883d9cd3a9c2..177fba1e7d87 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/local.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/local.md @@ -189,7 +189,8 @@ Method names are case-insensitive. The accepted values are `GET`, `HEAD`, 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. +takes one path. Repeating `--path` keeps only the last value, and a comma is +read as part of the path, so add a separate rule for each 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` diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md index 2c33d1aa0bd1..d3727531cd96 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/network.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md @@ -12,9 +12,9 @@ use separate network policy configuration. See 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. 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. +workflow needs, or block destinations that should stay unavailable. Rules can +also match the HTTP method and path of a request, so a policy can allow part of +an API without allowing all of it. You can configure network access in two places: @@ -58,8 +58,13 @@ 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). +Configure them in either place: + +- Organization policies, in the network rule composer in Docker Home. Set the + rule **Type** to **HTTP**, then select the methods and path patterns. See + [Add a network rule](organization.md#add-a-network-rule). +- Local policies, with `--method` and `--path` on `sbx policy`. See + [HTTP method and path rules](local.md#http-method-and-path-rules). ## Local network rules diff --git a/content/manuals/ai/sandboxes/governance/access-controls/organization.md b/content/manuals/ai/sandboxes/governance/access-controls/organization.md index 8007bf7890d3..fa83d693989d 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/organization.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/organization.md @@ -55,14 +55,47 @@ To create a policy: 1. Set the **Scope** to **Organization** or **Teams**. If you select **Teams**, choose the teams the policy applies to. See [Scope policies to teams](#scope-policies-to-teams). -1. Define the policy rules. For network and filesystem policies, select - **Add rule** for each rule. For MCP policies, enter Cedar statements in the - policy editor. For syntax and examples, use the relevant access-control page - in [Choose a policy type](#choose-a-policy-type). +1. Define the policy rules. + - Network and filesystem policies: select **Add rule** for each rule. For a + network policy, see [Add a network rule](#add-a-network-rule). + - MCP policies: enter Cedar statements in the policy editor. See + [MCP access policies](mcp.md). Existing policies are listed with their name, scope, rule count, and last update. Use the action menu (⋮) to edit or delete a policy. +### Add a network rule + +Each rule has an optional **Rule name**, an **Effect** of **Allow** or **Deny**, +and a **Type** that decides what the rule matches. + +- **All traffic** matches every request to the destinations you list, on any + port, method, and path. + - Under **Destinations**, add the hosts, IP addresses, or CIDR ranges the + rule covers. A destination matches any port unless you add one, such as + `example.com:8080`. + - Under **Protocols**, select the transport protocols the rule applies to. +- **HTTP** matches only HTTP requests with the methods and paths you specify. + - In **Destination**, enter the host or IP address the rule covers. It + matches any port unless you add one. Enter the destination with no scheme + and no path, so `api.github.com` rather than + `https://api.github.com/repos`. A CIDR range isn't accepted here. Use an + **All traffic** rule for one. A local HTTP rule accepts only a host. + - Under **HTTP methods**, select the methods the rule applies to. Leave + **any (\*)** selected to match every method listed. A method the composer + doesn't list won't match, which differs from the CLI, where `--method ANY` + matches every HTTP method. + - Under **Path patterns**, add one or more paths the rule covers, such as + `/repos/*` and `/v1/**`. Leave it empty to match any path. + +An HTTP rule's paths all belong to its one destination, so to cover paths on a +second host, add a second rule. For the pattern syntax and how HTTP rules +combine with **All traffic** rules, see +[HTTP rules](../concepts.md#http-method-and-path). + +The composer summarizes the rule in a sentence as you fill it in, so you can +confirm the effect, methods, and destination before saving. + ## Configure a support message Admins can add an optional support message that appears after the policy denial @@ -87,7 +120,7 @@ Organization policies are managed by access surface. Use the access-control pages for syntax, examples, and enforcement details: - [Network access policies](network.md): control outbound network access from - sandboxes. + sandboxes, by host or by 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, @@ -157,7 +190,8 @@ developer machine: - Network policy is evaluated on every outbound request. Once a policy change has synced to the developer's machine (up to 5 minutes), it applies - immediately to subsequent requests. + immediately to subsequent requests. HTTP rules are evaluated per request in + the same way. - Filesystem policy is only checked when a workspace is mounted — that is, when a sandbox is created. Once a sandbox is running, changing the diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index 0e0fdcc79176..1d0265209266 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -109,19 +109,28 @@ 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). +An HTTP rule names one or more methods, a destination, and path patterns. What +each part accepts depends on where you configure the rule: + +| Part | Organization policy | Local policy | +| ----------- | ------------------------------------------ | --------------------------------- | +| Method | **any (\*)**, or one or more listed methods | `ANY`, or one or more methods | +| Destination | A host or IP address | A host | +| Path | One or more absolute path patterns | One absolute path pattern | + +A destination can include a port, and a path pattern looks like `/api/**`. + +A CIDR range isn't a valid HTTP destination on either surface, and a local +rule doesn't accept an IP address either. Use a plain network rule for those +destinations. To cover a second path in a local policy, add a second rule. + +Every rule applies to at least one method. On the CLI, `--method ANY` covers +every HTTP method. In the composer, **any (\*)** covers every method the +composer lists. For the methods you can select individually, see +[Add a network rule](access-controls/organization.md#add-a-network-rule) for an +organization policy and +[HTTP method and path rules](access-controls/local.md#http-method-and-path-rules) +for a local one. Path patterns follow the same wildcard rules as filesystem paths, where `*` matches within one path segment and `**` matches any depth. A pattern without a 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 bc75018dc633..db25b17581a5 100644 --- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md @@ -161,6 +161,10 @@ POLICY SOURCE APPLIES TO SUMMARY local-policy local all network: 2 allow (L4), 1 deny (L7) ``` +When the same decision has entries at both layers, each layer gets its own +count, L4 first. Two host allows and one HTTP allow read +`network: 2 allow (L4), 1 allow (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