diff --git a/content/manuals/ai/sandboxes/governance/audit.md b/content/manuals/ai/sandboxes/governance/audit.md index fcf2a4d24c98..8e5d26ca4ca8 100644 --- a/content/manuals/ai/sandboxes/governance/audit.md +++ b/content/manuals/ai/sandboxes/governance/audit.md @@ -23,8 +23,8 @@ Audit logging is active only while your organization enforces a centralized governance policy. The subscription alone doesn't produce records. If your organization hasn't configured and enforced an [organization policy](org.md), the daemon writes no audit logs. To confirm governance is active, run `sbx -policy ls` — the output begins with a `Governance: managed by ` header -when an organization policy is in effect. +policy ls` — the output begins with a `Policy rules` header listing a +`Governance Managed by ` line when an organization policy is in effect. Audit logging complements [monitoring](monitoring.md). Monitoring with `sbx policy ls` and `sbx policy log` is for live, interactive debugging. Audit diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index 469ec5dd7d8b..ae2dfa278626 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -80,6 +80,10 @@ Both IPv4 and IPv6 notation are supported: `10.0.0.0/8`, `192.168.1.0/24`, Filesystem rules use the actions `read` and `write`. Resources are host paths that sandboxes can mount as workspaces. +A workspace mounted with write access must be allowed by both a `read` and a +`write` rule; a read-only workspace needs only `read`. When default deny blocks +a mount, the denial reason names whether read or write access was missing. + `~` expands to the user's home directory on every platform, including Windows, where it resolves to `%USERPROFILE%`. A single `~/**` rule therefore matches each user's home tree on macOS, Linux, and Windows. The policy engine expands diff --git a/content/manuals/ai/sandboxes/governance/local.md b/content/manuals/ai/sandboxes/governance/local.md index 89224a8a4e03..321df4d0284c 100644 --- a/content/manuals/ai/sandboxes/governance/local.md +++ b/content/manuals/ai/sandboxes/governance/local.md @@ -138,11 +138,12 @@ $ sbx policy reset --force 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: managed by ` -header, 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. +policy ls` to check: if the output starts with a `Policy rules` header listing a +`Governance Managed by ` line, 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. Organization policy can't be supplemented from your machine. To change what your sandboxes can access, ask your admin to update the organization policy in @@ -153,7 +154,8 @@ the Admin Console. 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: managed by ` header, it is. Add `--include-inactive` to -confirm your rule shows an `inactive` status. If so, the block can only be +`Policy rules` header listing a `Governance Managed by ` line, 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 the Admin Console or via the [API](/reference/api/ai-governance/). diff --git a/content/manuals/ai/sandboxes/governance/monitoring.md b/content/manuals/ai/sandboxes/governance/monitoring.md index 1df88ada4c73..0238e8af3f00 100644 --- a/content/manuals/ai/sandboxes/governance/monitoring.md +++ b/content/manuals/ai/sandboxes/governance/monitoring.md @@ -17,77 +17,119 @@ Use `sbx policy ls` to see all active rules and their current status: ```console $ sbx policy ls -NAME TYPE ORIGIN DECISION STATUS RESOURCES -balanced-dev network local allow active api.anthropic.com -ads-block network local deny active ads.example.com -kit:my-sandbox network sandbox:my-sandbox allow active api.example.com -kit:my-sandbox:deny network sandbox:my-sandbox deny active telemetry.example.com +PROVENANCE APPLIES_TO POLICY/RULE TYPE DECISION RESOURCES +local all default-ai-services network allow api.anthropic.com:443 + api.openai.com:443 +local all default-fs-read-allow-all filesystem:read allow ** +local all default-fs-write-allow-all filesystem:write allow ** +kit sandbox:docs kit:docs network allow api.github.com + registry.npmjs.org ``` The columns are: -- `NAME`: the rule name. -- `TYPE`: the rule domain, such as `network`. -- `ORIGIN`: where the rule was configured. `local` means the rule is global - and applies to all sandboxes. `sandbox:` means the rule is scoped to - the named sandbox. `remote` means the rule was set by your organization. +- `PROVENANCE`: where the rule came from. `local` is a rule from your local + policy — a preset default or one you added with `sbx policy`. `kit` is a rule + added by a [kit](../customize/kits.md#control-network-access). `remote` is a + rule set by your organization. +- `APPLIES_TO`: which sandboxes the rule applies to. `all` means the rule is + global. `sandbox:` means it's scoped to the named sandbox. +- `POLICY/RULE`: the rule's identity. Organization rules show as + ` / `. Local and kit rules show the rule name. +- `TYPE`: the rule domain. Network rules show as `network`. Filesystem rules + show as `filesystem:read` or `filesystem:write`, depending on the access the + rule controls. - `DECISION`: whether the rule allows or denies the resource. -- `STATUS`: whether the rule is in effect. A rule may be `inactive` if it's - overridden or suppressed — for example, when organization governance is - active, local rules are not evaluated. Inactive rules are hidden by default; - pass `--include-inactive` to list them. See - [Showing inactive rules](#showing-inactive-rules). - `RESOURCES`: the hosts or patterns the rule applies to. -When organization governance is active, the output starts with a governance -header showing which organization manages the policy and when it last synced: +A `STATUS` column also appears when you pass `--include-inactive`; see +[Showing inactive rules](#showing-inactive-rules). + +When organization governance is active, the output starts with a `Policy rules` +header showing which organization manages the policy, the sync state, and how +many inactive rules are hidden: ```console $ sbx policy ls -Governance: managed by my-org -[OK] last synced 13:54:21 -NAME TYPE ORIGIN DECISION STATUS RESOURCES -allow AI services network remote allow active api.anthropic.com - api.openai.com -allow Docker services network remote allow active *.docker.com - *.docker.io +Policy rules +------------ +Governance Managed by my-org +Sync OK, last synced 08:21:01 +Hidden 9 inactive rules. Show with: sbx policy ls --include-inactive + +PROVENANCE APPLIES_TO POLICY/RULE TYPE DECISION RESOURCES +remote all default filesystem / allow home subdirectories filesystem:write allow ~/** +remote all default filesystem / deny home directory filesystem:write deny ~/ +remote all default network / allow AI services network allow api.anthropic.com + api.openai.com +remote all default network / allow Docker services network allow *.docker.com + *.docker.io ``` -The governance header shows which organization is managing the policy and -confirms the daemon has successfully pulled the latest rules. If the sync -status shows an error or a stale timestamp, the daemon may not have the most -recent org policy. Run `sbx policy reset` to force a fresh pull. +The `Governance` line shows which organization manages the policy, and `Sync` +confirms the daemon has pulled the latest rules. If the sync state shows an +error or a stale timestamp, the daemon may not have the most recent org policy. +Run `sbx policy reset` to force a fresh pull. The `Hidden` line reports how many +inactive 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 -`--include-inactive`: +`--include-inactive`. This adds a `STATUS` column: ```console $ sbx policy ls --include-inactive -Governance: managed by my-org -[OK] last synced 13:54:21 -NAME TYPE ORIGIN DECISION STATUS RESOURCES -balanced-dev network local allow inactive api.anthropic.com -allow AI services network remote allow active api.anthropic.com - api.openai.com -allow Docker services network remote allow active *.docker.com - *.docker.io +Policy rules +------------ +Governance Managed by my-org +Sync OK, last synced 08:41:06 + +PROVENANCE APPLIES_TO POLICY/RULE TYPE DECISION STATUS RESOURCES +local default-fs-read-allow-all filesystem:read allow inactive — corporate policy ** + takes precedence and does + not delegate this rule type + to local policy. +local default-fs-write-allow-all filesystem:write allow inactive — corporate policy ** + takes precedence and does + not delegate this rule type + to local policy. +remote all default filesystem / allow home subdirectories filesystem:write allow active ~/** +remote all default filesystem / deny home directory filesystem:write deny active ~/ ``` -Inactive rules show with an `inactive` status. They have no effect while -organization governance is active. +Inactive rules show `inactive` in the `STATUS` column, along with the reason. +They have no effect while organization governance is active. -Use `--type network` to show only network rules. Without a sandbox argument, -`sbx policy ls` shows every rule across all sandboxes. Pass a sandbox name to -filter to global rules and rules scoped to that sandbox: +Use `--type network` or `--type filesystem` to show only rules of that type. +Without a sandbox argument, `sbx policy ls` shows every rule across all +sandboxes. Pass a sandbox name to filter to global rules and rules scoped to +that sandbox: ```console $ sbx policy ls my-sandbox ``` +### Filesystem rules + +`sbx policy ls` lists filesystem rules alongside network rules. Filesystem +rules control which host paths a sandbox can mount as a workspace. Pass +`--type filesystem` to show only them: + +```console +$ sbx policy ls --type filesystem +PROVENANCE APPLIES_TO POLICY/RULE TYPE DECISION RESOURCES +local all default-fs-read-allow-all filesystem:read allow ** +local all default-fs-write-allow-all filesystem:write allow ** +``` + +A writable workspace mount must be allowed by both a `filesystem:read` and a +`filesystem:write` rule; a read-only mount needs only `filesystem:read`. The +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). + ## Monitoring traffic Use `sbx policy log` to see which hosts your sandboxes have contacted and @@ -127,3 +169,5 @@ $ sbx policy log my-sandbox Use `--limit N` to show only the last `N` entries, `--json` for machine-readable output, or `--type network` to filter by policy type. +`sbx policy log` records network traffic only; filesystem mount decisions +aren't available in the log yet. diff --git a/content/manuals/ai/sandboxes/governance/org.md b/content/manuals/ai/sandboxes/governance/org.md index 46e734a056b2..1bf089f79474 100644 --- a/content/manuals/ai/sandboxes/governance/org.md +++ b/content/manuals/ai/sandboxes/governance/org.md @@ -71,8 +71,8 @@ access to. Admins can restrict which paths are mountable with filesystem allow and deny rules. Each rule takes a path pattern and an action (allow or deny). -For path pattern syntax including the difference between `*` and `**`, see -[Policy concepts](concepts.md#filesystem-rules). +For path pattern syntax and how read and write access combine to allow a +mount, see [Policy concepts](concepts.md#filesystem-rules). ## Scope policies to teams