diff --git a/content/manuals/ai/sandboxes/governance/concepts.md b/content/manuals/ai/sandboxes/governance/concepts.md index d72f5577c104..8c2ccaebfc00 100644 --- a/content/manuals/ai/sandboxes/governance/concepts.md +++ b/content/manuals/ai/sandboxes/governance/concepts.md @@ -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: - **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: @@ -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 @@ -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 | `example.com` and `*.example.com` don't cover each other. Specify both if you need to match the root domain and its subdomains. @@ -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 | Use `**` when you intend to match a directory tree recursively. A single `*` only matches within one path segment and won't cross directory boundaries. @@ -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). diff --git a/content/manuals/ai/sandboxes/governance/org.md b/content/manuals/ai/sandboxes/governance/org.md index b934c8ecc90c..902f6895dc7e 100644 --- a/content/manuals/ai/sandboxes/governance/org.md +++ b/content/manuals/ai/sandboxes/governance/org.md @@ -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, +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/). @@ -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 +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). @@ -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