From ae2ee928a03d85154c467e8bc742283da1659c25 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Tue, 20 Oct 2026 14:14:02 -0700 Subject: [PATCH 1/3] ai-gov: rearrange content Signed-off-by: Craig Osterhout --- content/get-started/tutorials/run-an-agent.md | 2 +- content/guides/firecrawl-sandbox-kit.md | 2 +- .../accounts/organization/activity-logs.md | 6 +- content/manuals/ai/sandboxes/_index.md | 2 +- content/manuals/ai/sandboxes/architecture.md | 2 +- .../ai/sandboxes/configuration/credentials.md | 2 +- .../ai/sandboxes/configuration/settings.md | 2 +- .../sandboxes/configuration/upstream-proxy.md | 2 +- .../sandboxes/customize/author/tool-mixins.md | 2 +- content/manuals/ai/sandboxes/faq.md | 8 +- content/manuals/ai/sandboxes/get-started.md | 4 +- .../manuals/ai/sandboxes/governance/_index.md | 69 ++-- .../governance/access-controls/_index.md | 27 -- .../governance/access-controls/local.md | 383 ------------------ .../governance/access-controls/network.md | 204 ---------- .../access-controls/organization.md | 245 ----------- .../ai/sandboxes/governance/audit/local.md | 99 ----- .../ai/sandboxes/governance/concepts.md | 317 --------------- .../ai/sandboxes/governance/local/_index.md | 45 ++ .../sandboxes/governance/local/approvals.md | 97 +++++ .../sandboxes/governance/local/get-started.md | 89 ++++ .../monitoring.md => local/inspect.md} | 82 ++-- .../governance/local/network-rules.md | 189 +++++++++ .../governance/local/test-monitor.md | 83 ++++ .../governance/monitor-and-enforce/_index.md | 16 - .../governance/organization/_index.md | 36 ++ .../{ => organization}/audit/_index.md | 54 ++- .../{ => organization}/audit/configure.md | 4 +- .../{ => organization}/audit/siem.md | 14 +- .../{ => organization}/audit/view-export.md | 4 +- .../organization/policies/_index.md | 160 ++++++++ .../organization/policies/create-manage.md | 99 +++++ .../policies}/filesystem.md | 14 +- .../policies}/mcp.md | 29 +- .../organization/policies/network.md | 145 +++++++ .../sign-in-enforcement.md | 7 +- .../sandboxes/governance/reference/_index.md | 6 +- .../ai/sandboxes/governance/reference/api.md | 4 +- .../audit-records.md} | 49 ++- .../governance/reference/filesystem-rules.md | 47 +++ .../governance/reference/mcp-policy.md | 28 +- .../governance/reference/network-rules.md | 92 +++++ content/manuals/ai/sandboxes/mcp-gateway.md | 2 +- .../manuals/ai/sandboxes/security/_index.md | 2 +- .../manuals/ai/sandboxes/security/defaults.md | 4 +- .../ai/sandboxes/security/isolation.md | 4 +- .../manuals/ai/sandboxes/troubleshooting.md | 8 +- .../ai/sandboxes/workflows/automation.md | 2 +- .../plans/ai-governance.md | 2 +- data/redirects.yml | 2 +- 50 files changed, 1361 insertions(+), 1436 deletions(-) delete mode 100644 content/manuals/ai/sandboxes/governance/access-controls/_index.md delete mode 100644 content/manuals/ai/sandboxes/governance/access-controls/local.md delete mode 100644 content/manuals/ai/sandboxes/governance/access-controls/network.md delete mode 100644 content/manuals/ai/sandboxes/governance/access-controls/organization.md delete mode 100644 content/manuals/ai/sandboxes/governance/audit/local.md delete mode 100644 content/manuals/ai/sandboxes/governance/concepts.md create mode 100644 content/manuals/ai/sandboxes/governance/local/_index.md create mode 100644 content/manuals/ai/sandboxes/governance/local/approvals.md create mode 100644 content/manuals/ai/sandboxes/governance/local/get-started.md rename content/manuals/ai/sandboxes/governance/{monitor-and-enforce/monitoring.md => local/inspect.md} (72%) create mode 100644 content/manuals/ai/sandboxes/governance/local/network-rules.md create mode 100644 content/manuals/ai/sandboxes/governance/local/test-monitor.md delete mode 100644 content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md create mode 100644 content/manuals/ai/sandboxes/governance/organization/_index.md rename content/manuals/ai/sandboxes/governance/{ => organization}/audit/_index.md (62%) rename content/manuals/ai/sandboxes/governance/{ => organization}/audit/configure.md (98%) rename content/manuals/ai/sandboxes/governance/{ => organization}/audit/siem.md (88%) rename content/manuals/ai/sandboxes/governance/{ => organization}/audit/view-export.md (96%) create mode 100644 content/manuals/ai/sandboxes/governance/organization/policies/_index.md create mode 100644 content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md rename content/manuals/ai/sandboxes/governance/{access-controls => organization/policies}/filesystem.md (85%) rename content/manuals/ai/sandboxes/governance/{access-controls => organization/policies}/mcp.md (91%) create mode 100644 content/manuals/ai/sandboxes/governance/organization/policies/network.md rename content/manuals/ai/sandboxes/governance/{monitor-and-enforce => organization}/sign-in-enforcement.md (97%) rename content/manuals/ai/sandboxes/governance/{audit/record-reference.md => reference/audit-records.md} (89%) create mode 100644 content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md create mode 100644 content/manuals/ai/sandboxes/governance/reference/network-rules.md diff --git a/content/get-started/tutorials/run-an-agent.md b/content/get-started/tutorials/run-an-agent.md index 852b764c205e..3e173ea1338f 100644 --- a/content/get-started/tutorials/run-an-agent.md +++ b/content/get-started/tutorials/run-an-agent.md @@ -94,7 +94,7 @@ The first time you run a sandbox, `sbx` asks you to choose a default network policy. This policy controls which external services your sandboxes can reach. Select **Balanced** to permit common development services and block other destinations by default. You can change these rules later with -[`sbx policy`](/manuals/ai/sandboxes/governance/access-controls/local.md). +[`sbx policy`](/manuals/ai/sandboxes/governance/local/_index.md). The built-in integrations start coding agents in their full-autonomy mode. For example, Codex bypasses approvals, Claude Code skips permission prompts, and diff --git a/content/guides/firecrawl-sandbox-kit.md b/content/guides/firecrawl-sandbox-kit.md index aa19302239d8..8ffa0a920dd6 100644 --- a/content/guides/firecrawl-sandbox-kit.md +++ b/content/guides/firecrawl-sandbox-kit.md @@ -173,7 +173,7 @@ rules determine which domains the sandbox can access. Under organization governance, organization policy controls which domains can be allowed; local and kit-defined allow rules are inactive, while deny rules can still restrict access. See -[Network policy precedence](/manuals/ai/sandboxes/governance/concepts.md#precedence). +[Network policy precedence](/manuals/ai/sandboxes/governance/organization/policies/_index.md#precedence). The Firecrawl kit requests access to PyPI during installation and `api.firecrawl.dev` at runtime. Its credential declaration tells the proxy to diff --git a/content/manuals/accounts/organization/activity-logs.md b/content/manuals/accounts/organization/activity-logs.md index db269a80ca56..e0a850312730 100644 --- a/content/manuals/accounts/organization/activity-logs.md +++ b/content/manuals/accounts/organization/activity-logs.md @@ -27,7 +27,7 @@ Organization owners and members with a custom role that includes the > Use activity logs for an admin audit trail of your organization and > repositories, including AI Governance policy and settings changes. For > enforcement events, such as policy decisions and sandbox sessions, see -> [AI Governance Audit Logs](/manuals/ai/sandboxes/governance/audit/_index.md). +> [AI Governance Audit Logs](/manuals/ai/sandboxes/governance/organization/audit/_index.md). ## Access activity logs @@ -234,7 +234,7 @@ The following table lists Offload events that cover lease start and end. The following table lists governance events that cover the AI Governance admin audit trail, such as policy and settings changes. For enforcement events, such as policy decisions and sandbox sessions, see -[AI Governance Audit Logs](/manuals/ai/sandboxes/governance/audit/_index.md). +[AI Governance Audit Logs](/manuals/ai/sandboxes/governance/organization/audit/_index.md). | Event | Description | |:------|:------------| @@ -249,7 +249,7 @@ events, such as policy decisions and sandbox sessions, see - [Roles and permissions](/manuals/security/roles-and-permissions/_index.md) for the **View activity logs** permission and custom roles -- [AI Governance Audit Logs](/manuals/ai/sandboxes/governance/audit/_index.md) for +- [AI Governance Audit Logs](/manuals/ai/sandboxes/governance/organization/audit/_index.md) for enforcement events such as policy decisions and sandbox sessions - [Audit logs API](/reference/api/hub/latest/#tag-audit-logs) to query events programmatically diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index ecb9d4727888..5d234ff25a48 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -18,7 +18,7 @@ work. Cloud compute uses a Model-provider charges are separate. Organization admins can -[centrally manage sandbox network, filesystem, and MCP policies](governance/access-controls/organization.md), +[centrally manage sandbox network, filesystem, and MCP policies](governance/organization/_index.md), for local sandboxes across developer machines. Available on a separate paid subscription. diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index 5e9be8737b0d..c2d1f38b539a 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -78,7 +78,7 @@ $ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run All outbound TCP traffic from the sandbox routes through a proxy on your host. Agents use a forward proxy for HTTP and HTTPS; other TCP traffic is forwarded transparently. Both paths enforce -[network access policies](governance/access-controls/network.md). The forward +[network access policies](governance/_index.md). The forward proxy also handles [credential injection](configuration/credentials.md). See [Network isolation](security/isolation.md#network-isolation) for how this works and [Default security posture](security/defaults.md) for what is diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index c351fc2a65b5..13f91cd60cfd 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -465,7 +465,7 @@ $ sbx secret set-custom \ ``` A `--host` value can also use wildcards, with the same syntax as -[network rules](../governance/concepts.md#network-rules): `*` matches a +[network rules](../governance/reference/network-rules.md): `*` matches a single label (`*.example.com` covers `api.example.com`) and `**` matches any number (`**.example.com` covers `api.example.com` and `v2.api.example.com`). diff --git a/content/manuals/ai/sandboxes/configuration/settings.md b/content/manuals/ai/sandboxes/configuration/settings.md index 6d57bd52564d..f539217e1ae8 100644 --- a/content/manuals/ai/sandboxes/configuration/settings.md +++ b/content/manuals/ai/sandboxes/configuration/settings.md @@ -628,7 +628,7 @@ $ sbx daemon restart This shared list applies to sandbox and daemon traffic unless a scope-specific list replaces it. A value of `*` bypasses the upstream proxy for all destinations. Proxy exclusions don't grant network access: sandbox requests must still pass -[network policy](../governance/access-controls/network.md). +[network policy](../governance/_index.md). #### no_proxy.sandbox {.wrap-anywhere} diff --git a/content/manuals/ai/sandboxes/configuration/upstream-proxy.md b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md index 93514fe688d8..54748f7f249f 100644 --- a/content/manuals/ai/sandboxes/configuration/upstream-proxy.md +++ b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md @@ -22,7 +22,7 @@ originating inside a cloud sandbox. For cloud sandbox egress controls, see An upstream proxy is the corporate or network proxy that Docker Sandboxes forwards outbound traffic through on its way to the internet. This is separate -from the [network policy](../governance/access-controls/network.md), which decides +from the [network policy](../governance/_index.md), which decides _which_ destinations are allowed. The upstream proxy decides _how_ allowed traffic reaches them. diff --git a/content/manuals/ai/sandboxes/customize/author/tool-mixins.md b/content/manuals/ai/sandboxes/customize/author/tool-mixins.md index 69bc14701a19..fc84e74a3bfd 100644 --- a/content/manuals/ai/sandboxes/customize/author/tool-mixins.md +++ b/content/manuals/ai/sandboxes/customize/author/tool-mixins.md @@ -165,7 +165,7 @@ your stored key. If authentication fails, check that you stored the key and approved the kit's request to use it. See [Credential bindings](/manuals/ai/sandboxes/configuration/credentials.md#credential-bindings). Network requests must also meet the sandbox's -[network policy](/manuals/ai/sandboxes/governance/concepts.md#precedence). +[network policy](/manuals/ai/sandboxes/governance/organization/policies/_index.md#precedence). Run `claude` without arguments to start an interactive session. Follow its first-run prompts. Exit Claude Code and the shell to return to your host. diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index 8125db917a11..d7a9ce4008e8 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -18,8 +18,8 @@ Model-provider charges are separate from sandbox compute. Organization governance for local sandboxes includes centrally managed network, filesystem, and MCP policies, -[sign-in enforcement](governance/monitor-and-enforce/sign-in-enforcement.md), -and [audit logs](governance/audit/). These +[sign-in enforcement](governance/organization/sign-in-enforcement.md), +and [audit logs](governance/organization/audit/_index.md). These [organization governance features](governance/) require a separate paid subscription — [contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) @@ -50,7 +50,7 @@ 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 +See [Organization policies](governance/organization/_index.md). This feature requires a separate paid subscription — [contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) to get started. @@ -112,7 +112,7 @@ the sandbox, to pick up the new value. ## Why do agents run without approval prompts? The sandbox itself is the safety boundary. Because agents run inside an -isolated microVM with [network policies](governance/access-controls/network.md), +isolated microVM with [network policies](governance/_index.md), [credential isolation](security/isolation.md#credential-isolation), and no access to your host system outside explicitly shared paths, the usual reasons for approval prompts (preventing destructive commands, network access, file modifications) are diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 28b6bfe6a9f0..98de6c25612d 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -72,7 +72,7 @@ Initialize the global network policy for your sandboxes: **Balanced** is a good starting point — it permits traffic to common development services while blocking everything else. You can adjust individual -rules later. See [Local policy](governance/access-controls/local.md) for a full +rules later. See [Local policy](governance/local/_index.md) for a full description of each option. Replace `claude` with the agent you want to use — see [Agents](agents/) for the @@ -140,7 +140,7 @@ $ sbx policy allow network registry.npmjs.org With **Locked Down**, even your model provider API is blocked unless you explicitly allow it. With **Balanced**, common development services are permitted by default. See -[local policy](governance/access-controls/local.md) for the full rule set +[local policy](governance/local/_index.md) for the full rule set and how to customize it. ## Clean up diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 7c1fba061daf..0fc612952e18 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -3,6 +3,9 @@ title: Governance weight: 120 description: Control what sandboxes can access, from local developer rules to org-wide enforcement. keywords: docker sandboxes, governance, policy, network access, filesystem access, mcp policy, organization policy +aliases: + - /ai/sandboxes/governance/access-controls/ + - /ai/sandboxes/governance/monitor-and-enforce/ --- The governance described here applies to local sandboxes. Cloud sandboxes @@ -16,7 +19,7 @@ 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. -See [Local policy](access-controls/local.md). +See [Local policy](local/_index.md). **Organization policy** is configured centrally in Docker Home. Network and filesystem policies can also be managed via the @@ -26,11 +29,11 @@ governance can also include MCP policies for sandbox MCP activity. When 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). +[Organization policies](organization/_index.md). Alongside this access-control policy, admins can require developers to sign in as members of their organization before using sandboxes at all. -[Sign-in enforcement](monitor-and-enforce/sign-in-enforcement.md) is deployed +[Sign-in enforcement](organization/sign-in-enforcement.md) is deployed through endpoint management and ensures developers can't bypass organization policy by using a personal account. @@ -39,38 +42,42 @@ policy by using a personal account. > [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) > to request access. -## Learn more +## Resource model -Start with [Policy concepts](concepts.md) for the resource model, rule syntax, -MCP policy basics, evaluation, and precedence. +Docker sandbox governance is built around two resource types: **policies** and +**rules**. -### Access controls +A **policy** is a named collection of rules that controls sandbox access. +Policies exist at two levels: -- [Local policy](access-controls/local.md): configure network rules on your - machine with the `sbx policy` CLI. -- [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, 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, - tool calls, resources, prompts, and approval gates. +- **Local**: configured per machine using the `sbx policy` CLI. Applies to + sandboxes on that machine only. +- **Organization**: configured in Docker Home. Network and filesystem policies + can also be managed via the + [Governance API](/reference/api/ai-governance/). Applies to sandboxes across + the organization. An organization can have several policies, each applying + either org-wide or to specific teams. See [Policy scope](organization/policies/_index.md#policy-scope). -### Monitor and enforce +When organization governance is active, only organization allow rules can grant +access. Local and kit-defined deny rules still apply on top. See +[Precedence](organization/policies/_index.md#precedence). -- [Monitoring policies](monitor-and-enforce/monitoring.md): inspect active - rules and monitor sandbox network traffic with `sbx policy ls` and - `sbx policy log`. -- [Audit logs](audit/): view, configure, export, and collect governance audit - records. -- [Sign-in enforcement](monitor-and-enforce/sign-in-enforcement.md): require - developers to sign in as organization members, enforced through endpoint - management. +A **rule** is the unit of access control within a policy. Each rule has: -### Reference +- **Name**: a human-readable label +- **Actions**: the type of access the rule controls +- **Resources**: the targets the rule matches against +- **Decision**: `allow` or `deny` -- [AI Governance API](/reference/api/ai-governance/): manage network and - filesystem org policies programmatically. -- [MCP policy reference](reference/mcp-policy.md): look up Docker MCP policy - actions, resources, attributes, context fields, and approval behavior. +Rules are grouped by domain. Network and filesystem rules in a policy must +share the same domain, either `network` or `filesystem`. MCP policies use Cedar +statements written in the `MCP` namespace instead of the network and filesystem +rule format. + +An organization network policy can also require approval, which turns every +allow in that policy into a request the developer must confirm before access is +granted. Approval is set on the policy rather than on individual rules, so it +applies to all of the policy's allow rules at once. Without organization +governance, a request with no matching allow or deny rule also asks for +approval. See +[Approval-required access](organization/policies/network.md#approval-required-access). diff --git a/content/manuals/ai/sandboxes/governance/access-controls/_index.md b/content/manuals/ai/sandboxes/governance/access-controls/_index.md deleted file mode 100644 index bcaabdd429a5..000000000000 --- a/content/manuals/ai/sandboxes/governance/access-controls/_index.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Access controls -weight: 20 -description: Configure local and organization controls for sandbox network, filesystem, and MCP access. -keywords: docker sandboxes, access controls, governance, network access, filesystem access, MCP access ---- - -Access controls are expressed as policies. Local and organization pages -describe where policies apply. Network and filesystem pages describe the rules -inside those policies. MCP policies use Cedar statements instead of the network -and filesystem rule format. - -## Policy scope - -- [Local policy](local.md): configure network rules on a developer machine with - the `sbx policy` CLI. -- [Organization policies](organization.md): manage centralized policies for an - organization or team. - -## Access surfaces - -- [Network access policies](network.md): control outbound network access from - 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, - resources, prompts, and approval gates with Cedar policy. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/local.md b/content/manuals/ai/sandboxes/governance/access-controls/local.md deleted file mode 100644 index c120e3863394..000000000000 --- a/content/manuals/ai/sandboxes/governance/access-controls/local.md +++ /dev/null @@ -1,383 +0,0 @@ ---- -title: Local policy -weight: 10 -description: Configure local network access rules for sandboxes on your machine. -keywords: docker sandboxes, local policy, network access, allow rules, deny rules, sbx policy -aliases: - - /ai/sandboxes/security/policy/ - - /ai/sandboxes/governance/local/ ---- - -The `sbx policy` command manages the local policy on your machine. The local -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 interacts with organization governance as follows: - -- **No org governance**: the local policy controls what sandboxes can access. -- **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). - -See [Organization policies](organization.md) for how organization governance -works. - -For domain patterns, wildcards, CIDR ranges, and filesystem path syntax, see -[Policy concepts](../concepts.md#rule-syntax). - -## Default preset - -Outbound TCP traffic passes through a proxy on your host, which enforces access -rules on every connection. Non-HTTP TCP traffic, including SSH, can be allowed -with a hostname rule (for example, `sbx policy allow network "myhost:22"`) or an -address-based rule. UDP requires the experimental feature and policy rules -described in [Allow outbound UDP](#allow-outbound-udp). ICMP is blocked. - -If you haven't chosen a default preset, the CLI prompts you before it runs a -sandbox. Running `sbx policy reset` clears the preset and prompts you to choose -again: - -```plaintext -Initialize the global network policy for your sandboxes: - - Applies to all sandboxes, current and future — change it later with - "sbx policy allow/deny/rm". Kits, including built-in agent kits, may - also add per-sandbox rules. - - 1. Open — All network traffic allowed, no restrictions. - ❯ 2. Balanced — Default deny, with common dev sites allowed. - 3. Locked Down — All network traffic blocked unless you allow it. - - Use ↑/↓ or 1–3 to navigate, Enter to confirm, Esc to cancel. -``` - -| Preset | Description | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| Open | All outbound TCP traffic is allowed. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`. | -| Balanced | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. | -| Locked Down | No baseline allow rules. Destinations need an allow rule from you or a kit. | - -Presets initialize the global policy. Built-in agent kits and other kits can -add per-sandbox allow rules, including under **Locked Down** (`deny-all`). The -preset isn't an explicit deny rule that overrides those allowances. - -Under **Balanced** and **Locked Down**, a sandbox request that no rule matches -is blocked and asks for your approval instead of being denied outright, so you -can open access to each destination as a sandbox needs it. See -[Approval-required access](network.md#approval-required-access). - -To inspect the rules a kit adds to a sandbox, run: - -```console -$ sbx policy ls my-sandbox --source kit --type network --wide -``` - -To block a destination allowed by a kit, add an explicit deny rule: - -```console -$ sbx policy deny network --sandbox my-sandbox openrouter.ai -``` - -Deny rules take precedence over allow rules. See -[Policy precedence](../concepts.md#precedence). - -The **Balanced** preset's baseline allowlist is a good starting point for most -workflows. Run `sbx policy ls` to see exactly which rules it includes. - -> [!NOTE] -> If your organization manages sandbox policies centrally, organization rules -> take precedence over the preset you select here. See -> [Organization policies](organization.md). - -### Non-interactive environments - -In non-interactive environments such as CI pipelines or headless servers, the -interactive prompt can't be displayed. Use `sbx policy init` to set the -preset before running any other `sbx` commands: - -```console -$ sbx policy init balanced -``` - -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 -all sandboxes by default: - -```console -$ sbx policy allow network api.anthropic.com -$ sbx policy deny network ads.example.com -``` - -Pass `--sandbox ` to scope a rule to one sandbox: - -```console -$ 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 -$ sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org" -``` - -Remove a rule by resource or by rule ID: - -```console -$ sbx policy rm network --resource ads.example.com -$ sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 -``` - -To remove a sandbox-scoped rule, pass `--sandbox `: - -```console -$ 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`. - -A path must start with `/` and be canonical. It can't contain a query string, a -fragment, percent-encoding, control characters, surrounding whitespace, -repeated or trailing slashes, or dot segments such as `.` and `..`. Each rule -takes one path. Repeating `--path` keeps only the last value, and a comma is -read as part of the path, so add a separate rule for each path: - -```console -$ sbx policy allow network api.github.com --method GET --path '/repos/**' -$ sbx policy allow network api.github.com --method GET --path '/users/**' -``` - -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 -rule-level detail including rule IDs. To inspect a single policy or rule in -full, use `sbx policy inspect`. See -[Monitoring](../monitor-and-enforce/monitoring.md). - -### Allow outbound UDP - -Outbound UDP is experimental and disabled by default. Turn on experimental -features and UDP egress before adding UDP allow rules: - -```console -$ sbx settings set platform.allowExperimentalFeatures true -$ sbx settings set feature.udp-egress true -$ sbx policy allow network --protocol udp api.example.com:443 -``` - -Local allow rules apply to TCP by default. Use `--protocol udp` for UDP or -`--protocol tcp,udp` for both. Deny rules apply to both protocols by default. -Use `--protocol` to restrict a deny rule to one protocol. - -UDP follows the same organization and local policy precedence as TCP. It is -refused when the destination requires an HTTP, SOCKS5, system, or PAC-selected -proxy, because those proxies can't carry UDP. ICMP remains blocked. - -UDP to local-network destinations is blocked before any policy is evaluated, -so no allow rule can permit it, including one that allows all hosts. This -covers multicast, link-local, and unspecified addresses, `255.255.255.255`, -and the broadcast addresses of the host's networks. As a result, discovery -protocols that use multicast, such as mDNS and SSDP, don't work from a -sandbox. UDP to `host.docker.internal` isn't affected. The network log records -these connections under the rule ``. - -Inspect UDP rules or check a destination: - -```console -$ sbx policy ls --protocol udp -$ sbx policy check network --protocol udp api.example.com:443 -``` - -The CLI warns if you save a UDP rule while UDP egress is disabled. - -## Testing policy - -Before running a sandbox, you can check whether the current policy would allow -a network request with `sbx policy check network`: - -```console -$ sbx policy check network api.anthropic.com -$ sbx policy check network blocked.example.com -``` - -The output reports `Allowed` or `Denied`, along with governance and context -details. A denied check returns a non-zero exit status. - -The target can be a hostname, a `host:port` pair, an IP address, or a URL. -Bare hostnames and IP addresses are evaluated against port 443. This is useful -for verifying custom rules or checking what the Locked Down preset blocks -before you start an agent. - -A check never creates an approval request. A destination that a sandbox would -ask you to approve shows as `Denied:`, with a `Reason:` line of -`no matching allow rule (default deny)`, or `approval required by policy` under -organization governance. - -To check policy in the context of a specific sandbox: - -```console -$ sbx policy check network --sandbox my-sandbox api.example.com -``` - -### Resetting - -To remove all custom rules and start fresh with a new preset, use -`sbx policy reset`: - -```console -$ sbx policy reset -``` - -This deletes the local policy store, restarts the daemon, and prompts you to -choose a new preset. Running sandboxes stop when the daemon shuts down. Pass -`--force` to skip the confirmation prompt: - -```console -$ sbx policy reset --force -``` - -## Troubleshooting - -### 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 summary block contains `Governance: 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. - -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. - -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 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/). - -### 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). - -### A request is blocked with "Approval required" - -The destination needs your confirmation. Either no allow or deny rule matches -it and your machine isn't under organization governance, or an organization -policy allows it but requires approval first. - -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). diff --git a/content/manuals/ai/sandboxes/governance/access-controls/network.md b/content/manuals/ai/sandboxes/governance/access-controls/network.md deleted file mode 100644 index b4a1c6c06320..000000000000 --- a/content/manuals/ai/sandboxes/governance/access-controls/network.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -title: Network access policies -linkTitle: Network access -weight: 30 -description: Control outbound network access from Docker Sandboxes with local and organization policy rules. -keywords: docker sandboxes, network access, network rules, governance, local policy, organization policy ---- - -The governance described here applies to local sandboxes. Cloud sandboxes -use separate network policy configuration. See -[Cloud network policy](../../cloud/network-policy.md) for cloud controls. - -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. 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: - -- [Local policy](local.md), which applies to sandboxes on one developer machine - when organization governance is not active. -- [Organization policies](organization.md), which apply centrally across an - organization or to selected teams. - -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 - -Network rules use `connect:tcp` for TCP and `connect:udp` for UDP. Resources are -hostnames, CIDR ranges, ports, or hostnames with ports. UDP requires -[experimental outbound UDP](local.md#allow-outbound-udp). ICMP is blocked. - -Examples: - -- `api.example.com` -- `*.example.com` -- `**.example.com` -- `example.com:443` -- `10.0.0.0/8` - -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 layer on top of network rules. 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 select 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 -network rules: - -```console -$ sbx policy allow network api.example.com -$ sbx policy deny network ads.example.com -``` - -For presets, sandbox-scoped rules, testing, and troubleshooting, see -[Local policy](local.md). - -## Organization network rules - -Organization network rules belong to policies that can apply to the whole -organization or to selected teams. For setup steps and team scoping, see -[Organization policies](organization.md). - -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. - -Without organization governance, a request with no matching allow or deny rule -also asks for approval rather than being denied outright, so access opens up as -the developer approves each destination. - -Under organization governance, 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 no policy that -allows it requires 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](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@1.md), -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. - -To require approval on an organization policy, see -[Organization policies](organization.md#require-approval-for-a-network-policy). - -### Respond to an approval request - -When a destination needs approval, a sandbox can't reach it 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 SANDBOX TITLE DETAIL OPTIONS -network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY my-sandbox api.example.com:443 Protocol: TCP Resource type: domain approval required by policy "default network" allow (Allow), dismiss (Dismiss) -``` - -Each entry names the destination, the sandbox that asked for it, and why it -needs approval. Under organization governance that reason names the policy, as -shown. Without it, the reason is that no matching allow rule covers the -destination. A request that an HTTP rule matches also shows the method and -path, such as `GET api.example.com:443/v1/data`. - -To inspect a single entry, pass its ID to `sbx policy approval inspect`: - -```console -$ sbx policy approval inspect network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY -``` - -Respond by selecting one of the options the entry offers: - -```console -$ sbx policy approval respond network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY --option 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 leaves one request to answer, not 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. - -When an [HTTP rule](../concepts.md#http-method-and-path) in the policy matches -the request, approving covers the method and exact path the sandbox requested -rather than the whole destination. `GET /v1/data` and `POST /v1/data` on the -same host are approved separately. A request whose method or path can't be -recorded as a rule, such as a path with percent-encoding, is blocked without an -entry to respond to. - -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 -> policies apply only to the gateway. Direct MCP connections from a sandbox -> don't use the gateway, but you can control access to remote MCP servers with -> network policy. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/organization.md b/content/manuals/ai/sandboxes/governance/access-controls/organization.md deleted file mode 100644 index d38d08507ba4..000000000000 --- a/content/manuals/ai/sandboxes/governance/access-controls/organization.md +++ /dev/null @@ -1,245 +0,0 @@ ---- -title: Organization policies -linkTitle: Org policies -weight: 20 -description: Centrally manage sandbox network, filesystem, and MCP policies for your organization. -keywords: docker sandboxes, governance, organization policy, AI governance, Docker Home, network access, filesystem access, mcp policy -aliases: - - /ai/sandboxes/security/governance/ - - /ai/sandboxes/governance/org/ ---- - -The governance described here applies to local sandboxes. Cloud sandboxes -use separate network policy configuration. See -[Cloud network policy](../../cloud/network-policy.md) for cloud controls. - -[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 local sandboxes across the organization, either to -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 -[Governance API](/reference/api/ai-governance/). - -By default, only organization -[owners](/manuals/security/roles-and-permissions/core-roles.md) can -view and manage AI Governance policies. To let someone other than an owner -manage policies, create a -[custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) -with the **Governance** permissions and assign it to a user or team. - -> [!NOTE] -> Sandbox organization governance is available on a separate paid -> subscription. -> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) -> to request access. - -## Create a policy - -Manage policies from the **AI Platform** section in the left-hand navigation -of [Docker Home](https://app.docker.com). - -To create a 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**, **Filesystem access**, or **MCP access**. -1. Select **Create policy**. -1. Enter a **Policy name**. -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. - - 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**, a **Type** that decides what the rule -matches, and a **Decision** of **Allow** or **Deny**. - -- **HTTP** matches only HTTP requests with the methods and paths you specify. - - In **Destination**, enter the host or IP address the rule covers. It - matches any port unless you add one. Enter the destination with no scheme - and no path, so `api.github.com` rather than - `https://api.github.com/repos`. A local HTTP rule accepts only a host. - - Under **HTTP methods**, select the methods the rule applies to. Use - **Select all** to select every method, or **Read-only** to select `GET`, - `HEAD`, and `OPTIONS`. A rule saved with no methods selected matches every - method the composer lists. The composer doesn't list `CONNECT` or - `TRACE`, which differs from the CLI, where `--method ANY` matches every - HTTP method. - - Under **Path patterns**, add one or more paths the rule covers, such as - `/repos/*` and `/v1/**`. Leave it empty to match any path. -- **All traffic** matches every request to the destinations you list, on any - port, method, and path. - - Under **Protocols**, select **TCP**, **UDP**, or **Both**. - - 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`. - -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). - -### 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). - -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. In the policy list, open the policy's action menu (⋮) and select **Edit**. -1. Turn on **Require approval before access**. -1. Select **Save**. - -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 -details when a sandbox action is blocked by organization governance. Use it to -point members to an internal support channel, ticket queue, or security contact. - -To set the message: - -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 **Manage**. -1. In **Support message**, enter up to 500 characters. -1. Select **Save changes**. - -Docker shows the message only for denials caused by organization governance -policy and for requests an -[approval-required policy](network.md#approval-required-access) blocks. If you -leave it blank, Docker shows the policy denial without additional contact text. - -## Choose a policy type - -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, 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, - resources, prompts, and approval gates with Cedar policy. - -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 - -An organization can have more than one policy, and each policy applies either -to the whole organization or to specific teams. Scoping lets you apply different -rules to different parts of the organization. - -A policy's [**Scope**](#create-a-policy) controls who it applies to. Set it to -**Organization** to apply the policy to every member, or to **Teams** to apply -it only to members of the teams you select. - -### Before you start - -Team scoping targets your organization's existing -[teams](/manuals/accounts/organization/manage/manage-a-team.md), so a team must -exist before you can scope a policy to it. Create teams and manage their members -in one of two ways: - -- Manually, in Docker Home. -- Automatically, by using - [group mapping](/manuals/security/provisioning/scim/group-mapping.md) - to synchronize your identity provider's groups with the teams in your - organization. Group mapping creates teams that don't already exist and keeps - their membership in step with your IdP groups. - -Because policies apply by team, a user's policies update automatically as their -team membership changes, including changes synced from your IdP. - -### How scoped policies combine - -A user is governed by all of their -[effective policies](../concepts.md#policy-scope): every org-wide policy, plus -the team-scoped policies for the teams they belong to. Use org-wide policies -for guardrails that must apply everywhere, and team-scoped policies for access -that only some teams need. - -For precedence between local and organization policies, and for how allow and -deny rules combine, see [Policy concepts](../concepts.md). - -## Troubleshooting - -### Policy changes not taking effect - -After updating organization policies, changes take up to 5 minutes to -propagate to developer machines. To apply changes immediately, users can run -`sbx policy reset`, which stops the daemon and forces it to pull the latest -organization policies on the next `sbx` command. - -> [!WARNING] -> `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 - -Policy types differ in when a change takes effect after it reaches the -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. 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 - filesystem policy has no effect on that sandbox. The sandbox continues to - access the previously allowed path until it is removed and a new one is - created. - -- MCP registration policy is evaluated when a server is registered with - `sbx mcp add`. Changing registration rules doesn't remove existing - registrations or stop an already-loaded server by itself. - -- MCP use-time policy is evaluated by the MCP gateway when a sandbox makes a - governed MCP request, such as a tool call, resource read, prompt retrieval, - or built-in gateway tool call. Once a policy change has synced, use-time - rules apply to subsequent governed MCP requests through the gateway. - -To apply a filesystem policy change immediately, remove the running sandbox -and create a new one. To prevent use of an MCP server that is already registered -or loaded, add use-time rules for the registered server name. For examples, see -[Withdraw server access](mcp.md#withdraw-server-access). diff --git a/content/manuals/ai/sandboxes/governance/audit/local.md b/content/manuals/ai/sandboxes/governance/audit/local.md deleted file mode 100644 index 0e1931fe9272..000000000000 --- a/content/manuals/ai/sandboxes/governance/audit/local.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Local audit logs -linkTitle: Local audit logs -weight: 10 -description: Collect Docker AI Governance audit records from local JSON Lines files written by the sandbox daemon. -keywords: docker sandboxes, audit log, local audit logs, audit logging, jsonl, SIEM, splunk, filebeat ---- - -The sandbox daemon writes local audit records as JSON Lines (`.jsonl`) files. -Local audit logs stay on the host that produced them and can be collected by -your own log shipper. Local delivery is independent of -[cloud delivery](configure.md), so you can use local files with cloud delivery -on or off. - -The sandbox daemon writes local audit records only for signed-in users who have -an AI Governance license and are governed by an enforced centralized -[organization policy](../access-controls/organization.md). Docker Sandboxes -users without both do not send audit data to audit logs. To confirm governance -is active, run `sbx policy ls`. The output includes a `Governance: Managed by -` line when an organization policy is in effect. - -## What gets recorded - -The daemon writes two categories of local record: - -- Evaluation records capture each policy decision: the resource, the action, - the verdict, and the reason for a denial. -- Session lifecycle records mark the start and end of each daemon run. - Evaluation records share the run's `audit_session_id`, so you can correlate - every decision back to a daemon session. - -Records contain metadata only. They don't contain prompt content, agent output, -or parameter values. For field details, see -[Audit record reference](record-reference.md). - -A network evaluation record looks like this: - -```json -{ - "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80", - "timestamp": "2026-05-28T19:15:00.728933Z", - "schema_version": "1.82.0", - "category": "AUDIT_CATEGORY_EVALUATION", - "decision": "AUDIT_DECISION_DENY", - "username": "jordandoe", - "user_email": "jordandoe@example.com", - "org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", - "org_name": "Acme Inc", - "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", - "resource_id": "example.com:443", - "os": "macos", - "app_version": "v0.31.0", - "client_name": "sbx", - "hostname": "host-machine", - "deny_reason": [ - "no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com:443)" - ], - "action_type": "network_egress", - "network_egress": { "protocol": "tcp" }, - "agent": "claude" -} -``` - -## Where records are stored - -The daemon writes audit records, not the CLI. Running a command such as -`sbx create` sends a request to the daemon, and the daemon emits the resulting -record to its own audit directory. - -The default location depends on your operating system: - -| OS | Default path | -| ------- | ----------------------------------------------------------------- | -| macOS | `~/Library/Logs/com.docker.sandboxes/sandboxes/auditkit/` | -| Linux | `${XDG_STATE_HOME:-~/.local/state}/sandboxes/sandboxes/auditkit/` | -| Windows | `%LOCALAPPDATA%\DockerSandboxes\sandboxes\logs\auditkit\` | - -The directory layout differs by platform because each operating system places -application logs in its own conventional location. - -Files are named `audit---.jsonl`. - -The daemon writes in-progress records to a temporary `.tmp` file and -finalizes it into a `.jsonl` file by atomic rename. Finalization happens at a -rotation threshold: by default, 5 minutes, 1000 events, or 50 MiB, whichever -comes first. Finalization also happens when the daemon shuts down cleanly. Only -`.jsonl` files are complete. Treat `.tmp` files as incomplete and don't collect -them. - -Sandboxes never delete `.jsonl` files. Retention and cleanup are the -responsibility of your log shipper or your own housekeeping. - -## Collect records with a SIEM - -Point your log shipper at the audit directory and configure it to collect -`.jsonl` files only. Tools such as the Splunk Universal Forwarder, -Filebeat, and CrowdStrike Falcon LogScale read the directory and forward each -line as an event. Because in-progress records live in `.tmp` files until they -are finalized, collectors never see partial records. diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md deleted file mode 100644 index a7c2928256ea..000000000000 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ /dev/null @@ -1,317 +0,0 @@ ---- -title: Policy concepts -weight: 10 -description: The resource model, rule syntax, and evaluation logic behind Docker sandbox governance. -keywords: docker sandboxes, policy concepts, rule syntax, network rules, filesystem rules, mcp policy, cedar policy, precedence, rule evaluation ---- - -The governance described here applies to local sandboxes. Cloud sandboxes -use separate network policy configuration. See -[Cloud network policy](../cloud/network-policy.md) for cloud controls. - -## Resource model - -Docker sandbox governance is built around two resource types: **policies** and -**rules**. - -A **policy** is a named collection of rules that controls sandbox access. -Policies exist at two levels: - -- **Local**: configured per machine using the `sbx policy` CLI. Applies to - sandboxes on that machine only. -- **Organization**: configured in Docker Home. Network and filesystem policies - can also be managed via the - [Governance API](/reference/api/ai-governance/). Applies to sandboxes across - 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, 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: - -- **Name**: a human-readable label -- **Actions**: the type of access the rule controls -- **Resources**: the targets the rule matches against -- **Decision**: `allow` or `deny` - -Rules are grouped by domain. Network and filesystem rules in a policy must -share the same domain, either `network` or `filesystem`. MCP policies use Cedar -statements written in the `MCP` namespace instead of the network and filesystem -rule format. - -An organization network policy can also require approval, which turns every -allow in that policy into a request the developer must confirm before access is -granted. Approval is set on the policy rather than on individual rules, so it -applies to all of the policy's allow rules at once. Without organization -governance, a request with no matching allow or deny rule also asks for -approval. See -[Approval-required access](access-controls/network.md#approval-required-access). - -Network approval is separate from the MCP `@requireApproval` annotation. An MCP -approval confirms a single call within the session and creates no rule, while -an approved network destination stays allowed until you remove the rule. See -[MCP access policies](access-controls/mcp.md). - -### Limits - -Organization policies have the following limits, which help ensure fair usage -and resource availability across organizations: - -| Limit | Value | -|---------------------------|-----------------------------------------------------| -| Policies per organization | 100 | -| Rules per policy | 250 | -| Policy size | 400 KB total, shared across all of a policy's rules | - -Typical policies use only a small fraction of the policy size limit. Domain -and file path values have no separate length limit beyond valid format. - -If these limits don't fit your organization's needs, -[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) -to discuss options. - -## Policy scope - -Each organization policy applies either across the whole organization or only -to specific teams: - -- Org-wide: with no teams assigned, the policy applies to every member of the - organization. -- Team-scoped: with one or more teams assigned, the policy applies only to - members of those teams. - -Teams are the same [teams](/manuals/accounts/organization/manage/manage-a-team.md) -you manage for your organization; Docker matches a policy's teams against each -user's team membership. Because an organization can mix org-wide and team-scoped -policies, a single user is often subject to several at once. The policies that -apply to a given user are their _effective policies_: every org-wide policy, -plus every team-scoped policy for a team they belong to. See -[Rule evaluation](#rule-evaluation) for how a user's effective policies combine. - -## Rule syntax - -### Network rules - -Network rules use `connect:tcp` for TCP and `connect:udp` for UDP. Resources are -hostnames, CIDR ranges, or ports. UDP requires -[experimental outbound UDP](access-controls/local.md#allow-outbound-udp). -ICMP is blocked. - -**Hostname patterns** - -| Pattern | Example | Matches | -| --------------------- | ----------------- | ------------------------------------------------------------- | -| Exact hostname | `example.com` | `example.com` on any port, not subdomains | -| Single-level wildcard | `*.example.com` | One subdomain level, any port: `api.example.com` | -| Multi-level wildcard | `**.example.com` | Any depth, any port: `api.example.com`, `v2.api.example.com` | -| Hostname with port | `example.com:443` | `example.com` on port 443 only | - -`example.com` and `*.example.com` don't cover each other. Specify both if you -need to match the root domain and its subdomains. - -**CIDR ranges** - -Both IPv4 and IPv6 notation are supported: `10.0.0.0/8`, `192.168.1.0/24`, -`2001:db8::/32`. - -#### HTTP method and path - -A network rule matches a destination host on its own. An HTTP rule is a network -rule that also names an HTTP method and URL path, so a policy can allow reads -from an API without allowing writes to it. - -An HTTP rule names one or more methods, a destination, and path patterns. What -each part accepts depends on where you configure the rule: - -| Part | Organization policy | Local policy | -| ----------- | ------------------------------------------ | --------------------------------- | -| Method | One or more listed methods | `ANY`, or one or more methods | -| Destination | A host or IP address | A host | -| Path | One or more absolute path patterns | One absolute path pattern | - -A destination can include a port, and a path pattern looks like `/api/**`. - -A local rule doesn't accept an IP address or a CIDR range. Use a plain network -rule for those destinations. To cover a second path in a local policy, add a -second rule. - -Every rule applies to at least one method. On the CLI, `--method ANY` covers -every HTTP method. In the composer, a rule with no methods selected covers -every method the composer lists. For the methods you can select individually, see -[Add a network rule](access-controls/organization.md#add-a-network-rule) for an -organization policy and -[HTTP method and path rules](access-controls/local.md#http-method-and-path-rules) -for a local one. - -Path patterns follow the same wildcard rules as filesystem paths, where `*` -matches within one path segment and `**` matches any depth. A pattern without a -wildcard matches that path exactly, so `/repos` matches `/repos` and nothing -below it. Every pattern must start with `/` and can't contain a query string, a -fragment, or a `..` segment. A local rule's path must also be canonical, so it -can't contain percent-encoding, control characters, repeated or trailing -slashes, or a `.` segment. For the full list, see -[HTTP method and path rules](access-controls/local.md#http-method-and-path-rules). - -HTTP requests are evaluated against both layers. A network rule sets the -baseline for a host, and HTTP rules adjust individual methods and paths within -it: - -| Rules that cover the host | Result for an HTTP request | -| --------------------------- | ----------------------------------------------------------------------- | -| Network allow only | Allowed at any method and path | -| HTTP allow only | Allowed only where a rule matches the method and path. Anything else is denied | -| Network allow and HTTP deny | The denied methods and paths are blocked. The rest stay allowed | -| Network deny | Blocked. An HTTP allow can't reopen a denied host | - -A network deny is therefore a floor that HTTP rules can't raise, while a -network allow is a ceiling that HTTP rules can carve into. - -When a rule requires a method and path decision, the sandbox HTTP proxy -evaluates each request separately instead of deciding once per connection. - -Those requests have to go through the proxy. A connection it can't inspect, -such as one it handles transparently, is blocked rather than evaluated. -Traffic that isn't HTTP, such as SSH, carries no method or path, so HTTP rules -never match it. Control those destinations with network rules. - -For local and organization policy configuration, see -[Network access policies](access-controls/network.md). - -### Filesystem rules - -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 -only `~`: it does not expand environment variables, so a pattern such as -`%USERPROFILE%\**` or `$HOME/**` matches nothing. - -For a path outside the home directory, write it in the format the user's -operating system uses. A rule matches only the format it's written in, so a -location that several platforms share needs a rule for each: - -| Operating system | Example path | -| ---------------- | ------------------------------------------ | -| macOS, Linux | `/data/project/**` | -| Windows | `C:\data\project\**` | -| WSL | `\\wsl.localhost\\data\project\**` | - -On Windows, `*:` matches any drive letter, so `*:\data\**` matches the path on -any drive. - -Wildcards behave the same way in every path format: - -| Pattern | Example | Matches | -| ------------------ | ---------- | ---------------------------------------------------------- | -| Exact path | `/data` | `/data` only | -| Segment wildcard | `/data/*` | `/data/project`, one path segment only, not subdirectories | -| Recursive wildcard | `/data/**` | `/data/project`, `/data/project/src`, any depth | - -Use `**` to match a directory tree recursively. A single `*` matches within one -path segment and won't cross a path separator. For example, `~/**` matches all -paths under the home directory, while `~/*` matches only its direct children. - -For organization policy configuration and enforcement details, see -[Filesystem access policies](access-controls/filesystem.md). - -### MCP policies - -MCP policies control Model Context Protocol activity made available to a -sandbox through Docker's [MCP gateway](../mcp-gateway.md). They are -organization policies written in Cedar using the `MCP` namespace, rather than -the network and filesystem rule format. - -MCP policy applies when a developer registers a server and when an agent uses -the MCP gateway. Registration rules control future `sbx mcp add` operations. -Use-time rules control tool calls, gateway meta-tools, resource reads, and -prompt retrieval from servers that are already registered or loaded. - -Governed MCP activity is default deny: a request is blocked unless a matching -`permit` allows it. A matching `forbid` overrides any `permit`, including a -permit that requires approval. Policy scope supplies the principal, so use -organization or team scope instead of matching users, teams, tenants, or roles -in Cedar. - -For representative policies, see [MCP access policies](access-controls/mcp.md). -For exact action, resource, context, and approval behavior, see the -[MCP policy reference](reference/mcp-policy.md). - -## Rule evaluation - -When organization governance is active, the rules from all of a user's -[effective policies](#policy-scope) are combined and evaluated together against -each request, following two principles: - -- Deny wins: if any rule matches with `decision: deny`, the request is denied, - regardless of any matching allow rules. -- Default deny: anything an allow rule doesn't match is blocked. Outbound - network traffic is blocked unless a network rule allows the destination, and a - host path can't be mounted unless a filesystem rule allows it. MCP activity is - blocked unless an MCP `permit` allows it. - -Because every effective policy feeds the same evaluation, allows are additive (a -request is allowed if any effective policy allows it) and denies are absolute (a -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 and kit-defined allow rules take no part in this evaluation. Deny rules -from those sources do still apply. See [Precedence](#precedence). - -A request that an approval-required policy allows produces a third outcome. -Rather than being allowed outright, it's held back until the developer confirms -the destination, and the confirmation governs later requests to it. This holds -even when another policy allows the same request without requiring approval. A -matching deny still wins, so a denied destination is blocked without asking. -See [Approval-required access](access-controls/network.md#approval-required-access). - -## Precedence - -What applies depends on whether your organization has governance enabled: - -- No organization governance: local rules and any kit-defined network rules - determine what sandboxes can access. -- 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. - -For kit-defined rules, see -[Network policies](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@1.md) -in the kit specification. - -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. - -A local deny takes precedence over an organization approval requirement as -well, so the request is blocked and no approval is requested. Rules that a -developer gains by approving a request are the one exception to local allow -rules being inactive, because they record an answer to the organization's own -approval requirement rather than granting new access. See -[Approval-required access](access-controls/network.md#approval-required-access). - -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/local/_index.md b/content/manuals/ai/sandboxes/governance/local/_index.md new file mode 100644 index 000000000000..99e8649a2df4 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/local/_index.md @@ -0,0 +1,45 @@ +--- +title: Local policy +weight: 10 +description: Configure local network access rules for sandboxes on your machine. +keywords: docker sandboxes, local policy, network access, allow rules, deny rules, sbx policy +aliases: + - /ai/sandboxes/security/policy/ + - /ai/sandboxes/governance/access-controls/local/ +--- + +The `sbx policy` command manages the local policy on your machine. The local +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 interacts with organization governance as follows: + +- **No org governance**: the local policy controls what sandboxes can access. +- **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](inspect.md#showing-inactive-rules). + +See [Organization policies](../organization/_index.md) for how organization governance +works. + +For domain patterns, wildcards, CIDR ranges, and filesystem path syntax, see +[Policy concepts](../reference/network-rules.md). + +Outbound TCP traffic passes through a proxy on your host, which enforces access +rules on every connection. Non-HTTP TCP traffic, including SSH, can be allowed +with a hostname rule (for example, `sbx policy allow network "myhost:22"`) or an +address-based rule. UDP requires the experimental feature and policy rules +described in [Allow outbound UDP](network-rules.md#allow-outbound-udp). ICMP is blocked. + +Under **Balanced** and **Locked Down**, a sandbox request that no rule matches +is blocked and asks for your approval instead of being denied outright, so you +can open access to each destination as a sandbox needs it. See +[Approval-required access](approvals.md). + +Without organization governance, a request with no matching allow or deny rule +also asks for approval rather than being denied outright, so access opens up as +the developer approves each destination. diff --git a/content/manuals/ai/sandboxes/governance/local/approvals.md b/content/manuals/ai/sandboxes/governance/local/approvals.md new file mode 100644 index 000000000000..5e725ccb4217 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/local/approvals.md @@ -0,0 +1,97 @@ +--- +title: Respond to approval requests +linkTitle: Respond to approvals +weight: 30 +description: Approve or deny sandbox network requests that need your confirmation. +keywords: docker sandboxes, approval required, approve network access, sbx policy, local policy +--- + +When a destination needs approval, a sandbox can't reach it 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/policies/create-manage.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 SANDBOX TITLE DETAIL OPTIONS +network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY my-sandbox api.example.com:443 Protocol: TCP Resource type: domain approval required by policy "default network" allow (Allow), dismiss (Dismiss) +``` + +Each entry names the destination, the sandbox that asked for it, and why it +needs approval. Under organization governance that reason names the policy, as +shown. Without it, the reason is that no matching allow rule covers the +destination. A request that an HTTP rule matches also shows the method and +path, such as `GET api.example.com:443/v1/data`. + +To inspect a single entry, pass its ID to `sbx policy approval inspect`: + +```console +$ sbx policy approval inspect network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY +``` + +Respond by selecting one of the options the entry offers: + +```console +$ sbx policy approval respond network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY --option 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 leaves one request to answer, not 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. + +When an [HTTP rule](../reference/network-rules.md#http-method-and-path) in the policy matches +the request, approving covers the method and exact path the sandbox requested +rather than the whole destination. `GET /v1/data` and `POST /v1/data` on the +same host are approved separately. A request whose method or path can't be +recorded as a rule, such as a path with percent-encoding, is blocked without an +entry to respond to. + +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`](network-rules.md). + +Approvals live in the local policy store, so [`sbx policy reset`](get-started.md#resetting) +removes all of them along with your other local rules. Each destination is +requested again the next time a sandbox reaches it. + +## Troubleshooting + +### A request is blocked with "Approval required" + +The destination needs your confirmation. Either no allow or deny rule matches +it and your machine isn't under organization governance, or an organization +policy allows it but requires approval first. + +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. diff --git a/content/manuals/ai/sandboxes/governance/local/get-started.md b/content/manuals/ai/sandboxes/governance/local/get-started.md new file mode 100644 index 000000000000..75b289d34a48 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/local/get-started.md @@ -0,0 +1,89 @@ +--- +title: Get started with local policy +linkTitle: Get started +weight: 10 +description: Choose and reset the default network preset for local sandbox policy. +keywords: docker sandboxes, local policy, network preset, sbx policy init, sbx policy reset +--- + +## Default preset + +If you haven't chosen a default preset, the CLI prompts you before it runs a +sandbox. Running `sbx policy reset` clears the preset and prompts you to choose +again: + +```plaintext +Initialize the global network policy for your sandboxes: + + Applies to all sandboxes, current and future — change it later with + "sbx policy allow/deny/rm". Kits, including built-in agent kits, may + also add per-sandbox rules. + + 1. Open — All network traffic allowed, no restrictions. + ❯ 2. Balanced — Default deny, with common dev sites allowed. + 3. Locked Down — All network traffic blocked unless you allow it. + + Use ↑/↓ or 1–3 to navigate, Enter to confirm, Esc to cancel. +``` + +| Preset | Description | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| Open | All outbound TCP traffic is allowed. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`. | +| Balanced | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. | +| Locked Down | No baseline allow rules. Destinations need an allow rule from you or a kit. | + +Presets initialize the global policy. Built-in agent kits and other kits can +add per-sandbox allow rules, including under **Locked Down** (`deny-all`). The +preset isn't an explicit deny rule that overrides those allowances. + +To inspect the rules a kit adds to a sandbox, run: + +```console +$ sbx policy ls my-sandbox --source kit --type network --wide +``` + +To block a destination allowed by a kit, add an explicit deny rule: + +```console +$ sbx policy deny network --sandbox my-sandbox openrouter.ai +``` + +Deny rules take precedence over allow rules. See +[Policy precedence](../organization/policies/_index.md#precedence). + +The **Balanced** preset's baseline allowlist is a good starting point for most +workflows. Run `sbx policy ls` to see exactly which rules it includes. + +> [!NOTE] +> If your organization manages sandbox policies centrally, organization rules +> take precedence over the preset you select here. See +> [Organization policies](../organization/_index.md). + +### Non-interactive environments + +In non-interactive environments such as CI pipelines or headless servers, the +interactive prompt can't be displayed. Use `sbx policy init` to set the +preset before running any other `sbx` commands: + +```console +$ sbx policy init balanced +``` + +Available values are `allow-all`, `balanced`, and `deny-all`. + +## Resetting + +To remove all custom rules and start fresh with a new preset, use +`sbx policy reset`: + +```console +$ sbx policy reset +``` + +This deletes the local policy store, restarts the daemon, and prompts you to +choose a new preset. Running sandboxes stop when the daemon shuts down. Pass +`--force` to skip the confirmation prompt: + +```console +$ sbx policy reset --force +``` diff --git a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md b/content/manuals/ai/sandboxes/governance/local/inspect.md similarity index 72% rename from content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md rename to content/manuals/ai/sandboxes/governance/local/inspect.md index 223bc8600c7b..228c77605111 100644 --- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md +++ b/content/manuals/ai/sandboxes/governance/local/inspect.md @@ -1,10 +1,12 @@ --- -title: Monitoring policies -weight: 10 +title: Inspect policy status and rules +linkTitle: Inspect policies +weight: 40 description: Inspect active policy rules and monitor sandbox network traffic with sbx policy ls and sbx policy log. keywords: docker sandboxes, policy monitoring, sbx policy ls, sbx policy log, network traffic, policy debugging aliases: - /ai/sandboxes/governance/monitoring/ + - /ai/sandboxes/governance/monitor-and-enforce/monitoring/ --- `sbx policy ls` and `sbx policy log` give you a combined view of all active @@ -29,7 +31,7 @@ The columns are: - `POLICY`: the policy name. - `SOURCE`: where the policy came from. `local` means your local configuration — a preset or rules you added with `sbx policy`. `kit` means a - [kit](/manuals/ai/sandboxes/governance/concepts.md#precedence). `org` means your + [kit](/manuals/ai/sandboxes/governance/organization/policies/_index.md#precedence). `org` means your organization. - `APPLIES TO`: which sandboxes the policy applies to. `all` means the policy is global. `sandbox:` scopes it to a single sandbox; a profile name @@ -61,7 +63,7 @@ destination. A wide listing shows the same information per rule: $ sbx policy ls --wide --created-via approval ``` -See [Approval-required access](../access-controls/network.md#approval-required-access). +See [Approval-required access](approvals.md). A `STATUS` column also appears when you pass `--include-inactive`; see [Showing inactive rules](#showing-inactive-rules). @@ -122,7 +124,7 @@ 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. 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). +organization policy. See [Precedence](../organization/policies/_index.md#precedence). Use `--type network`, `--type filesystem`, or `--type http` to show only policies of that type. Without a sandbox argument, `sbx policy ls` shows every @@ -149,7 +151,7 @@ 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). +[Policy concepts](../reference/filesystem-rules.md). ### HTTP rules @@ -188,51 +190,41 @@ filtered listing with no HTTP rules shows an unlabeled count, such as `network: 42 allow`. For the rule syntax, see -[HTTP method and path](../concepts.md#http-method-and-path). +[HTTP method and path](../reference/network-rules.md#http-method-and-path). -## Monitoring traffic +## Inspecting rules -Use `sbx policy log` to see which hosts your sandboxes have contacted and -which rules matched: +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 +rule-level detail including rule IDs. To inspect a single policy or rule in +full, use `sbx policy inspect`. -```console -$ sbx policy log -BLOCKED REQUESTS -SANDBOX TYPE HOST PROXY RULE REASON LAST SEEN COUNT -my-sandbox network blocked.example.com transparent domain-blocked default-deny 10:15:25 29-Jan 1 - -ALLOWED REQUESTS -SANDBOX TYPE HOST PROXY RULE REASON LAST SEEN COUNT -my-sandbox network api.anthropic.com forward domain-allowed 10:15:23 29-Jan 42 -my-sandbox network registry.npmjs.org forward-bypass domain-allowed 10:15:20 29-Jan 18 -my-sandbox network app.example.com browser-open 10:15:10 29-Jan 1 -``` - -The `PROXY` column shows how the request left the sandbox: +## Troubleshooting -| Value | Description | -| ---------------- | -------------------------------------------------------------------------------------------------------------- | -| `forward` | Routed through the forward proxy. Supports [credential injection](../../configuration/credentials.md). | -| `forward-bypass` | Routed through the forward proxy without credential injection. | -| `transparent` | Intercepted by the transparent proxy. Policy is enforced but credential injection is not available. | -| `network` | Non-HTTP traffic. TCP and experimental UDP egress follow network policy. ICMP is blocked. | -| `browser-open` | A sandbox process requested opening a URL in the host browser. Policy is enforced before opening the URL. | +### Local allow rules have no effect -The `RULE` column identifies the policy rule that matched the request. The -`REASON` column includes extra context when the daemon records one. +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 summary block contains `Governance: 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. -Filter by sandbox name by passing it as an argument: +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. -```console -$ sbx policy log my-sandbox -``` +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. -Use `--limit N` to show only the last `N` entries, `--json` or `--format yaml` 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. +### A domain is still blocked after adding an allow rule -Structured output uses the same document for local and cloud sandboxes: -`{updated_at, allowed: [...], blocked: [...]}`. Each entry includes `sandbox_id`, -`host`, `proxy_type`, `rule`, `reason`, `count`, `first_seen`, and `last_seen`. -The `--limit` flag applies to structured output too. +If a domain remains blocked after you add a local allow rule, your organization +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/local/network-rules.md b/content/manuals/ai/sandboxes/governance/local/network-rules.md new file mode 100644 index 000000000000..c65189e7d75d --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/local/network-rules.md @@ -0,0 +1,189 @@ +--- +title: Manage local network rules +linkTitle: Manage network rules +weight: 20 +description: Allow, deny, and remove local network rules for sandboxes on your machine with sbx policy. +keywords: docker sandboxes, local policy, network rules, sbx policy allow, sbx policy deny, HTTP rules, UDP +--- + +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 +all sandboxes by default: + +```console +$ sbx policy allow network api.anthropic.com +$ sbx policy deny network ads.example.com +``` + +Pass `--sandbox ` to scope a rule to one sandbox: + +```console +$ 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 +$ sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org" +``` + +Remove a rule by resource or by rule ID: + +```console +$ sbx policy rm network --resource ads.example.com +$ sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 +``` + +To remove a sandbox-scoped rule, pass `--sandbox `: + +```console +$ 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`. + +A path must start with `/` and be canonical. It can't contain a query string, a +fragment, percent-encoding, control characters, surrounding whitespace, +repeated or trailing slashes, or dot segments such as `.` and `..`. Each rule +takes one path. Repeating `--path` keeps only the last value, and a comma is +read as part of the path, so add a separate rule for each path: + +```console +$ sbx policy allow network api.github.com --method GET --path '/repos/**' +$ sbx policy allow network api.github.com --method GET --path '/users/**' +``` + +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](../reference/network-rules.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. + +## Allow outbound UDP + +Outbound UDP is experimental and disabled by default. Turn on experimental +features and UDP egress before adding UDP allow rules: + +```console +$ sbx settings set platform.allowExperimentalFeatures true +$ sbx settings set feature.udp-egress true +$ sbx policy allow network --protocol udp api.example.com:443 +``` + +Local allow rules apply to TCP by default. Use `--protocol udp` for UDP or +`--protocol tcp,udp` for both. Deny rules apply to both protocols by default. +Use `--protocol` to restrict a deny rule to one protocol. + +UDP follows the same organization and local policy precedence as TCP. It is +refused when the destination requires an HTTP, SOCKS5, system, or PAC-selected +proxy, because those proxies can't carry UDP. ICMP remains blocked. + +UDP to local-network destinations is blocked before any policy is evaluated, +so no allow rule can permit it, including one that allows all hosts. This +covers multicast, link-local, and unspecified addresses, `255.255.255.255`, +and the broadcast addresses of the host's networks. As a result, discovery +protocols that use multicast, such as mDNS and SSDP, don't work from a +sandbox. UDP to `host.docker.internal` isn't affected. The network log records +these connections under the rule ``. + +Inspect UDP rules or check a destination: + +```console +$ sbx policy ls --protocol udp +$ sbx policy check network --protocol udp api.example.com:443 +``` + +The CLI warns if you save a UDP rule while UDP egress is disabled. + +## Troubleshooting + +### 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). diff --git a/content/manuals/ai/sandboxes/governance/local/test-monitor.md b/content/manuals/ai/sandboxes/governance/local/test-monitor.md new file mode 100644 index 000000000000..0dc4bc044d7e --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/local/test-monitor.md @@ -0,0 +1,83 @@ +--- +title: Test and monitor network policy +linkTitle: Test and monitor +weight: 50 +description: Test which destinations a sandbox can reach and monitor sandbox network traffic. +keywords: docker sandboxes, test network policy, sbx policy log, network traffic, local policy +--- + +## Testing policy + +Before running a sandbox, you can check whether the current policy would allow +a network request with `sbx policy check network`: + +```console +$ sbx policy check network api.anthropic.com +$ sbx policy check network blocked.example.com +``` + +The output reports `Allowed` or `Denied`, along with governance and context +details. A denied check returns a non-zero exit status. + +The target can be a hostname, a `host:port` pair, an IP address, or a URL. +Bare hostnames and IP addresses are evaluated against port 443. This is useful +for verifying custom rules or checking what the Locked Down preset blocks +before you start an agent. + +A check never creates an approval request. A destination that a sandbox would +ask you to approve shows as `Denied:`, with a `Reason:` line of +`no matching allow rule (default deny)`, or `approval required by policy` under +organization governance. + +To check policy in the context of a specific sandbox: + +```console +$ sbx policy check network --sandbox my-sandbox api.example.com +``` + +## Monitoring traffic + +Use `sbx policy log` to see which hosts your sandboxes have contacted and +which rules matched: + +```console +$ sbx policy log +BLOCKED REQUESTS +SANDBOX TYPE HOST PROXY RULE REASON LAST SEEN COUNT +my-sandbox network blocked.example.com transparent domain-blocked default-deny 10:15:25 29-Jan 1 + +ALLOWED REQUESTS +SANDBOX TYPE HOST PROXY RULE REASON LAST SEEN COUNT +my-sandbox network api.anthropic.com forward domain-allowed 10:15:23 29-Jan 42 +my-sandbox network registry.npmjs.org forward-bypass domain-allowed 10:15:20 29-Jan 18 +my-sandbox network app.example.com browser-open 10:15:10 29-Jan 1 +``` + +The `PROXY` column shows how the request left the sandbox: + +| Value | Description | +| ---------------- | -------------------------------------------------------------------------------------------------------------- | +| `forward` | Routed through the forward proxy. Supports [credential injection](../../configuration/credentials.md). | +| `forward-bypass` | Routed through the forward proxy without credential injection. | +| `transparent` | Intercepted by the transparent proxy. Policy is enforced but credential injection is not available. | +| `network` | Non-HTTP traffic. TCP and experimental UDP egress follow network policy. ICMP is blocked. | +| `browser-open` | A sandbox process requested opening a URL in the host browser. Policy is enforced before opening the URL. | + +The `RULE` column identifies the policy rule that matched the request. The +`REASON` column includes extra context when the daemon records one. + +Filter by sandbox name by passing it as an argument: + +```console +$ sbx policy log my-sandbox +``` + +Use `--limit N` to show only the last `N` entries, `--json` or `--format yaml` 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. + +Structured output uses the same document for local and cloud sandboxes: +`{updated_at, allowed: [...], blocked: [...]}`. Each entry includes `sandbox_id`, +`host`, `proxy_type`, `rule`, `reason`, `count`, `first_seen`, and `last_seen`. +The `--limit` flag applies to structured output too. diff --git a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md deleted file mode 100644 index 0ff58d417a22..000000000000 --- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Monitor and enforce -weight: 40 -description: Inspect active sandbox governance rules, collect audit records, and enforce organization sign-in. -keywords: docker sandboxes, governance monitoring, audit logs, sign-in enforcement, policy enforcement ---- - -After policies are configured, use monitoring, audit records, and sign-in -enforcement to verify how governance behaves across developer machines. - -- [Monitoring policies](monitoring.md): inspect active policy rules and monitor - sandbox network traffic. -- [Audit logs](../audit/): view, configure, export, and collect governance audit - records. -- [Sign-in enforcement](sign-in-enforcement.md): require users to sign in as - members of approved Docker organizations. diff --git a/content/manuals/ai/sandboxes/governance/organization/_index.md b/content/manuals/ai/sandboxes/governance/organization/_index.md new file mode 100644 index 000000000000..2281bff481d6 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/_index.md @@ -0,0 +1,36 @@ +--- +title: Organization governance +weight: 20 +description: Centrally manage sandbox network, filesystem, and MCP policies for your organization. +keywords: docker sandboxes, governance, organization policy, AI governance, Docker Home, network access, filesystem access, mcp policy +aliases: + - /ai/sandboxes/security/governance/ + - /ai/sandboxes/governance/org/ + - /ai/sandboxes/governance/access-controls/organization/ +--- + +[Local policies](../local/_index.md) give individual developers control over what their +sandboxes can access. Organization policy moves that control to the admin level: +organization policies apply to local sandboxes across the organization, either to +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 +[Governance API](/reference/api/ai-governance/). + +By default, only organization +[owners](/manuals/security/roles-and-permissions/core-roles.md) can +view and manage AI Governance policies. To let someone other than an owner +manage policies, create a +[custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) +with the **Governance** permissions and assign it to a user or team. + +> [!NOTE] +> Sandbox organization governance is available on a separate paid +> subscription. +> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) +> to request access. diff --git a/content/manuals/ai/sandboxes/governance/audit/_index.md b/content/manuals/ai/sandboxes/governance/organization/audit/_index.md similarity index 62% rename from content/manuals/ai/sandboxes/governance/audit/_index.md rename to content/manuals/ai/sandboxes/governance/organization/audit/_index.md index bff10587de80..223441c37057 100644 --- a/content/manuals/ai/sandboxes/governance/audit/_index.md +++ b/content/manuals/ai/sandboxes/governance/organization/audit/_index.md @@ -1,9 +1,12 @@ --- title: AI Governance Audit Logs linkTitle: Audit logs -weight: 30 +weight: 40 description: Capture, view, export, and collect structured audit records for Docker AI Governance policy decisions. keywords: docker sandboxes, audit log, audit logging, AI Governance, policy decision, SIEM, compliance, jsonl +aliases: + - /ai/sandboxes/governance/audit/ + - /ai/sandboxes/governance/audit/local/ --- {{< summary-bar feature_name="AI Governance Audit Logs" >}} @@ -11,7 +14,7 @@ keywords: docker sandboxes, audit log, audit logging, AI Governance, policy deci The Docker Sandboxes coverage on this page applies to local sandboxes. Docker Cloud delivery stores their audit records in the cloud; it does not add cloud sandbox coverage. For cloud network decisions, see -[Cloud policy logs](../../cloud/network-policy.md#inspect-network-policy). +[Cloud policy logs](../../../cloud/network-policy.md#inspect-network-policy). AI Governance Audit Logs record Docker AI Governance activity for your organization. Each record captures the principal, action, target, decision, and @@ -21,7 +24,7 @@ prompt content, agent output, or parameter values. Audit logs are exposed when AI Governance is enabled for your organization. Docker Sandboxes send audit records only for signed-in users who have an AI Governance license and are governed by an enforced centralized [organization -policy](../access-controls/organization.md). Docker Sandboxes users without both +policy](../_index.md). Docker Sandboxes users without both don't send audit data to audit logs. > [!NOTE] @@ -71,6 +74,48 @@ Organizations that used local audit logging before hosted audit logs were available start with cloud delivery off until an owner opts in from [audit delivery settings](configure.md). +### Where records are stored + +The sandbox daemon writes local audit records as JSON Lines (`.jsonl`) files. +Local audit logs stay on the host that produced them and can be collected by +your own log shipper. Local delivery is independent of +[cloud delivery](configure.md), so you can use local files with cloud delivery +on or off. + +The sandbox daemon writes local audit records only for signed-in users who have +an AI Governance license and are governed by an enforced centralized +[organization policy](../_index.md). Docker Sandboxes +users without both do not send audit data to audit logs. To confirm governance +is active, run `sbx policy ls`. The output includes a `Governance: Managed by +` line when an organization policy is in effect. + +The daemon writes audit records, not the CLI. Running a command such as +`sbx create` sends a request to the daemon, and the daemon emits the resulting +record to its own audit directory. + +The default location depends on your operating system: + +| OS | Default path | +| ------- | ----------------------------------------------------------------- | +| macOS | `~/Library/Logs/com.docker.sandboxes/sandboxes/auditkit/` | +| Linux | `${XDG_STATE_HOME:-~/.local/state}/sandboxes/sandboxes/auditkit/` | +| Windows | `%LOCALAPPDATA%\DockerSandboxes\sandboxes\logs\auditkit\` | + +The directory layout differs by platform because each operating system places +application logs in its own conventional location. + +Files are named `audit---.jsonl`. + +The daemon writes in-progress records to a temporary `.tmp` file and +finalizes it into a `.jsonl` file by atomic rename. Finalization happens at a +rotation threshold: by default, 5 minutes, 1000 events, or 50 MiB, whichever +comes first. Finalization also happens when the daemon shuts down cleanly. Only +`.jsonl` files are complete. Treat `.tmp` files as incomplete and don't collect +them. + +Sandboxes never delete `.jsonl` files. Retention and cleanup are the +responsibility of your log shipper or your own housekeeping. + ## Data handling When Docker Cloud delivery is enabled, Docker stores audit records in Docker @@ -81,8 +126,7 @@ Policy](https://www.docker.com/legal/privacy/). ## Learn more -- [Local audit logs](local.md) - [Configure audit delivery](configure.md) - [View and export audit events](view-export.md) - [SIEM forwarding](siem.md) -- [Audit record reference](record-reference.md) +- [Audit record reference](../../reference/audit-records.md) diff --git a/content/manuals/ai/sandboxes/governance/audit/configure.md b/content/manuals/ai/sandboxes/governance/organization/audit/configure.md similarity index 98% rename from content/manuals/ai/sandboxes/governance/audit/configure.md rename to content/manuals/ai/sandboxes/governance/organization/audit/configure.md index 5afa22949ab6..764265946c09 100644 --- a/content/manuals/ai/sandboxes/governance/audit/configure.md +++ b/content/manuals/ai/sandboxes/governance/organization/audit/configure.md @@ -1,9 +1,11 @@ --- title: Configure audit delivery linkTitle: Configure delivery -weight: 20 +weight: 10 description: Configure local and cloud delivery, retention, and history for Docker AI Governance Audit Logs. keywords: docker sandboxes, audit delivery, AI Governance, audit logs, retention, cloud delivery, AI Platform +aliases: + - /ai/sandboxes/governance/audit/configure/ --- Organization owners and users with a [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) that includes AI Governance audit permissions can configure where Docker writes audit events. diff --git a/content/manuals/ai/sandboxes/governance/audit/siem.md b/content/manuals/ai/sandboxes/governance/organization/audit/siem.md similarity index 88% rename from content/manuals/ai/sandboxes/governance/audit/siem.md rename to content/manuals/ai/sandboxes/governance/organization/audit/siem.md index 9a4dd503d290..ef15d30aaad0 100644 --- a/content/manuals/ai/sandboxes/governance/audit/siem.md +++ b/content/manuals/ai/sandboxes/governance/organization/audit/siem.md @@ -1,9 +1,11 @@ --- title: SIEM forwarding -linkTitle: SIEM forwarding -weight: 40 +linkTitle: Forward to a SIEM +weight: 30 description: Forward Docker AI Governance audit events to Splunk, Dynatrace, Datadog, Sumo Logic, or CrowdStrike Falcon Next-Gen SIEM. keywords: docker sandboxes, SIEM, audit logs, Splunk, Dynatrace, Datadog, Sumo Logic, CrowdStrike, Falcon Next-Gen SIEM, AI Governance, forwarding, NDJSON +aliases: + - /ai/sandboxes/governance/audit/siem/ --- {{< summary-bar feature_name="AI Governance Audit Logs" >}} @@ -70,3 +72,11 @@ From the **SIEM forwarding** list, select the menu next to a destination to edit or delete it. The edit form lets you update credentials and toggle forwarding on or off for that destination. Deleting a destination permanently removes the endpoint and its stored credential and cannot be undone. + +## Collect records with a SIEM + +Point your log shipper at the audit directory and configure it to collect +`.jsonl` files only. Tools such as the Splunk Universal Forwarder, +Filebeat, and CrowdStrike Falcon LogScale read the directory and forward each +line as an event. Because in-progress records live in `.tmp` files until they +are finalized, collectors never see partial records. diff --git a/content/manuals/ai/sandboxes/governance/audit/view-export.md b/content/manuals/ai/sandboxes/governance/organization/audit/view-export.md similarity index 96% rename from content/manuals/ai/sandboxes/governance/audit/view-export.md rename to content/manuals/ai/sandboxes/governance/organization/audit/view-export.md index 7b1e7adf67b0..f37c254c5558 100644 --- a/content/manuals/ai/sandboxes/governance/audit/view-export.md +++ b/content/manuals/ai/sandboxes/governance/organization/audit/view-export.md @@ -1,9 +1,11 @@ --- title: View and export audit events linkTitle: View and export -weight: 30 +weight: 20 description: Search, filter, and export Docker AI Governance audit events from the hosted audit log UI. keywords: docker sandboxes, audit events, audit logs, AI Governance, CSV export +aliases: + - /ai/sandboxes/governance/audit/view-export/ --- Cloud delivery stores AI Governance audit records in Docker Cloud and makes diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/_index.md b/content/manuals/ai/sandboxes/governance/organization/policies/_index.md new file mode 100644 index 000000000000..4829d9f25737 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/policies/_index.md @@ -0,0 +1,160 @@ +--- +title: Policies +weight: 30 +description: How organization policy scope, rule evaluation, and precedence work for Docker Sandboxes. +keywords: docker sandboxes, organization policy, policy scope, rule evaluation, precedence, governance +aliases: + - /ai/sandboxes/governance/concepts/ +--- + +## Policy scope + +Each organization policy applies either across the whole organization or only +to specific teams: + +- Org-wide: with no teams assigned, the policy applies to every member of the + organization. +- Team-scoped: with one or more teams assigned, the policy applies only to + members of those teams. + +Teams are the same [teams](/manuals/accounts/organization/manage/manage-a-team.md) +you manage for your organization; Docker matches a policy's teams against each +user's team membership. Because an organization can mix org-wide and team-scoped +policies, a single user is often subject to several at once. The policies that +apply to a given user are their _effective policies_: every org-wide policy, +plus every team-scoped policy for a team they belong to. See +[Rule evaluation](#rule-evaluation) for how a user's effective policies combine. + +## How scoped policies combine + +A user is governed by all of their +[effective policies](#policy-scope): every org-wide policy, plus +the team-scoped policies for the teams they belong to. Use org-wide policies +for guardrails that must apply everywhere, and team-scoped policies for access +that only some teams need. + +For precedence between local and organization policies, and for how allow and +deny rules combine, see [Precedence](#precedence). + +## Rule evaluation + +When organization governance is active, the rules from all of a user's +[effective policies](#policy-scope) are combined and evaluated together against +each request, following two principles: + +- Deny wins: if any rule matches with `decision: deny`, the request is denied, + regardless of any matching allow rules. +- Default deny: anything an allow rule doesn't match is blocked. Outbound + network traffic is blocked unless a network rule allows the destination, and a + host path can't be mounted unless a filesystem rule allows it. MCP activity is + blocked unless an MCP `permit` allows it. + +Because every effective policy feeds the same evaluation, allows are additive (a +request is allowed if any effective policy allows it) and denies are absolute (a +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 and kit-defined allow rules take no part in this evaluation. Deny rules +from those sources do still apply. See [Precedence](#precedence). + +A request that an approval-required policy allows produces a third outcome. +Rather than being allowed outright, it's held back until the developer confirms +the destination, and the confirmation governs later requests to it. This holds +even when another policy allows the same request without requiring approval. A +matching deny still wins, so a denied destination is blocked without asking. +See [Approval-required access](network.md#approval-required-access). + +## Precedence + +What applies depends on whether your organization has governance enabled: + +- No organization governance: local rules and any kit-defined network rules + determine what sandboxes can access. +- 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. + +For kit-defined rules, see +[Network policies](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@1.md) +in the kit specification. + +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](../../local/inspect.md#showing-inactive-rules) for how +to list them. + +A local deny takes precedence over an organization approval requirement as +well, so the request is blocked and no approval is requested. Rules that a +developer gains by approving a request are the one exception to local allow +rules being inactive, because they record an answer to the organization's own +approval requirement rather than granting new access. See +[Approval-required access](network.md#approval-required-access). + +When organization governance is active, a user's organization policies are +evaluated together, as described in [Rule evaluation](#rule-evaluation). + +## Troubleshooting + +### Policy changes not taking effect + +After updating organization policies, changes take up to 5 minutes to +propagate to developer machines. To apply changes immediately, users can run +`sbx policy reset`, which stops the daemon and forces it to pull the latest +organization policies on the next `sbx` command. + +> [!WARNING] +> `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 + +Policy types differ in when a change takes effect after it reaches the +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. 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 + filesystem policy has no effect on that sandbox. The sandbox continues to + access the previously allowed path until it is removed and a new one is + created. + +- MCP registration policy is evaluated when a server is registered with + `sbx mcp add`. Changing registration rules doesn't remove existing + registrations or stop an already-loaded server by itself. + +- MCP use-time policy is evaluated by the MCP gateway when a sandbox makes a + governed MCP request, such as a tool call, resource read, prompt retrieval, + or built-in gateway tool call. Once a policy change has synced, use-time + rules apply to subsequent governed MCP requests through the gateway. + +To apply a filesystem policy change immediately, remove the running sandbox +and create a new one. To prevent use of an MCP server that is already registered +or loaded, add use-time rules for the registered server name. For examples, see +[Withdraw server access](mcp.md#withdraw-server-access). diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md b/content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md new file mode 100644 index 000000000000..33459d6a6a38 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md @@ -0,0 +1,99 @@ +--- +title: Create and manage policies +linkTitle: Create and manage +weight: 10 +description: Create, scope, edit, and delete organization network, filesystem, and MCP policies in Docker Home. +keywords: docker sandboxes, organization policy, create policy, Docker Home, team scope, policy limits +--- + +## Create a policy + +Manage policies from the **AI Platform** section in the left-hand navigation +of [Docker Home](https://app.docker.com). + +To create a 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**, **Filesystem access**, or **MCP access**. +1. Select **Create policy**. +1. Enter a **Policy name**. +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. + - Network and filesystem policies: select **Add rule** for each rule. For a + network policy, see [Add a network rule](network.md#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](network.md#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. + +## Configure a support message + +Admins can add an optional support message that appears after the policy denial +details when a sandbox action is blocked by organization governance. Use it to +point members to an internal support channel, ticket queue, or security contact. + +To set the message: + +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 **Manage**. +1. In **Support message**, enter up to 500 characters. +1. Select **Save changes**. + +Docker shows the message only for denials caused by organization governance +policy and for requests an +[approval-required policy](network.md#approval-required-access) blocks. If you +leave it blank, Docker shows the policy denial without additional contact text. + +## Scope policies to teams + +An organization can have more than one policy, and each policy applies either +to the whole organization or to specific teams. Scoping lets you apply different +rules to different parts of the organization. + +A policy's [**Scope**](#create-a-policy) controls who it applies to. Set it to +**Organization** to apply the policy to every member, or to **Teams** to apply +it only to members of the teams you select. + +### Before you start + +Team scoping targets your organization's existing +[teams](/manuals/accounts/organization/manage/manage-a-team.md), so a team must +exist before you can scope a policy to it. Create teams and manage their members +in one of two ways: + +- Manually, in Docker Home. +- Automatically, by using + [group mapping](/manuals/security/provisioning/scim/group-mapping.md) + to synchronize your identity provider's groups with the teams in your + organization. Group mapping creates teams that don't already exist and keeps + their membership in step with your IdP groups. + +Because policies apply by team, a user's policies update automatically as their +team membership changes, including changes synced from your IdP. + +## Limits + +Organization policies have the following limits, which help ensure fair usage +and resource availability across organizations: + +| Limit | Value | +|---------------------------|-----------------------------------------------------| +| Policies per organization | 100 | +| Rules per policy | 250 | +| Policy size | 400 KB total, shared across all of a policy's rules | + +Typical policies use only a small fraction of the policy size limit. Domain +and file path values have no separate length limit beyond valid format. + +If these limits don't fit your organization's needs, +[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) +to discuss options. diff --git a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md b/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md similarity index 85% rename from content/manuals/ai/sandboxes/governance/access-controls/filesystem.md rename to content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md index 7445a10d42f4..57a17c1c13fa 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md @@ -1,21 +1,23 @@ --- title: Filesystem access policies -linkTitle: Filesystem access -weight: 40 +linkTitle: Filesystem +weight: 30 description: Control which host paths Docker Sandboxes can mount as workspaces with organization filesystem policies. keywords: docker sandboxes, filesystem access, filesystem rules, workspace mount, organization policy, governance +aliases: + - /ai/sandboxes/governance/access-controls/filesystem/ --- Filesystem access policies control which host paths a sandbox can mount as a 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 +Filesystem access is managed with [organization policies](../_index.md). When 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). +[Precedence](_index.md#precedence). ## Rule syntax @@ -34,13 +36,13 @@ Examples: Use `**` to match a directory tree recursively. A single `*` matches only one path segment. For exact path matching behavior across macOS, Linux, Windows, -and WSL, see [Filesystem rules](../concepts.md#filesystem-rules). +and WSL, see [Filesystem rules](../../reference/filesystem-rules.md). ## Organization filesystem rules Organization filesystem rules belong to policies that can apply to the whole organization or to selected teams. For setup steps and team scoping, see -[Organization policies](organization.md). +[Organization policies](../_index.md). Filesystem policy is checked when a workspace is mounted, which happens when a sandbox is created. To apply a filesystem policy change to a running workflow, diff --git a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md b/content/manuals/ai/sandboxes/governance/organization/policies/mcp.md similarity index 91% rename from content/manuals/ai/sandboxes/governance/access-controls/mcp.md rename to content/manuals/ai/sandboxes/governance/organization/policies/mcp.md index 07475cb8984d..37e7a52e23e4 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/mcp.md @@ -1,9 +1,11 @@ --- title: MCP access policies -linkTitle: MCP access -weight: 50 +linkTitle: MCP +weight: 40 description: Use Cedar-based policies to control MCP server registration and activity routed through the Docker Sandboxes MCP gateway. keywords: docker sandboxes, MCP policy, MCP access, Cedar policy, requireApproval, AI Governance +aliases: + - /ai/sandboxes/governance/access-controls/mcp/ --- MCP access policies let organization administrators control which Model @@ -11,7 +13,7 @@ Context Protocol (MCP) servers developers can register and what agents can do through Docker's MCP gateway. Use these policies to approve trusted servers, withdraw access to a server, require approval for tool calls, and restrict host-run servers. To register MCP servers and connect them to sandboxes, see -[MCP gateway](../../mcp-gateway.md). +[MCP gateway](../../../mcp-gateway.md). MCP access policies apply only to server registration and requests handled by Docker's MCP gateway. They don't govern an MCP server that an agent or MCP @@ -26,7 +28,7 @@ Unlike [network access policies](network.md) and policies written in Cedar. Docker defines the `MCP` namespace, including the actions, resource types, attributes, and approval behavior that policies can match. This page focuses on representative access patterns. For Docker's exact -policy surface, see the [MCP policy reference](../reference/mcp-policy.md). For +policy surface, see the [MCP policy reference](../../reference/mcp-policy.md). For Cedar syntax and language semantics, see the [Cedar documentation](https://docs.cedarpolicy.com/). @@ -53,7 +55,7 @@ existing server must match every name under which it was registered. Built-in gateway tools, such as `mcp-add`, `code-mode`, and OAuth authorization helpers, are also governed at use time. They are `MCP::Primordial` resources rather than tools associated with a registered server. For details, see -[Built-in gateway tools](../../mcp-gateway.md#built-in-gateway-tools). +[Built-in gateway tools](../../../mcp-gateway.md#built-in-gateway-tools). Use-time policy doesn't hide or remove existing registrations. Tool and resource listings can also include entries that policy denies when an agent @@ -220,7 +222,7 @@ when { resource in MCP::Primordial::"example-authorize" }; Local stdio servers run on the host, outside the sandbox VM. This includes explicit host commands and OCI-packaged stdio servers started with host Docker. For details about this boundary, see -[Docker Engine isolation](../../security/isolation.md#docker-engine-isolation). +[Docker Engine isolation](../../../security/isolation.md#docker-engine-isolation). In a blocklist policy that otherwise permits registration, deny the host-run server type: @@ -234,12 +236,19 @@ when { resource.type == "local-stdio" }; container, and OCI-packaged stdio servers resolved from registry or manifest metadata with `--local`. +> [!NOTE] +> To manage Model Context Protocol (MCP) server registration and requests +> through Docker's MCP gateway, use MCP access policies. These +> policies apply only to the gateway. Direct MCP connections from a sandbox +> don't use the gateway, but you can control access to remote MCP servers with +> network policy. + ## Related information -- [MCP policy concepts](../concepts.md#mcp-policies): policy model and rule +- [MCP policy concepts](../../reference/mcp-policy.md#mcp-policies): policy model and rule evaluation. -- [MCP policy reference](../reference/mcp-policy.md): exact action, resource, +- [MCP policy reference](../../reference/mcp-policy.md): exact action, resource, attribute, context, and approval behavior. -- [Organization policies](organization.md): policy creation and scope. -- [MCP policy audit logs](../audit/): policy decision +- [Organization policies](../_index.md): policy creation and scope. +- [MCP policy audit logs](../audit/_index.md): policy decision records. diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/network.md b/content/manuals/ai/sandboxes/governance/organization/policies/network.md new file mode 100644 index 000000000000..4e77d3c26a89 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/policies/network.md @@ -0,0 +1,145 @@ +--- +title: Network access policies +linkTitle: Network +weight: 20 +description: Control outbound network access from Docker Sandboxes with local and organization policy rules. +keywords: docker sandboxes, network access, network rules, governance, local policy, organization policy +aliases: + - /ai/sandboxes/governance/access-controls/network/ +--- + +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. 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: + +- [Local policy](../../local/_index.md), which applies to sandboxes on one developer machine + when organization governance is not active. +- [Organization policies](../_index.md), which apply centrally across an + organization or to selected teams. + +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](_index.md#precedence). + +## Rule syntax + +Network rules use `connect:tcp` for TCP and `connect:udp` for UDP. Resources are +hostnames, CIDR ranges, ports, or hostnames with ports. UDP requires +[experimental outbound UDP](../../local/network-rules.md#allow-outbound-udp). ICMP is blocked. + +Examples: + +- `api.example.com` +- `*.example.com` +- `**.example.com` +- `example.com:443` +- `10.0.0.0/8` + +For exact wildcard behavior and CIDR support, see +[Network rules](../../reference/network-rules.md). + +## 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 layer on top of network rules. 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](../../reference/network-rules.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 select the methods and path patterns. See + [Add a network rule](#add-a-network-rule). +- Local policies, with `--method` and `--path` on `sbx policy`. See + [HTTP method and path rules](../../local/network-rules.md#http-method-and-path-rules). + +## Add a network rule + +Each rule has an optional **Rule name**, a **Type** that decides what the rule +matches, and a **Decision** of **Allow** or **Deny**. + +- **HTTP** matches only HTTP requests with the methods and paths you specify. + - In **Destination**, enter the host or IP address the rule covers. It + matches any port unless you add one. Enter the destination with no scheme + and no path, so `api.github.com` rather than + `https://api.github.com/repos`. A local HTTP rule accepts only a host. + - Under **HTTP methods**, select the methods the rule applies to. Use + **Select all** to select every method, or **Read-only** to select `GET`, + `HEAD`, and `OPTIONS`. A rule saved with no methods selected matches every + method the composer lists. The composer doesn't list `CONNECT` or + `TRACE`, which differs from the CLI, where `--method ANY` matches every + HTTP method. + - Under **Path patterns**, add one or more paths the rule covers, such as + `/repos/*` and `/v1/**`. Leave it empty to match any path. +- **All traffic** matches every request to the destinations you list, on any + port, method, and path. + - Under **Protocols**, select **TCP**, **UDP**, or **Both**. + - 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`. + +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](../../reference/network-rules.md#http-method-and-path). + +## 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. + +Under organization governance, 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 no policy that +allows it requires 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](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@1.md), +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. + +To require approval on an organization policy, see +[Organization policies](#require-approval-for-a-network-policy). + +Network approval is separate from the MCP `@requireApproval` annotation. An MCP +approval confirms a single call within the session and creates no rule, while +an approved network destination stays allowed until you remove the rule. See +[MCP access policies](mcp.md). + +### 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](#approval-required-access). + +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. In the policy list, open the policy's action menu (⋮) and select **Edit**. +1. Turn on **Require approval before access**. +1. Select **Save**. + +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. diff --git a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md b/content/manuals/ai/sandboxes/governance/organization/sign-in-enforcement.md similarity index 97% rename from content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md rename to content/manuals/ai/sandboxes/governance/organization/sign-in-enforcement.md index 8f60dac44d98..57fa7115063c 100644 --- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md +++ b/content/manuals/ai/sandboxes/governance/organization/sign-in-enforcement.md @@ -1,11 +1,12 @@ --- title: Sign-in enforcement -linkTitle: Sign-in enforcement +linkTitle: Enforce sign in weight: 20 description: Require Docker Sandboxes users to sign in as members of your organization, enforced through endpoint management. keywords: docker sandboxes, sign-in enforcement, organization enforcement, sbx login, MDM, configuration profile, registry key, allowedOrgs aliases: - /ai/sandboxes/governance/sign-in-enforcement/ + - /ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement/ --- Sign-in enforcement restricts Docker Sandboxes to users who are members of @@ -15,7 +16,7 @@ membership after the user authenticates. If the check fails, credentials are immediately revoked and the user can't run sandboxes. Without this enforcement, a developer can sign in with a personal account and -bypass organization [governance policies](../access-controls/organization.md). +bypass organization [governance policies](_index.md). Sign-in enforcement closes that gap at the endpoint, where users can't override it. @@ -264,7 +265,7 @@ For access, contact ACME IT Security: ## Related pages -- [Organization policies](../access-controls/organization.md): centrally manage +- [Organization policies](_index.md): centrally manage sandbox network, filesystem, and MCP access controls from the Docker Admin Console - [Governance overview](../_index.md): how local and organization governance fit diff --git a/content/manuals/ai/sandboxes/governance/reference/_index.md b/content/manuals/ai/sandboxes/governance/reference/_index.md index 5358776a0a49..3a0ab0198343 100644 --- a/content/manuals/ai/sandboxes/governance/reference/_index.md +++ b/content/manuals/ai/sandboxes/governance/reference/_index.md @@ -1,14 +1,14 @@ --- title: Reference -weight: 50 +weight: 30 description: Reference material for Docker AI Governance policy APIs and policy syntax. keywords: docker sandboxes, governance reference, governance API, policy reference --- Use reference material when you need API details or exact policy syntax. -- [Policy concepts](../concepts.md): resource model, rule syntax, policy - evaluation, and precedence. +- [Network and HTTP rule syntax](network-rules.md) and + [Filesystem mount rule syntax](filesystem-rules.md): rule syntax. - [AI Governance API](/reference/api/ai-governance/): HTTP API reference for network and filesystem organization policies. - [MCP policy reference](mcp-policy.md): Docker MCP policy actions, resources, diff --git a/content/manuals/ai/sandboxes/governance/reference/api.md b/content/manuals/ai/sandboxes/governance/reference/api.md index 36e6297f165b..18a83c5ad935 100644 --- a/content/manuals/ai/sandboxes/governance/reference/api.md +++ b/content/manuals/ai/sandboxes/governance/reference/api.md @@ -1,11 +1,13 @@ --- title: AI Governance API linkTitle: API reference +weight: 50 description: Programmatic management of Docker AI Governance policies and rules via HTTP+JSON. keywords: docker sandboxes, AI Governance API, governance API, policy API, organization policies -weight: 10 build: render: never sidebar: goto: /reference/api/ai-governance/ --- + + diff --git a/content/manuals/ai/sandboxes/governance/audit/record-reference.md b/content/manuals/ai/sandboxes/governance/reference/audit-records.md similarity index 89% rename from content/manuals/ai/sandboxes/governance/audit/record-reference.md rename to content/manuals/ai/sandboxes/governance/reference/audit-records.md index ce547f4e7eef..d8e80272aa44 100644 --- a/content/manuals/ai/sandboxes/governance/audit/record-reference.md +++ b/content/manuals/ai/sandboxes/governance/reference/audit-records.md @@ -1,9 +1,11 @@ --- title: Audit record reference -linkTitle: Record reference -weight: 50 +linkTitle: Audit records +weight: 40 description: Reference fields, categories, decisions, and payload types for Docker AI Governance audit records. keywords: docker sandboxes, audit record, audit schema, AI Governance, policy decision, action_type, jsonl +aliases: + - /ai/sandboxes/governance/audit/record-reference/ --- Docker AI Governance audit records use one schema across delivery modes. Local @@ -81,7 +83,7 @@ full approval. The approval applies to later requests from the sandbox. It doesn't retry the request that was blocked. If the user dismisses the request, it isn't resolved, so no second record is written and the destination is requested again the next time the sandbox reaches it. For how approval works, -see [Approval-required access](../access-controls/network.md#approval-required-access). +see [Approval-required access](../organization/policies/network.md#approval-required-access). For MCP approvals, an approved request is evaluated again and recorded with `AUDIT_DECISION_APPROVAL_ALLOW`, and a declined request is recorded with @@ -140,6 +142,47 @@ separate from the `network_egress` record for the connection. | `http_request.port` | Destination port. | | `http_request.path` | URL path, without the query string or fragment. | +## What gets recorded + +The daemon writes two categories of local record: + +- Evaluation records capture each policy decision: the resource, the action, + the verdict, and the reason for a denial. +- Session lifecycle records mark the start and end of each daemon run. + Evaluation records share the run's `audit_session_id`, so you can correlate + every decision back to a daemon session. + +Records contain metadata only. They don't contain prompt content, agent output, +or parameter values. + +A network evaluation record looks like this: + +```json +{ + "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80", + "timestamp": "2026-05-28T19:15:00.728933Z", + "schema_version": "1.82.0", + "category": "AUDIT_CATEGORY_EVALUATION", + "decision": "AUDIT_DECISION_DENY", + "username": "jordandoe", + "user_email": "jordandoe@example.com", + "org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", + "org_name": "Acme Inc", + "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", + "resource_id": "example.com:443", + "os": "macos", + "app_version": "v0.31.0", + "client_name": "sbx", + "hostname": "host-machine", + "deny_reason": [ + "no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com:443)" + ], + "action_type": "network_egress", + "network_egress": { "protocol": "tcp" }, + "agent": "claude" +} +``` + ## Sample record ```json diff --git a/content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md b/content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md new file mode 100644 index 000000000000..c670125800da --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md @@ -0,0 +1,47 @@ +--- +title: Filesystem mount rule syntax +weight: 20 +description: Syntax for sandbox filesystem rules, including path patterns across macOS, Linux, Windows, and WSL. +keywords: docker sandboxes, filesystem rules, path patterns, workspace mount, rule syntax +--- + +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 +only `~`: it does not expand environment variables, so a pattern such as +`%USERPROFILE%\**` or `$HOME/**` matches nothing. + +For a path outside the home directory, write it in the format the user's +operating system uses. A rule matches only the format it's written in, so a +location that several platforms share needs a rule for each: + +| Operating system | Example path | +| ---------------- | ------------------------------------------ | +| macOS, Linux | `/data/project/**` | +| Windows | `C:\data\project\**` | +| WSL | `\\wsl.localhost\\data\project\**` | + +On Windows, `*:` matches any drive letter, so `*:\data\**` matches the path on +any drive. + +Wildcards behave the same way in every path format: + +| Pattern | Example | Matches | +| ------------------ | ---------- | ---------------------------------------------------------- | +| Exact path | `/data` | `/data` only | +| Segment wildcard | `/data/*` | `/data/project`, one path segment only, not subdirectories | +| Recursive wildcard | `/data/**` | `/data/project`, `/data/project/src`, any depth | + +Use `**` to match a directory tree recursively. A single `*` matches within one +path segment and won't cross a path separator. For example, `~/**` matches all +paths under the home directory, while `~/*` matches only its direct children. + +For organization policy configuration and enforcement details, see +[Filesystem access policies](../organization/policies/filesystem.md). diff --git a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md index 2080e85a23ca..b68f5a2ed4a8 100644 --- a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md +++ b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md @@ -1,7 +1,7 @@ --- title: MCP policy reference linkTitle: MCP policy -weight: 20 +weight: 30 description: Reference for Docker MCP policy actions, resources, attributes, context fields, and approval behavior. keywords: docker sandboxes, MCP policy, Cedar policy, MCP actions, MCP resources, requireApproval, AI Governance --- @@ -11,10 +11,30 @@ namespace. This reference defines the Docker-specific policy surface for Model Context Protocol (MCP) activity made available to sandboxes through Docker's [MCP gateway](../../mcp-gateway.md). -Use this reference with [MCP access policies](../access-controls/mcp.md) for +Use this reference with [MCP access policies](../organization/policies/mcp.md) for common policy patterns. For the Cedar language, see the [Cedar documentation](https://docs.cedarpolicy.com/). +## MCP policies + +MCP policies control Model Context Protocol activity made available to a +sandbox through Docker's [MCP gateway](../../mcp-gateway.md). They are +organization policies written in Cedar using the `MCP` namespace, rather than +the network and filesystem rule format. + +MCP policy applies when a developer registers a server and when an agent uses +the MCP gateway. Registration rules control future `sbx mcp add` operations. +Use-time rules control tool calls, gateway meta-tools, resource reads, and +prompt retrieval from servers that are already registered or loaded. + +Governed MCP activity is default deny: a request is blocked unless a matching +`permit` allows it. A matching `forbid` overrides any `permit`, including a +permit that requires approval. Policy scope supplies the principal, so use +organization or team scope instead of matching users, teams, tenants, or roles +in Cedar. + +For representative policies, see [MCP access policies](../organization/policies/mcp.md). + ## Evaluation model Cedar evaluates MCP requests against a principal, action, resource, and context. @@ -28,7 +48,7 @@ Governed MCP activity is default deny. A request is blocked unless a matching permit annotated with `@requireApproval`. For details about when Docker Sandboxes evaluates MCP policies for a user, see -[Govern the server lifecycle](../access-controls/mcp.md#govern-the-server-lifecycle). +[Govern the server lifecycle](../organization/policies/mcp.md#govern-the-server-lifecycle). An actionless `permit` matches every MCP action that reaches Cedar evaluation: @@ -165,7 +185,7 @@ over a normal `permit`. A matching `forbid` denies the request without an elicitation. For the request flow and trust model, see -[Require confirmation with MCP elicitation](../access-controls/mcp.md#require-confirmation-with-mcp-elicitation). +[Require confirmation with MCP elicitation](../organization/policies/mcp.md#require-confirmation-with-mcp-elicitation). Approval requires a client session that can present an MCP elicitation request to the user. If the request can't be presented for approval, the request is diff --git a/content/manuals/ai/sandboxes/governance/reference/network-rules.md b/content/manuals/ai/sandboxes/governance/reference/network-rules.md new file mode 100644 index 000000000000..338f00d24fae --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/reference/network-rules.md @@ -0,0 +1,92 @@ +--- +title: Network and HTTP rule syntax +weight: 10 +description: Syntax for sandbox network rules, including domain patterns, CIDR ranges, ports, and HTTP method and path rules. +keywords: docker sandboxes, network rules, rule syntax, wildcards, CIDR, HTTP rules, method and path +--- + +Network rules use `connect:tcp` for TCP and `connect:udp` for UDP. Resources are +hostnames, CIDR ranges, or ports. UDP requires +[experimental outbound UDP](../local/network-rules.md#allow-outbound-udp). +ICMP is blocked. + +**Hostname patterns** + +| Pattern | Example | Matches | +| --------------------- | ----------------- | ------------------------------------------------------------- | +| Exact hostname | `example.com` | `example.com` on any port, not subdomains | +| Single-level wildcard | `*.example.com` | One subdomain level, any port: `api.example.com` | +| Multi-level wildcard | `**.example.com` | Any depth, any port: `api.example.com`, `v2.api.example.com` | +| Hostname with port | `example.com:443` | `example.com` on port 443 only | + +`example.com` and `*.example.com` don't cover each other. Specify both if you +need to match the root domain and its subdomains. + +**CIDR ranges** + +Both IPv4 and IPv6 notation are supported: `10.0.0.0/8`, `192.168.1.0/24`, +`2001:db8::/32`. + +## HTTP method and path + +A network rule matches a destination host on its own. An HTTP rule is a network +rule that also names an HTTP method and URL path, so a policy can allow reads +from an API without allowing writes to it. + +An HTTP rule names one or more methods, a destination, and path patterns. What +each part accepts depends on where you configure the rule: + +| Part | Organization policy | Local policy | +| ----------- | ------------------------------------------ | --------------------------------- | +| Method | One or more listed methods | `ANY`, or one or more methods | +| Destination | A host or IP address | A host | +| Path | One or more absolute path patterns | One absolute path pattern | + +A destination can include a port, and a path pattern looks like `/api/**`. + +A local rule doesn't accept an IP address or a CIDR range. Use a plain network +rule for those destinations. To cover a second path in a local policy, add a +second rule. + +Every rule applies to at least one method. On the CLI, `--method ANY` covers +every HTTP method. In the composer, a rule with no methods selected covers +every method the composer lists. For the methods you can select individually, see +[Add a network rule](../organization/policies/network.md#add-a-network-rule) for an +organization policy and +[HTTP method and path rules](../local/network-rules.md#http-method-and-path-rules) +for a local one. + +Path patterns follow the same wildcard rules as filesystem paths, where `*` +matches within one path segment and `**` matches any depth. A pattern without a +wildcard matches that path exactly, so `/repos` matches `/repos` and nothing +below it. Every pattern must start with `/` and can't contain a query string, a +fragment, or a `..` segment. A local rule's path must also be canonical, so it +can't contain percent-encoding, control characters, repeated or trailing +slashes, or a `.` segment. For the full list, see +[HTTP method and path rules](../local/network-rules.md#http-method-and-path-rules). + +HTTP requests are evaluated against both layers. A network rule sets the +baseline for a host, and HTTP rules adjust individual methods and paths within +it: + +| Rules that cover the host | Result for an HTTP request | +| --------------------------- | ----------------------------------------------------------------------- | +| Network allow only | Allowed at any method and path | +| HTTP allow only | Allowed only where a rule matches the method and path. Anything else is denied | +| Network allow and HTTP deny | The denied methods and paths are blocked. The rest stay allowed | +| Network deny | Blocked. An HTTP allow can't reopen a denied host | + +A network deny is therefore a floor that HTTP rules can't raise, while a +network allow is a ceiling that HTTP rules can carve into. + +When a rule requires a method and path decision, the sandbox HTTP proxy +evaluates each request separately instead of deciding once per connection. + +Those requests have to go through the proxy. A connection it can't inspect, +such as one it handles transparently, is blocked rather than evaluated. +Traffic that isn't HTTP, such as SSH, carries no method or path, so HTTP rules +never match it. Control those destinations with network rules. + +For local and organization policy configuration, see +[Manage local network rules](../local/network-rules.md) and +[Network access policies](../organization/policies/network.md). diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index 12cee969dc3e..e168c527214a 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -596,6 +596,6 @@ token, use `sbx mcp auth rm`. ## Governance Organizations with AI Governance can use -[MCP access policies](governance/access-controls/mcp.md) to control MCP server +[MCP access policies](governance/organization/policies/mcp.md) to control MCP server registration, tool calls, gateway meta-tools, resources, prompts, and approval requirements. MCP access policies are organization policies written in Cedar. diff --git a/content/manuals/ai/sandboxes/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index 463ceda6b988..2b5e1e125157 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -52,7 +52,7 @@ Outside the workspace and shared skills store, the agent cannot access your host filesystem. It also cannot access your host Docker daemon, your host network directly, or any destination not allowed by network policy. Sandboxes cannot communicate directly over the network. Outbound UDP is blocked unless -you turn on the [experimental UDP feature](../governance/access-controls/local.md#allow-outbound-udp) +you turn on the [experimental UDP feature](../governance/local/network-rules.md#allow-outbound-udp) and allow it through network policy. ICMP is blocked. MCP servers are an explicit integration point. Remote MCP servers run outside diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index 80cde27a73f4..6ef1a0c01bf9 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -15,7 +15,7 @@ following security posture. All outbound TCP traffic, including HTTP, HTTPS, and SSH, is blocked unless an explicit rule allows the destination. Outbound UDP is disabled by default. To -use it, turn on the [experimental UDP feature](../governance/access-controls/local.md#allow-outbound-udp) +use it, turn on the [experimental UDP feature](../governance/local/network-rules.md#allow-outbound-udp) and add UDP allow rules. ICMP is blocked. DNS queries use the sandbox's internal resolver, which enforces network policy. @@ -23,7 +23,7 @@ Run `sbx policy ls` to see the active network rules for your installation. Rules can be customized per machine with the `sbx policy` CLI, or managed centrally across your organization. Org-level rules take precedence over local rules. See -[Network access policies](../governance/access-controls/network.md). +[Network access policies](../governance/_index.md). ## Workspace defaults diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index 07070347a9ae..e43346a17318 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -48,13 +48,13 @@ running on the host through a policy-controlled connection, see [Accessing host services from a sandbox](../workflows/development.md#accessing-host-services-from-a-sandbox). All outbound TCP traffic passes through a proxy on your host that enforces the -[network access policy](../governance/access-controls/network.md). The sandbox +[network access policy](../governance/_index.md). The sandbox routes traffic through either a forward proxy or a transparent proxy depending on the client's configuration. Both enforce the network policy. Only the forward proxy [injects credentials](../configuration/credentials.md) for AI services. Outbound UDP is disabled by default. When you turn on -[experimental UDP egress](../governance/access-controls/local.md#allow-outbound-udp), +[experimental UDP egress](../governance/local/network-rules.md#allow-outbound-udp), network policy controls its destinations. ICMP is blocked. DNS queries use the sandbox's internal resolver, which enforces network policy. TCP connections are allowed only when a policy rule matches the destination. diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index 2b84b98f5c57..ed94660b11fd 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -110,7 +110,7 @@ $ sbx run docker.io/sbx/droid-kit:latest ## Agent can't install packages or reach an API -Sandboxes use [network access rules](governance/access-controls/network.md) to +Sandboxes use [network access rules](governance/local/network-rules.md) to control outbound traffic. If the agent fails to install packages or call an external API, the target domain is likely not in the allow list. Check which requests are being blocked: @@ -133,7 +133,7 @@ $ sbx policy allow network "**" If `sbx policy allow` doesn't unblock the request, your organization may manage sandbox policies centrally and take precedence over local rules. See -[Organization policies](governance/access-controls/organization.md). +[Organization policies](governance/organization/_index.md). ## Kit fails to install: source not in allowlist @@ -174,7 +174,7 @@ can't be recovered. Use an address-based rule in that case: $ sbx policy allow network "10.1.2.3:22" ``` -UDP requires [experimental UDP egress](governance/access-controls/local.md#allow-outbound-udp) +UDP requires [experimental UDP egress](governance/local/network-rules.md#allow-outbound-udp) and UDP allow rules. ICMP is blocked and can't be unblocked with policy rules. For Git operations over SSH, you can either add an allow rule for the Git @@ -212,7 +212,7 @@ If credentials are configured correctly but API calls still fail, check the `transparent` proxy don't get credential injection. This can happen when a client inside the sandbox (such as a process in a Docker container) isn't configured to use the forward proxy. See -[Monitoring network activity](governance/monitor-and-enforce/monitoring.md) +[Monitoring network activity](governance/local/test-monitor.md#monitoring-traffic) for details. ## MCP server streams stall diff --git a/content/manuals/ai/sandboxes/workflows/automation.md b/content/manuals/ai/sandboxes/workflows/automation.md index 78567684a2d1..ee4d27dee5ad 100644 --- a/content/manuals/ai/sandboxes/workflows/automation.md +++ b/content/manuals/ai/sandboxes/workflows/automation.md @@ -124,7 +124,7 @@ parsers for these commands: | `sbx ls` | A sandbox array, replacing `{sandboxes: [...]}`. `created_at` and `last_used_at` use RFC 3339 timestamps. Rows include `detached`. | | `sbx template ls` | An image array, replacing `{images: [...]}`. | | Local `sbx mcp ls` | A server array, replacing `{gateway: {...}, servers: [...]}`. Each row includes `gateway`. Cloud rows describe server usage across sandboxes and differ from local registration rows. | -| `sbx policy log` | `{updated_at, allowed: [...], blocked: [...]}` for local and cloud output. See [Monitoring traffic](/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md#monitoring-traffic). | +| `sbx policy log` | `{updated_at, allowed: [...], blocked: [...]}` for local and cloud output. See [Monitoring traffic](/manuals/ai/sandboxes/governance/local/test-monitor.md#monitoring-traffic). | | `sbx --cloud policy ls` | Field names use `snake_case` instead of camelCase. | | `sbx ports` | Local rows contain `host_ip`, `host_port`, `sandbox_port`, and `protocol`. Cloud rows contain `sandbox_port` and `url`, replacing `port`. Local publish and unpublish results include `action: published` or `action: unpublished`. | | Cloud `sbx volume create`, `sbx volume ls`, `sbx volume inspect` | Fields such as `ID`, `Name`, and `CreatedAt` become `id`, `name`, and `created_at`. `volume inspect` defaults to human-readable details, so request a structured format explicitly. | diff --git a/content/manuals/subscription-billing/plans/ai-governance.md b/content/manuals/subscription-billing/plans/ai-governance.md index 4920eff82989..3221f491e6ed 100644 --- a/content/manuals/subscription-billing/plans/ai-governance.md +++ b/content/manuals/subscription-billing/plans/ai-governance.md @@ -21,7 +21,7 @@ aliases: ## Usage -AI Governance lets organization owners enforce [organization policies](/manuals/ai/sandboxes/governance/access-controls/organization.md) for license-holding members. Organization policies override a license-holding member's local policies. +AI Governance lets organization owners enforce [organization policies](/manuals/ai/sandboxes/governance/organization/_index.md) for license-holding members. Organization policies override a license-holding member's local policies. You can [assign AI Governance licenses](/manuals/accounts/organization/manage/manage-licenses.md) to a team or to an individual organization member, even if they don't occupy a Docker Team or Docker Business seat. For best practice, review available licenses as you add new members since members without an AI Governance license can still use Docker AI products. diff --git a/data/redirects.yml b/data/redirects.yml index 3af405cce2a4..180053612990 100644 --- a/data/redirects.yml +++ b/data/redirects.yml @@ -376,7 +376,7 @@ # Links in Desktop # Docker Sandboxes -"/ai/sandboxes/governance/access-controls/mcp/": +"/ai/sandboxes/governance/organization/policies/mcp/": - /go/mcp-policy/ "/ai/sandboxes/mcp-gateway/": - /go/sbx-mcp-gateway/ From 863d2e38760f788cd5b07ad8e3e4dc48d5b51a20 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Tue, 20 Oct 2026 14:31:20 -0700 Subject: [PATCH 2/3] feedback Signed-off-by: Craig Osterhout --- content/manuals/agentic-platform/policies.md | 7 +- .../manuals/ai/sandboxes/governance/_index.md | 79 +++++++------- .../ai/sandboxes/governance/local/_index.md | 34 +++--- .../sandboxes/governance/local/get-started.md | 13 ++- .../ai/sandboxes/governance/local/inspect.md | 20 ++-- .../governance/organization/_index.md | 19 ++-- .../governance/organization/audit/_index.md | 15 +-- .../organization/policies/_index.md | 88 ++++----------- .../organization/policies/create-manage.md | 9 +- .../organization/policies/filesystem.md | 54 ++++------ .../governance/organization/policies/mcp.md | 30 ++++-- .../organization/policies/network.md | 100 ++++++------------ .../organization/sign-in-enforcement.md | 5 +- .../sandboxes/governance/reference/_index.md | 2 +- .../governance/reference/audit-records.md | 64 ++++------- .../governance/reference/filesystem-rules.md | 5 +- .../governance/reference/mcp-policy.md | 26 +---- .../governance/reference/network-rules.md | 69 ++++++------ 18 files changed, 257 insertions(+), 382 deletions(-) diff --git a/content/manuals/agentic-platform/policies.md b/content/manuals/agentic-platform/policies.md index 065f28c33640..b98b11b15564 100644 --- a/content/manuals/agentic-platform/policies.md +++ b/content/manuals/agentic-platform/policies.md @@ -49,8 +49,11 @@ removed, and review the allow rules in the remaining policies and kit. If the combined allow list contains any rules, destinations outside that list are blocked. This default behavior isn't an explicit deny rule: adding an allow rule in another policy permits the matching destinations. If the -combined allow list is empty or absent, the sandbox can reach any destination -except those blocked by deny rules. +combined allow list is empty or absent, your account's default network mode +applies. The default is deny all, so the sandbox can't reach any destination +until an allow rule permits it. Accounts created before deny all became the +default have an explicit allow all default instead, so their sandboxes can +reach any destination except those blocked by deny rules. ## Policy rules diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index 0fc612952e18..f7544ab474e1 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -8,37 +8,43 @@ aliases: - /ai/sandboxes/governance/monitor-and-enforce/ --- -The governance described here applies to local sandboxes. Cloud sandboxes -use separate network policy configuration. See -[Cloud network policy](../cloud/network-policy.md) for cloud controls. +Sandbox governance 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 has two parts: -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: +- **Local policy** is the policy you set on your machine with the `sbx policy` + CLI. It lets individual developers customize which domains their sandboxes + can reach. See [Local policy](local/_index.md). +- **Organization governance** is policy, sign-in enforcement, and audit logs + that administrators set for organization members, either organization-wide + or for selected teams. Organization policy is configured centrally in Docker + Home. Network, filesystem, and MCP policies can also be managed through the + [Governance API](/reference/api/ai-governance/). See + [Organization governance](organization/_index.md). -**Local policy** is configured per machine using the `sbx policy` CLI. It -lets individual developers customize which domains their sandboxes can reach. -See [Local policy](local/_index.md). +Both apply to local sandboxes. Cloud sandboxes use separate network policies. +See [Cloud network policy](../cloud/network-policy.md) and Docker Agentic +Platform [network policies](/manuals/agentic-platform/policies.md). -**Organization policy** is configured centrally in Docker Home. Network and -filesystem policies can also be managed via the -[Governance API](/reference/api/ai-governance/). Controls defined at the org -level apply uniformly across every local sandbox in the organization. Organization -governance can also include MCP policies for sandbox MCP activity. When -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](organization/_index.md). +Organization policies apply to members who hold an AI Governance license. +Developer machines must run sbx 0.35.0 or later to enforce HTTP method and +path rules. -Alongside this access-control policy, admins can require developers to sign in -as members of their organization before using sandboxes at all. +When an organization policy is enforced for you, access is default deny: a +request that no organization allow rule matches is blocked, and a matching deny +rule takes precedence over any allow rule. Governed MCP activity is default +deny in the same way. Without organization governance, a request that no rule +matches is handled according to your local preset. See +[Local policy](local/_index.md). + +Administrators can also require developers to sign in as members of their +organization before using sandboxes at all. [Sign-in enforcement](organization/sign-in-enforcement.md) is deployed through endpoint management and ensures developers can't bypass organization policy by using a personal account. > [!NOTE] -> Organization governance is available on a separate paid subscription. +> Organization governance requires a Docker AI Governance subscription. > [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) > to request access. @@ -52,14 +58,14 @@ Policies exist at two levels: - **Local**: configured per machine using the `sbx policy` CLI. Applies to sandboxes on that machine only. -- **Organization**: configured in Docker Home. Network and filesystem policies - can also be managed via the - [Governance API](/reference/api/ai-governance/). Applies to sandboxes across - the organization. An organization can have several policies, each applying - either org-wide or to specific teams. See [Policy scope](organization/policies/_index.md#policy-scope). +- **Organization**: configured in Docker Home or through the + [Governance API](/reference/api/ai-governance/). Applies to licensed members + of the organization. An organization can have several policies, each applying + either org-wide or to specific teams. See + [Policy scope](organization/policies/_index.md#policy-scope). -When organization governance is active, only organization allow rules can grant -access. Local and kit-defined deny rules still apply on top. See +When an organization policy is enforced for you, only organization allow rules +can grant access. Local and kit-defined deny rules still apply on top. See [Precedence](organization/policies/_index.md#precedence). A **rule** is the unit of access control within a policy. Each rule has: @@ -69,15 +75,6 @@ A **rule** is the unit of access control within a policy. Each rule has: - **Resources**: the targets the rule matches against - **Decision**: `allow` or `deny` -Rules are grouped by domain. Network and filesystem rules in a policy must -share the same domain, either `network` or `filesystem`. MCP policies use Cedar -statements written in the `MCP` namespace instead of the network and filesystem -rule format. - -An organization network policy can also require approval, which turns every -allow in that policy into a request the developer must confirm before access is -granted. Approval is set on the policy rather than on individual rules, so it -applies to all of the policy's allow rules at once. Without organization -governance, a request with no matching allow or deny rule also asks for -approval. See -[Approval-required access](organization/policies/network.md#approval-required-access). +Each policy covers one kind of access: network or filesystem. MCP policies use +Cedar statements written in the `MCP` namespace instead of the network and +filesystem rule format. diff --git a/content/manuals/ai/sandboxes/governance/local/_index.md b/content/manuals/ai/sandboxes/governance/local/_index.md index 99e8649a2df4..21fb7318e7a2 100644 --- a/content/manuals/ai/sandboxes/governance/local/_index.md +++ b/content/manuals/ai/sandboxes/governance/local/_index.md @@ -13,21 +13,14 @@ 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 interacts with organization governance as follows: +When an organization policy is enforced for you, your local allow rules stop +applying and your local deny rules still apply. See +[Precedence](../organization/policies/_index.md#precedence). To list the rules +that stopped applying, run `sbx policy ls --include-inactive`. See +[Showing inactive rules](inspect.md#showing-inactive-rules). -- **No org governance**: the local policy controls what sandboxes can access. -- **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](inspect.md#showing-inactive-rules). - -See [Organization policies](../organization/_index.md) for how organization governance -works. - -For domain patterns, wildcards, CIDR ranges, and filesystem path syntax, see -[Policy concepts](../reference/network-rules.md). +For domain patterns, wildcards, and CIDR ranges, see +[Network and HTTP rule syntax](../reference/network-rules.md). Outbound TCP traffic passes through a proxy on your host, which enforces access rules on every connection. Non-HTTP TCP traffic, including SSH, can be allowed @@ -35,11 +28,8 @@ with a hostname rule (for example, `sbx policy allow network "myhost:22"`) or an address-based rule. UDP requires the experimental feature and policy rules described in [Allow outbound UDP](network-rules.md#allow-outbound-udp). ICMP is blocked. -Under **Balanced** and **Locked Down**, a sandbox request that no rule matches -is blocked and asks for your approval instead of being denied outright, so you -can open access to each destination as a sandbox needs it. See -[Approval-required access](approvals.md). - -Without organization governance, a request with no matching allow or deny rule -also asks for approval rather than being denied outright, so access opens up as -the developer approves each destination. +Without organization governance, how a request that no rule matches is handled +depends on your preset. Under **Open**, every destination is allowed. Under **Balanced** and **Locked Down**, +the request is blocked and asks for your approval instead of being denied +outright, so you can open access to each destination as a sandbox needs it. See +[Respond to approval requests](approvals.md). diff --git a/content/manuals/ai/sandboxes/governance/local/get-started.md b/content/manuals/ai/sandboxes/governance/local/get-started.md index 75b289d34a48..412ffa61245e 100644 --- a/content/manuals/ai/sandboxes/governance/local/get-started.md +++ b/content/manuals/ai/sandboxes/governance/local/get-started.md @@ -55,9 +55,9 @@ The **Balanced** preset's baseline allowlist is a good starting point for most workflows. Run `sbx policy ls` to see exactly which rules it includes. > [!NOTE] -> If your organization manages sandbox policies centrally, organization rules -> take precedence over the preset you select here. See -> [Organization policies](../organization/_index.md). +> If an organization policy is enforced for you, organization rules take +> precedence over the preset you select here. See +> [Precedence](../organization/policies/_index.md#precedence). ### Non-interactive environments @@ -87,3 +87,10 @@ choose a new preset. Running sandboxes stop when the daemon shuts down. Pass ```console $ sbx policy reset --force ``` + +> [!WARNING] +> `sbx policy reset` deletes all locally configured policy rules, including any +> destinations you approved. Those destinations are requested again the next +> time a sandbox reaches them. To pick up organization policy changes without +> deleting local rules, use `sbx policy refresh` instead. See +> [Policy changes not taking effect](../organization/policies/_index.md#policy-changes-not-taking-effect). diff --git a/content/manuals/ai/sandboxes/governance/local/inspect.md b/content/manuals/ai/sandboxes/governance/local/inspect.md index 228c77605111..7708761d29ec 100644 --- a/content/manuals/ai/sandboxes/governance/local/inspect.md +++ b/content/manuals/ai/sandboxes/governance/local/inspect.md @@ -85,13 +85,11 @@ default network org all network: 38 allow, 4 deny ``` `Governance` shows which organization manages the policy, and `Sync` confirms -the daemon has pulled the latest rules. `Hidden` reports how many inactive rules -are suppressed and how to reveal them. - -If the sync state shows an error or a stale timestamp, run `sbx policy refresh` -to fetch and apply the latest policy without restarting the daemon or stopping -sandboxes. The policy applies to new connections. To close existing connections -that the updated policy denies, restart the sandbox. +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 refresh` to fetch and apply it right away. The command requires +sbx 0.49.0 or later. `Hidden` reports how many inactive +rules are suppressed and how to reveal them. If Docker can't determine which organization governs your account, policy output shows `Governance: Unresolved`, and the dashboard shows the same @@ -214,10 +212,10 @@ 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. -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. +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. See +[Precedence](../organization/policies/_index.md#precedence). ### A domain is still blocked after adding an allow rule diff --git a/content/manuals/ai/sandboxes/governance/organization/_index.md b/content/manuals/ai/sandboxes/governance/organization/_index.md index 2281bff481d6..7eee03d421ab 100644 --- a/content/manuals/ai/sandboxes/governance/organization/_index.md +++ b/content/manuals/ai/sandboxes/governance/organization/_index.md @@ -9,17 +9,15 @@ aliases: - /ai/sandboxes/governance/access-controls/organization/ --- -[Local policies](../local/_index.md) give individual developers control over what their -sandboxes can access. Organization policy moves that control to the admin level: -organization policies apply to local sandboxes across the organization, either to -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. +Organization governance is policy, sign-in enforcement, and audit logs that +administrators set for organization members, either organization-wide or for +selected teams. Organization policies apply to the local sandboxes of members +who hold an AI Governance license. When an organization policy is enforced for +a member, it takes precedence over their [local policy](../local/_index.md). +See [Precedence](policies/_index.md#precedence). Admins can manage organization policies through the Docker Home UI. For -programmatic management of network and filesystem policies, use the +programmatic management of network, filesystem, and MCP policies, use the [Governance API](/reference/api/ai-governance/). By default, only organization @@ -30,7 +28,6 @@ manage policies, create a with the **Governance** permissions and assign it to a user or team. > [!NOTE] -> Sandbox organization governance is available on a separate paid -> subscription. +> Organization governance requires a Docker AI Governance subscription. > [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) > to request access. diff --git a/content/manuals/ai/sandboxes/governance/organization/audit/_index.md b/content/manuals/ai/sandboxes/governance/organization/audit/_index.md index 223441c37057..0c61cea34437 100644 --- a/content/manuals/ai/sandboxes/governance/organization/audit/_index.md +++ b/content/manuals/ai/sandboxes/governance/organization/audit/_index.md @@ -76,17 +76,10 @@ available start with cloud delivery off until an owner opts in from ### Where records are stored -The sandbox daemon writes local audit records as JSON Lines (`.jsonl`) files. -Local audit logs stay on the host that produced them and can be collected by -your own log shipper. Local delivery is independent of -[cloud delivery](configure.md), so you can use local files with cloud delivery -on or off. - -The sandbox daemon writes local audit records only for signed-in users who have -an AI Governance license and are governed by an enforced centralized -[organization policy](../_index.md). Docker Sandboxes -users without both do not send audit data to audit logs. To confirm governance -is active, run `sbx policy ls`. The output includes a `Governance: Managed by +Local audit files stay on the host that produced them. Local delivery is +independent of [cloud delivery](configure.md), so you can use local files with +cloud delivery on or off. To confirm that a machine is governed and writes +records, run `sbx policy ls`. The output includes a `Governance: Managed by ` line when an organization policy is in effect. The daemon writes audit records, not the CLI. Running a command such as diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/_index.md b/content/manuals/ai/sandboxes/governance/organization/policies/_index.md index 4829d9f25737..5cae3dbeb8d6 100644 --- a/content/manuals/ai/sandboxes/governance/organization/policies/_index.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/_index.md @@ -25,20 +25,12 @@ apply to a given user are their _effective policies_: every org-wide policy, plus every team-scoped policy for a team they belong to. See [Rule evaluation](#rule-evaluation) for how a user's effective policies combine. -## How scoped policies combine - -A user is governed by all of their -[effective policies](#policy-scope): every org-wide policy, plus -the team-scoped policies for the teams they belong to. Use org-wide policies -for guardrails that must apply everywhere, and team-scoped policies for access -that only some teams need. - -For precedence between local and organization policies, and for how allow and -deny rules combine, see [Precedence](#precedence). +Use org-wide policies for guardrails that must apply everywhere, and +team-scoped policies for access that only some teams need. ## Rule evaluation -When organization governance is active, the rules from all of a user's +When an organization policy is enforced for you, the rules from all of your [effective policies](#policy-scope) are combined and evaluated together against each request, following two principles: @@ -55,9 +47,6 @@ 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 and kit-defined allow rules take no part in this evaluation. Deny rules -from those sources do still apply. See [Precedence](#precedence). - A request that an approval-required policy allows produces a third outcome. Rather than being allowed outright, it's held back until the developer confirms the destination, and the confirmation governs later requests to it. This holds @@ -65,13 +54,13 @@ even when another policy allows the same request without requiring approval. A matching deny still wins, so a denied destination is blocked without asking. See [Approval-required access](network.md#approval-required-access). -## Precedence +### Precedence -What applies depends on whether your organization has governance enabled: +What applies depends on whether an organization policy is enforced for you: -- No organization governance: local rules and any kit-defined network rules +- No organization policy: local rules and any kit-defined network rules determine what sandboxes can access. -- Organization governance active: organization policy determines what access can +- Organization policy enforced: 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 @@ -95,7 +84,7 @@ Precedence is decided by a rule's decision rather than its source: 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](../../local/inspect.md#showing-inactive-rules) for how +[Showing inactive rules](../../local/inspect.md#showing-inactive-rules) for how to list them. A local deny takes precedence over an organization approval requirement as @@ -105,56 +94,21 @@ rules being inactive, because they record an answer to the organization's own approval requirement rather than granting new access. See [Approval-required access](network.md#approval-required-access). -When organization governance is active, a user's organization policies are -evaluated together, as described in [Rule evaluation](#rule-evaluation). - ## Troubleshooting ### Policy changes not taking effect After updating organization policies, changes take up to 5 minutes to -propagate to developer machines. To apply changes immediately, users can run -`sbx policy reset`, which stops the daemon and forces it to pull the latest -organization policies on the next `sbx` command. - -> [!WARNING] -> `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 - -Policy types differ in when a change takes effect after it reaches the -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. 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 - filesystem policy has no effect on that sandbox. The sandbox continues to - access the previously allowed path until it is removed and a new one is - created. - -- MCP registration policy is evaluated when a server is registered with - `sbx mcp add`. Changing registration rules doesn't remove existing - registrations or stop an already-loaded server by itself. - -- MCP use-time policy is evaluated by the MCP gateway when a sandbox makes a - governed MCP request, such as a tool call, resource read, prompt retrieval, - or built-in gateway tool call. Once a policy change has synced, use-time - rules apply to subsequent governed MCP requests through the gateway. - -To apply a filesystem policy change immediately, remove the running sandbox -and create a new one. To prevent use of an MCP server that is already registered -or loaded, add use-time rules for the registered server name. For examples, see -[Withdraw server access](mcp.md#withdraw-server-access). +propagate to developer machines. To apply them right away on a developer +machine, run `sbx policy refresh`, which requires sbx 0.49.0 or later. It +fetches and applies the latest organization policy without restarting the +daemon or stopping running sandboxes. + +The refreshed policy applies to new connections only. A connection that a +sandbox opened while the previous policy allowed it stays open even if the new +policy denies it. Restart the sandbox to close those connections. + +When a synced change takes effect also depends on the policy type. See +[Network access policies](network.md#when-changes-take-effect), +[Filesystem access policies](filesystem.md#when-changes-take-effect), and +[MCP access policies](mcp.md#when-changes-take-effect). diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md b/content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md index 33459d6a6a38..6a9de492f552 100644 --- a/content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md @@ -24,7 +24,9 @@ To create a policy: [Scope policies to teams](#scope-policies-to-teams). 1. Define the policy rules. - Network and filesystem policies: select **Add rule** for each rule. For a - network policy, see [Add a network rule](network.md#add-a-network-rule). + network policy, see [Network rule fields](network.md#network-rule-fields). + For a filesystem policy, see + [Filesystem mount rule syntax](../../reference/filesystem-rules.md). - 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 @@ -34,6 +36,11 @@ To create a policy: Existing policies are listed with their name, scope, rule count, and last update. Use the action menu (⋮) to edit or delete a policy. +If you manage policies through the +[Governance API](/reference/api/ai-governance/), a network or filesystem +policy's `domain` field is `network` or `filesystem`. It's derived from the +policy's rule actions, so one policy can't mix network and filesystem rules. + ## Configure a support message Admins can add an optional support message that appears after the policy denial diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md b/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md index 57a17c1c13fa..89f9955608bc 100644 --- a/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md @@ -3,50 +3,32 @@ title: Filesystem access policies linkTitle: Filesystem weight: 30 description: Control which host paths Docker Sandboxes can mount as workspaces with organization filesystem policies. -keywords: docker sandboxes, filesystem access, filesystem rules, workspace mount, organization policy, governance +keywords: docker sandboxes, filesystem access, filesystem mount rules, workspace mount, organization policy, governance aliases: - /ai/sandboxes/governance/access-controls/filesystem/ --- -Filesystem access policies control which host paths a sandbox can mount as a -workspace. Each policy contains one or more rules that restrict sandbox -workspaces to approved directories. +Filesystem access policies are organization policies that control which host +paths a sandbox can mount as a workspace. Each policy contains one or more +filesystem mount rules that restrict sandbox workspaces to approved +directories. These rules control which host paths a sandbox can mount. They +don't control access to individual files inside an allowed mount. -Filesystem access is managed with [organization policies](../_index.md). When -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](_index.md#precedence). +To create a filesystem access policy, see +[Create and manage policies](create-manage.md). For path patterns and the +`read` and `write` actions, see +[Filesystem mount rule syntax](../../reference/filesystem-rules.md). -## Rule syntax +When an organization policy is enforced for you, organization filesystem mount +rules decide which paths a sandbox can mount, and the filesystem allow rules +from your local preset stop applying. See [Precedence](_index.md#precedence). -Filesystem rules use the actions `read` and `write`. Resources are host path -patterns. +## When changes take effect -A writable workspace mount must be allowed by both a `read` rule and a `write` -rule. A read-only workspace needs only `read`. - -Examples: - -- `~/**` -- `/data/project/**` -- `C:\data\project\**` -- `\\wsl.localhost\\data\project\**` - -Use `**` to match a directory tree recursively. A single `*` matches only one -path segment. For exact path matching behavior across macOS, Linux, Windows, -and WSL, see [Filesystem rules](../../reference/filesystem-rules.md). - -## Organization filesystem rules - -Organization filesystem rules belong to policies that can apply to the whole -organization or to selected teams. For setup steps and team scoping, see -[Organization policies](../_index.md). - -Filesystem policy is checked when a workspace is mounted, which happens when a -sandbox is created. To apply a filesystem policy change to a running workflow, -remove the sandbox and create a new one. +Filesystem policy is checked only when a workspace is mounted, which happens +when a sandbox is created. Changing the filesystem policy has no effect on a +running sandbox, which keeps access to the previously allowed path. To apply a +filesystem policy change, remove the sandbox and create a new one. ## Troubleshooting diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/mcp.md b/content/manuals/ai/sandboxes/governance/organization/policies/mcp.md index 37e7a52e23e4..39d5a8e68aab 100644 --- a/content/manuals/ai/sandboxes/governance/organization/policies/mcp.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/mcp.md @@ -25,7 +25,11 @@ access policy and block its network destination in network access policy. Unlike [network access policies](network.md) and [filesystem access policies](filesystem.md), MCP policies are organization -policies written in Cedar. Docker defines the `MCP` namespace, including the +policies written in Cedar. In the +[Governance API](/reference/api/ai-governance/), an MCP policy is a `cedar_v1` +policy whose rules are the Cedar statements in the policy text, rather than +separate rules managed through the rules endpoints. Docker defines the `MCP` +namespace, including the actions, resource types, attributes, and approval behavior that policies can match. This page focuses on representative access patterns. For Docker's exact policy surface, see the [MCP policy reference](../../reference/mcp-policy.md). For @@ -236,19 +240,25 @@ when { resource.type == "local-stdio" }; container, and OCI-packaged stdio servers resolved from registry or manifest metadata with `--local`. -> [!NOTE] -> To manage Model Context Protocol (MCP) server registration and requests -> through Docker's MCP gateway, use MCP access policies. These -> policies apply only to the gateway. Direct MCP connections from a sandbox -> don't use the gateway, but you can control access to remote MCP servers with -> network policy. +## When changes take effect + +- MCP registration policy is evaluated when a server is registered with + `sbx mcp add`. Changing registration rules doesn't remove existing + registrations or stop an already-loaded server by itself. + +- MCP use-time policy is evaluated by the MCP gateway when a sandbox makes a + governed MCP request, such as a tool call, resource read, prompt retrieval, + or built-in gateway tool call. Once a policy change has synced, use-time + rules apply to subsequent governed MCP requests through the gateway. + +To prevent use of an MCP server that is already registered or loaded, add +use-time rules for the registered server name. See +[Withdraw server access](#withdraw-server-access). ## Related information -- [MCP policy concepts](../../reference/mcp-policy.md#mcp-policies): policy model and rule - evaluation. - [MCP policy reference](../../reference/mcp-policy.md): exact action, resource, attribute, context, and approval behavior. -- [Organization policies](../_index.md): policy creation and scope. +- [Create and manage policies](create-manage.md): policy creation and scope. - [MCP policy audit logs](../audit/_index.md): policy decision records. diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/network.md b/content/manuals/ai/sandboxes/governance/organization/policies/network.md index 4e77d3c26a89..9fb352480e33 100644 --- a/content/manuals/ai/sandboxes/governance/organization/policies/network.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/network.md @@ -2,69 +2,27 @@ title: Network access policies linkTitle: Network weight: 20 -description: Control outbound network access from Docker Sandboxes with local and organization policy rules. -keywords: docker sandboxes, network access, network rules, governance, local policy, organization policy +description: Control outbound network access from Docker Sandboxes with organization network policies. +keywords: docker sandboxes, network access, network rules, HTTP rules, approval, governance, organization policy aliases: - /ai/sandboxes/governance/access-controls/network/ --- -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. 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. +Network access policies are organization policies that 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. 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: +To create a network access policy, see +[Create and manage policies](create-manage.md). For hostname patterns, CIDR +ranges, and how HTTP rules combine with network rules, see +[Network and HTTP rule syntax](../../reference/network-rules.md). Developers can +also add network rules on their own machines with +[local policy](../../local/network-rules.md). For how local and organization +rules combine, see [Precedence](_index.md#precedence). -- [Local policy](../../local/_index.md), which applies to sandboxes on one developer machine - when organization governance is not active. -- [Organization policies](../_index.md), which apply centrally across an - organization or to selected teams. - -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](_index.md#precedence). - -## Rule syntax - -Network rules use `connect:tcp` for TCP and `connect:udp` for UDP. Resources are -hostnames, CIDR ranges, ports, or hostnames with ports. UDP requires -[experimental outbound UDP](../../local/network-rules.md#allow-outbound-udp). ICMP is blocked. - -Examples: - -- `api.example.com` -- `*.example.com` -- `**.example.com` -- `example.com:443` -- `10.0.0.0/8` - -For exact wildcard behavior and CIDR support, see -[Network rules](../../reference/network-rules.md). - -## 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 layer on top of network rules. 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](../../reference/network-rules.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 select the methods and path patterns. See - [Add a network rule](#add-a-network-rule). -- Local policies, with `--method` and `--path` on `sbx policy`. See - [HTTP method and path rules](../../local/network-rules.md#http-method-and-path-rules). - -## Add a network rule +## Network rule fields Each rule has an optional **Rule name**, a **Type** that decides what the rule matches, and a **Decision** of **Allow** or **Deny**. @@ -73,13 +31,12 @@ matches, and a **Decision** of **Allow** or **Deny**. - In **Destination**, enter the host or IP address the rule covers. It matches any port unless you add one. Enter the destination with no scheme and no path, so `api.github.com` rather than - `https://api.github.com/repos`. A local HTTP rule accepts only a host. + `https://api.github.com/repos`. - Under **HTTP methods**, select the methods the rule applies to. Use **Select all** to select every method, or **Read-only** to select `GET`, - `HEAD`, and `OPTIONS`. A rule saved with no methods selected matches every - method the composer lists. The composer doesn't list `CONNECT` or - `TRACE`, which differs from the CLI, where `--method ANY` matches every - HTTP method. + `HEAD`, and `OPTIONS`. Select at least one method. A rule with no methods + selected fails validation. The composer doesn't list `CONNECT` or `TRACE`, + which differs from the CLI, where `--method ANY` matches every HTTP method. - Under **Path patterns**, add one or more paths the rule covers, such as `/repos/*` and `/v1/**`. Leave it empty to match any path. - **All traffic** matches every request to the destinations you list, on any @@ -115,9 +72,6 @@ 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. -To require approval on an organization policy, see -[Organization policies](#require-approval-for-a-network-policy). - Network approval is separate from the MCP `@requireApproval` annotation. An MCP approval confirms a single call within the session and creates no rule, while an approved network destination stays allowed until you remove the rule. See @@ -126,9 +80,7 @@ an approved network destination stays allowed until you remove the rule. See ### 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](#approval-required-access). +policy allows aren't reachable until the developer confirms each one. To set it on an existing policy: @@ -143,3 +95,15 @@ To set it on an existing policy: 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. + +## When changes take effect + +- 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. 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. diff --git a/content/manuals/ai/sandboxes/governance/organization/sign-in-enforcement.md b/content/manuals/ai/sandboxes/governance/organization/sign-in-enforcement.md index 57fa7115063c..f1e1ee246223 100644 --- a/content/manuals/ai/sandboxes/governance/organization/sign-in-enforcement.md +++ b/content/manuals/ai/sandboxes/governance/organization/sign-in-enforcement.md @@ -265,9 +265,8 @@ For access, contact ACME IT Security: ## Related pages -- [Organization policies](_index.md): centrally manage - sandbox network, filesystem, and MCP access controls from the Docker Admin - Console +- [Organization governance](_index.md): centrally manage + sandbox network, filesystem, and MCP policies in Docker Home - [Governance overview](../_index.md): how local and organization governance fit together - [Enforce sign-in for Docker Desktop](/manuals/desktop/enterprise/enforce-sign-in/_index.md): diff --git a/content/manuals/ai/sandboxes/governance/reference/_index.md b/content/manuals/ai/sandboxes/governance/reference/_index.md index 3a0ab0198343..791a387e4c2b 100644 --- a/content/manuals/ai/sandboxes/governance/reference/_index.md +++ b/content/manuals/ai/sandboxes/governance/reference/_index.md @@ -10,6 +10,6 @@ Use reference material when you need API details or exact policy syntax. - [Network and HTTP rule syntax](network-rules.md) and [Filesystem mount rule syntax](filesystem-rules.md): rule syntax. - [AI Governance API](/reference/api/ai-governance/): HTTP API reference for - network and filesystem organization policies. + network, filesystem, and MCP organization policies. - [MCP policy reference](mcp-policy.md): Docker MCP policy actions, resources, attributes, context fields, and approval behavior. diff --git a/content/manuals/ai/sandboxes/governance/reference/audit-records.md b/content/manuals/ai/sandboxes/governance/reference/audit-records.md index d8e80272aa44..9c928c9b4ab4 100644 --- a/content/manuals/ai/sandboxes/governance/reference/audit-records.md +++ b/content/manuals/ai/sandboxes/governance/reference/audit-records.md @@ -34,12 +34,31 @@ action. | `app_version` | Version of the Docker component that produced the record. | | `client_name` | Source component, such as `sbx` for Docker Sandboxes. | | `hostname` | Hostname of the machine that produced the record. | +| `sandbox_id` | Stable ID of the sandbox. It persists across restarts of the same sandbox. | | `deny_reason` | Why a denied request was blocked. Present on deny decisions. | +| `policy_rule` | Name of the policy rule that matched, or `default-deny` when no rule matched. | +| `policy_id` | ID of the policy that produced the decision. | +| `policy_type` | Schema type of the policy, such as `allowlist/v0` or `cedar:auth:v0`. | +| `policy_source` | Origin of the policy: `remote`, `local`, or `system`. | +| `policy_denial_code` | Why a request was denied. Present only on deny decisions. See [Denial codes](#denial-codes). | | `enforcement_mode` | Governance mode in effect when Docker evaluated the request. See [Enforcement modes](#enforcement-modes). | | `approval` | Approval details. Present when the decision involves an approval. See [Approval fields](#approval-fields). | | `action_type` | Payload discriminator that identifies the action-specific object in the record. | | `agent` | AI agent associated with the event, when Docker knows it. | +### Denial codes + +`policy_denial_code` classifies why a request was denied: + +| Code | Meaning | +| --- | --- | +| `POLICY_DENIAL_CODE_POLICY_DENY` | A deny rule matched. `policy_id` and `policy_rule` identify it. | +| `POLICY_DENIAL_CODE_DEFAULT_DENY` | No rule allowed the request, so default deny applied. | +| `POLICY_DENIAL_CODE_POLICY_SNAPSHOT_STALE` | The cached policy expired, so evaluation failed closed. | +| `POLICY_DENIAL_CODE_POLICY_EVALUATION_FAILED` | Loading or evaluating the policy failed, so evaluation failed closed. | +| `POLICY_DENIAL_CODE_GOVERNANCE_BLOCKED` | Governance couldn't be resolved for the user, for example because of membership in several organizations, so the request was denied without consulting local rules. | +| `POLICY_DENIAL_CODE_INVALID_REQUEST` | The request was malformed, so evaluation failed closed. | + ## Categories | Category | Description | @@ -48,6 +67,10 @@ action. | `AUDIT_CATEGORY_EVALUATION` | Governance policy decisions, such as allow, deny, or consent. | | `AUDIT_CATEGORY_EXECUTION` | Outcomes after an evaluated action runs. | +Session lifecycle records mark the start and end of each daemon run. Evaluation +records share the run's `audit_session_id`, so you can correlate every decision +back to a daemon session. + ## Decisions | Decision | Description | @@ -142,47 +165,6 @@ separate from the `network_egress` record for the connection. | `http_request.port` | Destination port. | | `http_request.path` | URL path, without the query string or fragment. | -## What gets recorded - -The daemon writes two categories of local record: - -- Evaluation records capture each policy decision: the resource, the action, - the verdict, and the reason for a denial. -- Session lifecycle records mark the start and end of each daemon run. - Evaluation records share the run's `audit_session_id`, so you can correlate - every decision back to a daemon session. - -Records contain metadata only. They don't contain prompt content, agent output, -or parameter values. - -A network evaluation record looks like this: - -```json -{ - "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80", - "timestamp": "2026-05-28T19:15:00.728933Z", - "schema_version": "1.82.0", - "category": "AUDIT_CATEGORY_EVALUATION", - "decision": "AUDIT_DECISION_DENY", - "username": "jordandoe", - "user_email": "jordandoe@example.com", - "org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", - "org_name": "Acme Inc", - "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", - "resource_id": "example.com:443", - "os": "macos", - "app_version": "v0.31.0", - "client_name": "sbx", - "hostname": "host-machine", - "deny_reason": [ - "no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com:443)" - ], - "action_type": "network_egress", - "network_egress": { "protocol": "tcp" }, - "agent": "claude" -} -``` - ## Sample record ```json diff --git a/content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md b/content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md index c670125800da..544d0098bac4 100644 --- a/content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md +++ b/content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md @@ -5,8 +5,9 @@ description: Syntax for sandbox filesystem rules, including path patterns across keywords: docker sandboxes, filesystem rules, path patterns, workspace mount, rule syntax --- -Filesystem rules use the actions `read` and `write`. Resources are host paths -that sandboxes can mount as workspaces. +Filesystem mount rules use the actions `read` and `write`. Resources are host +paths that sandboxes can mount as workspaces. The rules control which paths a +sandbox can mount, not access to individual files inside an allowed mount. 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 diff --git a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md index b68f5a2ed4a8..0c298665ed11 100644 --- a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md +++ b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md @@ -9,32 +9,16 @@ keywords: docker sandboxes, MCP policy, Cedar policy, MCP actions, MCP resources MCP policies are organization policies written in Cedar using Docker's `MCP` namespace. This reference defines the Docker-specific policy surface for Model Context Protocol (MCP) activity made available to sandboxes through Docker's -[MCP gateway](../../mcp-gateway.md). +[MCP gateway](../../mcp-gateway.md). MCP policy applies when a developer +registers a server and when an agent uses the MCP gateway. Registration rules +control future `sbx mcp add` operations. Use-time rules control tool calls, +gateway meta-tools, resource reads, and prompt retrieval from servers that are +already registered or loaded. Use this reference with [MCP access policies](../organization/policies/mcp.md) for common policy patterns. For the Cedar language, see the [Cedar documentation](https://docs.cedarpolicy.com/). -## MCP policies - -MCP policies control Model Context Protocol activity made available to a -sandbox through Docker's [MCP gateway](../../mcp-gateway.md). They are -organization policies written in Cedar using the `MCP` namespace, rather than -the network and filesystem rule format. - -MCP policy applies when a developer registers a server and when an agent uses -the MCP gateway. Registration rules control future `sbx mcp add` operations. -Use-time rules control tool calls, gateway meta-tools, resource reads, and -prompt retrieval from servers that are already registered or loaded. - -Governed MCP activity is default deny: a request is blocked unless a matching -`permit` allows it. A matching `forbid` overrides any `permit`, including a -permit that requires approval. Policy scope supplies the principal, so use -organization or team scope instead of matching users, teams, tenants, or roles -in Cedar. - -For representative policies, see [MCP access policies](../organization/policies/mcp.md). - ## Evaluation model Cedar evaluates MCP requests against a principal, action, resource, and context. diff --git a/content/manuals/ai/sandboxes/governance/reference/network-rules.md b/content/manuals/ai/sandboxes/governance/reference/network-rules.md index 338f00d24fae..0433562fb86c 100644 --- a/content/manuals/ai/sandboxes/governance/reference/network-rules.md +++ b/content/manuals/ai/sandboxes/governance/reference/network-rules.md @@ -5,34 +5,16 @@ description: Syntax for sandbox network rules, including domain patterns, CIDR r keywords: docker sandboxes, network rules, rule syntax, wildcards, CIDR, HTTP rules, method and path --- -Network rules use `connect:tcp` for TCP and `connect:udp` for UDP. Resources are -hostnames, CIDR ranges, or ports. UDP requires -[experimental outbound UDP](../local/network-rules.md#allow-outbound-udp). -ICMP is blocked. - -**Hostname patterns** - -| Pattern | Example | Matches | -| --------------------- | ----------------- | ------------------------------------------------------------- | -| Exact hostname | `example.com` | `example.com` on any port, not subdomains | -| Single-level wildcard | `*.example.com` | One subdomain level, any port: `api.example.com` | -| Multi-level wildcard | `**.example.com` | Any depth, any port: `api.example.com`, `v2.api.example.com` | -| Hostname with port | `example.com:443` | `example.com` on port 443 only | - -`example.com` and `*.example.com` don't cover each other. Specify both if you -need to match the root domain and its subdomains. - -**CIDR ranges** +A network rule matches a destination host on its own. An HTTP rule is a network +rule that also names an HTTP method and URL path, so a policy can allow reads +from an API without allowing writes to it. For how to write destinations, see +[Destinations](#destinations). -Both IPv4 and IPv6 notation are supported: `10.0.0.0/8`, `192.168.1.0/24`, -`2001:db8::/32`. +Developer machines must run sbx 0.35.0 or later to enforce HTTP method and path +rules. ## HTTP method and path -A network rule matches a destination host on its own. An HTTP rule is a network -rule that also names an HTTP method and URL path, so a policy can allow reads -from an API without allowing writes to it. - An HTTP rule names one or more methods, a destination, and path patterns. What each part accepts depends on where you configure the rule: @@ -44,15 +26,16 @@ each part accepts depends on where you configure the rule: A destination can include a port, and a path pattern looks like `/api/**`. -A local rule doesn't accept an IP address or a CIDR range. Use a plain network -rule for those destinations. To cover a second path in a local policy, add a -second rule. +A local HTTP rule accepts only a host pattern, not an IP address or a CIDR +range. To match an IP address or a CIDR range, use a network rule without +`--method` or `--path`. A local HTTP rule also takes one path, so add a separate +rule for each path. Every rule applies to at least one method. On the CLI, `--method ANY` covers -every HTTP method. In the composer, a rule with no methods selected covers -every method the composer lists. For the methods you can select individually, see -[Add a network rule](../organization/policies/network.md#add-a-network-rule) for an -organization policy and +every HTTP method. In the composer, select at least one method. A rule with no +methods selected fails validation. For the methods you can select individually, +see [Network rule fields](../organization/policies/network.md#network-rule-fields) +for an organization policy and [HTTP method and path rules](../local/network-rules.md#http-method-and-path-rules) for a local one. @@ -87,6 +70,30 @@ such as one it handles transparently, is blocked rather than evaluated. Traffic that isn't HTTP, such as SSH, carries no method or path, so HTTP rules never match it. Control those destinations with network rules. +## Destinations + +Network rules use `connect:tcp` for TCP and `connect:udp` for UDP. Resources are +hostnames, CIDR ranges, or ports. UDP requires +[experimental outbound UDP](../local/network-rules.md#allow-outbound-udp). +ICMP is blocked. + +**Hostname patterns** + +| Pattern | Example | Matches | +| --------------------- | ----------------- | ------------------------------------------------------------- | +| Exact hostname | `example.com` | `example.com` on any port, not subdomains | +| Single-level wildcard | `*.example.com` | One subdomain level, any port: `api.example.com` | +| Multi-level wildcard | `**.example.com` | Any depth, any port: `api.example.com`, `v2.api.example.com` | +| Hostname with port | `example.com:443` | `example.com` on port 443 only | + +`example.com` and `*.example.com` don't cover each other. Specify both if you +need to match the root domain and its subdomains. + +**CIDR ranges** + +Both IPv4 and IPv6 notation are supported: `10.0.0.0/8`, `192.168.1.0/24`, +`2001:db8::/32`. + For local and organization policy configuration, see [Manage local network rules](../local/network-rules.md) and [Network access policies](../organization/policies/network.md). From 1da100f79f69468aab930f39599378d147791ed3 Mon Sep 17 00:00:00 2001 From: Craig Osterhout Date: Wed, 21 Oct 2026 10:06:57 -0700 Subject: [PATCH 3/3] rework Signed-off-by: Craig Osterhout --- content/get-started/tutorials/admin-set-up.md | 4 +- content/get-started/tutorials/run-an-agent.md | 2 +- content/guides/firecrawl-sandbox-kit.md | 6 +- content/manuals/ai/sandboxes/architecture.md | 5 +- .../ai/sandboxes/configuration/credentials.md | 7 +- .../ai/sandboxes/configuration/settings.md | 3 +- .../sandboxes/configuration/upstream-proxy.md | 6 +- .../sandboxes/customize/author/tool-mixins.md | 5 +- content/manuals/ai/sandboxes/faq.md | 11 +- content/manuals/ai/sandboxes/get-started.md | 5 +- .../manuals/ai/sandboxes/governance/_index.md | 119 ++++---- .../ai/sandboxes/governance/local/_index.md | 108 ++++++-- .../sandboxes/governance/local/approvals.md | 102 ++++--- .../sandboxes/governance/local/get-started.md | 96 ------- .../ai/sandboxes/governance/local/inspect.md | 253 ++++++++---------- .../governance/local/network-rules.md | 143 ++++++---- .../governance/local/test-monitor.md | 88 +++--- .../sandboxes/governance/local/try-it-out.md | 137 ++++++++++ .../governance/organization/_index.md | 92 +++++-- .../governance/organization/audit/_index.md | 107 ++++---- .../organization/audit/configure.md | 73 +++-- .../governance/organization/audit/siem.md | 105 ++++---- .../organization/audit/view-export.md | 80 ++++-- .../governance/organization/get-started.md | 135 ++++++++++ .../organization/policies/_index.md | 115 ++++---- .../organization/policies/create-manage.md | 125 ++++----- .../organization/policies/filesystem.md | 69 +++-- .../governance/organization/policies/mcp.md | 81 +++--- .../organization/policies/network.md | 140 +++++----- .../organization/sign-in-enforcement.md | 197 ++++++++------ .../sandboxes/governance/reference/_index.md | 13 +- .../governance/reference/audit-records.md | 139 +++++----- .../governance/reference/filesystem-rules.md | 13 +- .../governance/reference/mcp-policy.md | 11 +- .../governance/reference/network-rules.md | 19 +- .../governance/reference/policy-limits.md | 32 +++ content/manuals/ai/sandboxes/mcp-gateway.md | 7 +- .../manuals/ai/sandboxes/security/_index.md | 8 +- .../manuals/ai/sandboxes/security/defaults.md | 3 +- .../ai/sandboxes/security/isolation.md | 9 +- .../manuals/ai/sandboxes/troubleshooting.md | 129 ++++++++- .../ai/sandboxes/workflows/automation.md | 2 +- content/manuals/platform-release-notes.md | 2 +- .../plans/ai-governance.md | 4 +- data/summary.yaml | 4 +- layouts/_shortcodes/summary-bar.html | 16 +- 46 files changed, 1737 insertions(+), 1093 deletions(-) delete mode 100644 content/manuals/ai/sandboxes/governance/local/get-started.md create mode 100644 content/manuals/ai/sandboxes/governance/local/try-it-out.md create mode 100644 content/manuals/ai/sandboxes/governance/organization/get-started.md create mode 100644 content/manuals/ai/sandboxes/governance/reference/policy-limits.md diff --git a/content/get-started/tutorials/admin-set-up.md b/content/get-started/tutorials/admin-set-up.md index f36f4513754e..5e8bd742238d 100644 --- a/content/get-started/tutorials/admin-set-up.md +++ b/content/get-started/tutorials/admin-set-up.md @@ -84,5 +84,5 @@ Continue with these guides when you're ready to expand the deployment: for additional policies and deployment controls - [Set up SSO and provisioning](/manuals/security/authentication/single-sign-on/_index.md) for centralized identity management -- [Govern Docker Sandboxes](/manuals/ai/sandboxes/governance/_index.md) for - organization-wide agent policies +- [Govern Docker Sandboxes](/manuals/ai/sandboxes/governance/organization/_index.md) + for organization-wide agent policies diff --git a/content/get-started/tutorials/run-an-agent.md b/content/get-started/tutorials/run-an-agent.md index 3e173ea1338f..1b6941955dc5 100644 --- a/content/get-started/tutorials/run-an-agent.md +++ b/content/get-started/tutorials/run-an-agent.md @@ -94,7 +94,7 @@ The first time you run a sandbox, `sbx` asks you to choose a default network policy. This policy controls which external services your sandboxes can reach. Select **Balanced** to permit common development services and block other destinations by default. You can change these rules later with -[`sbx policy`](/manuals/ai/sandboxes/governance/local/_index.md). +[`sbx policy`](/manuals/ai/sandboxes/governance/local/network-rules.md). The built-in integrations start coding agents in their full-autonomy mode. For example, Codex bypasses approvals, Claude Code skips permission prompts, and diff --git a/content/guides/firecrawl-sandbox-kit.md b/content/guides/firecrawl-sandbox-kit.md index 8ffa0a920dd6..6899c1aa59c9 100644 --- a/content/guides/firecrawl-sandbox-kit.md +++ b/content/guides/firecrawl-sandbox-kit.md @@ -170,10 +170,10 @@ API, including structured extraction with a schema, see the Without organization governance, your default network policy and kit-defined rules determine which domains the sandbox can access. Under organization -governance, organization policy controls which domains can be allowed; local -and kit-defined allow rules are inactive, while deny rules can still restrict +governance, organization policy controls which domains can be allowed; local and +kit-defined allow rules are inactive, while deny rules can still restrict access. See -[Network policy precedence](/manuals/ai/sandboxes/governance/organization/policies/_index.md#precedence). +[How organization policy relates to local and kit rules](/manuals/ai/sandboxes/governance/organization/policies/_index.md#how-organization-policy-relates-to-local-and-kit-rules). The Firecrawl kit requests access to PyPI during installation and `api.firecrawl.dev` at runtime. Its credential declaration tells the proxy to diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index c2d1f38b539a..853067ad6525 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -77,8 +77,9 @@ $ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run All outbound TCP traffic from the sandbox routes through a proxy on your host. Agents use a forward proxy for HTTP and HTTPS; other TCP traffic is forwarded -transparently. Both paths enforce -[network access policies](governance/_index.md). The forward +transparently. Both paths enforce network policy, the rules that decide which +destinations a sandbox can reach. For how those rules are set, see +[Governance](governance/_index.md). The forward proxy also handles [credential injection](configuration/credentials.md). See [Network isolation](security/isolation.md#network-isolation) for how this works and [Default security posture](security/defaults.md) for what is diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 13f91cd60cfd..0f329544349e 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -465,9 +465,10 @@ $ sbx secret set-custom \ ``` A `--host` value can also use wildcards, with the same syntax as -[network rules](../governance/reference/network-rules.md): `*` matches a -single label (`*.example.com` covers `api.example.com`) and `**` matches any -number (`**.example.com` covers `api.example.com` and `v2.api.example.com`). +[network rule hostname patterns](../governance/reference/network-rules.md#hostname-patterns): +`*` matches a single label (`*.example.com` covers `api.example.com`) and `**` +matches any number (`**.example.com` covers `api.example.com` and +`v2.api.example.com`). ### Resolve custom secrets dynamically diff --git a/content/manuals/ai/sandboxes/configuration/settings.md b/content/manuals/ai/sandboxes/configuration/settings.md index f539217e1ae8..843bd52b5f4c 100644 --- a/content/manuals/ai/sandboxes/configuration/settings.md +++ b/content/manuals/ai/sandboxes/configuration/settings.md @@ -628,7 +628,8 @@ $ sbx daemon restart This shared list applies to sandbox and daemon traffic unless a scope-specific list replaces it. A value of `*` bypasses the upstream proxy for all destinations. Proxy exclusions don't grant network access: sandbox requests must still pass -[network policy](../governance/_index.md). +network policy. For how network policy is set, see +[Governance](../governance/_index.md). #### no_proxy.sandbox {.wrap-anywhere} diff --git a/content/manuals/ai/sandboxes/configuration/upstream-proxy.md b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md index 54748f7f249f..72111f7d6efe 100644 --- a/content/manuals/ai/sandboxes/configuration/upstream-proxy.md +++ b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md @@ -22,9 +22,9 @@ originating inside a cloud sandbox. For cloud sandbox egress controls, see An upstream proxy is the corporate or network proxy that Docker Sandboxes forwards outbound traffic through on its way to the internet. This is separate -from the [network policy](../governance/_index.md), which decides -_which_ destinations are allowed. The upstream proxy decides _how_ allowed -traffic reaches them. +from network policy, which decides _which_ destinations are allowed. The +upstream proxy decides _how_ allowed traffic reaches them. For how network +policy is set, see [Governance](../governance/_index.md). Docker Sandboxes sends two kinds of outbound traffic, and you can proxy them independently: diff --git a/content/manuals/ai/sandboxes/customize/author/tool-mixins.md b/content/manuals/ai/sandboxes/customize/author/tool-mixins.md index fc84e74a3bfd..8e17174a7cef 100644 --- a/content/manuals/ai/sandboxes/customize/author/tool-mixins.md +++ b/content/manuals/ai/sandboxes/customize/author/tool-mixins.md @@ -164,8 +164,9 @@ A response confirms that Claude Code can reach the API and authenticate with your stored key. If authentication fails, check that you stored the key and approved the kit's request to use it. See [Credential bindings](/manuals/ai/sandboxes/configuration/credentials.md#credential-bindings). -Network requests must also meet the sandbox's -[network policy](/manuals/ai/sandboxes/governance/organization/policies/_index.md#precedence). +Network requests must also meet the sandbox's network policy, which combines +the mixin's network rules with the developer's own. For more details, see +[How rules combine](/manuals/ai/sandboxes/governance/local/_index.md#how-rules-combine). Run `claude` without arguments to start an interactive session. Follow its first-run prompts. Exit Claude Code and the shell to return to your host. diff --git a/content/manuals/ai/sandboxes/faq.md b/content/manuals/ai/sandboxes/faq.md index d7a9ce4008e8..21b35cc4a4d8 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -20,7 +20,7 @@ Organization governance for local sandboxes includes centrally managed network, filesystem, and MCP policies, [sign-in enforcement](governance/organization/sign-in-enforcement.md), and [audit logs](governance/organization/audit/_index.md). These -[organization governance features](governance/) require a separate paid +[organization governance features](governance/organization/_index.md) require a separate paid subscription — [contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) to get started. @@ -34,7 +34,7 @@ Signing in gives each sandbox a verified identity, which lets Docker: containers, install packages, and push code. Your Docker identity is the anchor. - **Enable team features.** Team-scale features like - [organization governance](governance/), shared environments, and audit logs + [organization governance](governance/organization/_index.md), shared environments, and audit logs need a concept of "who," and adding that later would be worse for everyone. - **Authenticate against Docker infrastructure.** Sandboxes pull images, run daemons, and talk to Docker services. A Docker account authenticates those @@ -50,8 +50,9 @@ 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/organization/_index.md). This -feature requires a separate paid subscription — +See +[How organization policy relates to local and kit rules](governance/organization/policies/_index.md#how-organization-policy-relates-to-local-and-kit-rules). +This feature requires a separate paid subscription — [contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) to get started. @@ -112,7 +113,7 @@ the sandbox, to pick up the new value. ## Why do agents run without approval prompts? The sandbox itself is the safety boundary. Because agents run inside an -isolated microVM with [network policies](governance/_index.md), +isolated microVM with [network isolation](security/isolation.md#network-isolation), [credential isolation](security/isolation.md#credential-isolation), and no access to your host system outside explicitly shared paths, the usual reasons for approval prompts (preventing destructive commands, network access, file modifications) are diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 98de6c25612d..76a1ea595e34 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -72,8 +72,9 @@ Initialize the global network policy for your sandboxes: **Balanced** is a good starting point — it permits traffic to common development services while blocking everything else. You can adjust individual -rules later. See [Local policy](governance/local/_index.md) for a full -description of each option. +rules later. See +[Start from a preset](governance/local/_index.md#start-from-a-preset) for a +full description of each option. Replace `claude` with the agent you want to use — see [Agents](agents/) for the full list. diff --git a/content/manuals/ai/sandboxes/governance/_index.md b/content/manuals/ai/sandboxes/governance/_index.md index f7544ab474e1..b504dc37cb08 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -8,73 +8,72 @@ aliases: - /ai/sandboxes/governance/monitor-and-enforce/ --- -Sandbox governance 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 has two parts: - -- **Local policy** is the policy you set on your machine with the `sbx policy` - CLI. It lets individual developers customize which domains their sandboxes - can reach. See [Local policy](local/_index.md). -- **Organization governance** is policy, sign-in enforcement, and audit logs - that administrators set for organization members, either organization-wide - or for selected teams. Organization policy is configured centrally in Docker - Home. Network, filesystem, and MCP policies can also be managed through the - [Governance API](/reference/api/ai-governance/). See - [Organization governance](organization/_index.md). - -Both apply to local sandboxes. Cloud sandboxes use separate network policies. -See [Cloud network policy](../cloud/network-policy.md) and Docker Agentic -Platform [network policies](/manuals/agentic-platform/policies.md). - -Organization policies apply to members who hold an AI Governance license. -Developer machines must run sbx 0.35.0 or later to enforce HTTP method and -path rules. - -When an organization policy is enforced for you, access is default deny: a -request that no organization allow rule matches is blocked, and a matching deny -rule takes precedence over any allow rule. Governed MCP activity is default -deny in the same way. Without organization governance, a request that no rule -matches is handled according to your local preset. See -[Local policy](local/_index.md). - -Administrators can also require developers to sign in as members of their -organization before using sandboxes at all. -[Sign-in enforcement](organization/sign-in-enforcement.md) is deployed -through endpoint management and ensures developers can't bypass organization -policy by using a personal account. +Agents in sandboxes work on their own. They install packages, call APIs, and +use tools without asking you first. Governance lets an agent work freely within +limits you set. It has two parts: local policy, which applies to one machine, +and organization governance, which applies across an organization and also +records what sandboxes did in audit logs. > [!NOTE] -> Organization governance requires a Docker AI Governance subscription. -> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) -> to request access. +> This section covers sandboxes that run on your machine. Cloud sandboxes use +> the same kinds of allow and deny rules, but they don't use local policy or +> organization policy. They use +> [cloud network policy](../cloud/network-policy.md), which is stored in your +> Docker account and managed with `sbx --cloud policy` or in the Docker Agentic +> Platform [Console](/manuals/agentic-platform/policies.md). -## Resource model +## Who sets the rules -Docker sandbox governance is built around two resource types: **policies** and -**rules**. +The two parts of governance differ in who sets the rules and who the rules +apply to. -A **policy** is a named collection of rules that controls sandbox access. -Policies exist at two levels: +### You, with local policy and kits -- **Local**: configured per machine using the `sbx policy` CLI. Applies to - sandboxes on that machine only. -- **Organization**: configured in Docker Home or through the - [Governance API](/reference/api/ai-governance/). Applies to licensed members - of the organization. An organization can have several policies, each applying - either org-wide or to specific teams. See - [Policy scope](organization/policies/_index.md#policy-scope). +[Local policy](local/_index.md) is the policy you set on your machine with the +`sbx policy` CLI. You start from a preset, then allow or block the network +destinations your sandboxes need. Local policy is available to everyone on their +machine. -When an organization policy is enforced for you, only organization allow rules -can grant access. Local and kit-defined deny rules still apply on top. See -[Precedence](organization/policies/_index.md#precedence). +The kits your sandboxes use, including the built-in agent kits, can add network +rules too, such as the API endpoints an agent needs. Kit rules work like the +rules you add yourself. -A **rule** is the unit of access control within a policy. Each rule has: +### Your organization, with organization governance -- **Name**: a human-readable label -- **Actions**: the type of access the rule controls -- **Resources**: the targets the rule matches against -- **Decision**: `allow` or `deny` +With [organization governance](organization/_index.md), administrators set +policies for the members of their organization who hold an AI Governance +license. Organization policies control network access, the host paths +sandboxes can mount, and MCP activity. Organization governance requires an +[AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md). -Each policy covers one kind of access: network or filesystem. MCP policies use -Cedar statements written in the `MCP` namespace instead of the network and -filesystem rule format. +## How governance works + +Governance works through rules. A rule allows or denies one kind of access, +such as a network destination, and a policy is a set of rules. When a sandbox +tries to reach a network destination, the request is checked against your +rules. With organization policy, the same check also applies when a sandbox +mounts a host path or uses an MCP server. + +The rules are enforced outside the sandbox, so an agent running inside it +can't change or bypass them. For where network rules are enforced as a request +leaves the sandbox, see [Networking](../architecture.md#networking). + +Local policy and organization policy both follow this model. For how each one +works, see [How local policy works](local/_index.md#how-local-policy-works) +and +[How organization governance works](organization/_index.md#how-organization-governance-works). + +Local policy, kit rules, and organization policy combine differently depending +on whether an organization policy is enforced for you. For more details, see +[How organization policy relates to local and kit rules](organization/policies/_index.md#how-organization-policy-relates-to-local-and-kit-rules). + +## Get started + +If you're a developer, start with +[Try out local policy](local/try-it-out.md), an example that allows and blocks +destinations for one sandbox. + +If you're an administrator, start with +[Get started with organization governance](organization/get-started.md) to set +up licenses, sign-in enforcement, policies, and audit logs for your +organization. diff --git a/content/manuals/ai/sandboxes/governance/local/_index.md b/content/manuals/ai/sandboxes/governance/local/_index.md index 21fb7318e7a2..30fdd2ae54f5 100644 --- a/content/manuals/ai/sandboxes/governance/local/_index.md +++ b/content/manuals/ai/sandboxes/governance/local/_index.md @@ -8,28 +8,100 @@ aliases: - /ai/sandboxes/governance/access-controls/local/ --- -The `sbx policy` command manages the local policy on your machine. The local -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 decides which network destinations the sandboxes on your machine +can reach. You manage it with the `sbx policy` command, and it holds the network +access rules for your machine. You start from a preset, add rules of your own, +and kits add the rules their agents need. -When an organization policy is enforced for you, your local allow rules stop -applying and your local deny rules still apply. See -[Precedence](../organization/policies/_index.md#precedence). To list the rules -that stopped applying, run `sbx policy ls --include-inactive`. See -[Showing inactive rules](inspect.md#showing-inactive-rules). +## How local policy works + +Local policy covers network access. Rules usually match a hostname, and HTTP +traffic can also be matched by method and path. Non-HTTP TCP traffic, including +SSH, can be allowed with a hostname rule, for example `sbx policy allow network +"myhost:22"`, or with an address-based rule. UDP requires the experimental +feature and policy rules described in [Allow outbound +UDP](network-rules.md#allow-outbound-udp). ICMP is blocked. For domain patterns, wildcards, and CIDR ranges, see [Network and HTTP rule syntax](../reference/network-rules.md). -Outbound TCP traffic passes through a proxy on your host, which enforces access -rules on every connection. Non-HTTP TCP traffic, including SSH, can be allowed -with a hostname rule (for example, `sbx policy allow network "myhost:22"`) or an -address-based rule. UDP requires the experimental feature and policy rules -described in [Allow outbound UDP](network-rules.md#allow-outbound-udp). ICMP is blocked. +## Start from a preset + +Local policy starts from a network preset, which sets how much network access +sandboxes have before you add rules of your own. If you haven't chosen a preset, +the CLI prompts you before it runs a sandbox: + +```plaintext +Initialize the global network policy for your sandboxes: + + Applies to all sandboxes, current and future — change it later with + "sbx policy allow/deny/rm". Kits, including built-in agent kits, may + also add per-sandbox rules. + + 1. Open — All network traffic allowed, no restrictions. + ❯ 2. Balanced — Default deny, with common dev sites allowed. + 3. Locked Down — All network traffic blocked unless you allow it. + + Use ↑/↓ or 1–3 to navigate, Enter to confirm, Esc to cancel. +``` + +| Preset | Description | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +| Open | All outbound TCP traffic is allowed. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`. | +| Balanced | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. | +| Locked Down | No baseline allow rules. Destinations need an allow rule from you or a kit. | + +The **Balanced** preset's baseline allowlist is a good starting point for most +workflows. Run `sbx policy ls` to see exactly which rules it includes. + +To set the preset without the prompt, or to choose again later, see +[Set or reset the preset](network-rules.md#set-or-reset-the-preset). + +## Add your own rules -Without organization governance, how a request that no rule matches is handled -depends on your preset. Under **Open**, every destination is allowed. Under **Balanced** and **Locked Down**, +The preset sets your global rules, which apply to every sandbox on your +machine. On top of the preset, you can add your own allow and deny rules, +either globally or scoped to one sandbox by name. For more details, see +[Manage local network rules](network-rules.md). + +## Add rules from kits + +Kits, including the built-in agent kits, can add network rules to the +sandboxes that use them, such as the API endpoints an agent needs. Kit rules +work like the rules you add yourself, and they apply under any preset, +including **Locked Down** (`deny-all`). A preset isn't an explicit deny rule, +so it doesn't override the allow rules a kit adds. For more details on kits, +see [Use kits](../../customize/use-kits.md). + +To list the rules a kit added to a sandbox, see +[Filter the listing](inspect.md#filter-the-listing). To block a destination +that a kit allows, see +[Allow or block a destination for one sandbox](network-rules.md#allow-or-block-a-destination-for-one-sandbox). + +## How rules combine + +Without organization governance, your rules and your kits' rules combine: a +destination is allowed if any rule allows it, and a deny rule from any source +takes precedence over an allow rule. + +How a request that no rule matches is handled depends on your preset. Under +**Open**, every destination is allowed. Under **Balanced** and **Locked Down**, the request is blocked and asks for your approval instead of being denied -outright, so you can open access to each destination as a sandbox needs it. See -[Respond to approval requests](approvals.md). +outright, so you can open access to each destination as a sandbox needs it. +For more details, see [Respond to approval requests](approvals.md). + +When an organization policy is enforced for you, it changes which of your +local rules apply. For more details, see +[How organization policy relates to local and kit rules](../organization/policies/_index.md#how-organization-policy-relates-to-local-and-kit-rules). +To list the rules that stopped applying, run `sbx policy ls --wide +--include-inactive`. For more details, see +[Show inactive rules](inspect.md#show-inactive-rules). + +[Approvals](approvals.md), [inspection](inspect.md), and +[testing](test-monitor.md) work the same way whether a rule comes from you, a +kit, or your organization. + +## Try it out + +[Try out local policy](try-it-out.md) walks you through an example that allows +and blocks destinations for one sandbox. diff --git a/content/manuals/ai/sandboxes/governance/local/approvals.md b/content/manuals/ai/sandboxes/governance/local/approvals.md index 5e725ccb4217..b43d614eb6b2 100644 --- a/content/manuals/ai/sandboxes/governance/local/approvals.md +++ b/content/manuals/ai/sandboxes/governance/local/approvals.md @@ -2,12 +2,33 @@ title: Respond to approval requests linkTitle: Respond to approvals weight: 30 -description: Approve or deny sandbox network requests that need your confirmation. -keywords: docker sandboxes, approval required, approve network access, sbx policy, local policy +description: Approve or dismiss sandbox network requests that need your confirmation, under local policy or an organization policy. +keywords: docker sandboxes, approval required, approve network access, sbx policy approval, local policy, organization policy --- -When a destination needs approval, a sandbox can't reach it until you confirm -it. The request is blocked and the sandbox receives a message naming the +When a sandbox tries to reach a destination that needs your approval, the +request is blocked and `sbx` records an approval request. Approve it to allow +the destination for that sandbox, or dismiss it to keep the destination +blocked. You respond the same way whether local policy or an organization +policy asks for the approval. + +A request needs approval in these cases: + +- Local policy: under the Balanced or Locked Down + [preset](_index.md#start-from-a-preset), a sandbox reaches a destination that + no rule allows or denies. A request never asks for approval under the Open + preset, because Open allows every destination. This applies only when no + organization policy is enforced for you. +- Organization policy: an organization network policy allows the destination + but requires approval first. For more details, see + [Approval-required access](../organization/policies/network.md#approval-required-access). + +A request that a deny rule matches is blocked without +asking. + +## List pending approval requests + +When a request needs approval, the sandbox receives a message naming the destination: ```plaintext @@ -17,15 +38,6 @@ Review and respond with: sbx policy approval ls ``` -If your organization -[configures a support message](../organization/policies/create-manage.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 @@ -36,16 +48,22 @@ network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY my-sandbox api.example.c Each entry names the destination, the sandbox that asked for it, and why it needs approval. Under organization governance that reason names the policy, as -shown. Without it, the reason is that no matching allow rule covers the +shown. Under local policy, the reason is that no matching allow rule covers the destination. A request that an HTTP rule matches also shows the method and path, such as `GET api.example.com:443/v1/data`. -To inspect a single entry, pass its ID to `sbx policy approval inspect`: +Repeated attempts collapse into a single entry, so a sandbox retrying in a loop +leaves one request to answer, not a queue of duplicates. + +To see the details of a single entry, pass its ID to +`sbx policy approval inspect`: ```console $ sbx policy approval inspect network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyyY ``` +## Approve or dismiss a request + Respond by selecting one of the options the entry offers: ```console @@ -54,44 +72,42 @@ $ sbx policy approval respond network:cWtN-4xUrNjxh4ouezcstgjrky6Rg57QfeRe3WEkyy 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 leaves one request to answer, not a queue of duplicates. +tries to reach it. -## What approving grants +The request that triggered the approval doesn't wait for your 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 other +tools, run the operation again. -Approving records a rule that allows the destination the sandbox actually -asked for, scoped to the sandbox that asked. Three things follow from that: +Approving records a rule that allows the destination the sandbox actually asked +for, scoped to the sandbox that asked: -- 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. +- The rule covers one destination, not a pattern. 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. -When an [HTTP rule](../reference/network-rules.md#http-method-and-path) in the policy matches -the request, approving covers the method and exact path the sandbox requested -rather than the whole destination. `GET /v1/data` and `POST /v1/data` on the -same host are approved separately. A request whose method or path can't be -recorded as a rule, such as a path with percent-encoding, is blocked without an -entry to respond to. +When an [HTTP rule](../reference/network-rules.md#http-method-and-path) in the +policy matches the request, approving covers the method and exact path the +sandbox requested rather than the whole destination. `GET /v1/data` and +`POST /v1/data` on the same host are approved separately. A request whose +method or path can't be recorded as a rule, such as a path with +percent-encoding, is blocked without an entry to respond to. -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`](network-rules.md). +## Review and remove approved destinations -Approvals live in the local policy store, so [`sbx policy reset`](get-started.md#resetting) -removes all of them along with your other local rules. Each destination is -requested again the next time a sandbox reaches it. +Approved destinations stay allowed until you remove the rule. List them: -## Troubleshooting +```console +$ sbx policy ls --wide --created-via approval +``` -### A request is blocked with "Approval required" +Remove one by its rule ID, the same way as any other local rule: -The destination needs your confirmation. Either no allow or deny rule matches -it and your machine isn't under organization governance, or an organization -policy allows it but requires approval first. +```console +$ sbx policy rm network --sandbox my-sandbox --id +``` -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. +For more details, see [Remove a rule](network-rules.md#remove-a-rule). diff --git a/content/manuals/ai/sandboxes/governance/local/get-started.md b/content/manuals/ai/sandboxes/governance/local/get-started.md deleted file mode 100644 index 412ffa61245e..000000000000 --- a/content/manuals/ai/sandboxes/governance/local/get-started.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Get started with local policy -linkTitle: Get started -weight: 10 -description: Choose and reset the default network preset for local sandbox policy. -keywords: docker sandboxes, local policy, network preset, sbx policy init, sbx policy reset ---- - -## Default preset - -If you haven't chosen a default preset, the CLI prompts you before it runs a -sandbox. Running `sbx policy reset` clears the preset and prompts you to choose -again: - -```plaintext -Initialize the global network policy for your sandboxes: - - Applies to all sandboxes, current and future — change it later with - "sbx policy allow/deny/rm". Kits, including built-in agent kits, may - also add per-sandbox rules. - - 1. Open — All network traffic allowed, no restrictions. - ❯ 2. Balanced — Default deny, with common dev sites allowed. - 3. Locked Down — All network traffic blocked unless you allow it. - - Use ↑/↓ or 1–3 to navigate, Enter to confirm, Esc to cancel. -``` - -| Preset | Description | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -| Open | All outbound TCP traffic is allowed. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`. | -| Balanced | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. | -| Locked Down | No baseline allow rules. Destinations need an allow rule from you or a kit. | - -Presets initialize the global policy. Built-in agent kits and other kits can -add per-sandbox allow rules, including under **Locked Down** (`deny-all`). The -preset isn't an explicit deny rule that overrides those allowances. - -To inspect the rules a kit adds to a sandbox, run: - -```console -$ sbx policy ls my-sandbox --source kit --type network --wide -``` - -To block a destination allowed by a kit, add an explicit deny rule: - -```console -$ sbx policy deny network --sandbox my-sandbox openrouter.ai -``` - -Deny rules take precedence over allow rules. See -[Policy precedence](../organization/policies/_index.md#precedence). - -The **Balanced** preset's baseline allowlist is a good starting point for most -workflows. Run `sbx policy ls` to see exactly which rules it includes. - -> [!NOTE] -> If an organization policy is enforced for you, organization rules take -> precedence over the preset you select here. See -> [Precedence](../organization/policies/_index.md#precedence). - -### Non-interactive environments - -In non-interactive environments such as CI pipelines or headless servers, the -interactive prompt can't be displayed. Use `sbx policy init` to set the -preset before running any other `sbx` commands: - -```console -$ sbx policy init balanced -``` - -Available values are `allow-all`, `balanced`, and `deny-all`. - -## Resetting - -To remove all custom rules and start fresh with a new preset, use -`sbx policy reset`: - -```console -$ sbx policy reset -``` - -This deletes the local policy store, restarts the daemon, and prompts you to -choose a new preset. Running sandboxes stop when the daemon shuts down. Pass -`--force` to skip the confirmation prompt: - -```console -$ sbx policy reset --force -``` - -> [!WARNING] -> `sbx policy reset` deletes all locally configured policy rules, including any -> destinations you approved. Those destinations are requested again the next -> time a sandbox reaches them. To pick up organization policy changes without -> deleting local rules, use `sbx policy refresh` instead. See -> [Policy changes not taking effect](../organization/policies/_index.md#policy-changes-not-taking-effect). diff --git a/content/manuals/ai/sandboxes/governance/local/inspect.md b/content/manuals/ai/sandboxes/governance/local/inspect.md index 7708761d29ec..8e29c1c4ddf1 100644 --- a/content/manuals/ai/sandboxes/governance/local/inspect.md +++ b/content/manuals/ai/sandboxes/governance/local/inspect.md @@ -2,22 +2,23 @@ title: Inspect policy status and rules linkTitle: Inspect policies weight: 40 -description: Inspect active policy rules and monitor sandbox network traffic with sbx policy ls and sbx policy log. -keywords: docker sandboxes, policy monitoring, sbx policy ls, sbx policy log, network traffic, policy debugging +description: List the policies and rules that apply to your sandboxes, see where they come from, and check organization governance status with sbx policy ls. +keywords: docker sandboxes, sbx policy ls, sbx policy inspect, policy rules, inactive rules, organization governance, policy debugging aliases: - /ai/sandboxes/governance/monitoring/ - /ai/sandboxes/governance/monitor-and-enforce/monitoring/ --- -`sbx policy ls` and `sbx policy log` give you a combined view of all active -policy rules and sandbox network activity, regardless of whether those rules -come from local configuration or organization governance. They're useful both -for verifying rules you've written and for debugging why a request is being -blocked or allowed. +Use `sbx policy ls` to see which policies and rules apply to your sandboxes and +where they come from, and `sbx policy inspect` to see one policy or rule in +full. A listing includes rules from your local policy, from kits, and from your +organization, so you can confirm the rules you added and work out why a request +is allowed or blocked. To watch network activity instead, see +[Test and monitor network policy](test-monitor.md). -## Listing rules +## List the policies that apply -Use `sbx policy ls` to see all active policies and their current status: +Run `sbx policy ls` to see every active policy: ```console $ sbx policy ls @@ -29,147 +30,89 @@ local-policy local all network: 42 The columns are: - `POLICY`: the policy name. -- `SOURCE`: where the policy came from. `local` means your local configuration - — a preset or rules you added with `sbx policy`. `kit` means a - [kit](/manuals/ai/sandboxes/governance/organization/policies/_index.md#precedence). `org` means your - organization. +- `SOURCE`: where the policy came from. `local` means your local policy, which + holds your preset and the rules you added with `sbx policy`. `kit` means a + [kit](../../customize/use-kits.md). `org` means your organization. - `APPLIES TO`: which sandboxes the policy applies to. `all` means the policy - is global. `sandbox:` scopes it to a single sandbox; a profile name - scopes it to sandboxes using that profile. + is global, and `sandbox:` scopes it to one sandbox. - `SUMMARY`: a count of rule entries by type and decision, for example `network: 5 allow, 1 deny`. A rule that names several destinations - contributes one entry per destination. When the listing includes rules that - match an HTTP method and path, the network count labels each part `(L4)` or - `(L7)`. See [HTTP rules](#http-rules). + contributes one entry per destination. -To see full rule-level detail including rule IDs and resources, pass `--wide`. -To inspect a single policy or rule, use `sbx policy inspect`: +## List the policies for one sandbox + +Pass a sandbox name to see only the global policies and the policies scoped to +that sandbox: ```console -$ sbx policy inspect Balanced +$ sbx policy ls my-sandbox ``` -Use `--source` to filter by origin (`local`, `org`, or `kit`) and `--decision` -to filter by outcome (`allow` or `deny`). +The output summarizes the rules by type, for example +`allow 46 hosts from local-policy`. To see each rule, add `--wide`. -Use `--protocol tcp` or `--protocol udp` to filter network rules. +## Show rule details -Use `--created-via` to filter by how a rule was created. Pass `default` for -preset rules, `added` for rules you added yourself, `provisioned` for rules a -kit or application added, or `approval` for rules recorded when you approved a -destination. A wide listing shows the same information per rule: +Pass `--wide` to list each rule on its own row, with its rule ID, type, +decision, protocols, and resources: ```console -$ sbx policy ls --wide --created-via approval +$ sbx policy ls --wide ``` -See [Approval-required access](approvals.md). - -A `STATUS` column also appears when you pass `--include-inactive`; see -[Showing inactive rules](#showing-inactive-rules). +Use the rule ID from this listing to remove a rule with +`sbx policy rm network --id`. For more details, see +[Remove a rule](network-rules.md#remove-a-rule). -When organization governance is active, the output starts with a summary block -showing which organization manages the policy, the sync state, and how many -inactive rules are hidden: +To see one policy or rule in full, pass its name or rule ID to +`sbx policy inspect`: ```console -$ sbx policy ls -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 - -POLICY SOURCE APPLIES TO SUMMARY -default filesystem org all filesystem read: 2 allow; filesystem write: 7 allow, 2 deny -default network org all network: 38 allow, 4 deny +$ sbx policy inspect local-policy ``` -`Governance` 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 refresh` to fetch and apply it right away. The command requires -sbx 0.49.0 or later. `Hidden` reports how many inactive -rules are suppressed and how to reveal them. +## Filter the listing -If Docker can't determine which organization governs your account, policy -output shows `Governance: Unresolved`, and the dashboard shows the same -unresolved state. For example, this happens when your account belongs to -multiple organizations with governance enabled. Policy enforcement fails closed -until the conflict is resolved, so local allow rules can't grant access. Contact -an administrator for the affected organizations to resolve the conflicting -governance configuration. +Filters work with both the summary and the `--wide` listing: -### Showing inactive rules +- `--type`: show only `network`, `http`, or `filesystem` policies. +- `--source`: show only policies from `local`, `kit`, or `org`. +- `--decision`: show only `allow` or `deny` rules. +- `--protocol`: show only network rules for `tcp` or `udp`. +- `--created-via`: show only rules created a certain way. Pass `default` for + preset rules, `added` for rules you added yourself, `provisioned` for rules a + kit or application added, or `approval` for rules recorded when you approved + a destination. -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: +For example, to list the destinations you've approved: ```console -$ sbx policy ls --include-inactive -POLICY RULES - Governance: Managed by my-org - Sync: OK, last synced 08:41:06 - -POLICY SOURCE APPLIES TO SUMMARY STATUS -default filesystem org all filesystem read: 2 allow; filesystem write: 7 allow, 2 deny active -default network org all network: 38 allow, 4 deny active -default-fs-read-allow-all local all filesystem read: 1 allow inactive -default-fs-write-allow-all local all filesystem write: 1 allow inactive +$ sbx policy ls --wide --created-via approval ``` -Inactive policies show `inactive` in the `STATUS` column. They have no effect -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](../organization/policies/_index.md#precedence). +For more details, see [Respond to approval requests](approvals.md). -Use `--type network`, `--type filesystem`, or `--type http` to show only -policies of that type. Without a sandbox argument, `sbx policy ls` shows every -policy across all sandboxes. Pass a sandbox name to filter to global policies -and those scoped to that sandbox: +To list the rules a kit added to a sandbox: ```console -$ sbx policy ls my-sandbox +$ sbx policy ls my-sandbox --source kit --wide ``` -### Filesystem rules +## List HTTP rules -`sbx policy ls` lists filesystem policies alongside network policies. Filesystem -rules control which host paths a sandbox can mount as a workspace. Pass -`--type filesystem` to show only them: +Rules that match an HTTP method and path have the type `http`. To list only +those rules, pass `--type http`: ```console -$ sbx policy ls --type filesystem -POLICY SOURCE APPLIES TO SUMMARY -local-policy local all filesystem read: 1 allow; filesystem write: 1 allow +$ sbx policy ls --type http ``` -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](../reference/filesystem-rules.md). - -### HTTP rules - -Rules that match an HTTP method and path are listed as type `http`. Pass -`--wide` to see the `METHOD` and `PATH` columns alongside network rules: - -```console -$ sbx policy ls --wide -TYPE METHOD PATH -network - - -http GET /repos/org/project/** -http POST /admin/** -``` +In a `--wide` listing, HTTP rules fill the `METHOD` and `PATH` columns. Rules +that match a whole destination show `-` in both columns. -Rules that match a whole destination show `-` in both columns. To list only -HTTP rules, pass `--type http`. - -HTTP rules are counted as network rules in the `SUMMARY` column, with each part +In the `SUMMARY` column, HTTP rules count as network rules, and each part is labeled by the network layer it matches on. `L4` counts entries that match a -whole destination, and `L7` counts those that also match an HTTP method and +whole destination, and `L7` counts entries that also match an HTTP method and path: ```console @@ -182,47 +125,73 @@ When the same decision has entries at both layers, each layer gets its own count, L4 first. Two host allows and one HTTP allow read `network: 2 allow (L4), 1 allow (L7)`. -The labels appear when the current listing includes at least one HTTP rule. +The labels appear only when the listing includes at least one HTTP rule. Because filters and hidden inactive rules change what the listing contains, a filtered listing with no HTTP rules shows an unlabeled count, such as `network: 42 allow`. -For the rule syntax, see +For more details, see [HTTP method and path](../reference/network-rules.md#http-method-and-path). -## Inspecting rules +## List filesystem 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 -rule-level detail including rule IDs. To inspect a single policy or rule in -full, use `sbx policy inspect`. +Filesystem rules control which host paths a sandbox can mount as a workspace. +To list only those rules, pass `--type filesystem`: -## Troubleshooting +```console +$ sbx policy ls --type filesystem +POLICY SOURCE APPLIES TO SUMMARY +local-policy local all filesystem read: 1 allow; filesystem write: 1 allow +``` -### Local allow rules have no effect +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`. Your +local policy allows read and write access to all paths by default, shown as the +two allow entries above. For more details, see +[Filesystem mount rule syntax](../reference/filesystem-rules.md). -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 summary block contains `Governance: 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. +## Check organization governance status -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. +When an organization policy is enforced for you, `sbx policy ls` starts with a +status line: -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. See -[Precedence](../organization/policies/_index.md#precedence). +```console +$ sbx policy ls +Governance: Managed by my-org · Sync: OK, last synced 08:21:01 · Hidden: 9 inactive rules. Show with: sbx policy ls --include-inactive -### A domain is still blocked after adding an allow rule +POLICY SOURCE APPLIES TO SUMMARY +default filesystem org all filesystem read: 2 allow; filesystem write: 7 allow, 2 deny +default network org all network: 38 allow, 4 deny +``` + +A `--wide` listing shows the same fields as a `POLICY RULES` block above the +table. + +- `Governance` shows which organization manages the policy. +- `Sync` shows when the daemon last pulled the organization policy. If it shows + an error or an old timestamp, run `sbx policy refresh` to fetch and apply the + latest organization policy right away, without restarting the daemon or + stopping sandboxes. The refreshed policy applies to new connections. To close + existing connections that the updated policy denies, restart the sandbox. +- `Hidden` shows how many inactive rules the listing leaves out. For more + details, see [Show inactive rules](#show-inactive-rules). + +If the status shows `Governance: Unresolved`, see +[`sbx policy ls` shows Governance: Unresolved](../../troubleshooting.md#sbx-policy-ls-shows-governance-unresolved). + +## Show inactive rules + +When an organization policy is enforced for you, local and kit allow rules +aren't evaluated, so `sbx policy ls` hides them. To list them, for example to +confirm which of your allow rules the organization policy overrides, pass +`--include-inactive` with `--wide`: + +```console +$ sbx policy ls --wide --include-inactive +``` -If a domain remains blocked after you add a local allow rule, your organization -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/). +The `STATUS` column shows `active` or `inactive` for each rule. Inactive rules +have no effect while the organization policy is enforced. Local and kit deny +rules stay active and aren't hidden, because a deny still applies on top of the +organization policy. For more details, see +[How organization policy relates to local and kit rules](../organization/policies/_index.md#how-organization-policy-relates-to-local-and-kit-rules). diff --git a/content/manuals/ai/sandboxes/governance/local/network-rules.md b/content/manuals/ai/sandboxes/governance/local/network-rules.md index c65189e7d75d..775244fc2158 100644 --- a/content/manuals/ai/sandboxes/governance/local/network-rules.md +++ b/content/manuals/ai/sandboxes/governance/local/network-rules.md @@ -6,10 +6,13 @@ description: Allow, deny, and remove local network rules for sandboxes on your m keywords: docker sandboxes, local policy, network rules, sbx policy allow, sbx policy deny, HTTP rules, UDP --- -A rule covers a destination host. It can also name HTTP methods and paths to -narrow the match to part of that host. +Local network rules allow or block destinations on top of your +[preset](_index.md#start-from-a-preset). You can add rules for all sandboxes or +for one sandbox, narrow a rule to HTTP methods and paths, and remove rules you +no longer need. For the host patterns a rule accepts, see +[Network and HTTP rule syntax](../reference/network-rules.md#destinations). -## Network rules +## Allow or block a destination Use [`sbx policy allow`](/reference/cli/sbx/policy/allow/) and [`sbx policy deny`](/reference/cli/sbx/policy/deny/) to add or restrict access @@ -21,6 +24,14 @@ $ sbx policy allow network api.anthropic.com $ sbx policy deny network ads.example.com ``` +Specify multiple hosts in one command with a comma-separated list: + +```console +$ sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org" +``` + +## Allow or block a destination for one sandbox + Pass `--sandbox ` to scope a rule to one sandbox: ```console @@ -28,9 +39,8 @@ $ 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: +You can also add deny rules for a sandbox when you create it, with +`--deny-network` on `sbx create` or `sbx run`: ```console $ sbx create --deny-network ads.example.com claude . @@ -38,29 +48,23 @@ $ 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 `. +appear in `sbx policy ls `, like any other rule scoped to the sandbox. -Specify multiple hosts in one command with a comma-separated list: - -```console -$ sbx policy allow network "api.anthropic.com,*.npmjs.org,*.pypi.org" -``` - -Remove a rule by resource or by rule ID: +To block a destination that a kit allows, add a deny rule for the sandbox that +uses the kit. A deny rule takes precedence over the kit's allow rule: ```console -$ sbx policy rm network --resource ads.example.com -$ sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 +$ sbx policy deny network --sandbox my-sandbox openrouter.ai ``` -To remove a sandbox-scoped rule, pass `--sandbox `: +Removing a sandbox also removes the rules scoped to it. -```console -$ sbx policy rm network --sandbox my-sandbox --resource api.example.com -``` +## Allow or block HTTP methods and paths -## HTTP method and path rules +The rules in the previous sections match a whole host. An HTTP rule matches +specific HTTP methods and paths on a host instead, so you can allow or block +specific API requests. For example, you can let an agent read from an API +without letting it write to it. 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: @@ -105,7 +109,7 @@ 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. +use a network rule without `--method` or `--path`. Deny rules take the same flags, which is the usual way to carve a method or path out of a broader allow: @@ -115,32 +119,42 @@ $ 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](../reference/network-rules.md#http-method-and-path). +For more details on how the two layers combine, see +[HTTP method and path](../reference/network-rules.md#http-method-and-path). + +To list only HTTP rules, run `sbx policy ls --type http`. In +`sbx policy ls --wide`, the `METHOD` and `PATH` columns show `-` for rules that +match a whole host. + +> [!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. -Remove an HTTP rule by naming the same qualifiers you added it with, or by -rule ID: +## Remove a rule + +Remove a rule by resource 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 +$ sbx policy rm network --resource ads.example.com +$ sbx policy rm network --id 2d3c1f0e-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: +To remove a rule scoped to a sandbox, pass `--sandbox `: ```console -$ sbx policy ls --wide -TYPE METHOD PATH -network - - -http GET /repos/org/project/** +$ sbx policy rm network --sandbox my-sandbox --resource api.example.com ``` -> [!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. +To remove an HTTP rule, name the same method and path you added it with, or +use its rule ID: + +```console +$ sbx policy rm network --resource api.github.com --method GET --path '/repos/org/project/**' +``` + +To find a rule's ID, run `sbx policy ls --wide`. For more details, see +[Inspect policy status and rules](inspect.md). ## Allow outbound UDP @@ -178,12 +192,47 @@ $ sbx policy check network --protocol udp api.example.com:443 The CLI warns if you save a UDP rule while UDP egress is disabled. -## Troubleshooting +## Set or reset the preset + +You choose a preset the first time you run a sandbox. For more details, see +[Start from a preset](_index.md#start-from-a-preset). To set the preset without +the prompt, or to start over with a new one, use `sbx policy init` or `sbx +policy reset`. + +### Set the preset without the prompt -### An HTTP method or path is blocked on an allowed host +In non-interactive environments such as CI pipelines or headless servers, the +interactive prompt can't be displayed. Use `sbx policy init` to set the +preset before running any other `sbx` commands: + +```console +$ sbx policy init balanced +``` + +Available values are `allow-all`, `balanced`, and `deny-all`. `sbx policy init` +only works before a preset is set. To change the preset after that, reset local +policy. + +### Reset local policy + +To remove all custom rules and start fresh with a new preset, use +`sbx policy reset`: + +```console +$ sbx policy reset +``` + +This deletes the local policy store, restarts the daemon, and prompts you to +choose a new preset. Running sandboxes stop when the daemon shuts down. Pass +`--force` to skip the confirmation prompt: + +```console +$ sbx policy reset --force +``` -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). +> [!WARNING] +> `sbx policy reset` deletes all locally configured policy rules, including any +> destinations you approved. Those destinations are requested again the next +> time a sandbox reaches them. To pick up organization policy changes without +> deleting local rules, use `sbx policy refresh` instead. For more details, see +> [Organization policy changes aren't taking effect](../../troubleshooting.md#organization-policy-changes-arent-taking-effect). diff --git a/content/manuals/ai/sandboxes/governance/local/test-monitor.md b/content/manuals/ai/sandboxes/governance/local/test-monitor.md index 0dc4bc044d7e..2cddefd7e8d6 100644 --- a/content/manuals/ai/sandboxes/governance/local/test-monitor.md +++ b/content/manuals/ai/sandboxes/governance/local/test-monitor.md @@ -2,14 +2,18 @@ title: Test and monitor network policy linkTitle: Test and monitor weight: 50 -description: Test which destinations a sandbox can reach and monitor sandbox network traffic. -keywords: docker sandboxes, test network policy, sbx policy log, network traffic, local policy +description: Check whether policy allows a destination, and view the network requests your sandboxes make, with sbx policy check and sbx policy log. +keywords: docker sandboxes, test network policy, sbx policy check, sbx policy log, network traffic, local policy --- -## Testing policy +Use `sbx policy check` to find out whether policy allows a destination before a +sandbox tries to reach it, and `sbx policy log` to see the requests your +sandboxes made and which rules matched. Both work the same way whether the +rules come from your local policy, a kit, or your organization. -Before running a sandbox, you can check whether the current policy would allow -a network request with `sbx policy check network`: +## Check whether a destination is allowed + +Run `sbx policy check network` with the destination you want to test: ```console $ sbx policy check network api.anthropic.com @@ -17,28 +21,34 @@ $ sbx policy check network blocked.example.com ``` The output reports `Allowed` or `Denied`, along with governance and context -details. A denied check returns a non-zero exit status. - -The target can be a hostname, a `host:port` pair, an IP address, or a URL. -Bare hostnames and IP addresses are evaluated against port 443. This is useful -for verifying custom rules or checking what the Locked Down preset blocks -before you start an agent. +details. A denied check returns exit status 1, so you can use the command in +scripts. -A check never creates an approval request. A destination that a sandbox would -ask you to approve shows as `Denied:`, with a `Reason:` line of -`no matching allow rule (default deny)`, or `approval required by policy` under -organization governance. +The destination can be a hostname, a `host:port` pair, an IP address, or a URL. +Hostnames and IP addresses without a port are checked on port 443. A URL +supplies only its host and port, so the check ignores its path. -To check policy in the context of a specific sandbox: +To check a destination for one sandbox, including the rules scoped to it, pass +`--sandbox`: ```console $ sbx policy check network --sandbox my-sandbox api.example.com ``` -## Monitoring traffic +A check never creates an approval request. A destination that a sandbox would +ask you to approve shows as `Denied`, with a `Reason` line of +`no matching allow rule (default deny)`, or `approval required by policy` under +organization governance. + +A check reports the decision for the host, not for an HTTP method or path. To +test an HTTP rule, send a request from inside the sandbox. For more details, +see +[Allow or block HTTP methods and paths](network-rules.md#allow-or-block-http-methods-and-paths). -Use `sbx policy log` to see which hosts your sandboxes have contacted and -which rules matched: +## View network activity + +Run `sbx policy log` to see which hosts your sandboxes contacted and which +rules matched: ```console $ sbx policy log @@ -53,7 +63,9 @@ my-sandbox network registry.npmjs.org forward-bypass domain-allowed my-sandbox network app.example.com browser-open 10:15:10 29-Jan 1 ``` -The `PROXY` column shows how the request left the sandbox: +The `RULE` column identifies the policy rule that matched the request. The +`REASON` column includes extra context when the daemon records one. The `PROXY` +column shows how the request left the sandbox: | Value | Description | | ---------------- | -------------------------------------------------------------------------------------------------------------- | @@ -63,21 +75,35 @@ The `PROXY` column shows how the request left the sandbox: | `network` | Non-HTTP traffic. TCP and experimental UDP egress follow network policy. ICMP is blocked. | | `browser-open` | A sandbox process requested opening a URL in the host browser. Policy is enforced before opening the URL. | -The `RULE` column identifies the policy rule that matched the request. The -`REASON` column includes extra context when the daemon records one. +For how the forward and transparent proxies handle sandbox traffic, see +[Networking](../../architecture.md#networking). + +The log records network requests only. Filesystem mount decisions aren't in +the log. + +## Filter the log -Filter by sandbox name by passing it as an argument: +To see only one sandbox's requests, pass its name: ```console $ sbx policy log my-sandbox ``` -Use `--limit N` to show only the last `N` entries, `--json` or `--format yaml` 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. +To show only the most recent entries, pass `--limit`: + +```console +$ sbx policy log --limit 20 +``` + +## Get the log as JSON or YAML + +Pass `--json` or `--format yaml` for output that scripts can read: + +```console +$ sbx policy log --json +``` -Structured output uses the same document for local and cloud sandboxes: -`{updated_at, allowed: [...], blocked: [...]}`. Each entry includes `sandbox_id`, -`host`, `proxy_type`, `rule`, `reason`, `count`, `first_seen`, and `last_seen`. -The `--limit` flag applies to structured output too. +The document has the form `{updated_at, allowed: [...], blocked: [...]}`. Each +entry includes `sandbox_id`, `host`, `proxy_type`, `rule`, `reason`, `count`, +`first_seen`, and `last_seen`. The `--limit` flag applies to structured output +too. diff --git a/content/manuals/ai/sandboxes/governance/local/try-it-out.md b/content/manuals/ai/sandboxes/governance/local/try-it-out.md new file mode 100644 index 000000000000..4f5b99c26f89 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/local/try-it-out.md @@ -0,0 +1,137 @@ +--- +title: Try out local policy +linkTitle: Try it out +weight: 10 +description: Follow an example that allows and blocks network destinations and HTTP methods for one sandbox with local policy. +keywords: docker sandboxes, local policy, try it out, tutorial, sbx policy check, sbx policy ls, sbx policy allow, sbx policy deny, sbx policy log, http rules +--- + +In this example, you create a sandbox, allow and block destinations for it, +block an HTTP method, and review what happened. It uses the `shell` agent, so +you don't need to sign in to an agent. + +## Before you begin + +[Install Docker Sandboxes](/manuals/ai/sandboxes/install.md). + +If your organization enforces a policy for you, some steps behave differently. +For more details, see +[How organization policy relates to local and kit rules](../organization/policies/_index.md#how-organization-policy-relates-to-local-and-kit-rules). + +## Step 1: Create a sandbox + +Create a sandbox named `policy-demo` that uses the current directory as its +workspace: + +```console +$ sbx create --name policy-demo shell . +``` + +If you haven't chosen a network [preset](_index.md#start-from-a-preset) yet, +`sbx` asks you to choose one. This example works with any preset. + +## Step 2: Allow a destination for this sandbox + +Add an allow rule for `example.com` that applies only to `policy-demo`: + +```console +$ sbx policy allow network --sandbox policy-demo example.com +``` + +The rule doesn't affect your other sandboxes. List the rules you've added that +apply to the sandbox: + +```console +$ sbx policy ls policy-demo --wide --created-via added +``` + +The listing includes the `example.com` rule, with `sandbox:policy-demo` in the +`APPLIES TO` column. Rules from your preset aren't listed, because +`--created-via added` shows only rules you added. For more details, see +[Inspect policy status and rules](inspect.md). + +Reach the destination from inside the sandbox: + +```console +$ sbx exec policy-demo -- curl -sI https://example.com +``` + +For more details, see [Manage local network rules](network-rules.md). + +## Step 3: Block a destination for this sandbox + +Add a deny rule for `registry.npmjs.org` that applies only to `policy-demo`: + +```console +$ sbx policy deny network --sandbox policy-demo registry.npmjs.org +``` + +Check the destination: + +```console +$ sbx policy check network --sandbox policy-demo registry.npmjs.org +``` + +The check reports `Denied`. A deny rule takes precedence over allow rules, +including the ones your preset and kits add. + +## Step 4: Block an HTTP method for this sandbox + +An HTTP rule matches a method and path on a host, rather than the whole host. +Use HTTP rules to allow or block specific API requests, such as letting an +agent read from an API without letting it write to it. Block `POST` requests to +`example.com` for `policy-demo`: + +```console +$ sbx policy deny network --sandbox policy-demo example.com --method POST +``` + +Send a `POST` request from inside the sandbox: + +```console +$ sbx exec policy-demo -- curl -s -X POST https://example.com +``` + +The response starts with `Blocked by local rule`. Other methods are still +allowed. Send a `GET` request to the same destination: + +```console +$ sbx exec policy-demo -- curl -s https://example.com +``` + +The response is the HTML of the `example.com` page. + +`sbx policy check network` reports the decision for the host, not for a method +or path, so use a request like this one to test an HTTP rule. For more details, +see +[Allow or block HTTP methods and paths](network-rules.md#allow-or-block-http-methods-and-paths). + +## Step 5: Review network activity + +See the sandbox's network activity: + +```console +$ sbx policy log policy-demo +``` + +For more details, see [Test and monitor network policy](test-monitor.md). + +## Step 6: Clean up + +Remove the sandbox: + +```console +$ sbx rm policy-demo +``` + +Removing a sandbox also removes the rules scoped to it, so you don't need to +remove the rules you added in this example. + +## Next steps + +- Learn how presets, rules for one sandbox, and kit rules combine in + [Local policy](_index.md). +- Approve destinations that no rule allows, under the Balanced and Locked Down + presets, in [Respond to approval requests](approvals.md). +- Reference the [Network and HTTP rule + syntax](../reference/network-rules.md#http-method-and-path). diff --git a/content/manuals/ai/sandboxes/governance/organization/_index.md b/content/manuals/ai/sandboxes/governance/organization/_index.md index 7eee03d421ab..c0ed9f494489 100644 --- a/content/manuals/ai/sandboxes/governance/organization/_index.md +++ b/content/manuals/ai/sandboxes/governance/organization/_index.md @@ -1,33 +1,89 @@ --- title: Organization governance weight: 20 -description: Centrally manage sandbox network, filesystem, and MCP policies for your organization. -keywords: docker sandboxes, governance, organization policy, AI governance, Docker Home, network access, filesystem access, mcp policy +description: Centrally manage sandbox network, filesystem, and MCP policies and review audit logs for your organization. +keywords: docker sandboxes, governance, organization policy, AI governance, Docker Home, network access, filesystem access, mcp policy, sign-in enforcement, audit logs aliases: - /ai/sandboxes/security/governance/ - /ai/sandboxes/governance/org/ - /ai/sandboxes/governance/access-controls/organization/ --- -Organization governance is policy, sign-in enforcement, and audit logs that -administrators set for organization members, either organization-wide or for -selected teams. Organization policies apply to the local sandboxes of members -who hold an AI Governance license. When an organization policy is enforced for -a member, it takes precedence over their [local policy](../local/_index.md). -See [Precedence](policies/_index.md#precedence). +{{< summary-bar feature_name="AI Governance" >}} -Admins can manage organization policies through the Docker Home UI. For -programmatic management of network, filesystem, and MCP policies, use the -[Governance API](/reference/api/ai-governance/). +Agents in sandboxes act on their own, on your developers' machines. With +[local policy](../local/_index.md), each developer decides what their +sandboxes can reach. Organization governance moves that decision to you, the +administrator. You set the rules once in Docker Home, and they apply to the +sandboxes on every governed developer's machine. Organization policy is default +deny, so those sandboxes can reach, mount, and use only what your policies +allow. You also get a record of what those sandboxes did. + +## How organization governance works + +Organization governance gives you central control, in three parts: you decide +who is governed, you set what their sandboxes can do, and you review what their +sandboxes did. + +### Decide who is governed + +Organization governance applies to the members of your organization who hold +an AI Governance license. You can apply each policy to the whole organization +or only to selected teams. + +A developer could avoid your rules by signing in to Docker Sandboxes with a +personal account. [Sign-in enforcement](sign-in-enforcement.md) closes that +gap by allowing only members of your organization to use sandboxes on your +managed machines. + +### Set what sandboxes can do + +Organization policies control what sandboxes can do. You can create three types +of policy: + +- [Organization network access policies](policies/network.md): the + destinations sandboxes can reach, down to HTTP methods and paths. +- [Organization filesystem access policies](policies/filesystem.md): the host + paths sandboxes can mount. +- [Organization MCP access policies](policies/mcp.md): the MCP servers + developers can register and what agents can do with them. + +When an organization policy is enforced for a developer, it changes which of +their local rules apply. For more details, see +[How organization policy relates to local and kit rules](policies/_index.md#how-organization-policy-relates-to-local-and-kit-rules). + +You manage policies in Docker Home, or programmatically through the +[AI Governance API](/reference/api/ai-governance/). + +### Review what sandboxes did + +[Audit logs](audit/_index.md) record governance activity for your +organization, such as the policy decision made for each sandbox request. You +can view and export them in Docker Home, or forward them to your SIEM. + +## What developers see + +Developers keep using the same `sbx` commands. When an organization policy is +enforced for them, `sbx policy ls` shows `Governance: Managed by ` in its +status line. A request that your policy blocks returns `Blocked by org policy`, +followed by your +[support message](policies/create-manage.md#configure-a-support-message) if +you configured one. For more details, see +[Inspect policy status and rules](../local/inspect.md). + +## Who can manage governance By default, only organization -[owners](/manuals/security/roles-and-permissions/core-roles.md) can -view and manage AI Governance policies. To let someone other than an owner -manage policies, create a +[owners](/manuals/security/roles-and-permissions/core-roles.md) can view and +manage AI Governance policies in Docker Home. To let someone else manage +policies, create a [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) with the **Governance** permissions and assign it to a user or team. -> [!NOTE] -> Organization governance requires a Docker AI Governance subscription. -> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) -> to request access. +## Get started + +To set up organization governance in this order, from licenses and sign-in +enforcement to policies and audit logs, see +[Get started with organization governance](get-started.md). To request an AI +Governance subscription, +[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales). diff --git a/content/manuals/ai/sandboxes/governance/organization/audit/_index.md b/content/manuals/ai/sandboxes/governance/organization/audit/_index.md index 0c61cea34437..d843347eee96 100644 --- a/content/manuals/ai/sandboxes/governance/organization/audit/_index.md +++ b/content/manuals/ai/sandboxes/governance/organization/audit/_index.md @@ -9,52 +9,54 @@ aliases: - /ai/sandboxes/governance/audit/local/ --- -{{< summary-bar feature_name="AI Governance Audit Logs" >}} +{{< summary-bar feature_name="AI Governance" >}} -The Docker Sandboxes coverage on this page applies to local sandboxes. -Docker Cloud delivery stores their audit records in the cloud; it does not add -cloud sandbox coverage. For cloud network decisions, see -[Cloud policy logs](../../../cloud/network-policy.md#inspect-network-policy). +Your organization's policies decide what sandboxes can do. AI Governance Audit +Logs show you what happened: each time a policy decides a request from a +governed developer's sandbox, a record captures who made the request, what it +was, and what the policy decided. You can review the records in Docker Home, +export them, forward them to your SIEM, or collect them from each machine. + +This page explains what audit logs record, what you need to generate them, +where records go, and what you can do with them. + +> [!NOTE] +> Audit logs cover local sandboxes, the sandboxes that run on developers' +> machines. Docker Cloud delivery stores their audit records in the cloud. It +> doesn't add cloud sandbox coverage. For cloud network decisions, see +> [Cloud policy logs](../../../cloud/network-policy.md#inspect-network-policy). + +## What audit logs record AI Governance Audit Logs record Docker AI Governance activity for your organization. Each record captures the principal, action, target, decision, and time for a governance event. Records contain metadata only. They don't contain prompt content, agent output, or parameter values. -Audit logs are exposed when AI Governance is enabled for your organization. -Docker Sandboxes send audit records only for signed-in users who have an AI -Governance license and are governed by an enforced centralized [organization -policy](../_index.md). Docker Sandboxes users without both -don't send audit data to audit logs. +Audit logs cover Docker Sandboxes policy decisions and sandbox session events. +Other Docker AI sources can emit records through the same schema as they +become available. For every field a record can contain, see the +[Audit record reference](../../reference/audit-records.md). -> [!NOTE] -> AI Governance Audit Logs are part of Docker AI Governance and require a -> separate paid subscription. -> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) -> to request access. - -## Requirements +## What you need -To use AI Governance Audit Logs, your organization needs: +Audit logs are exposed when AI Governance is enabled for your organization. +To use them, your organization needs: - A Docker [AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md) - An enforced organization governance policy -- A Docker organization account -- An organization owner, or a user with a [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) that includes AI Governance audit permissions, to configure delivery and view hosted events - -> [!NOTE] -> Other Docker subscriptions are not sufficient on their own to use AI Governance -> Audit Logs. Users without an AI Governance license and an enforced organization -> policy will not generate audit data and will not appear in audit events or SIEM -> forwarding output. Personal accounts are not supported. +- An organization owner, or a user with a + [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) + that includes AI Governance audit permissions, to configure delivery and view + hosted events -## Coverage - -AI Governance Audit Logs cover Docker Sandboxes policy decisions and sandbox -session events. Other Docker AI sources can emit records through the same schema -as they become available. +Records come only from developers whose activity your organization governs. +Docker Sandboxes send audit records only for signed-in users who have an AI +Governance license and are governed by an enforced centralized +[organization policy](../_index.md). Users without both don't generate audit +data, and they don't appear in audit events or SIEM forwarding output. -## Delivery modes +## Where records go Docker supports two delivery modes for audit records: @@ -63,16 +65,10 @@ Docker supports two delivery modes for audit records: collection, or collection through your own log shipper. - **Docker Cloud**: Docker stores audit records in Docker Cloud. Cloud delivery powers the hosted audit log view, CSV export, and SIEM streaming from - app.docker.com. Cloud delivery is on by default when AI Governance is enabled. - Organization owners can disable it in [audit delivery settings](configure.md). - -Organization owners and users with a [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) that includes AI Governance audit permissions can configure local disk, Docker Cloud, or both. + app.docker.com. -The hosted audit log view, CSV export, and SIEM forwarding all require Docker Cloud delivery to be enabled. Local delivery alone does not power these features. - -Organizations that used local audit logging before hosted audit logs were -available start with cloud delivery off until an owner opts in from -[audit delivery settings](configure.md). +To choose which delivery modes your organization uses, see +[Configure audit delivery](configure.md). ### Where records are stored @@ -109,17 +105,24 @@ them. Sandboxes never delete `.jsonl` files. Retention and cleanup are the responsibility of your log shipper or your own housekeeping. -## Data handling +## What you can do with records -When Docker Cloud delivery is enabled, Docker stores audit records in Docker -Cloud for the retention window configured by your organization. For legal and -privacy terms that govern Docker services, see Docker's [Terms of -Service](https://www.docker.com/legal/docker-terms-service/) and [Privacy -Policy](https://www.docker.com/legal/privacy/). +How you use audit records depends on where they go: + +- With Docker Cloud delivery, [view and export events](view-export.md) in + Docker Home, and [forward them to your SIEM](siem.md). The hosted view, CSV + export, and SIEM forwarding all require Docker Cloud delivery. Local delivery + alone doesn't power them. +- With local delivery, collect the `.jsonl` files from each machine with your + own log shipper. For more details, see + [Collect local audit files with a log shipper](siem.md#collect-local-audit-files-with-a-log-shipper). -## Learn more +To set up delivery, see [Configure audit delivery](configure.md). -- [Configure audit delivery](configure.md) -- [View and export audit events](view-export.md) -- [SIEM forwarding](siem.md) -- [Audit record reference](../../reference/audit-records.md) +## Data handling + +When Docker Cloud delivery is enabled, Docker stores audit records in Docker +Cloud for 90 days. For legal and privacy terms that govern Docker services, see +Docker's +[Terms of Service](https://www.docker.com/legal/docker-terms-service/) and +[Privacy Policy](https://www.docker.com/legal/privacy/). diff --git a/content/manuals/ai/sandboxes/governance/organization/audit/configure.md b/content/manuals/ai/sandboxes/governance/organization/audit/configure.md index 764265946c09..e5a5fdec28c8 100644 --- a/content/manuals/ai/sandboxes/governance/organization/audit/configure.md +++ b/content/manuals/ai/sandboxes/governance/organization/audit/configure.md @@ -2,20 +2,18 @@ title: Configure audit delivery linkTitle: Configure delivery weight: 10 -description: Configure local and cloud delivery, retention, and history for Docker AI Governance Audit Logs. +description: Configure local and cloud delivery for Docker AI Governance Audit Logs, and review who changed the delivery settings. keywords: docker sandboxes, audit delivery, AI Governance, audit logs, retention, cloud delivery, AI Platform aliases: - /ai/sandboxes/governance/audit/configure/ --- -Organization owners and users with a [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) that includes AI Governance audit permissions can configure where Docker writes audit events. -Two delivery destinations are available and can be used independently or -together: +{{< summary-bar feature_name="AI Governance" >}} -- **Local disk**: The sandbox daemon writes audit events to the local disk - on each host. -- **Docker Cloud**: Audit events are sent to Docker's cloud platform, enabling - the hosted log view, CSV export, and SIEM forwarding. +Configure where Docker delivers your organization's audit records, and review +who changed those settings. You can deliver records to local disk on each host, +to Docker Cloud, or to both. For how the two delivery modes differ, see +[Where records go](_index.md#where-records-go). ## Before you begin @@ -23,7 +21,9 @@ Your organization needs: - A Docker [AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md) - An enforced organization governance policy -- Organization owner access, or a [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) with AI Governance audit permissions +- Organization owner access, or a + [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) + with AI Governance audit permissions Only users who have an AI Governance license and are governed by the enforced organization policy send Docker Sandboxes audit data. @@ -32,44 +32,35 @@ organization policy send Docker Sandboxes audit data. To configure audit delivery: -1. Sign in to [Docker Home](https://app.docker.com/). -2. Open your organization. -3. Go to **AI Platform** > **Audit logs**. -4. Open **Audit Delivery**. -5. Choose one or both delivery modes: +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. +1. Go to **AI Platform** > **Audit logs**. +1. Open **Audit delivery**. +1. Choose one or both delivery modes: - **Local disk** writes audit records to JSON Lines files on each host. - **Docker Cloud** stores audit records in Docker Cloud for hosted search, CSV export, and SIEM forwarding. -6. Save your changes. +1. Save your changes. -Cloud delivery is on by default when AI Governance is enabled. To keep records -local to your hosts, turn off **Docker Cloud** and keep **Local disk** on. +Cloud delivery is on by default when AI Governance is enabled, except for +organizations that used local audit logging before hosted audit logs were +available. Those organizations start with cloud delivery off until an owner +turns it on. To keep records local to your hosts, turn off **Docker Cloud** and +keep **Local disk** on. -Organizations that used local audit logging before hosted audit logs were -available start with cloud delivery off until an owner opts in. +Docker Cloud keeps audit records searchable in the hosted audit log view for 90 +days, and in archive storage for 90 days. -## Configure retention - -When **Docker Cloud** is selected, you can also configure how long cloud-stored -events are retained: - -| Field | Description | Default | -| ------------------------------ | ------------------------------------------------------------------ | ------- | -| Searchable retention (days) | How long events stay searchable in the hosted audit log view. | 90 days | -| Archive retention (days) | How long events are kept in long-term archive storage. | 90 days | - -Archive retention must be greater than or equal to searchable retention. - -Retention reductions apply going forward. They don't delete records that were -already retained under a longer retention window. - -## Audit delivery change history +## Review delivery change history Docker keeps a record of every change made to your organization's audit delivery -settings. Each entry captures the timestamp, the user who made the change, and -the delivery configuration that was set. Use this history to audit configuration -changes and verify when delivery modes or retention windows were modified. +settings. Each entry shows who made the change, when it happened, and the before +and after values. Use this history to audit configuration changes and verify +when delivery modes were modified. + +To review the history: -Open **History** to review delivery and retention changes for your organization. -History entries show who made the change, when it happened, and the before and -after values. +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. +1. Go to **AI Platform** > **Audit logs**. +1. Open **History**. diff --git a/content/manuals/ai/sandboxes/governance/organization/audit/siem.md b/content/manuals/ai/sandboxes/governance/organization/audit/siem.md index ef15d30aaad0..38e4153c47fd 100644 --- a/content/manuals/ai/sandboxes/governance/organization/audit/siem.md +++ b/content/manuals/ai/sandboxes/governance/organization/audit/siem.md @@ -1,5 +1,5 @@ --- -title: SIEM forwarding +title: Forward audit events to a SIEM linkTitle: Forward to a SIEM weight: 30 description: Forward Docker AI Governance audit events to Splunk, Dynatrace, Datadog, Sumo Logic, or CrowdStrike Falcon Next-Gen SIEM. @@ -8,72 +8,81 @@ aliases: - /ai/sandboxes/governance/audit/siem/ --- -{{< summary-bar feature_name="AI Governance Audit Logs" >}} +{{< summary-bar feature_name="AI Governance" >}} -Docker can forward audit events to your security information and event -management (SIEM) system, letting you centralize Docker governance data -alongside other security signals. Docker verifies the endpoint is reachable -with the supplied credential before saving. +Send your Docker AI Governance audit events to your security information and +event management (SIEM) system to centralize Docker governance data alongside +other security signals. How you do it depends on where your audit records are +delivered: -## Supported destinations +- With Docker Cloud delivery, Docker forwards events directly to a supported + SIEM destination. For more details, see + [Forward events from Docker Cloud](#forward-events-from-docker-cloud). +- With local disk delivery, your own log shipper collects the audit files from + each machine. For more details, see + [Collect local audit files with a log shipper](#collect-local-audit-files-with-a-log-shipper). -| Destination | Description | -| -------------------------------- | --------------------------------------------------------------- | -| Splunk Cloud (HEC) | Hosted Splunk using the HTTP Event Collector | -| Dynatrace | Dynatrace Log Management using the Log Ingest API | -| Datadog | Datadog Logs using the HTTP log intake API | -| Sumo Logic | Sumo Logic using an HTTP Source | -| CrowdStrike Falcon Next-Gen SIEM | Falcon Next-Gen SIEM using an HEC / HTTP Event Connector | +For how the two delivery modes differ, see +[Where records go](_index.md#where-records-go). -## Before you begin +## Forward events from Docker Cloud -SIEM forwarding requires Docker Sandboxes -[0.39.0](/manuals/ai/sandboxes/release-notes.md) or later. Earlier versions -don't deliver audit records to a SIEM destination, even when forwarding is -configured. Update Docker Sandboxes before enabling a new destination. +Docker forwards audit events from Docker Cloud to the SIEM destinations you +add in Docker Home. + +### Supported destinations + +| Destination | Connects through | What you need | +| ---------------------------------------------------------------------------------------------------- | -------------------------- | ---------------------------------------------------------------------------------------- | +| [Splunk Cloud](https://docs.splunk.com/) | HTTP Event Collector (HEC) | HEC ingest URL and an HEC token. Optionally, a Splunk index name. | +| [Dynatrace](https://docs.dynatrace.com/) | Log Ingest API | Log Ingest API URL and an API token with the `logs.ingest` scope. | +| [Datadog](https://docs.datadoghq.com/) | HTTP log intake API | Logs intake URL for your Datadog site and an API key. | +| [Sumo Logic](https://www.sumologic.com/help/) | HTTP Source | HTTP Source URL and an auth token from an HTTP Logs & Metrics source. | +| [CrowdStrike Falcon Next-Gen SIEM](https://library.humio.com/logscale-api/log-shippers-hec-raw.html) | HEC / HTTP Event Connector | API URL and an API key from the connector. Append `/raw` to the API URL when you add it. | + +### Before you begin + +You need organization owner access, or a +[custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) +with AI Governance audit permissions. SIEM forwarding requires Docker Cloud delivery to be enabled for your -organization. If you haven't already, enable it under **AI Platform** > -**Audit logs** > **Audit delivery** before configuring a SIEM destination. See -[Configure audit delivery](configure.md). - -Gather the endpoint URL and credential from your SIEM before configuring -forwarding. Some destinations require you to create a connector or source -first: - -- **Splunk Cloud**: HEC ingest URL and an HEC token. Optionally, a Splunk index - name. See [Splunk documentation](https://docs.splunk.com/). -- **Dynatrace**: Log Ingest API URL and an API token with the `logs.ingest` - scope. See [Dynatrace documentation](https://docs.dynatrace.com/). -- **Datadog**: Logs intake URL for your Datadog site and an API key. See - [Datadog documentation](https://docs.datadoghq.com/). -- **Sumo Logic**: HTTP Source URL and an auth token from an HTTP Logs & - Metrics source. See [Sumo Logic documentation](https://www.sumologic.com/help/). -- **CrowdStrike Falcon Next-Gen SIEM**: API URL and an API key from an HEC / - HTTP Event Connector. Append `/raw` to the API URL when you add the - destination. See [CrowdStrike documentation](https://library.humio.com/logscale-api/log-shippers-hec-raw.html). - -## Add a SIEM destination - -1. Sign in to [Docker Home](https://app.docker.com/). -1. Open your organization. +organization. If you haven't already, enable it under **AI Platform** > **Audit +logs** > **Audit delivery** before configuring a SIEM destination. For more +details, see [Configure audit delivery](configure.md). + +Gather the endpoint URL and credential your destination needs, listed in +[Supported destinations](#supported-destinations). Some destinations require you +to create a connector or source first. + +### Add a SIEM destination + +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. 1. Go to **AI Platform** > **Audit logs**. 1. Open **Export & Connectors**. 1. Select **Add destination**. 1. Select your destination and complete the form. 1. Select **Save**. -If verification fails, check that the URL and credential are correct and that -the endpoint is accessible from the internet. +Docker verifies the endpoint is reachable with the supplied credential before +saving. If verification fails, check that the URL and credential are correct +and that the endpoint is accessible from the internet. -## Manage destinations +### Edit or delete a destination From the **SIEM forwarding** list, select the menu next to a destination to edit or delete it. The edit form lets you update credentials and toggle forwarding on or off for that destination. Deleting a destination permanently -removes the endpoint and its stored credential and cannot be undone. +removes the endpoint and its stored credential and can't be undone. + +## Collect local audit files with a log shipper -## Collect records with a SIEM +With local disk delivery, each machine writes its audit records to `.jsonl` +files in its own audit directory. For the directory on each operating system +and how files are named, see +[Where records are stored](_index.md#where-records-are-stored). For how to +turn on local disk delivery, see [Configure audit delivery](configure.md). Point your log shipper at the audit directory and configure it to collect `.jsonl` files only. Tools such as the Splunk Universal Forwarder, diff --git a/content/manuals/ai/sandboxes/governance/organization/audit/view-export.md b/content/manuals/ai/sandboxes/governance/organization/audit/view-export.md index f37c254c5558..5e8c35bef8dd 100644 --- a/content/manuals/ai/sandboxes/governance/organization/audit/view-export.md +++ b/content/manuals/ai/sandboxes/governance/organization/audit/view-export.md @@ -8,45 +8,83 @@ aliases: - /ai/sandboxes/governance/audit/view-export/ --- +{{< summary-bar feature_name="AI Governance" >}} + Cloud delivery stores AI Governance audit records in Docker Cloud and makes them available in the hosted audit log UI. Use the hosted view to investigate -policy decisions or export events to CSV. +policy decisions, such as why a developer's request was blocked or what +sandboxes reached over the past week. Open the view to see recent events, +narrow it to the ones you care about, then export them to CSV if you need an +offline copy. -## View audit events +## Before you begin -To view audit events: +- [Docker Cloud delivery](configure.md) must be turned on for your + organization. The hosted view shows only records delivered to Docker Cloud, + not records written to local disk. +- You need organization owner access, or a + [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) + with AI Governance audit permissions. -1. Sign in to [Docker Home](https://app.docker.com/). -1. Open your organization. +## View audit events + +1. Sign in to [Docker Home](https://app.docker.com) and select your + organization. 1. Go to **AI Platform** > **Audit logs**. -1. Open **Audit Events**. +1. Open **Audit events**. -The **Audit Events** view includes summary tiles for total events, allowed +The **Audit events** view includes summary tiles for total events, allowed events, denied events, and consent-required events. The event table includes: -| Column | Description | -| --------- | ------------------------------------------------------------- | -| Time | When Docker recorded the event. | -| Event | The event type or policy action. | -| Principal | The Docker user associated with the event. | -| Resource | The target resource, such as a domain, file path, or tool. | -| Decision | The governance decision, such as allow, deny, or consent. | -| Agent | The AI agent associated with the event, when Docker knows it. | +| Column | Description | +| --------- | ------------------------------------------------------------------- | +| Time | When Docker recorded the event. | +| Event | The event type or policy action. | +| Principal | The Docker user associated with the event. | +| Resource | The target resource, such as a domain, file path, or tool. | +| Decision | The governance decision, such as Allow, Deny, or Approval required. | +| Agent | The AI agent associated with the event, when Docker knows it. | + +For every field in a record and what its values mean, see +[Audit record reference](../../reference/audit-records.md). ## Filter and search events -Use the audit log filters to narrow the event table by decision and time range. -Use search to find events by principal, resource, event type, or agent. +The event table can hold a large number of events, so narrow it to the ones +you're investigating. Use the filters above the table: -The event table uses cursor pagination for large result sets. +- **Date range**: Today, Last 7 days, Last 14 days, Last 30 days, or a custom + range. The table shows the last 7 days by default. +- **Decision**: Allow, Deny, Approval required, or Approval unavailable. +- **Event type**: the kind of action, such as a network or filesystem + evaluation. For the full list, see + [Action types](../../reference/audit-records.md#action-types). +- **Agent**: the AI agent associated with the event. +- **Principal**: a Docker username. +- **Session ID**: an audit session ID. This filter shows the whole session, + whatever the date range. + +To search across events, principals, resources, and decisions, enter at least +three characters in the search box, then press Enter. + +For example, set **Decision** to Deny and **Principal** to a developer's +username to see what their sandboxes were blocked from. + +The table shows 25 events per page by default. You can show 100 per page +instead. ## Export events to CSV -Use CSV export when you need an offline copy of filtered audit events: +When you need an offline copy of the events you found, export them. The export +uses your current filters and search terms: -1. Open **Audit Events**. +1. Open **Audit events**. 1. Apply the filters and search terms for the events you want to export. 1. Select **Export**. 1. Download the generated CSV file from the link Docker provides. -CSV exports include up to 1 000 000 rows. Download links expire after 24 hours. +CSV exports include up to 1,000,000 rows. An export stays available to download +for 24 hours after Docker generates it. + +To monitor audit events continuously instead of searching them by hand, +[forward them to your SIEM](siem.md). diff --git a/content/manuals/ai/sandboxes/governance/organization/get-started.md b/content/manuals/ai/sandboxes/governance/organization/get-started.md new file mode 100644 index 000000000000..d138595c82ff --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/get-started.md @@ -0,0 +1,135 @@ +--- +title: Get started with organization governance +linkTitle: Get started +weight: 10 +description: Set up organization governance for Docker Sandboxes, from planning policies and assigning licenses to sign-in enforcement, audit logs, and verification. +keywords: docker sandboxes, AI Governance, organization governance, get started, organization policy, sign-in enforcement, audit logs, rollout +--- + +{{< summary-bar feature_name="AI Governance" >}} + +This page walks you through setting up organization governance, from planning +your first policies to confirming they work on a developer machine. Each step +explains what to do and what to decide, and links to the page with the full +instructions. + +## Before you begin + +You need: + +- A Docker + [AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md) + for your organization. +- Your developers added as + [members of your organization](/manuals/accounts/organization/manage/members.md). + To scope policies to groups of developers, such as a pilot team, also + [create teams](/manuals/accounts/organization/manage/manage-a-team.md) for + them. +- The organization + [owner](/manuals/security/roles-and-permissions/core-roles.md) role, or a + [custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) + with the **Governance** permissions. +- Access to the endpoint management tooling for your developers' machines, such + as an MDM solution or Group Policy, to enforce sign-in. + +## Step 1: Plan what to allow + +Organization policy is default deny. Once an organization policy is enforced +for a developer, their sandboxes can reach only the network destinations your +policies allow, mount only the host paths your policies allow, and use MCP +servers only as your policies permit. For more details, see +[Organization policies](policies/_index.md). + +Before you govern anyone, work out what their sandboxes need: + +- Network destinations, such as AI provider APIs, package registries, and code + hosts. On a developer machine, `sbx policy log` shows the hosts that sandboxes + contact today. +- Host paths that sandboxes mount as workspaces, such as the directory where + developers keep their projects. A sandbox can't start without a workspace it's + allowed to mount. +- MCP servers, if your developers use them through Docker's MCP gateway. + +Then decide how to scope your policies. Use org-wide policies for guardrails +that must apply everywhere, such as deny rules for destinations no one should +reach, and team-scoped policies for access that only some teams need. Plan to +start with one pilot team before you roll out to everyone. + +## Step 2: Create your policies + +In [Docker Home](https://app.docker.com), expand **AI Platform** and create +your policies under **Network access**, **Filesystem access**, and **MCP +access**. Create at least a network policy and a filesystem policy before you +assign any licenses, so governed developers can keep working. Scope your first +policies to the pilot team. + +For the steps, see +[Create and manage organization policies](policies/create-manage.md). For the +rules each type of policy supports, see +[Organization network access policies](policies/network.md), +[Organization filesystem access policies](policies/filesystem.md), and +[Organization MCP access policies](policies/mcp.md). + +Consider also +[configuring a support message](policies/create-manage.md#configure-a-support-message). +Developers see it when your policy blocks a request, so you can tell them how +to ask for access. + +## Step 3: Assign licenses + +Organization policies apply only to members who hold an AI Governance license. +Assign licenses to the members of your pilot team first. For more details, see +[Manage licenses](/manuals/accounts/organization/manage/manage-licenses.md). + +## Step 4: Enforce sign-in + +Without sign-in enforcement, a developer can sign in to Docker Sandboxes with a +personal account and avoid your policies. Deploy an enforcement configuration +to your developers' machines with your endpoint management tooling, listing +the organizations that developers must belong to. For more details, see +[Enforce sign-in](sign-in-enforcement.md). + +## Step 5: Configure audit delivery + +Audit logs record the policy decisions made for your developers' sandboxes. In +Docker Home, go to **AI Platform** > **Audit logs** to choose where records are +delivered. For more details, see +[Configure audit delivery](audit/configure.md). + +## Step 6: Verify on a developer machine + +On the machine of a developer in your pilot team, pick up the latest +organization policy right away instead of waiting for the next sync: + +```console +$ sbx policy refresh +``` + +Confirm that organization policy is enforced. The status line should show your +organization: + +```console +$ sbx policy ls +``` + +Check a destination your policy allows and one it doesn't: + +```console +$ sbx policy check network api.anthropic.com +$ sbx policy check network blocked.example.com +``` + +The first check should report `Allowed` and the second `Denied`. Then run a +sandbox and use `sbx policy log` to see which requests it made and which +rules matched. For more details, see +[Inspect policy status and rules](../local/inspect.md) and +[Test and monitor network policy](../local/test-monitor.md). + +## Step 7: Roll out to more teams + +When the pilot team works as expected, assign licenses to more members and widen +the scope of your policies, or add team-scoped policies for teams that need +different access. Use your audit logs to find requests your policies block, and +add allow rules where developers need them. Policy changes reach developer +machines within 5 minutes. For more details, see +[When policy changes reach developers](policies/_index.md#when-policy-changes-reach-developers). diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/_index.md b/content/manuals/ai/sandboxes/governance/organization/policies/_index.md index 5cae3dbeb8d6..381d87d0884f 100644 --- a/content/manuals/ai/sandboxes/governance/organization/policies/_index.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/_index.md @@ -1,5 +1,6 @@ --- -title: Policies +title: Organization policies +linkTitle: Policies weight: 30 description: How organization policy scope, rule evaluation, and precedence work for Docker Sandboxes. keywords: docker sandboxes, organization policy, policy scope, rule evaluation, precedence, governance @@ -7,32 +8,56 @@ aliases: - /ai/sandboxes/governance/concepts/ --- -## Policy scope +{{< summary-bar feature_name="AI Governance" >}} -Each organization policy applies either across the whole organization or only -to specific teams: +Organization policies control what sandboxes can access for organization +members. When a developer's sandbox makes a request, three questions decide +the outcome: which of your policies apply to that developer, what their rules +say about the request, and how your policy relates to the developer's own local +and kit rules. This page answers each in turn, then explains when your changes +reach developers. To create a policy, see +[Create and manage organization policies](create-manage.md). -- Org-wide: with no teams assigned, the policy applies to every member of the - organization. +## What a policy contains + +An organization policy is a named collection of rules. Each rule has a name, +the actions it controls, the resources it matches, and a decision of `allow` or +`deny`. Each policy covers one kind of access: + +- [Organization network access policies](network.md) control the destinations + sandboxes can reach. +- [Organization filesystem access policies](filesystem.md) control the host + paths sandboxes can mount. +- [Organization MCP access policies](mcp.md) control MCP activity. They use + Cedar statements in the `MCP` namespace instead of rules. + +## Which policies apply to a developer + +Organization policies apply only to members who hold an AI Governance license. +Each policy applies to those members either across the whole organization or +only on specific teams: + +- Org-wide: with no teams assigned, the policy applies to every licensed member + of the organization. - Team-scoped: with one or more teams assigned, the policy applies only to - members of those teams. + licensed members of those teams. Teams are the same [teams](/manuals/accounts/organization/manage/manage-a-team.md) -you manage for your organization; Docker matches a policy's teams against each -user's team membership. Because an organization can mix org-wide and team-scoped -policies, a single user is often subject to several at once. The policies that -apply to a given user are their _effective policies_: every org-wide policy, -plus every team-scoped policy for a team they belong to. See -[Rule evaluation](#rule-evaluation) for how a user's effective policies combine. +you manage for your organization. Docker matches a policy's teams against each +user's team membership. Because an organization can mix org-wide and +team-scoped policies, a single user is often subject to several at once. The +policies that apply to a given user are their effective policies: every +org-wide policy, plus every team-scoped policy for a team they belong to. Use org-wide policies for guardrails that must apply everywhere, and -team-scoped policies for access that only some teams need. +team-scoped policies for access that only some teams need. The next section +explains why org-wide deny rules work well as guardrails. -## Rule evaluation +## How rules decide a request When an organization policy is enforced for you, the rules from all of your -[effective policies](#policy-scope) are combined and evaluated together against -each request, following two principles: +effective policies are combined and evaluated together against each request, +following two principles: - Deny wins: if any rule matches with `decision: deny`, the request is denied, regardless of any matching allow rules. @@ -47,16 +72,17 @@ 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. -A request that an approval-required policy allows produces a third outcome. -Rather than being allowed outright, it's held back until the developer confirms -the destination, and the confirmation governs later requests to it. This holds -even when another policy allows the same request without requiring approval. A -matching deny still wins, so a denied destination is blocked without asking. -See [Approval-required access](network.md#approval-required-access). +A request that an approval-required policy allows produces a third outcome: it's +blocked, and the developer is asked to approve the destination. After they +approve it, later requests to that destination succeed. For more details, see +[Approval-required access](network.md#approval-required-access). -### Precedence +### How organization policy relates to local and kit rules -What applies depends on whether an organization policy is enforced for you: +Your organization's rules aren't the only ones on a developer's machine. +Developers also have their own local rules, and kits can add rules to the +sandboxes that use them. What applies depends on whether an organization +policy is enforced for the developer: - No organization policy: local rules and any kit-defined network rules determine what sandboxes can access. @@ -66,11 +92,8 @@ What applies depends on whether an organization policy is enforced for you: permits. Deny rules apply from every source, so a local or kit-defined deny can still restrict access further. -For kit-defined rules, see -[Network policies](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@1.md) -in the kit specification. - -Precedence is decided by a rule's decision rather than its source: +The following table summarizes which rules are evaluated under organization +governance: | Rule | Evaluated under organization governance | | ------------------- | --------------------------------------- | @@ -83,32 +106,24 @@ Precedence is decided by a rule's decision rather than its source: 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 -[Showing inactive rules](../../local/inspect.md#showing-inactive-rules) for how -to list them. +inactive rules by default. For more details on how to list them, see +[Show inactive rules](../../local/inspect.md#show-inactive-rules). A local deny takes precedence over an organization approval requirement as well, so the request is blocked and no approval is requested. Rules that a developer gains by approving a request are the one exception to local allow rules being inactive, because they record an answer to the organization's own -approval requirement rather than granting new access. See +approval requirement rather than granting new access. For more details, see [Approval-required access](network.md#approval-required-access). -## Troubleshooting - -### Policy changes not taking effect - -After updating organization policies, changes take up to 5 minutes to -propagate to developer machines. To apply them right away on a developer -machine, run `sbx policy refresh`, which requires sbx 0.49.0 or later. It -fetches and applies the latest organization policy without restarting the -daemon or stopping running sandboxes. +## When policy changes reach developers -The refreshed policy applies to new connections only. A connection that a -sandbox opened while the previous policy allowed it stays open even if the new -policy denies it. Restart the sandbox to close those connections. +Policy changes reach developer machines within 5 minutes. When a synced change +takes effect also depends on the policy type. For more details, see +[Organization network access policies](network.md#when-changes-take-effect), +[Organization filesystem access policies](filesystem.md#when-changes-take-effect), and +[Organization MCP access policies](mcp.md#when-changes-take-effect). -When a synced change takes effect also depends on the policy type. See -[Network access policies](network.md#when-changes-take-effect), -[Filesystem access policies](filesystem.md#when-changes-take-effect), and -[MCP access policies](mcp.md#when-changes-take-effect). +To apply changes right away on a developer machine, or if a change doesn't seem +to apply, see +[Organization policy changes aren't taking effect](../../../troubleshooting.md#organization-policy-changes-arent-taking-effect). diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md b/content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md index 6a9de492f552..ab9544a7cdd1 100644 --- a/content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md @@ -1,17 +1,29 @@ --- -title: Create and manage policies +title: Create and manage organization policies linkTitle: Create and manage -weight: 10 +weight: 40 description: Create, scope, edit, and delete organization network, filesystem, and MCP policies in Docker Home. keywords: docker sandboxes, organization policy, create policy, Docker Home, team scope, policy limits --- -## Create a policy +{{< summary-bar feature_name="AI Governance" >}} + +Create and manage organization policies in Docker Home. The steps are the same +for network, filesystem, and MCP policies. Only the rules you add differ. For +how scope, rule evaluation, and precedence work, see +[Organization policies](_index.md). + +To manage policies programmatically instead, use the +[AI Governance API](/reference/api/ai-governance/). -Manage policies from the **AI Platform** section in the left-hand navigation -of [Docker Home](https://app.docker.com). +## Before you begin -To create a policy: +You need the organization +[owner](/manuals/security/roles-and-permissions/core-roles.md) role, or a +[custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md) +with the **Governance** permissions. + +## Create a policy 1. Sign in to [Docker Home](https://app.docker.com) and select your organization. @@ -20,57 +32,31 @@ To create a policy: 1. Select **Create policy**. 1. Enter a **Policy name**. 1. Set the **Scope** to **Organization** or **Teams**. If you select **Teams**, - choose the teams the policy applies to. See + choose the teams the policy applies to. For more details, see [Scope policies to teams](#scope-policies-to-teams). 1. Define the policy rules. - Network and filesystem policies: select **Add rule** for each rule. For a - network policy, see [Network rule fields](network.md#network-rule-fields). + network policy, see + [What a network rule can match](network.md#what-a-network-rule-can-match). For a filesystem policy, see [Filesystem mount rule syntax](../../reference/filesystem-rules.md). - - MCP policies: enter Cedar statements in the policy editor. See - [MCP access policies](mcp.md). + - MCP policies: enter Cedar statements in the policy editor. For more + details, see [Organization 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](network.md#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. - -If you manage policies through the -[Governance API](/reference/api/ai-governance/), a network or filesystem -policy's `domain` field is `network` or `filesystem`. It's derived from the -policy's rule actions, so one policy can't mix network and filesystem rules. - -## Configure a support message - -Admins can add an optional support message that appears after the policy denial -details when a sandbox action is blocked by organization governance. Use it to -point members to an internal support channel, ticket queue, or security contact. - -To set the message: + should confirm each destination before a sandbox can reach it. The policy's + detail page reports approval as **Required** or **Not required**. For more + details, see [Approval-required access](network.md#approval-required-access). -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 **Manage**. -1. In **Support message**, enter up to 500 characters. -1. Select **Save changes**. - -Docker shows the message only for denials caused by organization governance -policy and for requests an -[approval-required policy](network.md#approval-required-access) blocks. If you -leave it blank, Docker shows the policy denial without additional contact text. +For the number of policies and rules you can create, see +[Organization policy limits](../../reference/policy-limits.md). ## Scope policies to teams -An organization can have more than one policy, and each policy applies either -to the whole organization or to specific teams. Scoping lets you apply different -rules to different parts of the organization. - -A policy's [**Scope**](#create-a-policy) controls who it applies to. Set it to -**Organization** to apply the policy to every member, or to **Teams** to apply -it only to members of the teams you select. - -### Before you start +A policy's **Scope** controls who it applies to. Set it to **Organization** to +apply the policy to every licensed member, or to **Teams** to apply it only to +licensed members of the teams you select. For more details on how org-wide and +team-scoped policies combine, see +[Which policies apply to a developer](_index.md#which-policies-apply-to-a-developer). Team scoping targets your organization's existing [teams](/manuals/accounts/organization/manage/manage-a-team.md), so a team must @@ -87,20 +73,39 @@ in one of two ways: Because policies apply by team, a user's policies update automatically as their team membership changes, including changes synced from your IdP. -## Limits +## Edit or delete a policy -Organization policies have the following limits, which help ensure fair usage -and resource availability across organizations: +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**, **Filesystem access**, or **MCP access**. +1. Find the policy in the list. Each policy is listed with its name, scope, + rule count, and last update. +1. Select the action menu (⋮) for the policy, then select **Edit**, or delete + the policy. +1. If you're editing, make your changes and select **Save**. + +Editing a policy replaces it in full. For example, turning off **Require +approval before access** on a network policy removes the requirement from every +rule in that policy. Changes reach developer machines within 5 minutes. For more +details, see +[When policy changes reach developers](_index.md#when-policy-changes-reach-developers). -| Limit | Value | -|---------------------------|-----------------------------------------------------| -| Policies per organization | 100 | -| Rules per policy | 250 | -| Policy size | 400 KB total, shared across all of a policy's rules | +## Configure a support message -Typical policies use only a small fraction of the policy size limit. Domain -and file path values have no separate length limit beyond valid format. +Admins can add an optional support message that appears after the policy denial +details when a sandbox action is blocked by organization governance. Use it to +point members to an internal support channel, ticket queue, or security contact. -If these limits don't fit your organization's needs, -[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) -to discuss options. +To set the message: + +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 **Manage**. +1. In **Support message**, enter up to 500 characters. +1. Select **Save changes**. + +Docker shows the message only for denials caused by organization governance +policy and for requests an +[approval-required policy](network.md#approval-required-access) blocks. If you +leave it blank, Docker shows the policy denial without additional contact text. diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md b/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md index 89f9955608bc..6c3563323a11 100644 --- a/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md @@ -1,39 +1,66 @@ --- -title: Filesystem access policies +title: Organization filesystem access policies linkTitle: Filesystem -weight: 30 +weight: 20 description: Control which host paths Docker Sandboxes can mount as workspaces with organization filesystem policies. keywords: docker sandboxes, filesystem access, filesystem mount rules, workspace mount, organization policy, governance aliases: - /ai/sandboxes/governance/access-controls/filesystem/ --- +{{< summary-bar feature_name="AI Governance" >}} + Filesystem access policies are organization policies that control which host -paths a sandbox can mount as a workspace. Each policy contains one or more -filesystem mount rules that restrict sandbox workspaces to approved -directories. These rules control which host paths a sandbox can mount. They -don't control access to individual files inside an allowed mount. +paths a sandbox can mount as a workspace. When an organization policy is +enforced for a developer, a sandbox can mount a host path only if a filesystem +rule allows it, so a developer can't create a sandbox for a workspace your +policies don't allow. Each policy contains one or more filesystem mount rules +that restrict sandbox workspaces to approved directories. These rules control +which host paths a sandbox can mount. They don't control access to individual +files inside an allowed mount. + +This page explains what a filesystem rule can match, how organization rules +change what developers can mount, and when your changes reach developers. To create a filesystem access policy, see -[Create and manage policies](create-manage.md). For path patterns and the -`read` and `write` actions, see +[Create and manage organization policies](create-manage.md). For path patterns +and the `read` and `write` actions, see [Filesystem mount rule syntax](../../reference/filesystem-rules.md). -When an organization policy is enforced for you, organization filesystem mount -rules decide which paths a sandbox can mount, and the filesystem allow rules -from your local preset stop applying. See [Precedence](_index.md#precedence). +## What a filesystem rule can match -## When changes take effect +Each filesystem mount rule allows or denies one or both of two actions on the +host paths it lists: -Filesystem policy is checked only when a workspace is mounted, which happens -when a sandbox is created. Changing the filesystem policy has no effect on a -running sandbox, which keeps access to the previously allowed path. To apply a -filesystem policy change, remove the sandbox and create a new one. +- `read` lets a sandbox mount the path as a read-only workspace. +- `write`, together with `read`, lets a sandbox mount the path as a writable + workspace. -## Troubleshooting +A writable workspace needs both a `read` and a `write` rule that allow it. A +read-only workspace needs only `read`. + +Paths can use wildcards, and `~` expands to each user's home directory on +every platform, so a single `~/**` rule matches every developer's home tree. +For the path formats on each operating system and how wildcards match, see +[Filesystem mount rule syntax](../../reference/filesystem-rules.md). -### Sandbox cannot mount workspace +## How organization rules change what developers can mount + +Without an organization policy, a sandbox can mount any host path the developer +chooses. Developers can't add filesystem rules with local policy, which manages +network rules only. Local policy does include two built-in rules that allow +read and write access to every path, which developers see as `default-fs-*` +rules in `sbx policy ls --wide`. + +When an organization policy is enforced for a developer, organization filesystem +mount rules decide which paths a sandbox can mount instead, and those built-in +rules stop applying. For more details, see +[How organization policy relates to local and kit rules](_index.md#how-organization-policy-relates-to-local-and-kit-rules). + +## When changes take effect -If a sandbox fails to mount with a `mount policy denied` error, verify that the -filesystem allow rule uses `**` rather than `*`. A single `*` doesn't match -across directory separators. +Filesystem policy is checked when a sandbox is created and each time it starts. +Once a policy change has +[synced to the developer's machine](_index.md#when-policy-changes-reach-developers), +it applies the next time a sandbox starts. A sandbox that's already running +keeps its mount until it stops. diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/mcp.md b/content/manuals/ai/sandboxes/governance/organization/policies/mcp.md index 39d5a8e68aab..bfe0520e2b1f 100644 --- a/content/manuals/ai/sandboxes/governance/organization/policies/mcp.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/mcp.md @@ -1,13 +1,15 @@ --- -title: MCP access policies +title: Organization MCP access policies linkTitle: MCP -weight: 40 +weight: 30 description: Use Cedar-based policies to control MCP server registration and activity routed through the Docker Sandboxes MCP gateway. keywords: docker sandboxes, MCP policy, MCP access, Cedar policy, requireApproval, AI Governance aliases: - /ai/sandboxes/governance/access-controls/mcp/ --- +{{< summary-bar feature_name="AI Governance" >}} + MCP access policies let organization administrators control which Model Context Protocol (MCP) servers developers can register and what agents can do through Docker's MCP gateway. Use these policies to approve trusted servers, @@ -19,24 +21,30 @@ MCP access policies apply only to server registration and requests handled by Docker's MCP gateway. They don't govern an MCP server that an agent or MCP client configures and connects to directly from inside the sandbox. A direct connection to a remote MCP server is outbound sandbox traffic, so -[network access policy](network.md) determines whether the sandbox can reach -the server. To prevent access through both paths, block the server in MCP -access policy and block its network destination in network access policy. - -Unlike [network access policies](network.md) and -[filesystem access policies](filesystem.md), MCP policies are organization -policies written in Cedar. In the -[Governance API](/reference/api/ai-governance/), an MCP policy is a `cedar_v1` -policy whose rules are the Cedar statements in the policy text, rather than -separate rules managed through the rules endpoints. Docker defines the `MCP` -namespace, including the -actions, resource types, attributes, and approval behavior that policies can -match. This page focuses on representative access patterns. For Docker's exact +[organization network access policies](network.md) determine whether the +sandbox can reach the server. To prevent access through both paths, block the +server in MCP access policy and block its network destination in network access +policy. + +Unlike [organization network access policies](network.md) and +[organization filesystem access policies](filesystem.md), MCP policies are +organization policies written in Cedar. In the +[AI Governance API](/reference/api/ai-governance/), an MCP policy is a +`cedar_v1` policy whose rules are the Cedar statements in the policy text, +rather than separate rules managed through the rules endpoints. Docker defines +the `MCP` namespace, including the actions, resource types, attributes, and +approval behavior that policies can match. This page focuses on representative access patterns. For Docker's exact policy surface, see the [MCP policy reference](../../reference/mcp-policy.md). For Cedar syntax and language semantics, see the [Cedar documentation](https://docs.cedarpolicy.com/). -## Govern the server lifecycle +This page explains where MCP policy applies, how to choose between an allowlist +and a blocklist, example policies for common tasks, and when your changes reach +developers. To create an MCP access policy and set its scope, see +[Create and manage organization policies](create-manage.md). MCP policy +decisions are recorded in [audit logs](../audit/_index.md). + +## Where MCP policy applies MCP policy applies at two points in a server's lifecycle. A rule for one point doesn't automatically govern the other. @@ -65,7 +73,7 @@ Use-time policy doesn't hide or remove existing registrations. Tool and resource listings can also include entries that policy denies when an agent tries to use them. -## Choose an access posture +## Allowlist and blocklist policies When MCP policy enforcement is active for a user, registration and governed MCP requests are denied unless a matching `permit` allows them. A matching `forbid` @@ -86,7 +94,13 @@ matching users, teams, tenants, or roles in Cedar. If MCP policy enforcement isn't active for a user, the gateway doesn't evaluate Cedar policy and permits MCP activity. MCP doesn't have a local preset equivalent to network policy. -## Approve a server +## Example policies + +The following policies show common ways to approve, confirm, withdraw, and +restrict MCP servers. Combine them in one policy or split them across policies, +and adapt the server names and identity URLs to your own servers. + +### Approve a server For an allowlist, approve both the server registration and its use-time capabilities. The following policy approves a remote server only when it is @@ -122,7 +136,7 @@ It prevents a developer from registering another endpoint under the approved name or registering the approved endpoint under another name. Remove the resource or prompt permit if users don't need that capability. -## Require confirmation with MCP elicitation +### Require confirmation with MCP elicitation Use `@requireApproval` to require per-request confirmation through MCP. When a request matches the annotated `permit`, the gateway sends an @@ -180,7 +194,7 @@ permit with `@requireApproval` results in a denial. Tool calls made from an execution context that can't relay an elicitation, including calls from inside `code-mode`, are also denied. -## Withdraw server access +### Withdraw server access To withdraw access from a server that broader rules permit, block it at registration and at use time. Registration policy controls future `sbx mcp add` @@ -221,7 +235,7 @@ forbid (principal, action == MCP::Action::"invokePrimordial", resource) when { resource in MCP::Primordial::"example-authorize" }; ``` -## Restrict host-run servers +### Restrict host-run servers Local stdio servers run on the host, outside the sandbox VM. This includes explicit host commands and OCI-packaged stdio servers started with host Docker. @@ -242,23 +256,16 @@ metadata with `--local`. ## When changes take effect -- MCP registration policy is evaluated when a server is registered with - `sbx mcp add`. Changing registration rules doesn't remove existing - registrations or stop an already-loaded server by itself. +MCP registration policy is evaluated when a server is registered with +`sbx mcp add`. Changing registration rules doesn't remove existing +registrations or stop an already-loaded server by itself. -- MCP use-time policy is evaluated by the MCP gateway when a sandbox makes a - governed MCP request, such as a tool call, resource read, prompt retrieval, - or built-in gateway tool call. Once a policy change has synced, use-time - rules apply to subsequent governed MCP requests through the gateway. +MCP use-time policy is evaluated by the MCP gateway when a sandbox makes a +governed MCP request, such as a tool call, resource read, prompt retrieval, or +built-in gateway tool call. Once a policy change has +[synced to the developer's machine](_index.md#when-policy-changes-reach-developers), +use-time rules apply to subsequent governed MCP requests through the gateway. To prevent use of an MCP server that is already registered or loaded, add -use-time rules for the registered server name. See +use-time rules for the registered server name. For more details, see [Withdraw server access](#withdraw-server-access). - -## Related information - -- [MCP policy reference](../../reference/mcp-policy.md): exact action, resource, - attribute, context, and approval behavior. -- [Create and manage policies](create-manage.md): policy creation and scope. -- [MCP policy audit logs](../audit/_index.md): policy decision - records. diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/network.md b/content/manuals/ai/sandboxes/governance/organization/policies/network.md index 9fb352480e33..d1fcddaf709f 100644 --- a/content/manuals/ai/sandboxes/governance/organization/policies/network.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/network.md @@ -1,50 +1,68 @@ --- -title: Network access policies +title: Organization network access policies linkTitle: Network -weight: 20 +weight: 10 description: Control outbound network access from Docker Sandboxes with organization network policies. keywords: docker sandboxes, network access, network rules, HTTP rules, approval, governance, organization policy aliases: - /ai/sandboxes/governance/access-controls/network/ --- +{{< summary-bar feature_name="AI Governance" >}} + Network access policies are organization policies that 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. 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. +connections from sandboxes. When an organization policy is enforced for a +developer, their sandboxes can reach only the destinations your network rules +allow. 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. 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. + +For destinations you want a person to confirm, a policy can require approval +instead of granting access outright. This page explains what a rule can match, +how approval works, and when your changes reach developers. To create a network access policy, see -[Create and manage policies](create-manage.md). For hostname patterns, CIDR -ranges, and how HTTP rules combine with network rules, see +[Create and manage organization policies](create-manage.md). For hostname +patterns, CIDR ranges, and how HTTP rules combine with network rules, see [Network and HTTP rule syntax](../../reference/network-rules.md). Developers can also add network rules on their own machines with [local policy](../../local/network-rules.md). For how local and organization -rules combine, see [Precedence](_index.md#precedence). +rules combine, see +[How organization policy relates to local and kit rules](_index.md#how-organization-policy-relates-to-local-and-kit-rules). -## Network rule fields +## What a network rule can match Each rule has an optional **Rule name**, a **Type** that decides what the rule -matches, and a **Decision** of **Allow** or **Deny**. - -- **HTTP** matches only HTTP requests with the methods and paths you specify. - - In **Destination**, enter the host or IP address the rule covers. It - matches any port unless you add one. Enter the destination with no scheme - and no path, so `api.github.com` rather than - `https://api.github.com/repos`. - - Under **HTTP methods**, select the methods the rule applies to. Use - **Select all** to select every method, or **Read-only** to select `GET`, - `HEAD`, and `OPTIONS`. Select at least one method. A rule with no methods - selected fails validation. The composer doesn't list `CONNECT` or `TRACE`, - which differs from the CLI, where `--method ANY` matches every HTTP method. - - Under **Path patterns**, add one or more paths the rule covers, such as - `/repos/*` and `/v1/**`. Leave it empty to match any path. -- **All traffic** matches every request to the destinations you list, on any - port, method, and path. - - Under **Protocols**, select **TCP**, **UDP**, or **Both**. - - 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`. +matches, and a **Decision** of **Allow** or **Deny**. The type is either +**All traffic**, which covers whole destinations, or **HTTP**, which covers +specific requests to one destination. + +### All traffic rules + +An **All traffic** rule matches every request to the destinations you list, on +any port, method, and path. + +- Under **Protocols**, select **TCP**, **UDP**, or **Both**. +- 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`. + +### HTTP rules + +An **HTTP** rule matches only HTTP requests with the methods and paths you +specify. + +- In **Destination**, enter the host or IP address the rule covers. It matches + any port unless you add one. Enter the destination with no scheme and no + path, so `api.github.com` rather than `https://api.github.com/repos`. +- Under **HTTP methods**, select the methods the rule applies to. Use + **Select all** to select every method, or **Read-only** to select `GET`, + `HEAD`, and `OPTIONS`. Select at least one method. A rule with no methods + selected fails validation. The composer doesn't list `CONNECT` or `TRACE`, + which differs from the CLI, where `--method ANY` matches every HTTP method. +- Under **Path patterns**, add one or more paths the rule covers, such as + `/repos/*` and `/v1/**`. 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 @@ -56,7 +74,9 @@ combine with **All traffic** rules, see 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. +putting a person in front of each destination an agent reaches for. To turn +it on when you create or edit a policy, see +[Create and manage organization policies](create-manage.md). Under organization governance, approval is a property of the policy rather than of individual rules, so turning it on applies it to every allow rule in @@ -64,46 +84,30 @@ that policy. A destination stays directly reachable only when no policy that allows it requires 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](https://github.com/docker/sandbox-kit-spec/blob/main/docs/spec/capabilities/com.docker.sandbox/network-policy@1.md), -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. - -Network approval is separate from the MCP `@requireApproval` annotation. An MCP -approval confirms a single call within the session and creates no rule, while -an approved network destination stays allowed until you remove the rule. See -[MCP access policies](mcp.md). - -### Require approval for a network policy +Only a destination the developer has already approved satisfies the requirement. +Preset rules, kit-defined rules, 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. -Turning on **Require approval before access** means the destinations a network -policy allows aren't reachable until the developer confirms each one. +Developers respond to approval requests from the command line. For what they +see and how they respond, see +[Respond to approval requests](../../local/approvals.md). -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. In the policy list, open the policy's action menu (⋮) and select **Edit**. -1. Turn on **Require approval before access**. -1. Select **Save**. - -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. +Network approval is separate from the MCP `@requireApproval` annotation. An MCP +approval confirms a single call within the session and creates no rule, while an +approved network destination stays allowed until you remove the rule. For more +details, see [Organization MCP access policies](mcp.md). ## When changes take effect -- 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. HTTP rules are evaluated per request in - the same way. +Network policy is evaluated on every outbound request. Once a policy change has +[synced to the developer's machine](_index.md#when-policy-changes-reach-developers), +it applies 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. +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. diff --git a/content/manuals/ai/sandboxes/governance/organization/sign-in-enforcement.md b/content/manuals/ai/sandboxes/governance/organization/sign-in-enforcement.md index f1e1ee246223..fb2ed8a021dc 100644 --- a/content/manuals/ai/sandboxes/governance/organization/sign-in-enforcement.md +++ b/content/manuals/ai/sandboxes/governance/organization/sign-in-enforcement.md @@ -1,6 +1,6 @@ --- -title: Sign-in enforcement -linkTitle: Enforce sign in +title: Enforce sign-in for Docker Sandboxes +linkTitle: Enforce sign-in weight: 20 description: Require Docker Sandboxes users to sign in as members of your organization, enforced through endpoint management. keywords: docker sandboxes, sign-in enforcement, organization enforcement, sbx login, MDM, configuration profile, registry key, allowedOrgs @@ -9,23 +9,19 @@ aliases: - /ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement/ --- -Sign-in enforcement restricts Docker Sandboxes to users who are members of -specific Docker organizations. An administrator deploys an enforcement -configuration to managed endpoints, and `sbx login` verifies organization -membership after the user authenticates. If the check fails, credentials are -immediately revoked and the user can't run sandboxes. +{{< summary-bar feature_name="AI Governance" >}} -Without this enforcement, a developer can sign in with a personal account and -bypass organization [governance policies](_index.md). -Sign-in enforcement closes that gap at the endpoint, where users can't override -it. +Your organization's [governance policies](_index.md) apply only when a +developer signs in to Docker Sandboxes as a member of your organization. +Without sign-in enforcement, a developer can sign in with a personal account +and bypass those policies. Sign-in enforcement closes that gap on the machine +itself, where users can't override it. -> [!NOTE] -> Sign-in enforcement is part of Docker's AI Governance offering. -> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) -> to learn more. +To set it up, you write an enforcement configuration that lists your +organizations, test it on one machine, then deploy it to your developers' +machines with your endpoint management tooling. -## How it works +## How sign-in enforcement works 1. An administrator deploys an enforcement configuration to managed endpoints through MDM, Group Policy, or configuration management, specifying one or @@ -36,17 +32,18 @@ it. 3. If the user belongs to at least one allowed organization, login succeeds and the credentials are kept. 4. If not, Docker Sandboxes immediately revokes the saved credentials and the - user receives an [error message](#error-messages) listing the required - organizations. + user receives a [denial message](#check-what-denied-developers-see) listing + the required organizations. `sbx login` and `sbx logout` always run regardless of organization membership. Other commands require a valid signed-in session, so they fail after a denied login until the user signs in with an allowed account. -## Enforcement configuration +## Write the enforcement configuration -All platforms express the same logical schema. The canonical JSON -representation: +The configuration lists the organizations developers must belong to, and +optionally who to contact for access. Every platform uses the same fields. The +canonical JSON representation: ```json { @@ -71,7 +68,82 @@ The optional `adminName`, `adminEmail`, and `adminURL` fields give denied users a path to resolution. Include the contact details your organization uses for access requests. -## Deploy the configuration +## Test the configuration on one machine + +Before you deploy to every machine, write the configuration on one machine and +confirm that `sbx login` behaves as you expect. + +{{< tabs >}} +{{< tab name="macOS" >}} + +Write the configuration to the user preferences domain: + +```console +$ defaults write com.docker.sbx allowedOrgs -array "acme-corp" +$ defaults write com.docker.sbx adminEmail "it@acme.com" +``` + +To remove the test configuration: + +```console +$ defaults delete com.docker.sbx +``` + +`defaults write` uses the user preferences domain, not the managed-preferences +domain. On a managed device, the MDM profile is authoritative and user-level +settings in the same domain are ignored. + +{{< /tab >}} +{{< tab name="Windows" >}} + +Run the following in an elevated PowerShell session. Use `New-ItemProperty` to +create values with an explicit type. `Set-ItemProperty` doesn't create new +values. + +```powershell +New-Item -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" -Force + +New-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" ` + -Name "allowedOrgs" -Value @("acme-corp") -PropertyType MultiString -Force +New-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" ` + -Name "adminEmail" -Value "it@acme.com" -PropertyType String -Force +``` + +To remove the test configuration: + +```powershell +Remove-Item -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" -Recurse -Force +``` + +{{< /tab >}} +{{< tab name="Linux" >}} + +Write the configuration file and set its ownership: + +```console +$ sudo mkdir -p /etc/docker-sbx +$ sudo tee /etc/docker-sbx/config.json <<'EOF' +{"allowedOrgs": ["acme-corp"], "adminEmail": "it@acme.com"} +EOF +$ sudo chown root:root /etc/docker-sbx/config.json +$ sudo chmod 644 /etc/docker-sbx/config.json +``` + +To remove the test configuration: + +```console +$ sudo rm -f /etc/docker-sbx/config.json +``` + +{{< /tab >}} +{{< /tabs >}} + +Then run `sbx login` with an account that belongs to an allowed organization, +and again with one that doesn't. The second sign-in is denied with the message +described in +[Check what denied developers see](#check-what-denied-developers-see). + +## Deploy the configuration to your managed machines Use your existing endpoint management tooling to deploy the configuration. Each platform reads it from a native location that ordinary users can't modify. @@ -140,29 +212,12 @@ contact details: ``` -To test the configuration locally without MDM, write to the user preferences -domain: - -```console -$ defaults write com.docker.sbx allowedOrgs -array "acme-corp" -$ defaults write com.docker.sbx adminEmail "it@acme.com" -``` - -To remove the test configuration: - -```console -$ defaults delete com.docker.sbx -``` - -`defaults write` uses the user preferences domain, not the managed-preferences -domain. On a managed device, the MDM profile is authoritative and user-level -settings in the same domain are ignored. - {{< /tab >}} {{< tab name="Windows" >}} -Deploy it through Group Policy, Intune, or any endpoint management tool that can -write registry values. +On Windows, the configuration is a set of registry values under +`HKLM\SOFTWARE\Policies\Docker\SBX`. Deploy them through Group Policy, Intune, +or any endpoint management tool that can write registry values. | Value name | Type | Description | | ------------- | -------------- | --------------------------------------------------- | @@ -171,25 +226,6 @@ write registry values. | `adminEmail` | `REG_SZ` | Contact email (optional) | | `adminURL` | `REG_SZ` | Help desk URL (optional) | -To test the configuration locally, run the following in an elevated PowerShell -session. Use `New-ItemProperty` to create values with an explicit type; -`Set-ItemProperty` doesn't create new values. - -```powershell -New-Item -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" -Force - -New-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" ` - -Name "allowedOrgs" -Value @("acme-corp") -PropertyType MultiString -Force -New-ItemProperty -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" ` - -Name "adminEmail" -Value "it@acme.com" -PropertyType String -Force -``` - -To remove the configuration: - -```powershell -Remove-Item -Path "HKLM:\SOFTWARE\Policies\Docker\SBX" -Recurse -Force -``` - {{< /tab >}} {{< tab name="Linux" >}} @@ -208,37 +244,22 @@ Salt. The file must be owned by root with `644` permissions. } ``` -To deploy and set ownership: - -```console -$ sudo mkdir -p /etc/docker-sbx -$ sudo tee /etc/docker-sbx/config.json <<'EOF' -{"allowedOrgs": ["acme-corp"], "adminEmail": "it@acme.com"} -EOF -$ sudo chown root:root /etc/docker-sbx/config.json -$ sudo chmod 644 /etc/docker-sbx/config.json -``` - -To remove the configuration: - -```console -$ sudo rm -f /etc/docker-sbx/config.json -``` - The Linux loader fails closed if the file is a symlink, isn't a regular file, isn't owned by root, or is writable by group or other. Any deviation is treated as a configuration error and `sbx login` is denied with a descriptive message. -Deploying with the commands above passes these checks. +Deploying with the commands in +[Test the configuration on one machine](#test-the-configuration-on-one-machine) +passes these checks. {{< /tab >}} {{< /tabs >}} -## Error messages +## Check what denied developers see When a user signs in with an account that isn't a member of an allowed organization, they're signed out and shown a denial message. Only the contact -fields you configure appear: if only `adminEmail` is set, the URL line is -omitted. +fields you configure appear. For example, if only `adminEmail` is set, the URL +line is omitted. When no admin contact details are configured: @@ -263,11 +284,9 @@ For access, contact ACME IT Security: URL: https://acme-corp.atlassian.net/servicedesk/it ``` -## Related pages +## Turn off enforcement -- [Organization governance](_index.md): centrally manage - sandbox network, filesystem, and MCP policies in Docker Home -- [Governance overview](../_index.md): how local and organization governance fit - together -- [Enforce sign-in for Docker Desktop](/manuals/desktop/enterprise/enforce-sign-in/_index.md): - the equivalent control for Docker Desktop +To turn off sign-in enforcement on a machine, remove the configuration with +the same tooling you used to deploy it. You can also leave `allowedOrgs` empty, +which makes enforcement inactive so any authenticated user can use Docker +Sandboxes. diff --git a/content/manuals/ai/sandboxes/governance/reference/_index.md b/content/manuals/ai/sandboxes/governance/reference/_index.md index 791a387e4c2b..ad9577629042 100644 --- a/content/manuals/ai/sandboxes/governance/reference/_index.md +++ b/content/manuals/ai/sandboxes/governance/reference/_index.md @@ -1,15 +1,6 @@ --- +build: + render: never title: Reference weight: 30 -description: Reference material for Docker AI Governance policy APIs and policy syntax. -keywords: docker sandboxes, governance reference, governance API, policy reference --- - -Use reference material when you need API details or exact policy syntax. - -- [Network and HTTP rule syntax](network-rules.md) and - [Filesystem mount rule syntax](filesystem-rules.md): rule syntax. -- [AI Governance API](/reference/api/ai-governance/): HTTP API reference for - network, filesystem, and MCP organization policies. -- [MCP policy reference](mcp-policy.md): Docker MCP policy actions, resources, - attributes, context fields, and approval behavior. diff --git a/content/manuals/ai/sandboxes/governance/reference/audit-records.md b/content/manuals/ai/sandboxes/governance/reference/audit-records.md index 9c928c9b4ab4..de00b7e65d90 100644 --- a/content/manuals/ai/sandboxes/governance/reference/audit-records.md +++ b/content/manuals/ai/sandboxes/governance/reference/audit-records.md @@ -17,47 +17,47 @@ action. ## Common fields -| Field | Description | -| ------------------ | ---------------------------------------------------------------------------------------------------------------- | -| `audit_event_id` | Unique ID for the audit event. | -| `timestamp` | UTC time when Docker recorded the event. | -| `schema_version` | Version of the record schema. Pin SIEM field mappings to this value. | -| `category` | Event category, such as `AUDIT_CATEGORY_MANAGEMENT`, `AUDIT_CATEGORY_EVALUATION`, or `AUDIT_CATEGORY_EXECUTION`. | -| `decision` | Governance decision for evaluation records. | -| `username` | The signed-in Docker user's Docker Hub username. | -| `user_email` | The signed-in Docker user's email address. | -| `org_id` | ID of the organization whose governance policy is in effect. | -| `org_name` | Display name of the organization whose governance policy is in effect. | -| `audit_session_id` | Identifies the daemon session that produced the record. | -| `resource_id` | Target of the evaluation, such as a host and port, file path, or tool. | -| `os` | Operating system that produced the record. | -| `app_version` | Version of the Docker component that produced the record. | -| `client_name` | Source component, such as `sbx` for Docker Sandboxes. | -| `hostname` | Hostname of the machine that produced the record. | -| `sandbox_id` | Stable ID of the sandbox. It persists across restarts of the same sandbox. | -| `deny_reason` | Why a denied request was blocked. Present on deny decisions. | -| `policy_rule` | Name of the policy rule that matched, or `default-deny` when no rule matched. | -| `policy_id` | ID of the policy that produced the decision. | -| `policy_type` | Schema type of the policy, such as `allowlist/v0` or `cedar:auth:v0`. | -| `policy_source` | Origin of the policy: `remote`, `local`, or `system`. | -| `policy_denial_code` | Why a request was denied. Present only on deny decisions. See [Denial codes](#denial-codes). | -| `enforcement_mode` | Governance mode in effect when Docker evaluated the request. See [Enforcement modes](#enforcement-modes). | -| `approval` | Approval details. Present when the decision involves an approval. See [Approval fields](#approval-fields). | -| `action_type` | Payload discriminator that identifies the action-specific object in the record. | -| `agent` | AI agent associated with the event, when Docker knows it. | +| Field | Description | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------- | +| `audit_event_id` | Unique ID for the audit event. | +| `timestamp` | UTC time when Docker recorded the event. | +| `schema_version` | Version of the record schema. Pin SIEM field mappings to this value. | +| `category` | Event category, such as `AUDIT_CATEGORY_MANAGEMENT`, `AUDIT_CATEGORY_EVALUATION`, or `AUDIT_CATEGORY_EXECUTION`. | +| `decision` | Governance decision for evaluation records. | +| `username` | The signed-in Docker user's Docker Hub username. | +| `user_email` | The signed-in Docker user's email address. | +| `org_id` | ID of the organization whose governance policy is in effect. | +| `org_name` | Display name of the organization whose governance policy is in effect. | +| `audit_session_id` | Identifies the daemon session that produced the record. | +| `resource_id` | Target of the evaluation, such as a host and port, file path, or tool. | +| `os` | Operating system that produced the record. | +| `app_version` | Version of the Docker component that produced the record. | +| `client_name` | Source component, such as `sbx` for Docker Sandboxes. | +| `hostname` | Hostname of the machine that produced the record. | +| `sandbox_id` | Stable ID of the sandbox. It persists across restarts of the same sandbox. | +| `deny_reason` | Why a denied request was blocked. Present on deny decisions. | +| `policy_rule` | Name of the policy rule that matched, or `default-deny` when no rule matched. | +| `policy_id` | ID of the policy that produced the decision. | +| `policy_type` | Schema type of the policy, such as `AllowList:V0`. | +| `policy_source` | Origin of the policy: `remote`, `local`, or `system`. | +| `policy_denial_code` | Why a request was denied. Present only on deny decisions. For more details, see [Denial codes](#denial-codes). | +| `enforcement_mode` | Governance mode in effect when Docker evaluated the request. For more details, see [Enforcement modes](#enforcement-modes). | +| `approval` | Approval details. Present when the decision involves an approval. For more details, see [Approval fields](#approval-fields). | +| `action_type` | Payload discriminator that identifies the action-specific object in the record. | +| `agent` | AI agent associated with the event, when Docker knows it. | ### Denial codes `policy_denial_code` classifies why a request was denied: -| Code | Meaning | -| --- | --- | -| `POLICY_DENIAL_CODE_POLICY_DENY` | A deny rule matched. `policy_id` and `policy_rule` identify it. | -| `POLICY_DENIAL_CODE_DEFAULT_DENY` | No rule allowed the request, so default deny applied. | -| `POLICY_DENIAL_CODE_POLICY_SNAPSHOT_STALE` | The cached policy expired, so evaluation failed closed. | -| `POLICY_DENIAL_CODE_POLICY_EVALUATION_FAILED` | Loading or evaluating the policy failed, so evaluation failed closed. | -| `POLICY_DENIAL_CODE_GOVERNANCE_BLOCKED` | Governance couldn't be resolved for the user, for example because of membership in several organizations, so the request was denied without consulting local rules. | -| `POLICY_DENIAL_CODE_INVALID_REQUEST` | The request was malformed, so evaluation failed closed. | +| Code | Meaning | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `POLICY_DENIAL_CODE_POLICY_DENY` | A deny rule matched. `policy_id` and `policy_rule` identify it. | +| `POLICY_DENIAL_CODE_DEFAULT_DENY` | No rule allowed the request, so default deny applied. | +| `POLICY_DENIAL_CODE_POLICY_SNAPSHOT_STALE` | The cached policy expired, so evaluation failed closed. | +| `POLICY_DENIAL_CODE_POLICY_EVALUATION_FAILED` | Loading or evaluating the policy failed, so evaluation failed closed. | +| `POLICY_DENIAL_CODE_GOVERNANCE_BLOCKED` | Governance couldn't be resolved for the user, for example because of membership in several organizations, so the request was denied without consulting local rules. | +| `POLICY_DENIAL_CODE_INVALID_REQUEST` | The request was malformed, so evaluation failed closed. | ## Categories @@ -131,25 +131,25 @@ an `AUDIT_DECISION_DENY` decision and includes the `approval` object. The `action_type` field identifies the action-specific payload in the record. -| Action type | Description | -| ---------------------------- | --------------------------------------------------------------------------- | -| `session` | Sandbox daemon session lifecycle event. | -| `network_egress` | Network access evaluation. | -| `http_request` | HTTP request evaluation. See [HTTP request payload](#http-request-payload). | -| `filesystem_mount` | Filesystem mount or path access evaluation. | -| `tool_invocation` | Tool invocation evaluation. | -| `resource_read` | Resource read evaluation. | -| `server_registration` | Server registration event. | -| `prompt` | Prompt-related metadata event. | -| `network_egress_execution` | Outcome of a network action. | -| `filesystem_mount_execution` | Outcome of a filesystem action. | -| `tool_execution` | Outcome of a tool invocation. | -| `resource_read_execution` | Outcome of a resource read. | -| `prompt_execution` | Outcome of a prompt request. | -| `policy_sync` | Policy synchronization event. | -| `pii_detection` | Metadata event for a data detection result. | -| `c_score_report` | Metadata event for a C-score report. | -| `policy_action` | Policy configuration or policy action event. | +| Action type | Description | +| ---------------------------- | --------------------------------------------------------------------------------------------- | +| `session` | Sandbox daemon session lifecycle event. | +| `network_egress` | Network access evaluation. | +| `http_request` | HTTP request evaluation. For more details, see [HTTP request payload](#http-request-payload). | +| `filesystem_mount` | Filesystem mount or path access evaluation. | +| `tool_invocation` | Tool invocation evaluation. | +| `resource_read` | Resource read evaluation. | +| `server_registration` | Server registration event. | +| `prompt` | Prompt-related metadata event. | +| `network_egress_execution` | Outcome of a network action. | +| `filesystem_mount_execution` | Outcome of a filesystem action. | +| `tool_execution` | Outcome of a tool invocation. | +| `resource_read_execution` | Outcome of a resource read. | +| `prompt_execution` | Outcome of a prompt request. | +| `policy_sync` | Policy synchronization event. | +| `pii_detection` | Metadata event for a data detection result. | +| `c_score_report` | Metadata event for a C-score report. | +| `policy_action` | Policy configuration or policy action event. | ## HTTP request payload @@ -167,29 +167,38 @@ separate from the `network_egress` record for the connection. ## Sample record +The following sample shows a request that a deny rule blocked: + ```json { - "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80", - "timestamp": "2026-05-28T19:15:00.728933Z", - "schema_version": "1.82.0", + "audit_event_id": "032d5bf2-6be0-484c-9fd1-296680bb9af4", + "timestamp": "2026-10-22T21:15:32.674118Z", + "schema_version": "1.228.0", "category": "AUDIT_CATEGORY_EVALUATION", "decision": "AUDIT_DECISION_DENY", "username": "jordandoe", "user_email": "jordandoe@example.com", + "audit_session_id": "d038717d-e86d-48c5-abbb-19b7f14c37c8", + "agent": "shell", + "sandbox_id": "my-sandbox", + "resource_id": "example.com:443", + "policy_rule": "local:fa56f4d3-7f16-4144-af84-caa7917b2387", + "policy_id": "f588126a-8323-47d5-b099-b3d184055733", + "policy_type": "AllowList:V0", + "policy_source": "local", + "policy_denial_code": "POLICY_DENIAL_CODE_POLICY_DENY", "org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", "org_name": "Acme Inc", - "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", - "resource_id": "example.com:443", - "os": "macos", - "app_version": "v0.31.0", + "os": "windows", + "app_version": "v0.48.0", "client_name": "sbx", "hostname": "host-machine", "deny_reason": [ - "no applicable policies for op(action=net:connect:tcp, resource=net:domain:example.com:443)" + "denied: rule \"local:fa56f4d3-7f16-4144-af84-caa7917b2387\" matched op(action=net:connect:tcp, resource=net:domain:example.com:443)" ], + "enforcement_mode": "audit", "action_type": "network_egress", - "network_egress": { "protocol": "tcp" }, - "agent": "claude" + "network_egress": { "destination_port": "443", "protocol": "tcp" } } ``` diff --git a/content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md b/content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md index 544d0098bac4..98ac562d67cf 100644 --- a/content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md +++ b/content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md @@ -5,12 +5,15 @@ description: Syntax for sandbox filesystem rules, including path patterns across keywords: docker sandboxes, filesystem rules, path patterns, workspace mount, rule syntax --- -Filesystem mount rules use the actions `read` and `write`. Resources are host -paths that sandboxes can mount as workspaces. The rules control which paths a -sandbox can mount, not access to individual files inside an allowed mount. +Filesystem mount rules are written in organization +[organization filesystem access policies](../organization/policies/filesystem.md). +Developers can't add them with local policy. Filesystem mount rules use the +actions `read` and `write`. Resources are host paths that sandboxes can mount +as workspaces. The rules control which paths a sandbox can mount, not access to +individual files inside an allowed mount. 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 +`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, @@ -45,4 +48,4 @@ path segment and won't cross a path separator. For example, `~/**` matches all paths under the home directory, while `~/*` matches only its direct children. For organization policy configuration and enforcement details, see -[Filesystem access policies](../organization/policies/filesystem.md). +[Organization filesystem access policies](../organization/policies/filesystem.md). diff --git a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md index 0c298665ed11..68425f347085 100644 --- a/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md +++ b/content/manuals/ai/sandboxes/governance/reference/mcp-policy.md @@ -15,8 +15,9 @@ control future `sbx mcp add` operations. Use-time rules control tool calls, gateway meta-tools, resource reads, and prompt retrieval from servers that are already registered or loaded. -Use this reference with [MCP access policies](../organization/policies/mcp.md) for -common policy patterns. For the Cedar language, see the +Use this reference with +[Organization MCP access policies](../organization/policies/mcp.md) for common +policy patterns. For the Cedar language, see the [Cedar documentation](https://docs.cedarpolicy.com/). ## Evaluation model @@ -32,7 +33,7 @@ Governed MCP activity is default deny. A request is blocked unless a matching permit annotated with `@requireApproval`. For details about when Docker Sandboxes evaluates MCP policies for a user, see -[Govern the server lifecycle](../organization/policies/mcp.md#govern-the-server-lifecycle). +[Where MCP policy applies](../organization/policies/mcp.md#where-mcp-policy-applies). An actionless `permit` matches every MCP action that reaches Cedar evaluation: @@ -87,8 +88,8 @@ and are advisory. | `resource.destructive` | Tools | Defaults to `true` when a tool doesn't declare it. | | `resource.idempotent` | Tools | Defaults to `false` when a tool doesn't declare it. | | `resource.openWorld` | Tools | Defaults to `true` when a tool doesn't declare it. | -| `resource.type` | Servers | Use for server registration rules. See [Server type values](#server-type-values). | -| `resource.identityURL` | Servers | Canonical server identity. The value depends on the registration type. See [Server identity values](#server-identity-values). | +| `resource.type` | Servers | Use for server registration rules. For more details, see [Server type values](#server-type-values). | +| `resource.identityURL` | Servers | Canonical server identity. The value depends on the registration type. For more details, see [Server identity values](#server-identity-values). | | `resource.requiresOAuth` | Servers | Use for server registration rules. | | `resource.requiresNetwork` | Servers | Use for server registration rules. | | `resource.command` | Servers | Local stdio server command, such as `npx` or `docker`, when available. Empty for remote servers and registrations that don't include command details. | diff --git a/content/manuals/ai/sandboxes/governance/reference/network-rules.md b/content/manuals/ai/sandboxes/governance/reference/network-rules.md index 0433562fb86c..3de649198070 100644 --- a/content/manuals/ai/sandboxes/governance/reference/network-rules.md +++ b/content/manuals/ai/sandboxes/governance/reference/network-rules.md @@ -10,9 +10,6 @@ rule that also names an HTTP method and URL path, so a policy can allow reads from an API without allowing writes to it. For how to write destinations, see [Destinations](#destinations). -Developer machines must run sbx 0.35.0 or later to enforce HTTP method and path -rules. - ## HTTP method and path An HTTP rule names one or more methods, a destination, and path patterns. What @@ -34,9 +31,10 @@ rule for each path. Every rule applies to at least one method. On the CLI, `--method ANY` covers every HTTP method. In the composer, select at least one method. A rule with no methods selected fails validation. For the methods you can select individually, -see [Network rule fields](../organization/policies/network.md#network-rule-fields) +see +[What a network rule can match](../organization/policies/network.md#what-a-network-rule-can-match) for an organization policy and -[HTTP method and path rules](../local/network-rules.md#http-method-and-path-rules) +[Allow or block HTTP methods and paths](../local/network-rules.md#allow-or-block-http-methods-and-paths) for a local one. Path patterns follow the same wildcard rules as filesystem paths, where `*` @@ -44,9 +42,8 @@ matches within one path segment and `**` matches any depth. A pattern without a wildcard matches that path exactly, so `/repos` matches `/repos` and nothing below it. Every pattern must start with `/` and can't contain a query string, a fragment, or a `..` segment. A local rule's path must also be canonical, so it -can't contain percent-encoding, control characters, repeated or trailing -slashes, or a `.` segment. For the full list, see -[HTTP method and path rules](../local/network-rules.md#http-method-and-path-rules). +can't contain percent-encoding, control characters, surrounding whitespace, +repeated or trailing slashes, or a `.` segment. HTTP requests are evaluated against both layers. A network rule sets the baseline for a host, and HTTP rules adjust individual methods and paths within @@ -77,7 +74,7 @@ hostnames, CIDR ranges, or ports. UDP requires [experimental outbound UDP](../local/network-rules.md#allow-outbound-udp). ICMP is blocked. -**Hostname patterns** +### Hostname patterns | Pattern | Example | Matches | | --------------------- | ----------------- | ------------------------------------------------------------- | @@ -89,11 +86,11 @@ ICMP is blocked. `example.com` and `*.example.com` don't cover each other. Specify both if you need to match the root domain and its subdomains. -**CIDR ranges** +### CIDR ranges Both IPv4 and IPv6 notation are supported: `10.0.0.0/8`, `192.168.1.0/24`, `2001:db8::/32`. For local and organization policy configuration, see [Manage local network rules](../local/network-rules.md) and -[Network access policies](../organization/policies/network.md). +[Organization network access policies](../organization/policies/network.md). diff --git a/content/manuals/ai/sandboxes/governance/reference/policy-limits.md b/content/manuals/ai/sandboxes/governance/reference/policy-limits.md new file mode 100644 index 000000000000..78de68a93504 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/reference/policy-limits.md @@ -0,0 +1,32 @@ +--- +title: Organization policy limits +linkTitle: Policy limits +weight: 35 +description: Limits on the number and size of Docker Sandboxes organization policies and their rules. +keywords: docker sandboxes, organization policy, policy limits, rules per policy, AI Governance +--- + +Organization policies have the following limits, which help ensure fair usage +and resource availability across organizations: + +| Limit | Value | Applies to | +|---------------------------|--------|-------------------------------------------------------------------------------| +| Policies per organization | 100 | All organization policies combined, whatever their type | +| Rules per policy | 250 | Each network or filesystem policy. MCP policies don't have a rule limit. | +| Policy size | 400 KB | Each policy, whatever its type | + +The policies per organization limit is one shared total, not a separate +allowance for each policy type. For example, an organization with 60 network +policies, 30 filesystem policies, and 10 MCP policies has reached the limit. + +The policy size limit applies to each policy as Docker stores it. This +includes the policy's content, such as its name, description, scope, and +rules or Cedar statements, plus a small amount of metadata that Docker stores +with every policy. Typical policies use only a small fraction of this limit. +Domain and file path values have no separate length limit beyond valid format. +Because MCP policies have no rule limit, the policy size limit is what caps how +many Cedar statements an MCP policy can hold. + +If these limits don't fit your organization's needs, +[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) +to discuss options. diff --git a/content/manuals/ai/sandboxes/mcp-gateway.md b/content/manuals/ai/sandboxes/mcp-gateway.md index e168c527214a..dd7fb132744a 100644 --- a/content/manuals/ai/sandboxes/mcp-gateway.md +++ b/content/manuals/ai/sandboxes/mcp-gateway.md @@ -596,6 +596,7 @@ token, use `sbx mcp auth rm`. ## Governance Organizations with AI Governance can use -[MCP access policies](governance/organization/policies/mcp.md) to control MCP server -registration, tool calls, gateway meta-tools, resources, prompts, and approval -requirements. MCP access policies are organization policies written in Cedar. +[Organization MCP access policies](governance/organization/policies/mcp.md) to +control MCP server registration, tool calls, gateway meta-tools, resources, +prompts, and approval requirements. MCP access policies are organization +policies written in Cedar. diff --git a/content/manuals/ai/sandboxes/security/_index.md b/content/manuals/ai/sandboxes/security/_index.md index 2b5e1e125157..f77490285f72 100644 --- a/content/manuals/ai/sandboxes/security/_index.md +++ b/content/manuals/ai/sandboxes/security/_index.md @@ -146,8 +146,8 @@ move these controls to the organization level so that security, policy, and access apply consistently across every developer's sandboxes, rather than depending on local configuration. -See [Governance](../governance/) for the controls available to organization -admins. +See [Organization governance](../governance/organization/_index.md) for the +controls available to organization admins. ## Learn more @@ -157,5 +157,5 @@ admins. blocks - [Manage credentials](../configuration/credentials.md): provide and manage API keys while keeping their values outside the sandbox -- [Governance](../governance/): configure network, filesystem, and MCP access - controls locally or across your organization +- [Governance](../governance/): configure network, filesystem, and MCP policies + locally or across your organization diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index 6ef1a0c01bf9..059cf951a5d1 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -22,8 +22,7 @@ resolver, which enforces network policy. Run `sbx policy ls` to see the active network rules for your installation. Rules can be customized per machine with the `sbx policy` CLI, or managed centrally across your organization. Org-level rules take precedence over local -rules. See -[Network access policies](../governance/_index.md). +rules. See [Governance](../governance/_index.md). ## Workspace defaults diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index e43346a17318..5e07de71aab6 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -47,10 +47,11 @@ directly with each other or share a network with your host. To reach a service running on the host through a policy-controlled connection, see [Accessing host services from a sandbox](../workflows/development.md#accessing-host-services-from-a-sandbox). -All outbound TCP traffic passes through a proxy on your host that enforces the -[network access policy](../governance/_index.md). The sandbox -routes traffic through either a forward proxy or a transparent proxy depending -on the client's configuration. Both enforce the network policy. Only the +All outbound TCP traffic passes through a proxy on your host that enforces +network policy. The sandbox routes traffic through either a forward proxy or a +transparent proxy depending on the client's configuration. Both enforce the +network policy. For how network policy is set, see +[Governance](../governance/_index.md). Only the forward proxy [injects credentials](../configuration/credentials.md) for AI services. Outbound UDP is disabled by default. When you turn on diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index ed94660b11fd..012b8257da2f 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -108,12 +108,18 @@ $ sbx run docker.io/sbx/copilot-kit:latest $ sbx run docker.io/sbx/droid-kit:latest ``` -## Agent can't install packages or reach an API +## Network access and policy -Sandboxes use [network access rules](governance/local/network-rules.md) to -control outbound traffic. -If the agent fails to install packages or call an external API, the target -domain is likely not in the allow list. Check which requests are being blocked: +These problems come from the [governance](governance/_index.md) rules that +control what sandboxes can reach and mount, and from the audit logs that record +those decisions. + +### Agent can't install packages or reach an API + +Sandboxes use [network rules](governance/local/network-rules.md) to control +outbound traffic. If the agent fails to install packages or call an external +API, the destination probably isn't allowed. Check which requests are being +blocked: ```console $ sbx policy log @@ -131,9 +137,114 @@ To allow all outbound traffic instead: $ sbx policy allow network "**" ``` -If `sbx policy allow` doesn't unblock the request, your organization may -manage sandbox policies centrally and take precedence over local rules. See -[Organization policies](governance/organization/_index.md). +If `sbx policy allow` doesn't unblock the request, see +[A local allow rule has no effect](#a-local-allow-rule-has-no-effect). + +### Every request from a sandbox is blocked + +When policy enforcement can't get a valid organization policy, it fails closed +and blocks every network request and workspace mount, whatever your rules +allow. The message a blocked request returns tells you why: + +- `Denied because governance could not be resolved`: run `sbx policy ls`. If + the status line shows `Governance: Unresolved`, see + [`sbx policy ls` shows Governance: Unresolved](#sbx-policy-ls-shows-governance-unresolved). +- `Denied because the policy snapshot is stale`: the daemon lost its connection + to the governance service, or your Docker session expired. Check your network + connection, then run `sbx login` to sign in again if the problem continues. + +### A local allow rule has no effect + +If a destination is still blocked after you add a local allow rule, an +organization policy is probably enforced for you. Run `sbx policy ls` and check +for `Governance: Managed by ` in the status line. When an organization +policy is enforced, local allow rules are inactive and can't loosen what the +organization policy allows. + +To confirm, run `sbx policy ls --wide --include-inactive` and check that your +rule shows `inactive` in the `STATUS` column. + +Ask your administrator to update the organization policy if you need access to +another destination. For more details, see +[How organization policy relates to local and kit rules](governance/organization/policies/_index.md#how-organization-policy-relates-to-local-and-kit-rules). + +### `sbx policy ls` shows Governance: Unresolved + +Docker can't determine which organization governs your account. For example, +this happens when your account belongs to more than one organization with +governance enabled. A `Details` line below the status explains the cause. + +Policy enforcement fails closed until the conflict is resolved, so local allow +rules can't grant access. Contact an administrator for the affected +organizations to resolve the conflicting governance configuration. + +### A request is blocked with "Approval required" + +The destination needs your confirmation. Either no allow or deny rule matches +it and your machine isn't under organization governance, or an organization +policy allows it but requires approval first. + +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. For more details, see +[Respond to approval requests](governance/local/approvals.md). + +### 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. For more +details, see +[Allow or block HTTP methods and paths](governance/local/network-rules.md#allow-or-block-http-methods-and-paths). + +### A sandbox can't mount its workspace + +If a sandbox fails to mount with a `mount policy denied` error, an organization +filesystem policy doesn't allow the path. Check that the filesystem allow rule +uses `**` rather than `*`. A single `*` doesn't match across directory +separators. For more details, see +[Organization filesystem access policies](governance/organization/policies/filesystem.md). + +### Organization policy changes aren't taking effect + +After an administrator updates organization policies, changes take up to 5 +minutes to reach developer machines. To apply them right away on a developer +machine, run `sbx policy refresh`. It fetches and applies the latest +organization policy without restarting the daemon or stopping running +sandboxes. + +The refreshed policy applies to new connections only. A connection that a +sandbox opened while the previous policy allowed it stays open even if the new +policy denies it. Restart the sandbox to close those connections. + +When a synced change takes effect also depends on the policy type. For more +details, see +[Organization network access policies](governance/organization/policies/network.md#when-changes-take-effect), +[Organization filesystem access policies](governance/organization/policies/filesystem.md#when-changes-take-effect), +and +[Organization MCP access policies](governance/organization/policies/mcp.md#when-changes-take-effect). + +### Audit records are missing + +If an organization's audit logs don't include records from a developer, check +the following: + +- The developer is governed. Records come only from signed-in users who have an + AI Governance license and are governed by an enforced organization policy. On + the developer's machine, run `sbx policy ls` and check for + `Governance: Managed by ` in the status line. +- The developer runs Docker Sandboxes 0.39.0 or later. Run `sbx version` to + check, and [install](install.md) a newer version if needed. +- Cloud delivery is on. Records reach audit events in Docker Home and SIEM + streaming only through cloud delivery. Organizations that used local audit + logging before hosted audit logs were available start with cloud delivery + off. For more details, see + [Configure audit delivery](governance/organization/audit/configure.md). +- Local files are finalized. With local delivery, the daemon writes records to + a `.tmp` file and renames it to `.jsonl` after 5 minutes, 1000 events, or 50 + MiB, or when the daemon shuts down cleanly. For more details, see + [Where records are stored](governance/organization/audit/_index.md#where-records-are-stored). ## Kit fails to install: source not in allowlist @@ -212,7 +323,7 @@ If credentials are configured correctly but API calls still fail, check the `transparent` proxy don't get credential injection. This can happen when a client inside the sandbox (such as a process in a Docker container) isn't configured to use the forward proxy. See -[Monitoring network activity](governance/local/test-monitor.md#monitoring-traffic) +[View network activity](governance/local/test-monitor.md#view-network-activity) for details. ## MCP server streams stall diff --git a/content/manuals/ai/sandboxes/workflows/automation.md b/content/manuals/ai/sandboxes/workflows/automation.md index ee4d27dee5ad..37e982b8607a 100644 --- a/content/manuals/ai/sandboxes/workflows/automation.md +++ b/content/manuals/ai/sandboxes/workflows/automation.md @@ -124,7 +124,7 @@ parsers for these commands: | `sbx ls` | A sandbox array, replacing `{sandboxes: [...]}`. `created_at` and `last_used_at` use RFC 3339 timestamps. Rows include `detached`. | | `sbx template ls` | An image array, replacing `{images: [...]}`. | | Local `sbx mcp ls` | A server array, replacing `{gateway: {...}, servers: [...]}`. Each row includes `gateway`. Cloud rows describe server usage across sandboxes and differ from local registration rows. | -| `sbx policy log` | `{updated_at, allowed: [...], blocked: [...]}` for local and cloud output. See [Monitoring traffic](/manuals/ai/sandboxes/governance/local/test-monitor.md#monitoring-traffic). | +| `sbx policy log` | `{updated_at, allowed: [...], blocked: [...]}` for local and cloud output. See [Get the log as JSON or YAML](/manuals/ai/sandboxes/governance/local/test-monitor.md#get-the-log-as-json-or-yaml). | | `sbx --cloud policy ls` | Field names use `snake_case` instead of camelCase. | | `sbx ports` | Local rows contain `host_ip`, `host_port`, `sandbox_port`, and `protocol`. Cloud rows contain `sandbox_port` and `url`, replacing `port`. Local publish and unpublish results include `action: published` or `action: unpublished`. | | Cloud `sbx volume create`, `sbx volume ls`, `sbx volume inspect` | Fields such as `ID`, `Name`, and `CreatedAt` become `id`, `name`, and `created_at`. `volume inspect` defaults to human-readable details, so request a structured format explicitly. | diff --git a/content/manuals/platform-release-notes.md b/content/manuals/platform-release-notes.md index b604df6501e1..1a67dfa09f3c 100644 --- a/content/manuals/platform-release-notes.md +++ b/content/manuals/platform-release-notes.md @@ -138,7 +138,7 @@ and subscriptions. now available. Administrators can purchase licenses through sales, [assign them to members](/manuals/accounts/organization/manage/manage-licenses.md), and enforce - [organization policies](/manuals/ai/sandboxes/governance/_index.md) for + [organization policies](/manuals/ai/sandboxes/governance/organization/policies/_index.md) for Docker AI products from Docker Home. ## 2026-03-03 diff --git a/content/manuals/subscription-billing/plans/ai-governance.md b/content/manuals/subscription-billing/plans/ai-governance.md index 3221f491e6ed..0de8b29e352c 100644 --- a/content/manuals/subscription-billing/plans/ai-governance.md +++ b/content/manuals/subscription-billing/plans/ai-governance.md @@ -14,14 +14,14 @@ aliases: - /subscription/ai-governance/ --- -[AI Governance](/manuals/ai/sandboxes/governance/_index.md) lets organization owners enforce policies for members across supported Docker AI products, like [Docker Sandbox](/manuals/ai/sandboxes/_index.md). When you add an AI Governance plan, you work with your Docker sales representative to determine the number of licenses needed, which are applied to your account. +[AI Governance](/manuals/ai/sandboxes/governance/organization/_index.md) lets organization owners enforce policies for members across supported Docker AI products, like [Docker Sandbox](/manuals/ai/sandboxes/_index.md). When you add an AI Governance plan, you work with your Docker sales representative to determine the number of licenses needed, which are applied to your account. > [!TIP] > To subscribe to AI Governance, contact sales. ## Usage -AI Governance lets organization owners enforce [organization policies](/manuals/ai/sandboxes/governance/organization/_index.md) for license-holding members. Organization policies override a license-holding member's local policies. +AI Governance lets organization owners enforce [organization policies](/manuals/ai/sandboxes/governance/organization/policies/_index.md) for license-holding members. Organization policies override a license-holding member's local policies. You can [assign AI Governance licenses](/manuals/accounts/organization/manage/manage-licenses.md) to a team or to an individual organization member, even if they don't occupy a Docker Team or Docker Business seat. For best practice, review available licenses as you add new members since members without an AI Governance license can still use Docker AI products. diff --git a/data/summary.yaml b/data/summary.yaml index cae0e0b9817d..f544ef798130 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -1,9 +1,9 @@ 2FA: subscription: [Personal, Pro] for: Individuals -AI Governance Audit Logs: +AI Governance: subscription: [AI Governance] - requires: Docker Sandboxes [0.39.0](/manuals/ai/sandboxes/release-notes.md) or later + for: Administrators Activity logs: subscription: [Team, Business] for: Administrators diff --git a/layouts/_shortcodes/summary-bar.html b/layouts/_shortcodes/summary-bar.html index aa434c1dd17c..e65920df7e69 100644 --- a/layouts/_shortcodes/summary-bar.html +++ b/layouts/_shortcodes/summary-bar.html @@ -13,7 +13,10 @@ "Docker Hardened Images Enterprise" "/icons/dhi.svg" "Docker Hardened Images Select or Enterprise" "/icons/dhi.svg" "Docker Offload" "cloud" - "AI Governance" "shield-check" + "AI Governance" "lock-closed" + }} + {{ $subscriptionLinks := dict + "AI Governance" "/manuals/subscription-billing/plans/ai-governance" }} {{ $availabilityIcons := dict "Experimental" "beaker" @@ -34,7 +37,16 @@
Subscription: {{ range . }} - {{ . }} + {{ $name := . }} + {{ with index $subscriptionLinks $name }} + {{ with site.GetPage . }} + {{ $name }} + {{ else }} + {{ errorf "[summary-bar] subscription link page not found: %s" . }} + {{ end }} + {{ else }} + {{ $name }} + {{ end }} {{ $icon := index $subscriptionIcons . }} {{ if $icon }}