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 852b764c205e..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/access-controls/local.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 aa19302239d8..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/concepts.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/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/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/_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..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/access-controls/network.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 c351fc2a65b5..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/concepts.md#network-rules): `*` 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 6d57bd52564d..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/access-controls/network.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 93514fe688d8..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/access-controls/network.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 69bc14701a19..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/concepts.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 8125db917a11..21b35cc4a4d8 100644 --- a/content/manuals/ai/sandboxes/faq.md +++ b/content/manuals/ai/sandboxes/faq.md @@ -18,9 +18,9 @@ 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 -[organization governance features](governance/) require a separate paid +[sign-in enforcement](governance/organization/sign-in-enforcement.md), +and [audit logs](governance/organization/audit/_index.md). These +[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/access-controls/organization.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/access-controls/network.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 28b6bfe6a9f0..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/access-controls/local.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. @@ -140,7 +141,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..b504dc37cb08 100644 --- a/content/manuals/ai/sandboxes/governance/_index.md +++ b/content/manuals/ai/sandboxes/governance/_index.md @@ -3,74 +3,77 @@ 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 -use separate network policy configuration. See -[Cloud network policy](../cloud/network-policy.md) for cloud controls. - -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 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). - -**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](access-controls/organization.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 -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 is available on a separate paid subscription. -> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales) -> to request access. - -## Learn more - -Start with [Policy concepts](concepts.md) for the resource model, rule syntax, -MCP policy basics, evaluation, and precedence. - -### Access controls - -- [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. - -### Monitor and enforce - -- [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. - -### Reference - -- [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. +> 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). + +## Who sets the rules + +The two parts of governance differ in who sets the rules and who the rules +apply to. + +### You, with local policy and kits + +[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. + +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. + +### Your organization, with organization governance + +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). + +## 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/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/filesystem.md b/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md deleted file mode 100644 index 7445a10d42f4..000000000000 --- a/content/manuals/ai/sandboxes/governance/access-controls/filesystem.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Filesystem access policies -linkTitle: Filesystem access -weight: 40 -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 ---- - -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 -organization governance is active, organization rules determine which paths a -sandbox can mount, and the local filesystem allow rules from the default preset -become inactive. `sbx policy deny` applies to network access only, so there are -no local filesystem deny rules to layer on top. See -[Precedence](../concepts.md#precedence). - -## Rule syntax - -Filesystem rules use the actions `read` and `write`. Resources are host path -patterns. - -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](../concepts.md#filesystem-rules). - -## 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). - -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. - -## Troubleshooting - -### Sandbox cannot mount workspace - -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. 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/_index.md b/content/manuals/ai/sandboxes/governance/audit/_index.md deleted file mode 100644 index bff10587de80..000000000000 --- a/content/manuals/ai/sandboxes/governance/audit/_index.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: AI Governance Audit Logs -linkTitle: Audit logs -weight: 30 -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 ---- - -{{< summary-bar feature_name="AI Governance Audit Logs" >}} - -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). - -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](../access-controls/organization.md). Docker Sandboxes users without both -don't send audit data to audit logs. - -> [!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 - -To use AI Governance Audit Logs, 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. - -## 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. - -## Delivery modes - -Docker supports two delivery modes for audit records: - -- **Local disk**: the sandbox daemon writes JSON Lines (`.jsonl`) - files on each host. Use this mode for host-local retention, air-gapped - 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. - -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). - -## Data handling - -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/). - -## 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) diff --git a/content/manuals/ai/sandboxes/governance/audit/configure.md b/content/manuals/ai/sandboxes/governance/audit/configure.md deleted file mode 100644 index 5afa22949ab6..000000000000 --- a/content/manuals/ai/sandboxes/governance/audit/configure.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Configure audit delivery -linkTitle: Configure delivery -weight: 20 -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 ---- - -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: - -- **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. - -## Before you begin - -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 - -Only users who have an AI Governance license and are governed by the enforced -organization policy send Docker Sandboxes audit data. - -## Configure delivery - -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: - - **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. - -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. - -Organizations that used local audit logging before hosted audit logs were -available start with cloud delivery off until an owner opts in. - -## 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 - -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. - -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. 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/audit/siem.md b/content/manuals/ai/sandboxes/governance/audit/siem.md deleted file mode 100644 index 9a4dd503d290..000000000000 --- a/content/manuals/ai/sandboxes/governance/audit/siem.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: SIEM forwarding -linkTitle: SIEM forwarding -weight: 40 -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 ---- - -{{< summary-bar feature_name="AI Governance Audit Logs" >}} - -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. - -## Supported destinations - -| 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 | - -## Before you begin - -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. - -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. -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. - -## Manage destinations - -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. diff --git a/content/manuals/ai/sandboxes/governance/audit/view-export.md b/content/manuals/ai/sandboxes/governance/audit/view-export.md deleted file mode 100644 index 7b1e7adf67b0..000000000000 --- a/content/manuals/ai/sandboxes/governance/audit/view-export.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: View and export audit events -linkTitle: View and export -weight: 30 -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 ---- - -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. - -## View audit events - -To view audit events: - -1. Sign in to [Docker Home](https://app.docker.com/). -1. Open your organization. -1. Go to **AI Platform** > **Audit logs**. -1. Open **Audit Events**. - -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. | - -## 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 uses cursor pagination for large result sets. - -## Export events to CSV - -Use CSV export when you need an offline copy of filtered 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. 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..30fdd2ae54f5 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/local/_index.md @@ -0,0 +1,107 @@ +--- +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/ +--- + +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. + +## 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). + +## 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 + +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. +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 new file mode 100644 index 000000000000..b43d614eb6b2 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/local/approvals.md @@ -0,0 +1,113 @@ +--- +title: Respond to approval requests +linkTitle: Respond to approvals +weight: 30 +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 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 +Approval required for api.example.com. + +Review and respond with: + sbx policy approval ls +``` + +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. 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`. + +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 +$ 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. + +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: + +- 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. + +## Review and remove approved destinations + +Approved destinations stay allowed until you remove the rule. List them: + +```console +$ sbx policy ls --wide --created-via approval +``` + +Remove one by its rule ID, the same way as any other local rule: + +```console +$ sbx policy rm network --sandbox my-sandbox --id +``` + +For more details, see [Remove a rule](network-rules.md#remove-a-rule). diff --git a/content/manuals/ai/sandboxes/governance/local/inspect.md b/content/manuals/ai/sandboxes/governance/local/inspect.md new file mode 100644 index 000000000000..8e29c1c4ddf1 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/local/inspect.md @@ -0,0 +1,197 @@ +--- +title: Inspect policy status and rules +linkTitle: Inspect policies +weight: 40 +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/ +--- + +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). + +## List the policies that apply + +Run `sbx policy ls` to see every active policy: + +```console +$ sbx policy ls +POLICY SOURCE APPLIES TO SUMMARY +local-policy local all network: 42 allow, 1 deny; filesystem read: 1 allow; filesystem write: 1 allow +1b2633ea-e604-48bb-a5e6-3ac86ba383fe kit sandbox:my-sandbox network: 3 allow +``` + +The columns are: + +- `POLICY`: the policy name. +- `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, 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. + +## 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 ls my-sandbox +``` + +The output summarizes the rules by type, for example +`allow 46 hosts from local-policy`. To see each rule, add `--wide`. + +## Show rule details + +Pass `--wide` to list each rule on its own row, with its rule ID, type, +decision, protocols, and resources: + +```console +$ sbx policy ls --wide +``` + +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). + +To see one policy or rule in full, pass its name or rule ID to +`sbx policy inspect`: + +```console +$ sbx policy inspect local-policy +``` + +## Filter the listing + +Filters work with both the summary and the `--wide` listing: + +- `--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. + +For example, to list the destinations you've approved: + +```console +$ sbx policy ls --wide --created-via approval +``` + +For more details, see [Respond to approval requests](approvals.md). + +To list the rules a kit added to a sandbox: + +```console +$ sbx policy ls my-sandbox --source kit --wide +``` + +## List HTTP rules + +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 http +``` + +In a `--wide` listing, HTTP rules fill the `METHOD` and `PATH` columns. Rules +that match a whole destination show `-` in both columns. + +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 entries that also match an HTTP method and +path: + +```console +$ sbx policy ls +POLICY SOURCE APPLIES TO SUMMARY +local-policy local all network: 2 allow (L4), 1 deny (L7) +``` + +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 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 more details, see +[HTTP method and path](../reference/network-rules.md#http-method-and-path). + +## List filesystem rules + +Filesystem rules control which host paths a sandbox can mount as a workspace. +To list only those rules, pass `--type filesystem`: + +```console +$ sbx policy ls --type filesystem +POLICY SOURCE APPLIES TO SUMMARY +local-policy local all filesystem read: 1 allow; filesystem write: 1 allow +``` + +A writable workspace mount must be allowed by both a `filesystem:read` and a +`filesystem:write` rule. A read-only mount needs only `filesystem:read`. 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). + +## Check organization governance status + +When an organization policy is enforced for you, `sbx policy ls` starts with a +status line: + +```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 + +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 +``` + +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 new file mode 100644 index 000000000000..775244fc2158 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/local/network-rules.md @@ -0,0 +1,238 @@ +--- +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 +--- + +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). + +## 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 +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 +``` + +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 +$ sbx policy allow network --sandbox my-sandbox api.example.com +$ sbx policy deny network --sandbox my-sandbox ads.example.com +``` + +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 . +$ 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 `, like any other rule scoped to the sandbox. + +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 deny network --sandbox my-sandbox openrouter.ai +``` + +Removing a sandbox also removes the rules scoped to it. + +## Allow or block HTTP methods and paths + +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: + +```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, +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: + +```console +$ sbx policy allow network api.example.com +$ sbx policy deny network api.example.com --method POST --path '/admin/**' +``` + +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 a rule + +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 rule scoped to a sandbox, pass `--sandbox `: + +```console +$ sbx policy rm network --sandbox my-sandbox --resource api.example.com +``` + +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 + +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. + +## 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 + +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 +``` + +> [!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 new file mode 100644 index 000000000000..2cddefd7e8d6 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/local/test-monitor.md @@ -0,0 +1,109 @@ +--- +title: Test and monitor network policy +linkTitle: Test and monitor +weight: 50 +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 +--- + +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. + +## 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 +$ sbx policy check network blocked.example.com +``` + +The output reports `Allowed` or `Denied`, along with governance and context +details. A denied check returns exit status 1, so you can use the command in +scripts. + +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 a destination for one sandbox, including the rules scoped to it, pass +`--sandbox`: + +```console +$ sbx policy check network --sandbox my-sandbox api.example.com +``` + +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). + +## View network activity + +Run `sbx policy log` to see which hosts your sandboxes 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 `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 | +| ---------------- | -------------------------------------------------------------------------------------------------------------- | +| `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. | + +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 + +To see only one sandbox's requests, pass its name: + +```console +$ sbx policy log my-sandbox +``` + +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 +``` + +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/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/monitor-and-enforce/monitoring.md b/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md deleted file mode 100644 index 223bc8600c7b..000000000000 --- a/content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: Monitoring policies -weight: 10 -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/ ---- - -`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. - -## Listing rules - -Use `sbx policy ls` to see all active policies and their current status: - -```console -$ sbx policy ls -POLICY SOURCE APPLIES TO SUMMARY -local-policy local all network: 42 allow, 1 deny; filesystem read: 1 allow; filesystem write: 1 allow -1b2633ea-e604-48bb-a5e6-3ac86ba383fe kit sandbox:my-sandbox network: 3 allow -``` - -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 - 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. -- `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). - -To see full rule-level detail including rule IDs and resources, pass `--wide`. -To inspect a single policy or rule, use `sbx policy inspect`: - -```console -$ sbx policy inspect Balanced -``` - -Use `--source` to filter by origin (`local`, `org`, or `kit`) and `--decision` -to filter by outcome (`allow` or `deny`). - -Use `--protocol tcp` or `--protocol udp` to filter network rules. - -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: - -```console -$ sbx policy ls --wide --created-via approval -``` - -See [Approval-required access](../access-controls/network.md#approval-required-access). - -A `STATUS` column also appears when you pass `--include-inactive`; see -[Showing inactive rules](#showing-inactive-rules). - -When organization governance is active, the output starts with a summary block -showing which organization manages the policy, the sync state, and how many -inactive rules are hidden: - -```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 -``` - -`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. - -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. - -### Showing inactive rules - -When organization governance is active, local and kit-defined allow rules are -not evaluated, so `sbx policy ls` hides them by default. To list them too — for -example, to confirm which allow rules the organization policy overrides — pass -`--include-inactive`. This adds a `STATUS` column: - -```console -$ 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 -``` - -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). - -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: - -```console -$ sbx policy ls my-sandbox -``` - -### Filesystem 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: - -```console -$ sbx policy ls --type filesystem -POLICY SOURCE APPLIES TO SUMMARY -local-policy local all filesystem read: 1 allow; filesystem write: 1 allow -``` - -A writable workspace mount must be allowed by both a `filesystem:read` and a -`filesystem:write` rule; a read-only mount needs only `filesystem:read`. The -default local policy allows read and write access to all paths, shown as the -two `default-fs-*` rules above. For the rule syntax and path patterns, see -[Policy concepts](../concepts.md#filesystem-rules). - -### 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/** -``` - -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 -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 -path: - -```console -$ sbx policy ls -POLICY SOURCE APPLIES TO SUMMARY -local-policy local all network: 2 allow (L4), 1 deny (L7) -``` - -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. -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 -[HTTP method and path](../concepts.md#http-method-and-path). - -## 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/organization/_index.md b/content/manuals/ai/sandboxes/governance/organization/_index.md new file mode 100644 index 000000000000..c0ed9f494489 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/_index.md @@ -0,0 +1,89 @@ +--- +title: Organization governance +weight: 20 +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/ +--- + +{{< summary-bar feature_name="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 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. + +## 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 new file mode 100644 index 000000000000..d843347eee96 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/audit/_index.md @@ -0,0 +1,128 @@ +--- +title: AI Governance Audit Logs +linkTitle: Audit logs +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" >}} + +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 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). + +## What you need + +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 +- 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 + +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. + +## Where records go + +Docker supports two delivery modes for audit records: + +- **Local disk**: the sandbox daemon writes JSON Lines (`.jsonl`) + files on each host. Use this mode for host-local retention, air-gapped + 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. + +To choose which delivery modes your organization uses, see +[Configure audit delivery](configure.md). + +### Where records are stored + +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 +`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. + +## What you can do with records + +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). + +To set up delivery, see [Configure audit delivery](configure.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 new file mode 100644 index 000000000000..e5a5fdec28c8 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/audit/configure.md @@ -0,0 +1,66 @@ +--- +title: Configure audit delivery +linkTitle: Configure delivery +weight: 10 +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/ +--- + +{{< summary-bar feature_name="AI Governance" >}} + +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 + +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 + +Only users who have an AI Governance license and are governed by the enforced +organization policy send Docker Sandboxes audit data. + +## Configure delivery + +To configure audit delivery: + +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. +1. Save your changes. + +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. + +Docker Cloud keeps audit records searchable in the hosted audit log view for 90 +days, and in archive storage for 90 days. + +## Review delivery change history + +Docker keeps a record of every change made to your organization's audit delivery +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: + +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 new file mode 100644 index 000000000000..38e4153c47fd --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/audit/siem.md @@ -0,0 +1,91 @@ +--- +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. +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" >}} + +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: + +- 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). + +For how the two delivery modes differ, see +[Where records go](_index.md#where-records-go). + +## Forward events from Docker Cloud + +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. 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**. + +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. + +### 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 can't be undone. + +## Collect local audit files with a log shipper + +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, +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/organization/audit/view-export.md b/content/manuals/ai/sandboxes/governance/organization/audit/view-export.md new file mode 100644 index 000000000000..5e8c35bef8dd --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/audit/view-export.md @@ -0,0 +1,90 @@ +--- +title: View and export audit events +linkTitle: View and export +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/ +--- + +{{< 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, 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. + +## Before you begin + +- [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. + +## 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**. + +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 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 + +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: + +- **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 + +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. 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. 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 new file mode 100644 index 000000000000..381d87d0884f --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/policies/_index.md @@ -0,0 +1,129 @@ +--- +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 +aliases: + - /ai/sandboxes/governance/concepts/ +--- + +{{< summary-bar feature_name="AI Governance" >}} + +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). + +## 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 + 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. + +Use org-wide policies for guardrails that must apply everywhere, and +team-scoped policies for access that only some teams need. The next section +explains why org-wide deny rules work well as guardrails. + +## How rules decide a request + +When an organization policy is enforced for you, the rules from all of your +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. +- 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. + +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). + +### How organization policy relates to local and kit rules + +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. +- 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 + can still restrict access further. + +The following table summarizes which rules are evaluated under organization +governance: + +| 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. 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. For more details, see +[Approval-required access](network.md#approval-required-access). + +## When policy changes reach developers + +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). + +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 new file mode 100644 index 000000000000..ab9544a7cdd1 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/policies/create-manage.md @@ -0,0 +1,111 @@ +--- +title: Create and manage organization policies +linkTitle: Create and manage +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 +--- + +{{< 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/). + +## Before you begin + +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. +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. 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 + [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. 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. The policy's + detail page reports approval as **Required** or **Not required**. For more + details, see [Approval-required access](network.md#approval-required-access). + +For the number of policies and rules you can create, see +[Organization policy limits](../../reference/policy-limits.md). + +## Scope policies to teams + +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 +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. + +## Edit or delete 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. 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). + +## 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. diff --git a/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md b/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md new file mode 100644 index 000000000000..6c3563323a11 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/policies/filesystem.md @@ -0,0 +1,66 @@ +--- +title: Organization filesystem access policies +linkTitle: Filesystem +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. 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 organization policies](create-manage.md). For path patterns +and the `read` and `write` actions, see +[Filesystem mount rule syntax](../../reference/filesystem-rules.md). + +## What a filesystem rule can match + +Each filesystem mount rule allows or denies one or both of two actions on the +host paths it lists: + +- `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. + +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). + +## 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 + +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/access-controls/mcp.md b/content/manuals/ai/sandboxes/governance/organization/policies/mcp.md similarity index 77% rename from content/manuals/ai/sandboxes/governance/access-controls/mcp.md rename to content/manuals/ai/sandboxes/governance/organization/policies/mcp.md index 07475cb8984d..bfe0520e2b1f 100644 --- a/content/manuals/ai/sandboxes/governance/access-controls/mcp.md +++ b/content/manuals/ai/sandboxes/governance/organization/policies/mcp.md @@ -1,36 +1,50 @@ --- -title: MCP access policies -linkTitle: MCP access -weight: 50 +title: Organization MCP access policies +linkTitle: MCP +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, 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 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. 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 +[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. @@ -53,13 +67,13 @@ 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 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` @@ -80,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 @@ -116,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 @@ -174,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` @@ -215,12 +235,12 @@ 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. 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 +254,18 @@ when { resource.type == "local-stdio" }; container, and OCI-packaged stdio servers resolved from registry or manifest metadata with `--local`. -## Related information +## 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 to the developer's machine](_index.md#when-policy-changes-reach-developers), +use-time rules apply to subsequent governed MCP requests through the gateway. -- [MCP policy concepts](../concepts.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](organization.md): policy creation and scope. -- [MCP policy audit logs](../audit/): policy decision - records. +To prevent use of an MCP server that is already registered or loaded, add +use-time rules for the registered server name. For more details, see +[Withdraw server access](#withdraw-server-access). 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..d1fcddaf709f --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/organization/policies/network.md @@ -0,0 +1,113 @@ +--- +title: Organization network access policies +linkTitle: Network +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. 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 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 +[How organization policy relates to local and kit rules](_index.md#how-organization-policy-relates-to-local-and-kit-rules). + +## 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**. 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 +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. 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 +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, 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. + +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). + +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](_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. 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 74% 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..fb2ed8a021dc 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,30 +1,27 @@ --- -title: Sign-in enforcement -linkTitle: Sign-in enforcement +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 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 -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](../access-controls/organization.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 @@ -35,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 { @@ -70,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. @@ -139,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 | | ------------- | -------------- | --------------------------------------------------- | @@ -170,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" >}} @@ -207,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: @@ -262,12 +284,9 @@ For access, contact ACME IT Security: URL: https://acme-corp.atlassian.net/servicedesk/it ``` -## Related pages +## Turn off enforcement -- [Organization policies](../access-controls/organization.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 - 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 5358776a0a49..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: 50 -description: Reference material for Docker AI Governance policy APIs and policy syntax. -keywords: docker sandboxes, governance reference, governance API, policy reference +weight: 30 --- - -Use reference material when you need API details or exact policy syntax. - -- [Policy concepts](../concepts.md): resource model, rule syntax, policy - evaluation, and precedence. -- [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, - attributes, context fields, and approval behavior. 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 52% rename from content/manuals/ai/sandboxes/governance/audit/record-reference.md rename to content/manuals/ai/sandboxes/governance/reference/audit-records.md index ce547f4e7eef..de00b7e65d90 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 @@ -15,28 +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. | -| `deny_reason` | Why a denied request was blocked. Present on deny decisions. | -| `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. | ## Categories @@ -46,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 | @@ -81,7 +106,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 @@ -106,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 @@ -142,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 new file mode 100644 index 000000000000..98ac562d67cf --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/reference/filesystem-rules.md @@ -0,0 +1,51 @@ +--- +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 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 +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 +[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 2080e85a23ca..68425f347085 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 --- @@ -9,10 +9,15 @@ 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). - -Use this reference with [MCP access policies](../access-controls/mcp.md) for -common policy patterns. For the Cedar language, see the +[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 +[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 @@ -28,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](../access-controls/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: @@ -83,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. | @@ -165,7 +170,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..3de649198070 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/reference/network-rules.md @@ -0,0 +1,96 @@ +--- +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 +--- + +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). + +## HTTP method and path + +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 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, select at least one method. A rule with no +methods selected fails validation. For the methods you can select individually, +see +[What a network rule can match](../organization/policies/network.md#what-a-network-rule-can-match) +for an organization policy and +[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 `*` +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, 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 +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. + +## 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 +[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 12cee969dc3e..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/access-controls/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 463ceda6b988..f77490285f72 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 @@ -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 80cde27a73f4..059cf951a5d1 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -15,15 +15,14 @@ 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. 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). +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 07070347a9ae..5e07de71aab6 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -47,14 +47,15 @@ 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/access-controls/network.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 -[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..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/access-controls/network.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/access-controls/organization.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 @@ -174,7 +285,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 +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/monitor-and-enforce/monitoring.md) +[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 78567684a2d1..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/monitor-and-enforce/monitoring.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 4920eff82989..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/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/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/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/ 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 }}