diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index 469ec5dd7d8..ae2dfa27862 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/monitoring.md b/content/manuals/ai/sandboxes/governance/monitoring.md index 1df88ada4c7..757e16b8221 100644 --- a/content/manuals/ai/sandboxes/governance/monitoring.md +++ b/content/manuals/ai/sandboxes/governance/monitoring.md @@ -27,7 +27,9 @@ kit:my-sandbox:deny network sandbox:my-sandbox deny active telemet The columns are: - `NAME`: the rule name. -- `TYPE`: the rule domain, such as `network`. +- `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. - `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. @@ -80,14 +82,34 @@ allow Docker services network remote allow active *.doc Inactive rules show with an `inactive` status. 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 +NAME TYPE ORIGIN DECISION STATUS RESOURCES +default-fs-read-allow-all filesystem:read local allow active ** +default-fs-write-allow-all filesystem:write local allow active ** +``` + +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 +149,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 46e734a056b..1bf089f7947 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