ai-gov: http method and path rules, and approval-required network access

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,

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,

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 <name>`:
 $ 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 <org>`, 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).

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

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