diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 0c9976752fa..ab3c16b4071 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -51,7 +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. + 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 a2d2e1ff1f3..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. + 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 566138f474e..511289a70e8 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/local.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/local.md @@ -85,6 +85,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 @@ -134,6 +139,80 @@ 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`. Paths must +start with `/` and can't contain a query string, a fragment, or a `..` segment. + +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 @@ -210,3 +289,19 @@ 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/). + +### A request is blocked with "Approval required" + +The destination is allowed by an organization policy that requires approval. +Run `sbx policy approval ls` to see the pending request and respond to it with +`sbx policy approval respond`. Approving applies to later requests, not the one +that was blocked, so run the operation again afterward. See +[Respond to an approval request](network.md#respond-to-an-approval-request). + +### 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 46a7486f68d..6d149f242c7 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/network.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md @@ -12,7 +12,9 @@ governance is not available for cloud sandboxes in this release. 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. +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: @@ -44,6 +46,26 @@ 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). + +Configure them in either place: + +- Organization policies, in the network rule composer in Docker Home. Set the + rule **Type** to **HTTP**, then choose 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 Use `sbx policy allow network` and `sbx policy deny network` to manage local @@ -66,6 +88,103 @@ organization or to selected teams. For setup steps and team scoping, see Use [Monitoring policies](../monitor-and-enforce/monitoring.md) to inspect which network rules are active on a developer machine. +## Approval-required access + +An organization network policy can require approval instead of granting access +outright. Destinations the policy allows aren't reachable until the developer +confirms them, which keeps an allowlist broad enough to be usable while still +putting a person in front of each destination an agent reaches for. + +Approval is a property of the policy rather than of individual rules, so +turning it on applies it to every allow rule in that policy. A destination stays +directly reachable only when every policy that allows it is one that doesn't +require approval. If a policy that requires approval also matches, the request +needs approval regardless of what the other policies allow. + +Only a destination the developer has already approved satisfies the +requirement. Preset rules, [kit-defined rules](../../customize/kits.md#control-network-access), +and rules the developer added with `sbx policy allow network` don't answer it. +An approval also can't reach a destination the organization doesn't allow at +all, and it can't override a deny rule. To withdraw a destination, add a deny +rule, which takes precedence over any approval already recorded. + +Requiring approval on a policy is available only with organization +governance. To turn it on, see +[Organization policies](organization.md#require-approval-for-a-network-policy). + +### Respond to an approval request + +When an organization policy requires approval, a sandbox can't reach a +destination until you confirm it. The request is blocked and the sandbox +receives a message naming the destination: + +```plaintext +Approval required for api.example.com. + +Review and respond with: + sbx policy approval ls +``` + +If your organization +[configures a support message](organization.md#configure-a-support-message), it +appears after the approval instructions. + +The request that triggers the prompt doesn't wait for an answer. It's denied, +and approving the destination affects later requests. Agents that retry a +failed request pick up the new access on their next attempt. For others, run +the operation again. + +List the destinations waiting for a response: + +```console +$ sbx policy approval ls +APPROVAL network:c2FuZGJveA (sandbox: my-sandbox) + api.example.com:443 + Protocol: TCP + Resource type: domain + approval required by policy "default network" + + OPTION LABEL + allow Allow + dismiss Dismiss +``` + +Each entry names the destination, the sandbox that asked for it, and the policy +that requires the approval. To inspect a single entry, pass its ID to +`sbx policy approval inspect`. + +Respond by selecting one of the options the entry offers: + +```console +$ sbx policy approval respond network:c2FuZGJveA --option allow +Recorded: Allow +``` + +Choosing `allow` grants access to that destination. Choosing `dismiss` leaves +it blocked, and the destination is requested again the next time the sandbox +tries to reach it. Repeated attempts collapse into a single entry, so a sandbox +retrying in a loop doesn't produce a queue of duplicates. + +#### What approving grants + +Approving records a rule that allows the destination the sandbox actually +asked for, scoped to the sandbox that asked. Three things follow from that: + +- The rule covers one destination, not the pattern the policy rule used. A + policy that allows `*.example.com` with approval asks about + `api.example.com` and `cdn.example.com` separately. +- A destination includes its port, so `api.example.com:443` and + `api.example.com:8443` are approved separately. +- Another sandbox reaching the same destination asks again. + +Approved destinations stay allowed until the rule is removed. List them with +`sbx policy ls --wide --created-via approval`, and remove one the same way as +any other local rule, with [`sbx policy rm network`](local.md#managing-rules). + +Approvals live in the local policy store, so [`sbx policy reset`](local.md#resetting) +removes all of them along with your other local rules. Each destination is +requested again the next time a sandbox reaches it. + > [!NOTE] > To manage Model Context Protocol (MCP) server registration and requests > through Docker's MCP gateway, use [MCP access policies](mcp.md). These diff --git a/content/manuals/ai/sandboxes/governance/access-controls/organization.md b/content/manuals/ai/sandboxes/governance/access-controls/organization.md index 47995bf4a1f..a413dc09dc0 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/organization.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/organization.md @@ -55,14 +55,75 @@ 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). 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 the rule covers. It matches any port + unless you add one. Enter a bare host 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. + - Under **HTTP methods**, select the methods the rule applies to from the + methods listed. Leave **any (\*)** selected to match every method the + composer offers. + - Under **Path patterns**, add the paths the rule covers. 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. + +### Require approval for a network policy + +Turning on **Require approval before access** means the destinations a network +policy allows aren't reachable until the developer confirms each one. For how +approval behaves and what satisfies it, see +[Approval-required access](network.md#approval-required-access). + +Before you turn it on, note that you shouldn't combine an approval requirement +with HTTP method and path rules in the same policy. Approval works on whole +destinations, and an HTTP request that a gated HTTP rule allows is blocked +without a request a developer can respond to. Keep HTTP rules in a policy that +doesn't require approval. + +To set it on an existing policy: + +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. +1. In the left-hand navigation, expand **AI Platform** and select + **Network access**. +1. Select the policy, then choose **Edit**. +1. Turn on **Require approval before access**. +1. Select **Save changes**. + +The policy's detail page reports approval as **Required** or **Not required**. +Editing a policy replaces it in full, so turning the setting off removes the +requirement from every rule in that policy. + ## Configure a support message Admins can add an optional support message that appears after the policy denial @@ -87,7 +148,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, @@ -147,8 +208,11 @@ propagate to developer machines. To apply changes immediately, users can run organization policies on the next `sbx` command. > [!WARNING] -> `sbx policy reset` deletes all locally configured policy rules. The command -> prompts for confirmation before proceeding. +> `sbx policy reset` deletes all locally configured policy rules, including any +> destinations the developer has approved under an +> [approval-required policy](network.md#approval-required-access). Those destinations are requested +> again the next time a sandbox reaches them. The command prompts for +> confirmation before proceeding. #### Enforcement timing by policy type @@ -157,7 +221,13 @@ 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 + approval is recorded on the developer's machine. To withdraw one, add a deny + rule. A deny takes precedence over a recorded approval. - 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 070d3349f31..858c458b514 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -41,6 +41,12 @@ share the same domain, either `network` or `filesystem`. MCP policies use Cedar statements written in the `MCP` namespace instead of the network and filesystem rule format. +An organization network policy can also require approval, which turns every +allow in that policy into a request the developer must confirm before access is +granted. Approval is set on the policy rather than on individual rules, so it +applies to all of the policy's allow rules at once. See +[Approval-required access](access-controls/network.md#approval-required-access). + ### Limits Organization policies have the following limits, which help ensure fair usage @@ -103,6 +109,56 @@ 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 one or more paths: + +| 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. The methods you can select +individually depend on where you configure the rule, so 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 can't contain a query string, a +fragment, or a `..` segment. + +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. + +Because an HTTP rule matches on request contents, the proxy has to inspect each +request rather than deciding once per connection. When any HTTP rule covers a +host, connections to that host are intercepted and every request on them is +evaluated separately. 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). @@ -193,6 +249,13 @@ team-scoped policy, which makes org-wide deny rules useful as guardrails. Local and kit-defined allow rules take no part in this evaluation. Deny rules from those sources do still apply. See [Precedence](#precedence). +A request that an approval-required policy allows produces a third outcome. +Rather than being allowed outright, it's held back until the developer confirms +the destination, and the confirmation governs later requests to it. This holds +even when another policy allows the same request without requiring approval. A +matching deny still wins, so a denied destination is blocked without asking. +See [Approval-required access](access-controls/network.md#approval-required-access). + ## Precedence What applies depends on whether your organization has governance enabled: @@ -223,5 +286,12 @@ inactive rules by default. See [Monitoring](monitor-and-enforce/monitoring.md#showing-inactive-rules) for how to list them. +A local deny takes precedence over an organization approval requirement as +well, so the request is blocked and no approval is requested. Rules that a +developer gains by approving a request are the one exception to local allow +rules being inactive, because they record an answer to the organization's own +approval requirement rather than granting new access. See +[Approval-required access](access-controls/network.md#approval-required-access). + When organization governance is active, a user's organization policies are evaluated together, as described in [Rule evaluation](#rule-evaluation). 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 70054518722..319f1feb06f 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`: @@ -47,6 +50,17 @@ $ sbx policy inspect Balanced Use `--source` to filter by origin (`local`, `org`, or `kit`) and `--decision` to filter by outcome (`allow` or `deny`). +Use `--created-via` to filter by how a rule was created. Pass `default` for +preset rules, `added` for rules you added yourself, `provisioned` for rules a +kit or application added, or `approval` for rules recorded when you approved a +destination. A wide listing shows the same information per rule: + +```console +$ sbx policy ls --wide --created-via approval +``` + +See [Approval-required access](../access-controls/network.md#approval-required-access). + A `STATUS` column also appears when you pass `--include-inactive`; see [Showing inactive rules](#showing-inactive-rules). @@ -100,10 +114,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 +141,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