diff --git a/content/manuals/ai/sandboxes/customize/kits.md b/content/manuals/ai/sandboxes/customize/kits.md index 23ee81c2d3a..f690b9a53b5 100644 --- a/content/manuals/ai/sandboxes/customize/kits.md +++ b/content/manuals/ai/sandboxes/customize/kits.md @@ -158,10 +158,10 @@ hosts the agent should not reach, such as telemetry endpoints. If a domain matches both an allow rule and a deny rule, the deny rule wins. > [!IMPORTANT] -> Kit network rules don't apply when organization governance is active. In -> that case, only organization rules are evaluated, so kit-defined allow and -> deny rules are ignored — including any domains a kit allows for the agent -> to reach. For details, see +> When organization governance is active, only organization allow rules grant +> access, so kit-defined `allow` rules are ignored — including any domains a kit +> allows for the agent to reach. Kit-defined `deny` rules still apply, because a +> deny can only restrict access further. For details, see > [Policy precedence](../governance/concepts.md#precedence). For authenticated services, see diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 2bb4a73b082..3beca95fad1 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -42,8 +42,9 @@ Your Docker account email is only used for authentication, not marketing. Yes. Admins can centrally manage network, filesystem, and MCP policies. These controls apply to every sandbox in the organization. When organization -governance is active, it replaces local rules set with `sbx policy` — local -rules are no longer evaluated. +governance is active, only organization allow rules grant access: local allow +rules set with `sbx policy` are no longer evaluated, while local deny rules +still apply on top. See [Organization policies](governance/access-controls/organization.md). This feature requires a separate paid subscription — diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 2d2b9432d69..8a6b2bc1bb0 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -8,7 +8,7 @@ keywords: docker sandboxes, governance, policy, network access, filesystem acces Sandbox governance covers the policy system that controls what sandboxes can access over the network, on the filesystem, and through MCP. For MCP setup and server registration, see [MCP gateway](../mcp-gateway.md). Governance operates -at two layers, and only one applies at a time: +at two layers: **Local policy** is configured per machine using the `sbx policy` CLI. It lets individual developers customize which domains their sandboxes can reach. @@ -19,8 +19,9 @@ filesystem policies can also be managed via the [Governance API](/reference/api/ai-governance/). Controls defined at the org level apply uniformly across every sandbox in the organization. Organization governance can also include MCP policies for sandbox MCP activity. When -organization governance is active, it replaces local policy entirely: local -`sbx policy` rules are no longer evaluated. See +organization governance is active, only organization allow rules grant access: +local `sbx policy` allow rules are no longer evaluated, while local deny rules +still apply on top. See [Organization policies](access-controls/organization.md). Alongside this access-control policy, admins can require developers to sign in diff --git a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md index 76ce6408e6f..7445a10d42f 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md @@ -11,8 +11,11 @@ workspace. Each policy contains one or more rules that restrict sandbox workspaces to approved directories. Filesystem access is managed with [organization policies](organization.md). When -organization governance is active, filesystem rules replace local behavior for -workspace mounts. +organization governance is active, organization rules determine which paths a +sandbox can mount, and the local filesystem allow rules from the default preset +become inactive. `sbx policy deny` applies to network access only, so there are +no local filesystem deny rules to layer on top. See +[Precedence](../concepts.md#precedence). ## Rule syntax diff --git a/content/manuals/ai/sandboxes/governance/access-controls/local.md b/content/manuals/ai/sandboxes/governance/access-controls/local.md index a3d1208d08e..7ce2b0ce72c 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/local.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/local.md @@ -13,12 +13,13 @@ policy contains network access rules. Rules apply to all sandboxes on the machine when you use the global scope, or to a single sandbox when scoped by name. -Local policy applies only when your organization doesn't enforce governance: +Local policy interacts with organization governance as follows: - **No org governance**: the local policy controls what sandboxes can access. -- **Org governance active**: organization policies replace local policy. - Local rules are inactive, and `sbx policy allow` and `sbx policy deny` have - no effect. To list the inactive local rules, run +- **Org governance active**: only organization allow rules grant access, so + local allow rules are inactive and can't expand what the organization permits. + Local deny rules are still evaluated, so you can restrict access further than + the organization policy does. To list inactive rules, run `sbx policy ls --include-inactive`. See [Monitoring](../monitor-and-enforce/monitoring.md#showing-inactive-rules). @@ -102,6 +103,19 @@ $ sbx policy allow network --sandbox my-sandbox api.example.com $ sbx policy deny network --sandbox my-sandbox ads.example.com ``` +As of v0.38.0, you can also set per-sandbox deny rules at creation time with +`--deny-network` on `sbx create` or `sbx run`, instead of adding them after the +fact: + +```console +$ sbx create --deny-network ads.example.com claude . +$ sbx run --deny-network ads.example.com claude +``` + +Pass the flag multiple times to deny more than one host. Rules added this way +appear in `sbx policy ls ` and can be removed with +`sbx policy rm network --sandbox --resource `. + Specify multiple hosts in one command with a comma-separated list: ```console @@ -171,26 +185,29 @@ $ sbx policy reset --force ## Troubleshooting -### Local rules have no effect +### Local allow rules have no effect + +If rules you add with `sbx policy allow` don't change sandbox behavior, your +organization likely has governance enabled. Run `sbx policy ls` to check: if +the output starts with a `Governance:` status line showing `Managed by `, +org governance is active. When it's active, local allow rules are inactive. +You can't use them to loosen restrictions the org policy imposes. -If rules you add with `sbx policy allow` or `sbx policy deny` don't change -sandbox behavior, your organization likely has governance enabled. Run `sbx -policy ls` to check: if the output starts with a `Governance:` status line -showing `Managed by `, org governance is active. When it's active, -the organization policy replaces local policy, so your rules have no effect. -They're hidden from `sbx policy ls` by default; run `sbx policy ls ---include-inactive` to see them with an `inactive` status in the `STATUS` -column. +Inactive allow rules are hidden from `sbx policy ls` by default; run +`sbx policy ls --include-inactive` to see them with an `inactive` status in +the `STATUS` column. -Organization policy can't be supplemented from your machine. To change what -your sandboxes can access, ask your admin to update the organization policy. +When organization governance is active, only organization allow rules can grant +access. Ask your admin to update the organization policy if you need access to +an additional resource. Local deny rules remain active, so you can use +`sbx policy deny` to restrict access further. ### A domain is still blocked after adding an allow rule If a domain remains blocked after you add a local allow rule, your organization -likely enforces governance, which makes local rules inactive. Run `sbx policy -ls` to check whether org governance is active; if the output starts with 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 +likely enforces governance, which makes local allow rules inactive. Run `sbx +policy ls` to check whether org governance is active; if the output starts with +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/). diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md index 1223244da41..b30d1dbb5a0 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/network.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/network.md @@ -17,9 +17,10 @@ You can configure network access in two places: - [Organization policies](organization.md), which apply centrally across an organization or to selected teams. -When organization governance is active, organization network rules replace -local rules. Local rules are inactive until organization governance no longer -applies. +When organization governance is active, only organization allow rules grant +network access. Local allow rules are inactive until organization governance no +longer applies, while local deny rules still apply on top of the organization +policy. See [Precedence](../concepts.md#precedence). ## Rule syntax diff --git a/content/manuals/ai/sandboxes/governance/access-controls/organization.md b/content/manuals/ai/sandboxes/governance/access-controls/organization.md index f2730954378..eb1c9402d3d 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/organization.md +++ b/content/manuals/ai/sandboxes/governance/access-controls/organization.md @@ -12,9 +12,11 @@ aliases: [Local policies](local.md) give individual developers control over what their sandboxes can access. Organization policy moves that control to the admin level: organization policies apply to sandboxes across the organization, either to -every member or to specific teams. When organization governance is active, it -replaces local `sbx policy` rules entirely — local rules are no longer -evaluated and can't be used to supplement or override the organization policy. +every member or to specific teams. When organization governance is active, only +organization allow rules grant access: local `sbx policy` allow rules are no +longer evaluated and can't expand what the organization permits. Local network +deny rules remain active, so developers can restrict access further but never +loosen it. Admins can manage organization policies through the Docker Home UI. For programmatic management of network and filesystem policies, use the @@ -87,8 +89,10 @@ pages for syntax, examples, and enforcement details: - [MCP access policies](mcp.md): control MCP server registration, tool calls, resources, prompts, and approval gates with Cedar policy. -When organization governance is active, local and kit-defined rules are not -evaluated. To see which rules are active on a developer machine, use +When organization governance is active, local and kit-defined allow rules are +not evaluated, while deny rules from those sources still apply. See +[Precedence](../concepts.md#precedence). To see which rules are active on a +developer machine, use [Monitoring policies](../monitor-and-enforce/monitoring.md). ## Scope policies to teams diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index 28095c159ad..624661f3997 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -21,8 +21,9 @@ Policies exist at two levels: the organization. An organization can have several policies, each applying either org-wide or to specific teams. See [Policy scope](#policy-scope). -When organization governance is active, organization policies replace local -policies entirely. See [Precedence](#precedence). +When organization governance is active, only organization allow rules can grant +access. Local and kit-defined deny rules still apply on top. See +[Precedence](#precedence). A **rule** is the unit of access control within a policy. Each rule has: @@ -165,21 +166,38 @@ request is blocked if any effective policy denies it). A deny rule in an org-wide policy therefore applies to everyone and can't be overridden by a team-scoped policy, which makes org-wide deny rules useful as guardrails. -Local rules take no part in this evaluation; see [Precedence](#precedence). +Local and kit-defined allow rules take no part in this evaluation. Deny rules +from those sources do still apply. See [Precedence](#precedence). ## Precedence -Local and organization policies don't combine. Which one applies depends on -whether your organization has governance enabled: +What applies depends on whether your organization has governance enabled: - No organization governance: local rules and any [kit-defined network rules](../customize/kits.md#control-network-access) determine what sandboxes can access. -- Organization governance active: organization rules apply across all developer - machines, and local and kit-defined rules are not evaluated. `sbx policy ls` - hides these inactive rules by default; see - [Monitoring](monitor-and-enforce/monitoring.md#showing-inactive-rules) for how - to list them. +- Organization governance active: organization policy determines what access can + be granted. Only organization allow rules grant access, so local and + kit-defined allow rules are inactive and can't expand what the organization + permits. Deny rules apply from every source, so a local or kit-defined deny + can still restrict access further. + +Precedence is decided by a rule's decision rather than its source: + +| Rule | Evaluated under organization governance | +| ------------------- | --------------------------------------- | +| Organization allow | Yes | +| Organization deny | Yes | +| Local allow | No | +| Local deny | Yes | +| Kit-defined allow | No | +| Kit-defined deny | Yes | + +Local and kit-defined rules cover network access only, so a deny that layers on +top of organization policy is always a network deny. `sbx policy ls` hides +inactive rules by default. See +[Monitoring](monitor-and-enforce/monitoring.md#showing-inactive-rules) for how +to list them. 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 3116effd9b0..9030d7e39ee 100644 --- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md +++ b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md @@ -71,9 +71,9 @@ rules are suppressed and how to reveal them. ### Showing inactive rules -When organization governance is active, local and kit-defined rules are not -evaluated, so `sbx policy ls` hides them by default. To list them too — for -example, to confirm which local rules the organization policy overrides — pass +When organization governance is active, local and kit-defined allow rules are +not evaluated, so `sbx policy ls` hides them by default. To list them too — for +example, to confirm which allow rules the organization policy overrides — pass `--include-inactive`. This adds a `STATUS` column: ```console @@ -88,7 +88,9 @@ default-fs-write-allow-all local all filesystem write: 1 allow ``` Inactive policies show `inactive` in the `STATUS` column. They have no effect -while organization governance is active. +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