diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index 2b59e6b2e7a..c54c9c16541 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -133,7 +133,9 @@ 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 allow rules take no part in this evaluation. Local deny rules are still +evaluated and layer on top of the organization policy. See +[Precedence](#precedence). ## Precedence @@ -144,8 +146,10 @@ whether your organization has governance enabled: [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 + machines. Local and kit-defined allow rules are not evaluated. They can't + be used to loosen org policy restrictions. Local deny rules are still + evaluated and layer on top of the organization policy. `sbx policy ls` hides + inactive rules by default. See [Monitoring](monitoring.md#showing-inactive-rules) for how to list them. When organization governance is active, a user's organization policies are diff --git a/content/manuals/ai/sandboxes/governance/local.md b/content/manuals/ai/sandboxes/governance/local.md index 992e6d3737c..c3bebf69cef 100644 --- a/content/manuals/ai/sandboxes/governance/local.md +++ b/content/manuals/ai/sandboxes/governance/local.md @@ -11,13 +11,15 @@ The `sbx policy` command manages network access rules on your local machine. Rules apply to all sandboxes on the machine when you use the global scope, or to a single sandbox when scoped by name. -Local rules apply only when your organization doesn't enforce governance: +Local rules interact with organization governance as follows: - **No org governance**: local rules fully control what sandboxes can access. -- **Org governance active**: the organization policy replaces local policy. - Local rules are inactive, and `sbx policy allow` and `sbx policy deny` have - no effect. To list the inactive local rules, run - `sbx policy ls --include-inactive`. See +- **Org governance active**: organization rules are the primary policy. + Local allow rules are inactive and have no effect. You can't use them to + loosen a restriction the org policy imposes. Local deny rules are still + evaluated and layer on top of the organization policy, so you can further + restrict access beyond what the org policy allows. To list inactive rules, + run `sbx policy ls --include-inactive`. See [Monitoring](monitoring.md#showing-inactive-rules). See [Organization policy](org.md) for how organization governance works. @@ -94,6 +96,18 @@ $ sbx policy allow network --sandbox my-sandbox api.example.com $ sbx policy deny network --sandbox my-sandbox ads.example.com ``` +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 @@ -163,26 +177,31 @@ $ 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. +Local deny rules are still evaluated under org governance and layer on top of +the org policy. Use them to further restrict access beyond what the org policy +allows. + ### 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/org.md b/content/manuals/ai/sandboxes/governance/org.md index bedf5c56fa7..724a481459f 100644 --- a/content/manuals/ai/sandboxes/governance/org.md +++ b/content/manuals/ai/sandboxes/governance/org.md @@ -10,10 +10,12 @@ aliases: [Local policies](local.md) give individual developers control over what their sandboxes can access. Organization policy moves that control to the admin level: -rules 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. +rules apply to sandboxes across the organization, either to every member or to +specific teams. When organization governance is active, local `sbx policy allow` +rules are no longer evaluated and can't be used to loosen org policy +restrictions. Local `sbx policy deny` rules are still evaluated and layer on top +of the organization policy, so developers can further restrict access beyond +what the org allows. Admins can manage organization policies through the Docker Home UI or programmatically using the [Governance API](/reference/api/ai-governance/). @@ -82,9 +84,10 @@ add multiple entries at once, one per line. For the full syntax reference (exact hostnames, wildcard subdomains, port suffixes, and CIDR ranges), see [Policy concepts](concepts.md#network-rules). -When organization governance is active, local network rules are not evaluated. -The organization policy is the only policy in effect. `sbx policy ls` hides -these inactive local rules by default. See +When organization governance is active, local network allow rules are not +evaluated — the organization policy controls what developers can access. Local +network deny rules are still evaluated and layer on top of the org policy. `sbx +policy ls` hides inactive rules by default. See [Monitoring](monitoring.md#showing-inactive-rules) for how to list them and read the rule view. @@ -189,11 +192,16 @@ wildcards match. ## Precedence -When organization governance is active, local rules are not evaluated. Only -organization rules determine what is allowed or denied, -and they can't be supplemented or overridden from a developer's machine. The -same applies to filesystem policies: organization rules replace local behavior -entirely. For how a user's organization policies are evaluated together, see +When organization governance is active, local allow rules are not evaluated. +Only organization rules determine what access is permitted, and local allow +rules can't loosen those restrictions. The same applies to filesystem policies: +local filesystem allow rules are replaced by organization rules entirely. + +Local deny rules are still evaluated and layer on top of the organization +policy. Developers can use `sbx policy deny` to further restrict access beyond +what the org policy allows, even when governance is active. + +For how a user's organization policies are evaluated together, see [Policy concepts](concepts.md#rule-evaluation). To unblock a domain when organization governance is active, update the rule in