Skip to content

sbx: document team-scoped governance policies #25251

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dvdksn merged 8 commits into from
Jun 4, 2026
+133 −52
Merged

sbx: document team-scoped governance policies #25251

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
3c6439c
sbx: document team-scoped governance policies
dvdksn Jun 3, 2026
d249426
sbx: add setup steps and team integration for org policies
dvdksn Jun 3, 2026
c7fa99d
sbx: drop bold from conceptual list labels per style guide
dvdksn Jun 3, 2026
58737db
sbx: tone down projecting language in team policy docs
dvdksn Jun 3, 2026
35a3208
sbx: align team/group-mapping framing with source docs
dvdksn Jun 3, 2026
9e6b34f
sbx: consolidate policy evaluation into a single source of truth
dvdksn Jun 3, 2026
5fa4f8f
sbx: fix Admin Console navigation for policy creation
dvdksn Jun 3, 2026
77936b5
sbx: cover filesystem policies in the default-deny principle
dvdksn Jun 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 55 additions & 33 deletions content/manuals/ai/sandboxes/governance/concepts.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,18 +11,17 @@ 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 different levels:
Policies exist at two levels:
Comment thread
dvdksn marked this conversation as resolved.

- **Local**: configured per machine using the `sbx policy` CLI. Applies to
sandboxes on that machine only.
- **Organization**: configured in the Docker Admin Console or via the
[Governance API](/reference/api/ai-governance/). Applies uniformly across every sandbox in the
organization.
- **Team**: applies to sandboxes used by a specific team within an
organization. Coming soon.
[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 multiple levels are active, organization policies take precedence over
local policies. See [Precedence](#precedence).
When organization governance is active, organization policies replace local
policies entirely. See [Precedence](#precedence).

A **rule** is the unit of access control within a policy. Each rule has:

Expand All @@ -34,6 +33,24 @@ A **rule** is the unit of access control within a policy. Each rule has:
Rules are grouped by domain: all rules in a policy must share the same domain,
either `network` or `filesystem`.

## 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/admin/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
Expand All @@ -43,12 +60,12 @@ hostnames, CIDR ranges, or ports.

**Hostname patterns**

| Pattern | Example | Matches |
| ------- | ------- | ------- |
| Exact hostname | `example.com` | `example.com` only, not subdomains |
| Single-level wildcard | `*.example.com` | One subdomain level: `api.example.com` |
| Multi-level wildcard | `**.example.com` | Any depth: `api.example.com`, `v2.api.example.com` |
| Hostname with port | `example.com:443` | `example.com` on port 443 only |
| Pattern | Example | Matches |
| --------------------- | ----------------- | -------------------------------------------------- |
| Exact hostname | `example.com` | `example.com` only, not subdomains |
| Single-level wildcard | `*.example.com` | One subdomain level: `api.example.com` |
| Multi-level wildcard | `**.example.com` | Any depth: `api.example.com`, `v2.api.example.com` |
| Hostname with port | `example.com:443` | `example.com` on port 443 only |
Comment on lines -46 to +68

@dvdksn dvdksn Jun 3, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just formatting noise


`example.com` and `*.example.com` don't cover each other. Specify both if you
need to match the root domain and its subdomains.
Expand All @@ -63,11 +80,11 @@ Both IPv4 and IPv6 notation are supported: `10.0.0.0/8`, `192.168.1.0/24`,
Filesystem rules use the actions `read` and `write`. Resources are host paths
that sandboxes can mount as workspaces.

| 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 |
| 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 |
Comment on lines -66 to +87

@dvdksn dvdksn Jun 3, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just formatting noise


Use `**` when you intend to match a directory tree recursively. A single `*`
only matches within one path segment and won't cross directory boundaries.
Expand All @@ -76,30 +93,35 @@ matches only direct children of `~`.

## Rule evaluation

All rules in a policy are evaluated against every request. The outcome follows
two principles:
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.
- 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.

**Default deny.** Outbound traffic is blocked unless an explicit allow rule
matches.
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.

These principles apply within whichever policy is active. When organization
governance is active, only organization rules are evaluated; local rules have
no effect.
Local rules take no part in this evaluation; see [Precedence](#precedence).

## Precedence

Local and organization policies don't combine. Which one applies depends on
whether your organization has governance enabled:

- **No organization governance**: local rules and any
- No organization governance: local rules and any
[kit-defined network rules](../customize/kits.md#control-network-access)
determine what sandboxes can access.
- **Organization governance active**: organization rules apply across all
developer machines, and local and kit-defined rules are not evaluated. They
still appear in `sbx policy ls`, but with an `inactive` status.
- Organization governance active: organization rules apply across all developer
machines, and local and kit-defined rules are not evaluated. They still appear
in `sbx policy ls`, but with an `inactive` status.

Within the active policy, deny rules beat allow rules regardless of specificity
or order.
When organization governance is active, a user's organization policies are
evaluated together, as described in [Rule evaluation](#rule-evaluation).
97 changes: 78 additions & 19 deletions content/manuals/ai/sandboxes/governance/org.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,10 @@ aliases:

[Local policies](local.md) give individual developers control over what their
sandboxes can access. Organization policy moves that control to the admin level:
rules defined in the [Docker Admin Console](https://app.docker.com/admin) apply
uniformly to every sandbox in the organization. When organization governance is
active, it replaces local `sbx policy` rules entirely — local rules are no
longer evaluated and can't be used to supplement or override the organization
policy.
rules defined in **Admin Console** apply to sandboxes across the organization,
Comment thread
dvdksn marked this conversation as resolved.
either to every member or to specific teams. When organization governance is active, it replaces local `sbx policy`
rules entirely — local rules are no longer evaluated and can't be used to
supplement or override the organization policy.

Admins can manage organization policies through the Admin Console UI or
programmatically using the [Governance API](/reference/api/ai-governance/).
Expand All @@ -25,13 +24,34 @@ programmatically using the [Governance API](/reference/api/ai-governance/).
> [Contact Docker Sales](https://www.docker.com/products/ai-governance/#contact-sales)
> to request access.

## Create a policy

Manage policies under **Admin Console**, a section in the left-hand navigation
Comment thread
dvdksn marked this conversation as resolved.
of [Docker Home](https://app.docker.com). Network and filesystem policies are
managed separately, under **Network access** and **Filesystem access**.

To create a policy:

1. Sign in to [Docker Home](https://app.docker.com) and select your
organization.
1. Select **Admin Console**, then **AI governance**.
1. Select **Network access** or **Filesystem access**, then **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. Select **Add rule** to add each rule. For rule syntax, see
[Policy concepts](concepts.md#rule-syntax).

Existing policies are listed with their name, scope, rule count, and last
update. Use the action menu (⋮) to edit or delete a policy.

## Network policies

### Configuring org-level network rules

Define network allow and deny rules in the Admin Console under
**AI governance > Network access**. Each rule takes a network target and an
action (allow or deny). You can add multiple entries at once, one per line.
A network rule takes a network target and an action (allow or deny). You can
add multiple entries at once, one per line.

For the full syntax reference (exact hostnames, wildcard subdomains, port
suffixes, and CIDR ranges), see [Policy concepts](concepts.md#network-rules).
Expand All @@ -47,24 +67,63 @@ Filesystem policies control which host paths a sandbox can mount as
workspaces. By default, sandboxes can mount any directory the user has
access to.

Admins can restrict which paths are mountable by defining filesystem allow
and deny rules in the Admin Console under **AI governance > Filesystem
access**. Each rule takes a path pattern and an action (allow or deny).
Admins can restrict which paths are mountable with filesystem allow and deny
rules. Each rule takes a path pattern and an action (allow or deny).

For path pattern syntax including the difference between `*` and `**`, see
[Policy concepts](concepts.md#filesystem-rules).

## Precedence
## 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.

Within the active policy, deny rules beat allow rules. If a domain matches both,
it's blocked regardless of specificity. Outbound traffic is blocked unless a
rule allows it.
### Before you start

Team scoping targets your organization's existing
[teams](/manuals/admin/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 the Admin Console.
- Automatically, by using
[group mapping](/manuals/enterprise/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 org-wide and team-scoped policies combine

A user is governed by all of their
[effective policies](concepts.md#policy-scope) at once — every org-wide policy,
plus the team-scoped policies for the teams they belong to. The rules combine
into a single evaluation in which deny always wins, so a team-scoped policy can
grant access on top of the org-wide policies but can't loosen a restriction they
impose. For the full evaluation model, see
[Rule evaluation](concepts.md#rule-evaluation).

This makes org-wide policies the natural home for guardrails that must hold
everywhere. For example, an org-wide policy can deny a category of domains for
all members, while a team-scoped policy grants a research team access to extra
package mirrors. Research-team members get the extra access, but the org-wide
deny still applies.

## Precedence

When organization governance is active, local rules are not evaluated. Only
organization rules set in the Admin Console determine what is allowed or
denied, and they can't be supplemented or overridden from a developer's machine.
The same model applies to filesystem policies: organization rules replace local
behavior entirely.
organization rules set in the Admin Console determine what is allowed or denied,
and they can't be supplemented or overridden from a developer's machine. The
same applies to filesystem policies: organization rules replace local behavior
entirely. For how a user's organization policies are evaluated together, see
[Policy concepts](concepts.md#rule-evaluation).

To unblock a domain when organization governance is active, update the rule in
the Admin Console or via the [API](/reference/api/ai-governance/). Without
Expand Down