diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 76e57efe765..7c1fba061da 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 79a892b72fe..bcaabdd429a 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 55a58cef832..7dfb5024ea2 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/local.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/local.md @@ -193,7 +193,13 @@ 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: + +```console +$ sbx policy allow network api.github.com --method GET --path '/repos/**' +$ sbx policy allow network api.github.com --method GET --path '/users/**' +``` 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 6582be2a30b..1fbdbe1ed12 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 944b0bfbe1b..d38d08507ba 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/organization.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/organization.md @@ -55,10 +55,11 @@ 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). 1. For a network policy, set **Require approval before access** if developers should confirm each destination before a sandbox can reach it. See [Require approval for a network policy](#require-approval-for-a-network-policy). @@ -66,6 +67,36 @@ To create a policy: 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**, a **Type** that decides what the rule +matches, and a **Decision** of **Allow** or **Deny**. + +- **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 local HTTP rule accepts only a host. + - Under **HTTP methods**, select the methods the rule applies to. Use + **Select all** to select every method, or **Read-only** to select `GET`, + `HEAD`, and `OPTIONS`. A rule saved with no methods selected matches every + method the composer lists. The composer doesn't list `CONNECT` or + `TRACE`, 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. +- **All traffic** matches every request to the destinations you list, on any + port, method, and path. + - Under **Protocols**, select **TCP**, **UDP**, or **Both**. + - 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`. + +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). + ### Require approval for a network policy Turning on **Require approval before access** means the destinations a network @@ -112,7 +143,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, @@ -185,7 +216,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. - An approval requirement applies from the point the policy change syncs. Destinations a developer already approved stay reachable, because the diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index bb17a1bcaad..a7c2928256e 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -122,26 +122,37 @@ 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: +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 | 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/**` | +| Part | Organization policy | Local policy | +| ----------- | ------------------------------------------ | --------------------------------- | +| Method | 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 CIDR range isn't a valid HTTP destination. Use a network rule to cover one. +A destination can include a port, and a path pattern looks like `/api/**`. -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). +A local rule doesn't accept an IP address or a CIDR range. 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, a rule with no methods selected 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 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 `..`. +below it. Every pattern must start with `/` and can't contain a query string, a +fragment, or a `..` segment. A local rule's path must also be canonical, so it +can't contain percent-encoding, control characters, repeated or trailing +slashes, or a `.` segment. For the full list, see +[HTTP method and path rules](access-controls/local.md#http-method-and-path-rules). 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 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 5e46ba7c931..9db93309bf9 100644 --- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md @@ -170,6 +170,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