nprasad2077/docker-docs
1
0 Fork 0
mirror of https://github.com/docker/docs.git synced 2026-11-04 10:01:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

ai-gov: rearrange and feedback (#26412)

Browse Source 
<!--Delete sections as needed -->

## Description

Rearrange AI Gov section and apply internal feedback.

https://deploy-preview-26412--docsdocker.netlify.app/ai/governance/

## Related issues or tickets

https://docs-review-portal.internal.tools/comments?build_id=18

## Reviews

<!-- Notes for reviewers here -->
<!-- List applicable reviews (optionally @tag reviewers) -->

- [ ] Technical review
- [ ] Editorial review
- [ ] Product review

---------

Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
This commit is contained in:
Craig Osterhout authored and GitHub committed 2026-11-03 10:30:14 -08:00
1 parent 1315bf2c3c
commit b34003b104
72 files changed
+2720 -2327
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

content/get-started/tutorials/admin-set-up.md
+2 -2
View File
@@ -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/governance/organization/_index.md)
for organization-wide agent policies
content/get-started/tutorials/run-an-agent.md
+1 -1
View File
@@ -99,7 +99,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/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
content/guides/firecrawl-sandbox-kit.md
+3 -3
View File
@@ -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/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
content/manuals/_index.md
+4
View File
@@ -27,6 +27,10 @@ params:
description: Create and manage cloud sandboxes from your applications.
icon: code-bracket
link: /ai/sandboxes-api/
- title: Sandbox governance
description: Control what agents in sandboxes can reach, and audit what they did.
icon: lock-closed
link: /ai/governance/
- title: MCP Catalog and Toolkit
description: Augment your AI workflow with MCP servers.
icon: /icons/toolkit.svg
content/manuals/accounts/organization/activity-logs.md
+3 -3
View File
@@ -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/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/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/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
content/manuals/agentic-platform/policies.md
+5 -2
View File
@@ -58,8 +58,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
content/manuals/ai-overview.md
+2 -1
View File
@@ -3,7 +3,7 @@ title: Docker AI overview
linkTitle: Overview
description: Docker's AI tools help you build, run, and manage AI-powered applications and workflows.
weight: 1
keywords: docker, ai, gordon, docker agent, sandboxes, agentic platform, model runner, mcp
keywords: docker, ai, gordon, docker agent, sandboxes, governance, agentic platform, model runner, mcp
params:
sidebar:
group: AI and agents
@@ -17,6 +17,7 @@ Each tool serves a different purpose.
| I want to... | Use | Interface |
| --------------------------------------------------------------- | -------------------------------------------------------- | ---------------- |
| Run coding agents in isolated environments | [Docker Sandboxes](./ai/sandboxes/) | `sbx` |
| Control what sandbox agents can reach, and audit what they did | [Sandbox governance](./ai/governance/) | `sbx policy`, Docker Home |
| Run agents in cloud sandboxes through a web Console | [Docker Agentic Platform](./agentic-platform/_index.md) (experimental) | Web Console |
| Get AI help with Docker tasks (containers, images, Dockerfiles) | [Gordon](./ai/gordon/) | `docker ai` |
| Run AI models locally with an OpenAI-compatible API | [Model Runner](./ai/model-runner/) | `docker model` |
content/manuals/ai/governance/_index.md
+67
View File
@@ -0,0 +1,67 @@
---
title: AI governance
weight: 20
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
params:
sidebar:
group: AI and agents
aliases:
- /ai/sandboxes/governance/
- /ai/sandboxes/governance/access-controls/
- /ai/sandboxes/governance/monitor-and-enforce/
- /ai/sandboxes/governance/reference/
---
Agents in [Docker Sandboxes](../sandboxes/_index.md) work on their own. They
install packages, call APIs, and use tools without asking you first.
Governance lets an agent work freely within rules that limit what it can
access. The rules are enforced outside the sandbox, so the agent can't change or
bypass them. They come from three sources: your local policy, the kits your
sandboxes use, and your organization.
> [!NOTE]
> 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](../sandboxes/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).
## Where the rules come from
You set your local policy and choose which kits your sandboxes use. Your
organization's administrators set its organization policies.
### Local policy and kits
With [local policy](local/_index.md), you decide which network destinations
your sandboxes can reach. You start from a preset, then use `sbx policy` to
allow what your work needs and block what sandboxes shouldn't reach.
[Kits](../sandboxes/customize/use-kits.md), including the built-in agent kits,
bring rules of their own. Whoever authors a kit defines the rules its agent
needs, such as access to the agent's API, and the rules come with the kit
whether you build it yourself or pull it from a registry or Git repository.
They apply only to the sandboxes that use the kit.
### Organization governance
If your organization has an
[AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md),
administrators set rules centrally with
[organization governance](organization/_index.md). Their policies apply to the
sandboxes of licensed members and go beyond the network, controlling which
host paths sandboxes can mount and which MCP servers they can use.
Administrators then review the decisions those policies make in audit logs.
## 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 policies, audit logs, licenses, sign-in enforcement, and Docker Sandboxes
for your organization.
content/manuals/ai/governance/local/_index.md
+94
View File
@@ -0,0 +1,94 @@
---
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/
- /ai/sandboxes/governance/local/
---
Local policy is how you, the developer, control which network destinations the
sandboxes on your machine can reach. You start from a preset that sets how much
access sandboxes have, then use the `sbx policy` command to allow what your work
needs and block what sandboxes shouldn't reach. If a sandbox uses a kit, the kit
brings the rules its agent needs, so you don't have to add them yourself.
Local policy covers only the network. You already decide which host paths a
sandbox mounts when you create it, and which MCP servers it can use when you
register them. Unless an organization policy applies to you, nothing restricts
those choices.
## How local policy works
Every outbound TCP request from a sandbox, including HTTP and SSH, passes
through a proxy on your host, which checks the request against your rules
before it leaves your machine. A rule names a destination and says whether to
allow or deny it. Other protocols are blocked by default. UDP needs the
experimental feature described in
[Allow outbound UDP](network-rules.md#allow-outbound-udp), and ICMP is always
blocked.
Most rules match a hostname, such as `api.github.com`, or an IP address or CIDR
range. For HTTP traffic, a rule can also match the request's method, path, and
query parameters, so you can allow part of an API without allowing all of it. A
rule for other TCP traffic, such as SSH, can name a port, for example
`sbx policy allow network "myhost:22"`. For the full pattern syntax, including
wildcards, 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 to choose one when you run a sandbox in an interactive
terminal. If a preset is already set, including one carried over from an
earlier installation, the CLI uses it without prompting.
| Preset | CLI value | Description |
| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open | `allow-all` | All outbound TCP traffic is allowed. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`. |
| Balanced | `balanced` | Default deny, with a baseline allowlist covering AI provider APIs, package managers, OS package repositories, code hosts, container registries, cloud services, and certificate validation. |
| Locked Down | `deny-all` | 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. After you choose it, 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).
## Use kits that add rules
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. For more details, see
[Use kits](../../sandboxes/customize/use-kits.md).
## How rules combine
Without organization governance, your rules and kit rules combine: a
destination is allowed if any rule allows it, and a deny rule from any source
takes precedence over an allow rule. Kit rules apply under any preset,
including **Locked Down**, because a preset isn't an explicit deny 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).
## Try it out
[Try out local policy](try-it-out.md) walks you through an example that allows
and blocks destinations for one sandbox.
content/manuals/ai/governance/local/approvals.md
+113
View File
@@ -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: a network access 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. When an organization policy is enforced for you, 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 <RULE_ID>
```
For more details, see [Remove a rule](network-rules.md#remove-a-rule).
content/manuals/ai/governance/local/inspect.md
+194
View File
@@ -0,0 +1,194 @@
---
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](../../sandboxes/customize/use-kits.md). `org` means your organization.
- `APPLIES TO`: which sandboxes the policy applies to. `all` means the policy
is global, and `sandbox:<name>` 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 mount rules
Filesystem mount 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
```
Your local policy allows read and write access to all paths by default, shown
as the two allow entries above. For how read and write rules combine, 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. For more details, see
[Organization policy changes aren't taking effect](../troubleshooting.md#organization-policy-changes-arent-taking-effect).
- `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).
content/manuals/ai/governance/local/network-rules.md
+240
View File
@@ -0,0 +1,240 @@
---
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 <name>` 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 <name>`, 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, and
`--path` to narrow it to part of the host's URL space. Quote the path so your
shell doesn't expand the wildcard:
```console
$ sbx policy allow network api.github.com --method GET --path '/repos/org/project/**'
```
Write the host without a scheme, such as `api.github.com` rather than
`https://api.github.com`. It follows the same patterns as network rules and can
include a port, but it must be a hostname. To match an IP address or a CIDR
range, use a network rule without `--method` or `--path`.
### Choose methods
Pass several methods as a comma-separated list, or `ANY` to match every
method. Method names are case-insensitive, and `ANY` can't be combined with
specific methods:
```console
$ sbx policy allow network api.github.com --method GET,HEAD
```
The accepted methods are `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, `DELETE`,
`OPTIONS`, `CONNECT`, and `TRACE`.
### Choose paths
A rule without `--path` matches every path on the host. A rule takes one path,
and a path needs a method. 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/**'
```
A path must start with `/` and be canonical. For the full path rules, see
[HTTP method and path](../reference/network-rules.md#http-method-and-path).
### Match query parameters
Add `--query` to require URL query parameters, separately from the path. Repeat
the flag to require more than one. Like a path, a query restriction needs a
method, so keep `--method` or use `--method ANY`:
```console
$ sbx policy allow network api.example.com --method GET --path '/search' \
--query 'team=platform' --query 'label=release*'
```
For value patterns and matching behavior, see
[Query parameters](../reference/network-rules.md#query-parameters).
### Block part of an allowed host
To restrict part of a host, add a deny rule with the same flags on top of a
broader allow:
```console
$ sbx policy allow network api.example.com
$ sbx policy deny network api.example.com --method POST --path '/admin/**'
```
## 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 <name>`:
```console
$ sbx policy rm network --sandbox my-sandbox --resource api.example.com
```
To remove an HTTP rule, name the same method, path, and any `--query` flags you
added it with, or use its rule ID:
```console
$ sbx policy rm network --resource api.example.com --method GET --path '/search' \
--query 'team=platform' --query 'label=release*'
```
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 you add UDP allow rules. The CLI warns you if
you save a UDP rule while UDP egress is off:
```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,
and `--protocol` restricts a deny rule to one. UDP rules follow the same
organization and local precedence as TCP rules.
Some UDP traffic is blocked whatever your rules allow:
- Traffic to a destination that needs an HTTP, SOCKS5, system, or PAC-selected
proxy, because those proxies can't carry UDP.
- Traffic to local-network destinations, including multicast, link-local, and
unspecified addresses, `255.255.255.255`, and the broadcast addresses of the
host's networks. This block applies before any policy is evaluated, so even a
rule that allows all hosts doesn't permit it, and discovery protocols 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
`<udp local network boundary>`.
To list UDP rules or check a destination:
```console
$ sbx policy ls --protocol udp
$ sbx policy check network --protocol udp api.example.com:443
```
## Set or reset the preset
If no preset is set, the CLI prompts you to choose one when you run a sandbox
in an interactive terminal. 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
CLI can't prompt you, so commands such as `sbx run` return an error until a
preset is set. Use `sbx policy init` to set the preset before you run a
sandbox:
```console
$ sbx policy init balanced
```
Available values are `allow-all` (Open), `balanced` (Balanced), and `deny-all`
(Locked Down). `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).
content/manuals/ai/governance/local/test-monitor.md
+109
View File
@@ -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` when
an organization policy is enforced for you.
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. |
| `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](../../sandboxes/architecture.md#networking).
The log records network requests by host, without their HTTP methods and
paths. 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.
content/manuals/ai/governance/local/try-it-out.md
+137
View File
@@ -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).
content/manuals/ai/governance/organization/_index.md
+70
View File
@@ -0,0 +1,70 @@
---
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" >}}
Organization governance lets you, the administrator, control what sandboxes can
do across your organization. You set the rules once in Docker Home, and they
apply to the sandboxes on every governed developer's machine, instead of each
developer deciding with local policy. Organization policy is default deny, so
those sandboxes can reach, mount, and use only what your policies allow.
## How organization governance works
Organization governance has three parts. Licenses and sign-in enforcement
decide who is governed, organization policies control what their sandboxes can
do, and audit logs record the decisions those policies make.
### Licenses and sign-in enforcement
Organization governance applies to the members of your organization who hold
an AI Governance license. You assign licenses in Docker Home, either to the
members you choose or automatically when members sign in to Docker Sandboxes.
For more details, see
[Manage licenses](/manuals/accounts/organization/manage/manage-licenses.md).
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.
### Organization policies
Organization policies control which destinations sandboxes can reach, which
host paths developers can mount, and which MCP servers developers can register
and use. You create them in Docker Home, or programmatically through the
[AI Governance API](/reference/api/ai-governance/). For more details, see
[Organization policies](policies/_index.md).
### Audit logs
[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.
## Developer experience
Developers keep using the same `sbx` commands. When an organization policy is
enforced for them, `sbx policy ls` shows `Governance: Managed by <org>` in its
status line, and only your allow rules grant access, so local and kit allow
rules on their machines stop applying. 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).
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.
## Get started
To set up organization governance step by step, see
[Get started with organization governance](get-started.md). To get an AI
Governance plan,
[contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales).
content/manuals/ai/governance/organization/audit/_index.md
+101
View File
@@ -0,0 +1,101 @@
---
title: 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. 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, where records go, and what you can
do with them.
> [!NOTE]
> Audit logs cover local sandboxes, the sandboxes that run on developers'
> machines. Cloud delivery stores their audit records in the cloud. It
> doesn't add cloud sandbox coverage. For cloud network decisions, see
> [Cloud policy logs](../../../sandboxes/cloud/network-policy.md#inspect-network-policy).
## What audit logs record
Audit logs cover two kinds of events from Docker Sandboxes: the policy decision
made for each request, and sandbox session lifecycle events.
Records contain metadata only, such as who made a request, what it targeted,
and what the policy decided. They never contain prompt content, agent output,
or parameter values. For every field a record can contain, see the
[Audit record reference](../../reference/audit-records.md).
Records come only from developers your organization governs: signed-in users
who have an AI Governance license and for whom an organization policy is
enforced. Other users don't generate audit records, so they don't appear in
audit events or SIEM forwarding output.
## 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, SIEM streaming, and
the Audit Logs API.
To choose which delivery modes your organization uses, see
[Configure audit delivery](configure.md).
### Where records are stored
With local delivery, the sandbox daemon on each machine writes audit records to
its audit directory. Local files stay on the host that produced them, whether
cloud delivery is on or off.
The directory follows each operating system's convention for application logs:
| 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\` |
Each file is named `audit-<utc-timestamp>-<process-uuid>-<seq>.jsonl`. The
daemon writes records to a temporary `.tmp` file first, then renames it to
`.jsonl` when it reaches a rotation threshold or shuts down cleanly. By
default, the threshold is 5 minutes, 1000 events, or 50 MiB, whichever comes
first. Collect only `.jsonl` files, because `.tmp` files are still being
written.
Docker Sandboxes never deletes `.jsonl` files, so retention and cleanup are up
to your log shipper or your own housekeeping.
## What you can do with records
How you use audit records depends on where they go:
- With cloud delivery, [view and export events](view-export.md) in
Docker Home, [forward them to your SIEM](siem.md), and
[retrieve them with the Audit Logs API](api.md). The hosted view, CSV export,
SIEM forwarding, and the API all require 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).
## Data handling
When cloud delivery is on, 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/).
content/manuals/ai/sandboxes/governance/audit/api.md → content/manuals/ai/governance/organization/audit/api.md
+7 -5
View File
@@ -1,12 +1,14 @@
---
title: Retrieve audit events with the API
linkTitle: Audit Logs API
linkTitle: Retrieve with the API
weight: 45
description: Retrieve and filter Docker AI Governance audit events with the Audit Logs API.
keywords: docker sandboxes, AI Governance, audit logs API, audit events, organization access token, OAT
aliases:
- /ai/sandboxes/governance/audit/api/
---
{{< summary-bar feature_name="AI Governance Audit Logs" >}}
{{< summary-bar feature_name="AI Governance" >}}
The Audit Logs API retrieves cloud-delivered Docker AI Governance events for
automation, investigation, and reporting. The API returns the same event data
@@ -17,8 +19,8 @@ shown in the hosted audit log view.
Before you use the API, you need:
- A Docker [AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md)
- Docker Cloud delivery turned on in [audit delivery settings](configure.md)
- An Organization Access Token (OAT) with the **View audit logs** permission
- Cloud delivery turned on in [audit delivery settings](configure.md)
- An organization access token (OAT) with the **View audit logs** permission
Personal Access Tokens and Docker account session tokens aren't supported.
@@ -85,7 +87,7 @@ array of events and an opaque cursor for the next page:
}
```
See the [audit record reference](record-reference.md) for category, decision,
See the [audit record reference](../../reference/audit-records.md) for category, decision,
action, and payload fields.
## Filter events
content/manuals/ai/governance/organization/audit/configure.md
+61
View File
@@ -0,0 +1,61 @@
---
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
[Delivery modes](_index.md#delivery-modes).
## Before you begin
Your organization needs:
- A Docker [AI Governance plan](/manuals/subscription-billing/plans/ai-governance.md)
- Organization owner access, or a
[custom role](/manuals/security/roles-and-permissions/custom-roles/_index.md)
with AI Governance audit permissions
## 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, 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**.
content/manuals/ai/governance/organization/audit/siem.md
+85
View File
@@ -0,0 +1,85 @@
---
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 cloud delivery, Docker forwards events directly to a supported
SIEM destination.
- With local delivery, your own log shipper collects the audit files from
each machine.
## 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 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. 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 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).
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.
content/manuals/ai/governance/organization/audit/view-export.md
+91
View File
@@ -0,0 +1,91 @@
---
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 view.
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 view. Use it 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
- [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 **Events**, **Allowed**,
**Denied**, and **Consent required**. **Consent required** counts the events
with an Approval required decision. 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).
content/manuals/ai/governance/organization/get-started.md
+152
View File
@@ -0,0 +1,152 @@
---
title: Get started with organization governance
linkTitle: Get started
weight: 10
description: Set up organization governance for Docker Sandboxes, from planning policies and configuring audit logs to assigning licenses, enforcing sign-in, deploying Docker Sandboxes, 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.
- Host paths that sandboxes mount as workspaces. By default, `sbx run` mounts
the directory it's run from, so allow the directories where developers keep
their projects. A sandbox can't start if its workspace isn't allowed.
- MCP servers that developers add with `sbx mcp add`. A server that an agent
connects to directly, without `sbx`, is a network destination, so plan for it
with your network rules instead.
Before you assign licenses, you can run `sbx policy log` on a developer's
machine to see the network requests its sandboxes make. Once developers are
governed, your audit logs record their network requests, mounts, and MCP
activity in more detail. If you're not sure what sandboxes need, start the
pilot team with the rules you're confident about, then review your audit logs
for requests your policies deny and add allow rules where developers need them.
Audit records are available after you configure audit delivery and assign
licenses in steps 3 and 4.
Then decide how to scope your policies. Use org-wide policies for guardrails
that must apply everywhere, such as deny rules that block a destination even
when a team-scoped policy allows it, and team-scoped policies for access that
only some teams need. For an example of how the two combine, see
[How rules decide a request](policies/_index.md#how-rules-decide-a-request).
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).
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: Configure audit delivery
Audit logs record the policy decisions made for your developers' sandboxes.
Configure delivery before you assign licenses, so records are collected from
the first governed request. 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 4: 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 5: 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 6: Deploy Docker Sandboxes
If your developers don't have Docker Sandboxes yet, deploy it after you assign
licenses and enforce sign-in, so developers are governed from their first
sign-in. For installation options, see
[Install Docker Sandboxes](/manuals/ai/sandboxes/install.md).
## Step 7: 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 8: Roll out to more teams
When the pilot team works as expected, assign licenses to more members, deploy
Docker Sandboxes to their machines, and widen the scope of your policies, or
add team-scoped policies for teams that need different access. As more
developers are governed, keep reviewing your audit logs for requests your
policies block, and add allow rules where developers need them. Each change you make reaches developer machines within 5 minutes.
For more details, see
[When policy changes reach developers](policies/_index.md#when-policy-changes-reach-developers).
content/manuals/ai/governance/organization/policies/_index.md
+141
View File
@@ -0,0 +1,141 @@
---
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 local and kit
rules on the developer's machine. 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 developers can mount into sandboxes.
- [Organization MCP access policies](mcp.md) control the MCP servers developers
can register and what agents can do with them. They use Cedar statements in
the `MCP` namespace instead of rules.
## Policy scope
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
member's team membership. Because an organization can mix org-wide and
team-scoped policies, a single member is often subject to several at once. The
policies that apply to a given member 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, a
host path can't be mounted unless a filesystem mount rule allows it, and 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.
For example, an org-wide policy allows `git.example.com` and denies
`paste.example.com`, and a team-scoped policy for the Data team allows
`packages.example.com` and `paste.example.com`:
| Destination | Data team member | Everyone else |
| ---------------------- | --------------------------------------- | ------------------------------ |
| `git.example.com` | Allowed by the org-wide policy | Allowed by the org-wide policy |
| `packages.example.com` | Allowed by the team-scoped policy | Blocked by default deny |
| `paste.example.com` | Blocked, because the org-wide deny wins | Blocked by the org-wide deny |
| Anything else | Blocked by default deny | Blocked by default deny |
An approval requirement adds a step before access is allowed. If the Data
team's policy required approval, a Data team member's first request to
`packages.example.com` would be blocked and they'd be asked to approve it, and
later requests would succeed. `paste.example.com` would still be blocked
without asking, because a deny never asks for approval. 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 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
allow rules are inactive and can't expand what the organization permits.
Deny rules apply from every source, so a local or kit deny rule can still
restrict access further.
The following table summarizes which rules are evaluated when an organization
policy is enforced:
| Rule | Evaluated |
| ------------------ | --------- |
| Organization allow | Yes |
| Organization deny | Yes |
| Local allow | No |
| Local deny | Yes |
| Kit allow | No |
| Kit deny | Yes |
Local and kit rules cover network access only, so a local or kit deny can
narrow your network rules but never your filesystem or MCP rules. A local deny
also takes precedence over an organization approval requirement, so the request
is blocked without asking for approval.
Approved destinations are the one exception to local allow rules being
inactive. When a developer approves a destination, the resulting rule records
their answer to your policy's approval requirement rather than granting new
access, so it stays active.
## 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).
content/manuals/ai/governance/organization/policies/create-manage.md
+105
View File
@@ -0,0 +1,105 @@
---
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, and only the rules you add differ.
To manage policies programmatically instead, use the
[AI Governance API](/reference/api/ai-governance/). For how scope, rule
evaluation, and precedence work, see [Organization policies](_index.md).
## 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
To scope a policy to teams, the teams must already exist in your organization.
Create teams and manage their members in one of two ways:
- Manually, by
[creating teams](/manuals/accounts/organization/manage/manage-a-team.md) 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.
A team-scoped policy follows team membership, so when someone joins or leaves a
team, including through IdP sync, the policies that apply to them update
automatically. For how org-wide and team-scoped policies combine, see
[Policy scope](_index.md#policy-scope).
## 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
Administrators can add an optional support message that appears after the policy denial
details when an organization policy blocks a sandbox action. 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 an organization 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.
content/manuals/ai/governance/organization/policies/filesystem.md
+48
View File
@@ -0,0 +1,48 @@
---
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 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 path only if one of your filesystem mount rules allows it, so a
developer can't create a sandbox for a directory you haven't approved. The
rules work at the level of the mount. Once a path is mounted, they don't
control which files inside it an agent can read or change.
Without an organization policy, a sandbox can mount any host path the developer
chooses. Developers can't add filesystem mount rules with local policy, but it
includes 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`. Under
an enforced organization policy, those built-in rules stop applying, and only
your filesystem mount rules decide which paths a sandbox can mount. For more
details, see
[How organization policy relates to local and kit rules](_index.md#how-organization-policy-relates-to-local-and-kit-rules).
This page explains what a filesystem mount rule can match and when your changes
reach developers. To create a filesystem access policy, see
[Create and manage organization policies](create-manage.md).
## What a filesystem mount rule can match
Each filesystem mount rule allows or denies `read`, `write`, or both on the
host paths it lists. A read-only workspace needs only `read`, and a writable
workspace needs both. Paths can use wildcards, and `~` expands to each user's
home directory, 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).
## 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.
content/manuals/ai/sandboxes/governance/access-controls/mcp.md → content/manuals/ai/governance/organization/policies/mcp.md
+80 -53
View File
@@ -1,36 +1,52 @@
---
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](../../../sandboxes/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.
[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 [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
Cedar syntax and language semantics, see the
[Cedar documentation](https://docs.cedarpolicy.com/).
Developers can't restrict MCP activity with local policy. Without an enforced
organization policy, the gateway doesn't evaluate Cedar policy and permits all
MCP activity. For more details, see
[How organization policy relates to local and kit rules](_index.md#how-organization-policy-relates-to-local-and-kit-rules).
## Govern the server lifecycle
MCP policies are written in Cedar. Docker defines the `MCP` namespace your
statements use, including the actions, resource types, attributes, and approval
annotation you can match. The examples on this page cover common access
patterns. For every action and attribute, see the
[MCP policy reference](../../reference/mcp-policy.md), and for Cedar syntax,
see the [Cedar documentation](https://docs.cedarpolicy.com/). If you manage
policies through the [AI Governance API](/reference/api/ai-governance/), an MCP
policy is a `cedar_v1` policy whose statements are part of the policy text
rather than separate rules.
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).
## 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.
@@ -40,28 +56,28 @@ doesn't automatically govern the other.
| Whether a server can be registered | When a developer runs `sbx mcp add` | The registered name and resolved server attributes, such as `identityURL` |
| What agents can do through the MCP gateway | When the gateway handles a governed request | The registered server name, tool annotations, resource URI, or prompt name |
Registration rules affect future registrations. They don't remove a saved
registration or prevent an existing registration from being loaded with
`sbx mcp load`. Use-time rules govern tool calls, resource reads, and prompt
retrieval from servers that are already registered or loaded.
Registration rules apply when a developer registers a server. They affect only
future registrations, so they don't remove a saved registration or stop an
existing one from being loaded with `sbx mcp load`.
Server names are chosen during registration. Registration rules can match the
chosen name and resolved server identity together. At use time, tools,
resources, and prompts are associated with the registered name, so rules for an
existing server must match every name under which it was registered.
Use-time rules apply to tool calls, resource reads, and prompt retrieval from
servers that are already registered or loaded. They don't hide anything:
registrations stay saved, and tool and resource listings can still show
entries that policy denies when an agent tries to use them.
Developers choose a server's name when they register it. Registration rules can
match that name together with the resolved server identity. At use time, tools,
resources, and prompts are tied to the registered name, so rules for an
existing server must match every name it was registered under.
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).
helpers, are governed at use time too. They're `MCP::Primordial` resources
rather than tools of a registered server. For details, see
[Built-in gateway tools](../../../sandboxes/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.
## Allowlist and blocklist policies
## Choose an access posture
When MCP policy enforcement is active for a user, registration and governed MCP
When an organization policy is enforced for a developer, registration and governed MCP
requests are denied unless a matching `permit` allows them. A matching `forbid`
overrides any `permit`, including a permit with `@requireApproval`.
@@ -75,12 +91,17 @@ permit (principal, action, resource);
This statement permits every MCP action that reaches Cedar evaluation. Add
`forbid` statements for the restrictions the policy must enforce.
Policy scope supplies the principal. Use organization or team scope instead of
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.
You don't need to match users, teams, tenants, or roles in Cedar. The policy's
organization or team scope decides who it applies to and supplies the
principal.
## 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
@@ -114,9 +135,9 @@ when { resource in MCP::Server::"example" };
Matching both the name and identity URL establishes a canonical registration.
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.
resource or prompt permit if developers 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,11 +195,11 @@ 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`
operations, while use-time policy controls requests from servers that are
registration and at use time. Registration rules control future `sbx mcp add`
operations, while use-time rules control requests from servers that are
already registered or loaded.
Prevent future registrations of the server by matching its identity URL:
@@ -215,12 +236,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](../../../sandboxes/security/isolation.md#docker-engine-isolation).
In a blocklist policy that otherwise permits registration, deny the host-run
server type:
@@ -234,12 +255,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 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.
Registration rules are 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.
Use-time rules are evaluated by the MCP gateway when a sandbox makes a
governed MCP request, such as a tool call, resource read, prompt retrieval, or
built-in gateway tool call. Once a policy change has
[synced to the developer's machine](_index.md#when-policy-changes-reach-developers),
use-time rules apply to subsequent governed MCP requests through the gateway.
To prevent use of an MCP server that is already registered or loaded, add
use-time rules for the registered server name. For more details, see
[Withdraw server access](#withdraw-server-access).
content/manuals/ai/governance/organization/policies/network.md
+119
View File
@@ -0,0 +1,119 @@
---
title: Organization network access policies
linkTitle: Network
weight: 10
description: Control outbound network access from Docker Sandboxes with organization network access 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 hosts, 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.
Developers can also add network rules on their own machines with
[local policy](../../local/network-rules.md), but under an enforced
organization policy, only your allow rules grant access. For more details, see
[How organization policy relates to local and kit rules](_index.md#how-organization-policy-relates-to-local-and-kit-rules).
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).
## 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
A network access 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).
In an organization policy, 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.
A request is handled as follows:
```mermaid
flowchart TD
request["Sandbox sends an outbound request"] --> denied{"Does any deny rule match?"}
denied -->|"Yes, from any source"| block["Block request"]
denied -->|"No"| orgallow{"Does an organization policy allow it?"}
orgallow -->|"No"| block
orgallow -->|"Yes"| needs{"Does any allowing policy require approval?"}
needs -->|"No"| allow["Allow request"]
needs -->|"Yes"| approved{"Did the developer already approve this destination?"}
approved -->|"Yes"| allow
approved -->|"No"| ask["Block request and ask the developer to approve"]
ask -.->|"Later requests after approval"| allow
```
Only a destination the developer has already approved satisfies the requirement.
Preset rules, kit 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).
## 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.
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.
content/manuals/ai/sandboxes/governance/monitor-and-enforce/sign-in-enforcement.md → content/manuals/ai/governance/organization/sign-in-enforcement.md
+111 -92
View File
@@ -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.
Organization policies 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
@@ -32,20 +29,21 @@ it.
2. When a user runs `sbx login`, they authenticate with Docker. Credentials
are saved temporarily, then Docker Sandboxes calls the Docker API to
verify organization membership.
3. If the user belongs to at least one allowed organization, login succeeds and
3. If the user belongs to at least one allowed organization, sign-in 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.
sign-in 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:
</plist>
```
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.
content/manuals/ai/governance/reference/_index.md
+6
View File
@@ -0,0 +1,6 @@
---
build:
render: never
title: Reference
weight: 30
---
content/manuals/ai/sandboxes/governance/reference/api.md → content/manuals/ai/governance/reference/api.md
+5 -3
View File
@@ -1,11 +1,13 @@
---
title: AI Governance API
linkTitle: API reference
linkTitle: AI Governance API
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/
goto: /reference/api/ai-governance/latest/
---
content/manuals/ai/governance/reference/audit-logs-api.md
+11
View File
@@ -0,0 +1,11 @@
---
title: AI Governance Audit Logs API
linkTitle: AI Governance Audit Logs API
weight: 55
description: HTTP API for retrieving Docker AI Governance audit events programmatically.
keywords: docker sandboxes, AI Governance, audit logs API, audit events, REST API
build:
render: never
sidebar:
goto: /reference/api/ai-governance-audit-logs/latest/
---
content/manuals/ai/sandboxes/governance/audit/record-reference.md → content/manuals/ai/governance/reference/audit-records.md
+94 -60
View File
@@ -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,36 +17,59 @@ 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 policy is in effect. |
| `org_name` | Display name of the organization whose 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
| Category | Description |
| --------------------------- | ------------------------------------------------------------- |
| `AUDIT_CATEGORY_MANAGEMENT` | Session lifecycle, policy sync, and configuration events. |
| `AUDIT_CATEGORY_EVALUATION` | Governance policy decisions, such as allow, deny, or consent. |
| `AUDIT_CATEGORY_EXECUTION` | Outcomes after an evaluated action runs. |
| Category | Description |
| --------------------------- | -------------------------------------------------------------------------- |
| `AUDIT_CATEGORY_MANAGEMENT` | Session lifecycle, policy sync, and configuration events. |
| `AUDIT_CATEGORY_EVALUATION` | Policy decisions for individual requests, 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
@@ -63,7 +88,7 @@ Docker evaluated it.
| Mode | Description |
| --------- | ------------------------------------------------------------------------------- |
| `enforce` | Your organization's governance policy is enforced. |
| `enforce` | Your organization policy is enforced. |
| `audit` | Docker records the decision for observability but doesn't enforce policy. |
| `off` | Governance isn't active. Docker still writes the record to the local audit log. |
@@ -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" }
}
```
content/manuals/ai/governance/reference/filesystem-rules.md
+49
View File
@@ -0,0 +1,49 @@
---
title: Filesystem mount rule syntax
linkTitle: Filesystem mount rules
weight: 20
description: Syntax for sandbox filesystem mount 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 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\<distro>\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.
content/manuals/ai/sandboxes/governance/reference/mcp-policy.md → content/manuals/ai/governance/reference/mcp-policy.md
+35 -28
View File
@@ -1,18 +1,25 @@
---
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
aliases:
- /ai/sandboxes/governance/reference/mcp-policy/
---
MCP policies are organization policies written in Cedar using Docker's `MCP`
namespace. This reference defines the Docker-specific policy surface for Model
Context Protocol (MCP) activity made available to sandboxes through Docker's
[MCP gateway](../../mcp-gateway.md).
[MCP gateway](../../sandboxes/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,
built-in gateway tools, resource reads, and prompt retrieval from servers that are
already registered or loaded.
Use this reference with [MCP access policies](../access-controls/mcp.md) for
common policy patterns. For the Cedar language, see the
Use this reference with
[Organization MCP access policies](../organization/policies/mcp.md) for common
policy patterns. For the Cedar language, see the
[Cedar documentation](https://docs.cedarpolicy.com/).
## Evaluation model
@@ -28,7 +35,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:
@@ -38,28 +45,28 @@ permit (principal, action, resource);
## Actions
| Action | Governs | Notes |
| ------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `register` | MCP server registration | Server registration needs an explicit `permit`. Use server attributes to scope registration. |
| `invokeTool` | MCP tool calls | Most tool access policies target this action. |
| `invokePrimordial` | Gateway meta-tool calls | Applies to built-in gateway tools such as `mcp-exec`, `mcp-add`, `code-mode`, and OAuth authorization helpers. |
| `readResource` | MCP resource reads | Rules match `MCP::Resource` and `resource.uri`. |
| `getPrompt` | MCP prompt retrieval | Rules match `MCP::Prompt` and `resource.name`. |
| `listTools` | MCP tool listing | Defined in the schema but not Cedar-gated. Tool listings can include tools denied at invocation. |
| `listResources` | MCP resource listing | Defined in the schema but not Cedar-gated. Resource listings can include resources denied by policy. |
| `subscribeResource` | MCP resource subscription | Defined in the schema but not Cedar-gated. |
| Action | Governs | Notes |
| ------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `register` | MCP server registration | Server registration needs an explicit `permit`. Use server attributes to scope registration. |
| `invokeTool` | MCP tool calls | Most tool access policies target this action. |
| `invokePrimordial` | Built-in gateway tool calls | Applies to built-in gateway tools such as `mcp-exec`, `mcp-add`, `code-mode`, and OAuth authorization helpers. |
| `readResource` | MCP resource reads | Rules match `MCP::Resource` and `resource.uri`. |
| `getPrompt` | MCP prompt retrieval | Rules match `MCP::Prompt` and `resource.name`. |
| `listTools` | MCP tool listing | Defined in the schema but not Cedar-gated. Tool listings can include tools denied at invocation. |
| `listResources` | MCP resource listing | Defined in the schema but not Cedar-gated. Resource listings can include resources denied by policy. |
| `subscribeResource` | MCP resource subscription | Defined in the schema but not Cedar-gated. |
## Resources
Match resources with the MCP entity type and attributes for the request.
| Entity | Match with | Notes |
| ----------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `MCP::Server` | Registered server name | The canonical server identity is the `resource.identityURL` attribute, not the entity ID. |
| `MCP::Tool` | Bare tool name | Use `resource.name`. Display prefixes aren't included. A bare-name match applies to every server exposing a tool with that name. |
| `MCP::Resource` | Resource URI | Use `resource.uri`. |
| `MCP::Prompt` | Prompt name | Use `resource.name`. |
| `MCP::Primordial` | Gateway meta-tool name | Match a specific primordial with an entity reference. |
| Entity | Match with | Notes |
| ----------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `MCP::Server` | Registered server name | The canonical server identity is the `resource.identityURL` attribute, not the entity ID. |
| `MCP::Tool` | Bare tool name | Use `resource.name`. Display prefixes aren't included. A bare-name match applies to every server exposing a tool with that name. |
| `MCP::Resource` | Resource URI | Use `resource.uri`. |
| `MCP::Prompt` | Prompt name | Use `resource.name`. |
| `MCP::Primordial` | Built-in gateway tool name | Match a specific built-in gateway tool with an entity reference. |
Examples:
@@ -83,8 +90,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. |
@@ -99,12 +106,12 @@ attributes, use `like`.
### Server type values
Local gateway registrations use these values:
Registrations through the MCP gateway use these values:
- `local-stdio`: a host-run stdio server. This includes explicit commands and
OCI-packaged stdio servers resolved from metadata with `--local`.
- `container-stdio`: an OCI-packaged server resolved from metadata without
`--local`. This value can appear in `register` decisions, but the local
`--local`. This value can appear in `register` decisions, but the MCP
gateway can't attach or run this server type.
- `remote-dcr`: a remote endpoint that doesn't require OAuth or supports OAuth
Dynamic Client Registration.
@@ -165,7 +172,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
@@ -187,7 +194,7 @@ don't require approval.
- Approval-gated requests are denied when the execution context can't relay an
MCP elicitation to the originating client. This includes tool calls made from
inside `code-mode`.
- Registration policy is evaluated when a server is registered. It doesn't
- Registration rules are evaluated when a server is registered. They don't
remove existing registrations or stop an already-loaded server by itself.
Govern existing registrations with use-time rules such as `invokeTool`,
`readResource`, and `getPrompt`.
content/manuals/ai/governance/reference/network-rules.md
+119
View File
@@ -0,0 +1,119 @@
---
title: Network and HTTP rule syntax
linkTitle: Network rules
weight: 10
description: Syntax for sandbox network rules, including hostname 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. There are two kinds:
- A host rule names no method or path, so it matches all traffic to the
destination. The Docker Home composer calls it an **All traffic** rule.
- An HTTP rule also names an HTTP method and URL path, with optional
query-parameter restrictions, so a policy can allow selected API requests.
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.
### Query parameters
An HTTP rule can also restrict query parameters independently of the path.
Use exact parameter names and values, or a single `*` at the start or end of a
value to match a suffix or prefix. A value of `*` matches any value, including
an empty one. Names cannot contain wildcards. Names and values are
case-sensitive.
For rules created with `--query`, every specified parameter must match.
Parameter order doesn't matter, and requests may include additional
parameters. Repeating a parameter name in the rule requires separate matching
occurrences in the request. A rule without query restrictions matches
regardless of query parameters.
Write names and value patterns using URL query encoding: `+` or `%20` for a
space, `%2B` for a literal plus, and `%2A` for a literal asterisk. Keep query
parameters out of `--path`. For CLI examples, see
[Allow or block HTTP methods and paths](../local/network-rules.md#allow-or-block-http-methods-and-paths).
### Combine HTTP and host rules
HTTP requests are evaluated against both kinds of rule. A host rule sets the
baseline for a host, and HTTP rules narrow access by method, path, and query
parameters:
| Rules that cover the host | Result for an HTTP request |
| ------------------------- | ------------------------------------------------------------------------------------------------------- |
| Host allow only | Allowed at any method and path |
| HTTP allow only | Allowed only where a rule matches the method, path, and any query restrictions. Anything else is denied |
| Host allow and HTTP deny | Requests matching the HTTP deny are blocked. The rest stay allowed |
| Host deny | Blocked. An HTTP allow can't reopen a denied host |
A host deny is therefore a floor that HTTP rules can't raise, while a host
allow is a ceiling that HTTP rules can carve into.
When a rule requires an HTTP 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 host 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`.
content/manuals/ai/governance/reference/policy-limits.md
+32
View File
@@ -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.
content/manuals/ai/governance/troubleshooting.md
+156
View File
@@ -0,0 +1,156 @@
---
title: Troubleshoot governance
linkTitle: Troubleshooting
weight: 40
description: Resolve blocked requests, inactive rules, approval prompts, policy sync, and missing audit records for Docker Sandboxes governance.
keywords: docker sandboxes, governance, troubleshooting, network policy, sbx policy, approval, organization policy, audit logs
---
These problems come from the governance rules that control what sandboxes can
reach and mount, and from the audit logs that record those decisions. For other
Docker Sandboxes problems, see
[Troubleshooting](../sandboxes/troubleshooting.md).
## A command fails with "global network policy has not been initialized"
No network preset is set, and the CLI can't prompt you to choose one because
it isn't running in an interactive terminal, for example in a CI pipeline or a
script. Commands that work with sandboxes, such as `sbx run`, `sbx create`, and
`sbx exec`, return this error until a preset is set. Set the preset first:
```console
$ sbx policy init balanced
```
Available values are `allow-all` (Open), `balanced` (Balanced), and `deny-all`
(Locked Down). For more details, see
[Set the preset without the prompt](local/network-rules.md#set-the-preset-without-the-prompt).
## Agent can't install packages or reach an API
Docker Sandboxes uses [network rules](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
```
Then allow the destinations your workflow needs:
```console
$ sbx policy allow network "*.npmjs.org,*.pypi.org,files.pythonhosted.org"
```
To allow all outbound traffic instead:
```console
$ sbx policy allow network "**"
```
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 <org>` 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](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 no organization policy is enforced for you, 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](local/approvals.md).
## An HTTP method or path is blocked on an allowed host
A destination that a host 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](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](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
[When policy changes reach developers](organization/policies/_index.md#when-policy-changes-reach-developers).
## 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 <org>` in the status line.
- The developer runs Docker Sandboxes 0.39.0 or later. Run `sbx version` to
check, and [install](../sandboxes/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](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](organization/audit/_index.md#where-records-are-stored).
content/manuals/ai/sandboxes/_index.md
+1 -1
View File
@@ -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.
content/manuals/ai/sandboxes/architecture.md
+3 -2
View File
@@ -77,8 +77,9 @@ $ DOCKER_SANDBOXES_ENABLE_VIRTIOFS_CACHE=0 sbx run <agent>
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
[Sandbox 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
content/manuals/ai/sandboxes/configuration/credentials.md
+4 -3
View File
@@ -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
content/manuals/ai/sandboxes/configuration/settings.md
+2 -1
View File
@@ -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
[Sandbox governance](../../governance/_index.md).
#### no_proxy.sandbox {.wrap-anywhere}
content/manuals/ai/sandboxes/configuration/upstream-proxy.md
+3 -3
View File
@@ -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 [Sandbox governance](../../governance/_index.md).
Docker Sandboxes sends two kinds of outbound traffic, and you can proxy them
independently:
content/manuals/ai/sandboxes/customize/author/tool-mixins.md
+3 -2
View File
@@ -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/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.
content/manuals/ai/sandboxes/faq.md
+8 -7
View File
@@ -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
content/manuals/ai/sandboxes/get-started.md
+4 -4
View File
@@ -60,8 +60,8 @@ is already configured, the CLI uses it without prompting.
To initialize the policy without an interactive prompt, run
`sbx policy init balanced` before `sbx run`. See
[Local policy](governance/access-controls/local.md) for the available presets
and how to change an existing policy.
[Start from a preset](../governance/local/_index.md#start-from-a-preset) for the
available presets and how to change an existing policy.
Replace `claude` with the agent you want to use — see [Agents](agents/) for the
full list.
@@ -128,7 +128,7 @@ $ sbx policy allow network registry.npmjs.org
With Balanced, common development services are permitted by default. With
Locked Down, destinations need an allow rule from you or a kit. Built-in agent
kits can add rules for their model providers. 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
@@ -175,5 +175,5 @@ Then explore:
network rules into a reusable definition you launch with a single flag.
- [Agents](agents/) — the full list of supported agents and how to configure
each one.
- [Governance](governance/) — centrally manage network, filesystem, and MCP
- [Sandbox governance](../governance/) — centrally manage network, filesystem, and MCP
policies across a team.
content/manuals/ai/sandboxes/governance/_index.md
-76
View File
@@ -1,76 +0,0 @@
---
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
---
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.
> [!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.
content/manuals/ai/sandboxes/governance/access-controls/_index.md
-27
View File
@@ -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.
content/manuals/ai/sandboxes/governance/access-controls/filesystem.md
-55
View File
@@ -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\<distro>\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.
content/manuals/ai/sandboxes/governance/access-controls/local.md
-394
View File
@@ -1,394 +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 the global network policy hasn't been initialized, the CLI prompts you to
choose a preset when you run a sandbox in an interactive terminal. If a policy
is already configured, including one carried over from an earlier installation,
the CLI uses it without prompting.
To initialize the policy without an interactive prompt, run:
```console
$ sbx policy init balanced
```
Available values are `allow-all`, `balanced`, and `deny-all`. Initialization is
a one-time setup. To change an existing preset, use
[`sbx policy reset`](#resetting).
| 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, an
uninitialized policy causes `sbx run` to return an error. Use `sbx policy init`
to set the preset before running a sandbox:
```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 <name>` 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 <name>` and can be removed with
`sbx policy rm network --sandbox <name> --resource <host>`.
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 <name>`:
```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/**'
```
Add `--query` to match URL query parameters
separately from the path:
```console
$ sbx policy allow network api.example.com --method GET --path '/search' \
--query 'team=platform' --query 'label=release*'
```
Repeat the flag to require multiple parameters. Keep `--method` in the command,
or use `--method ANY` to match all methods. Query restrictions use the same
flags on deny rules. For value patterns and matching behavior, see
[Query parameters](../concepts.md#query-parameters).
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, including
any `--query` flags, or by rule ID:
```console
$ sbx policy rm network --resource api.example.com --method GET --path '/search' \
--query 'team=platform' --query 'label=release*'
$ 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 `<udp local network boundary>`.
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>`,
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 <org>`, 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).
content/manuals/ai/sandboxes/governance/access-controls/network.md
-204
View File
@@ -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, path, and query parameters 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`, `--path`, and `--query` 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.
content/manuals/ai/sandboxes/governance/access-controls/organization.md
-245
View File
@@ -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).
content/manuals/ai/sandboxes/governance/audit/_index.md
-89
View File
@@ -1,89 +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)
- [Retrieve audit events with the API](api.md)
- [Audit record reference](record-reference.md)
content/manuals/ai/sandboxes/governance/audit/configure.md
-73
View File
@@ -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.
content/manuals/ai/sandboxes/governance/audit/local.md
-99
View File
@@ -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
<org>` 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-<utc-timestamp>-<process-uuid>-<seq>.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.
content/manuals/ai/sandboxes/governance/audit/siem.md
-72
View File
@@ -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.
content/manuals/ai/sandboxes/governance/audit/view-export.md
-50
View File
@@ -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.
content/manuals/ai/sandboxes/governance/concepts.md
-338
View File
@@ -1,338 +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, with optional query-parameter
restrictions, so a policy can allow selected API requests.
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).
##### Query parameters
An HTTP rule can also restrict query parameters independently of the path.
Use exact parameter names and values, or a single `*` at the start or end of a
value to match a suffix or prefix. A value of `*` matches any value, including
an empty one. Names cannot contain wildcards. Names and values are
case-sensitive.
For rules created with `--query`, every specified parameter must match.
Parameter order doesn't matter, and requests may include additional parameters. Repeating a parameter
name in the rule requires separate matching occurrences in the request. A rule
without query restrictions matches regardless of query parameters.
Write names and value patterns using URL query encoding: `+` or `%20` for a
space, `%2B` for a literal plus, and `%2A` for a literal asterisk. Keep query
parameters out of `--path`. For CLI examples, see
[Local HTTP rules](access-controls/local.md#http-method-and-path-rules).
##### Combine HTTP and network rules
HTTP requests are evaluated against both layers. A network rule sets the
baseline for a host, and HTTP rules narrow access by method, path, and query
parameters:
| 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, path, and any query restrictions. Anything else is denied |
| Network allow and HTTP deny | Requests matching the HTTP deny 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 an HTTP 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\<distro>\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).
content/manuals/ai/sandboxes/governance/monitor-and-enforce/_index.md
-16
View File
@@ -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.
content/manuals/ai/sandboxes/governance/monitor-and-enforce/monitoring.md
-238
View File
@@ -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:<name>` 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.
content/manuals/ai/sandboxes/governance/reference/_index.md
-15
View File
@@ -1,15 +0,0 @@
---
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
---
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.
content/manuals/ai/sandboxes/mcp-gateway.md
+5 -4
View File
@@ -559,7 +559,7 @@ to the sandbox's gateway and disappears when the gateway is replaced or stops.
In MCP access policies, built-in gateway tools are `MCP::Primordial` resources
and use the `invokePrimordial` action. Tools from registered MCP servers are
`MCP::Tool` resources and use the `invokeTool` action. For details, see the
[MCP policy reference](governance/reference/mcp-policy.md).
[MCP policy reference](../governance/reference/mcp-policy.md).
## Manage registrations
@@ -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.
content/manuals/ai/sandboxes/security/_index.md
+5 -5
View File
@@ -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
- [Sandbox governance](../../governance/): configure network, filesystem, and MCP policies
locally or across your organization
content/manuals/ai/sandboxes/security/defaults.md
+2 -3
View File
@@ -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 [Sandbox governance](../../governance/_index.md).
## Workspace defaults
content/manuals/ai/sandboxes/security/isolation.md
+6 -5
View File
@@ -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
[Sandbox 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.
content/manuals/ai/sandboxes/troubleshooting.md
+6 -27
View File
@@ -108,32 +108,11 @@ $ 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:
```console
$ sbx policy log
```
Then allow the domains your workflow needs:
```console
$ sbx policy allow network "*.npmjs.org,*.pypi.org,files.pythonhosted.org"
```
To allow all outbound traffic instead:
```console
$ 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).
For problems caused by network rules, approvals, or organization governance,
such as blocked requests, inactive allow rules, or missing audit records, see
[Troubleshoot governance](../governance/troubleshooting.md).
## Kit fails to install: source not in allowlist
@@ -191,7 +170,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
@@ -229,7 +208,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
content/manuals/ai/sandboxes/workflows/automation.md
+1 -1
View File
@@ -129,7 +129,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/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. |
content/manuals/platform-release-notes.md
+1 -1
View File
@@ -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/governance/organization/policies/_index.md) for
Docker AI products from Docker Home.
## 2026-03-03
content/manuals/subscription-billing/plans/ai-governance.md
+2 -2
View File
@@ -17,11 +17,11 @@ aliases:
> [!TIP]
> To subscribe to AI Governance, <a href="https://www.docker.com/pricing/contact-sales/" id="dkr_docs_cs_plans_aigov" class="link" rel="noopener">contact sales</a>.
[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/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.
## 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/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.
data/api-reference.json
Generated
+4 -4
View File
@@ -25041,7 +25041,7 @@
"experimental": false,
"guides": [],
"id": "ai-governance",
"manual": "/manuals/ai/sandboxes/governance/",
"manual": "/manuals/ai/governance/organization/policies/",
"operations": [
{
"acceptMedia": "application/json",
@@ -28965,10 +28965,10 @@
"exampleCount": 25,
"experimental": false,
"guides": [
"/manuals/ai/sandboxes/governance/audit/api.md"
"/manuals/ai/governance/organization/audit/api.md"
],
"id": "ai-governance-audit-logs",
"manual": "/manuals/ai/sandboxes/governance/audit/",
"manual": "/manuals/ai/governance/organization/audit/",
"operations": [
{
"acceptMedia": "application/json",
@@ -29586,7 +29586,7 @@
}
],
"owner": "docker/docs",
"product": "ai-governance",
"product": "ai-governance-audit-logs",
"schemaCount": 26,
"schemaURLs": {
"#/components/schemas/ApplicationRateLimitError": "/reference/api/ai-governance-audit-logs/latest/schemas/ApplicationRateLimitError/",
data/redirects.yml
+1 -1
View File
@@ -383,7 +383,7 @@
# Links in Desktop
# Docker Sandboxes
"/ai/sandboxes/governance/access-controls/mcp/":
"/ai/governance/organization/policies/mcp/":
- /go/mcp-policy/
"/ai/sandboxes/mcp-gateway/":
- /go/sbx-mcp-gateway/
data/summary.yaml
+2 -2
View File
@@ -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
hack/api-docs/sources.json
+4 -4
View File
@@ -36,19 +36,19 @@
"title": "AI Governance",
"source": "content/reference/api/ai-governance/api.yaml",
"owner": "docker/governor-services",
"manual": "/manuals/ai/sandboxes/governance/",
"manual": "/manuals/ai/governance/organization/policies/",
"connection": "hosted",
"guides": []
},
{
"id": "ai-governance-audit-logs",
"product": "ai-governance",
"product": "ai-governance-audit-logs",
"title": "AI Governance Audit Logs",
"source": "content/reference/api/ai-governance-audit-logs/api.yaml",
"owner": "docker/docs",
"manual": "/manuals/ai/sandboxes/governance/audit/",
"manual": "/manuals/ai/governance/organization/audit/",
"connection": "hosted",
"guides": ["/manuals/ai/sandboxes/governance/audit/api.md"]
"guides": ["/manuals/ai/governance/organization/audit/api.md"]
},
{
"id": "sandboxes",
layouts/_shortcodes/summary-bar.html
+1 -1
View File
@@ -13,7 +13,7 @@
"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"
}}
{{ $availabilityIcons := dict
"Experimental" "beaker"