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

Merge updated documentation base into policy listing clarification

Browse Source 
The governance reorganization replaced the monitoring page with focused policy pages. Preserve that structure and carry the fallback examples and explanation into Inspect policies, with the preset link updated to its replacement.
This commit is contained in:
David Karlsson committed 2026-11-04 08:33:19 +00:00
2 parents fe8c0ee83b d40e4d2c02
commit 7e8fd70015
156 files changed
+5922 -4670
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.github/workflows/sync-custom-role-permissions.yml
+71
View File
@@ -0,0 +1,71 @@
name: Sync custom role permissions
# Vendors the IAM source of truth (custom-role-metadata.yaml in
# docker/iam-services) into data/custom_role_permissions.yaml and opens a PR for
# review. The permissions reference page renders that file with an inline
# shortcode, so the site build never needs access to the private upstream
# repository.
# Triggered by the "Sync docs permissions" workflow in docker/iam-services when
# that file changes on main; can also be run manually.
on:
workflow_dispatch:
inputs:
ref:
description: "The git ref in docker/iam-services to read custom-role-metadata.yaml from."
type: string
required: false
default: "main"
concurrency:
group: sync-custom-role-permissions
cancel-in-progress: true
jobs:
sync:
name: Sync custom role permissions data
runs-on: ubuntu-latest
steps:
- id: setup
uses: docker/actions/setup@707e5d98a430d92e8e6c2d34faa5bfb2a9149e9b
with:
app_id: ${{ secrets.HUB_PLATFORM_APP_ID }}
app_private_key: ${{ secrets.HUB_PLATFORM_APP_PRIVATE_KEY }}
- name: Checkout docs
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
with:
token: ${{ steps.setup.outputs.token }}
show-progress: false
- name: Vendor custom-role-metadata.yaml from iam-services
env:
GH_TOKEN: ${{ steps.setup.outputs.token }}
REF: ${{ inputs.ref }}
run: |
gh api \
"repos/docker/iam-services/contents/internal/services/access_control/config/custom-role-metadata.yaml?ref=${REF}" \
-H "Accept: application/vnd.github.raw+json" \
> data/custom_role_permissions.yaml
- name: Create PR
uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0
with:
token: ${{ steps.setup.outputs.token }}
title: "⚙️ Sync custom role permissions data"
body: |
Automatically generated from
[`custom-role-metadata.yaml`](https://github.com/docker/iam-services/blob/main/internal/services/access_control/config/custom-role-metadata.yaml)
in `docker/iam-services` by the **Sync custom role permissions**
workflow, triggered by a change to that file.
Only `data/custom_role_permissions.yaml` is updated. The
permissions reference page renders it with an inline shortcode. If
this change is unexpected or shouldn't ship yet, close this PR —
the workflow will re-open it the next time the source changes.
commit-message: "Sync custom role permissions data"
sign-commits: true
add-paths: |
data/custom_role_permissions.yaml
branch: chore/sync-custom-role-permissions
delete-branch: true
Dockerfile
+1 -1
View File
@@ -5,7 +5,7 @@ ARG ALPINE_VERSION=3.23
ARG GO_VERSION=1.27
ARG HTMLTEST_VERSION=0.17.0
ARG VALE_VERSION=3.17.0
ARG HUGO_VERSION=0.163.0
ARG HUGO_VERSION=0.169.0
ARG NODE_VERSION=24
ARG PAGEFIND_VERSION=1.5.2
ARG TARGETARCH
_vendor/github.com/docker/compose/v5/docs/reference/compose.md
Generated
+6 -2
View File
@@ -215,9 +215,13 @@ Profiles can also be set by `COMPOSE_PROFILES` environment variable.
### Configuring parallelism
Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls.
Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls or builds.
Calling `docker compose --parallel 1 pull` pulls the pullable images defined in the Compose file
one at a time. This can also be used to control build concurrency.
one at a time.
Limiting build concurrency requires Buildx 0.38.0 or later. When services are linked by
`additional_contexts` (`service:`), Buildx rejects a limit lower than the number of images to
build, so Compose ignores it with a warning.
Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable.
_vendor/github.com/docker/compose/v5/docs/reference/compose_push.md
Generated
+6 -6
View File
@@ -22,12 +22,12 @@ services:
### Options
| Name | Type | Default | Description |
|:-------------------------|:-------|:--------|:-------------------------------------------------------|
| `--dry-run` | `bool` | | Execute command in dry run mode |
| `--ignore-push-failures` | `bool` | | Push what it can and ignores images with push failures |
| `--include-deps` | `bool` | | Also push images of services declared as dependencies |
| `-q`, `--quiet` | `bool` | | Push without printing progress information |
| Name | Type | Default | Description |
|:-------------------|:-------|:--------|:---------------------------------------------------------------------------|
| `--dry-run` | `bool` | | Execute command in dry run mode |
| `--ignore-missing` | `bool` | | Skip images that are not available locally instead of failing to push them |
| `--include-deps` | `bool` | | Also push images of services declared as dependencies |
| `-q`, `--quiet` | `bool` | | Push without printing progress information |
<!---MARKER_GEN_END-->
_vendor/github.com/docker/compose/v5/docs/reference/compose_run.md
Generated
+28 -27
View File
@@ -57,33 +57,34 @@ specified in the service configuration.
### Options
| Name | Type | Default | Description |
|:------------------------|:--------------|:---------|:---------------------------------------------------------------------------------|
| `--build` | `bool` | | Build image before starting container |
| `--cap-add` | `list` | | Add Linux capabilities |
| `--cap-drop` | `list` | | Drop Linux capabilities |
| `-d`, `--detach` | `bool` | | Run container in background and print container ID |
| `--dry-run` | `bool` | | Execute command in dry run mode |
| `--entrypoint` | `string` | | Override the entrypoint of the image |
| `-e`, `--env` | `stringArray` | | Set environment variables |
| `--env-from-file` | `stringArray` | | Set environment variables from file |
| `-i`, `--interactive` | `bool` | `true` | Keep STDIN open even if not attached |
| `-l`, `--label` | `stringArray` | | Add or override a label |
| `--name` | `string` | | Assign a name to the container |
| `--no-deps` | `bool` | | Don't start linked services |
| `-T`, `--no-tty` | `bool` | `true` | Disable pseudo-TTY allocation (default: auto-detected) |
| `-p`, `--publish` | `stringArray` | | Publish a container's port(s) to the host |
| `--pull` | `string` | `policy` | Pull image before running ("always"\|"missing"\|"never") |
| `-q`, `--quiet` | `bool` | | Don't print anything to STDOUT |
| `--quiet-build` | `bool` | | Suppress progress output from the build process |
| `--quiet-pull` | `bool` | | Pull without printing progress information |
| `--remove-orphans` | `bool` | | Remove containers for services not defined in the Compose file |
| `--rm` | `bool` | | Automatically remove the container when it exits |
| `-P`, `--service-ports` | `bool` | | Run command with all service's ports enabled and mapped to the host |
| `--use-aliases` | `bool` | | Use the service's network useAliases in the network(s) the container connects to |
| `-u`, `--user` | `string` | | Run as specified username or uid |
| `-v`, `--volume` | `stringArray` | | Bind mount a volume |
| `-w`, `--workdir` | `string` | | Working directory inside the container |
| Name | Type | Default | Description |
|:------------------------|:--------------|:---------|:-------------------------------------------------------------------------------------------------|
| `--build` | `bool` | | Build image before starting container |
| `--cap-add` | `list` | | Add Linux capabilities |
| `--cap-drop` | `list` | | Drop Linux capabilities |
| `-d`, `--detach` | `bool` | | Run container in background and print container ID |
| `--dry-run` | `bool` | | Execute command in dry run mode |
| `--entrypoint` | `string` | | Override the entrypoint of the image |
| `-e`, `--env` | `stringArray` | | Set environment variables |
| `--env-from-file` | `stringArray` | | Set environment variables from file |
| `-i`, `--interactive` | `bool` | `true` | Keep STDIN open even if not attached |
| `-l`, `--label` | `stringArray` | | Add or override a label |
| `--name` | `string` | | Assign a name to the container |
| `--no-deps` | `bool` | | Don't start linked services |
| `--no-recreate` | `bool` | | If dependent containers already exist, don't recreate them, even if their configuration diverged |
| `-T`, `--no-tty` | `bool` | `true` | Disable pseudo-TTY allocation (default: auto-detected) |
| `-p`, `--publish` | `stringArray` | | Publish a container's port(s) to the host |
| `--pull` | `string` | `policy` | Pull image before running ("always"\|"missing"\|"never") |
| `-q`, `--quiet` | `bool` | | Don't print anything to STDOUT |
| `--quiet-build` | `bool` | | Suppress progress output from the build process |
| `--quiet-pull` | `bool` | | Pull without printing progress information |
| `--remove-orphans` | `bool` | | Remove containers for services not defined in the Compose file |
| `--rm` | `bool` | | Automatically remove the container when it exits |
| `-P`, `--service-ports` | `bool` | | Run command with all service's ports enabled and mapped to the host |
| `--use-aliases` | `bool` | | Use the service's network useAliases in the network(s) the container connects to |
| `-u`, `--user` | `string` | | Run as specified username or uid |
| `-v`, `--volume` | `stringArray` | | Bind mount a volume |
| `-w`, `--workdir` | `string` | | Working directory inside the container |
<!---MARKER_GEN_END-->
_vendor/github.com/docker/compose/v5/docs/reference/compose_stats.md
Generated
+9 -7
View File
@@ -5,13 +5,15 @@ Display a live stream of container(s) resource usage statistics
### Options
| Name | Type | Default | Description |
|:--------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `-a`, `--all` | `bool` | | Show all containers (default shows just running) |
| `--dry-run` | `bool` | | Execute command in dry run mode |
| `--format` | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/engine/cli/formatting/ for more information about formatting output with templates |
| `--no-stream` | `bool` | | Disable streaming stats and only pull the first result |
| `--no-trunc` | `bool` | | Do not truncate output |
| Name | Type | Default | Description |
|:-----------------|:---------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--aggregate` | `bool` | | Show one line per project, summing the resource usage of its containers (only 'table' and 'json' formats) |
| `-a`, `--all` | `bool` | | Show all containers (default shows just running) |
| `--all-projects` | `bool` | | Show the containers of all projects instead of the current one, with their project (only 'table' and 'json' formats) |
| `--dry-run` | `bool` | | Execute command in dry run mode |
| `--format` | `string` | | Format output using a custom template:<br>'table': Print output in table format with column headers (default)<br>'table TEMPLATE': Print output in table format using the given Go template<br>'json': Print in JSON format<br>'TEMPLATE': Print output using the given Go template.<br>Refer to https://docs.docker.com/engine/cli/formatting/ for more information about formatting output with templates |
| `--no-stream` | `bool` | | Disable streaming stats and only pull the first result |
| `--no-trunc` | `bool` | | Do not truncate output |
<!---MARKER_GEN_END-->
_vendor/github.com/docker/compose/v5/docs/reference/docker_compose.yaml
Generated
+6 -2
View File
@@ -389,9 +389,13 @@ examples: |-
### Configuring parallelism
Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls.
Use `--parallel` to specify the maximum level of parallelism for concurrent engine calls or builds.
Calling `docker compose --parallel 1 pull` pulls the pullable images defined in the Compose file
one at a time. This can also be used to control build concurrency.
one at a time.
Limiting build concurrency requires Buildx 0.38.0 or later. When services are linked by
`additional_contexts` (`service:`), Buildx rejects a limit lower than the number of images to
build, so Compose ignores it with a warning.
Parallelism can also be set by the `COMPOSE_PARALLEL_LIMIT` environment variable.
_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_push.yaml
Generated
+13 -2
View File
@@ -23,12 +23,23 @@ usage: docker compose push [OPTIONS] [SERVICE...]
pname: docker compose
plink: docker_compose.yaml
options:
- option: ignore-missing
value_type: bool
default_value: "false"
description: |
Skip images that are not available locally instead of failing to push them
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: ignore-push-failures
value_type: bool
default_value: "false"
description: Push what it can and ignores images with push failures
deprecated: false
hidden: false
deprecated: true
hidden: true
experimental: false
experimentalcli: false
kubernetes: false
_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_run.yaml
Generated
+11
View File
@@ -168,6 +168,17 @@ options:
experimentalcli: false
kubernetes: false
swarm: false
- option: no-recreate
value_type: bool
default_value: "false"
description: |
If dependent containers already exist, don't recreate them, even if their configuration diverged
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: no-tty
shorthand: T
value_type: bool
_vendor/github.com/docker/compose/v5/docs/reference/docker_compose_stats.yaml
Generated
+22
View File
@@ -5,6 +5,17 @@ usage: docker compose stats [OPTIONS] [SERVICE]
pname: docker compose
plink: docker_compose.yaml
options:
- option: aggregate
value_type: bool
default_value: "false"
description: |
Show one line per project, summing the resource usage of its containers (only 'table' and 'json' formats)
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: all
shorthand: a
value_type: bool
@@ -16,6 +27,17 @@ options:
experimentalcli: false
kubernetes: false
swarm: false
- option: all-projects
value_type: bool
default_value: "false"
description: |
Show the containers of all projects instead of the current one, with their project (only 'table' and 'json' formats)
deprecated: false
hidden: false
experimental: false
experimentalcli: false
kubernetes: false
swarm: false
- option: format
value_type: string
description: |-
_vendor/modules.txt
Generated
+4 -4
View File
@@ -1,7 +1,7 @@
# github.com/moby/moby/api v1.56.1
# github.com/moby/buildkit v0.34.0
# github.com/docker/buildx v0.38.1
# github.com/docker/cli v29.9.1+incompatible
# github.com/docker/compose/v5 v5.6.1
# github.com/moby/buildkit v0.34.2
# github.com/docker/buildx v0.38.2
# github.com/docker/cli v29.9.2+incompatible
# github.com/docker/compose/v5 v5.7.0
# github.com/docker/model-runner v1.1.36
# github.com/docker/docker-agent v1.152.0
content/get-started/tutorials/admin-set-up.md
+3 -3
View File
@@ -76,7 +76,7 @@ pilot's feedback to refine the policy and its deployment communication.
Continue with these guides when you're ready to expand the deployment:
- [Set up your company for success with Docker](/guides/admin-set-up/) for the
- [Plan and roll out Docker](/manuals/accounts/organization/setup/rollout.md) for the
full deployment handbook
- [Manage organization members](/manuals/accounts/organization/manage/members.md)
for roles, teams, and bulk invitations
@@ -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/admin-set-up.md
-330
View File
@@ -1,330 +0,0 @@
---
title: Set up your company for success with Docker
linkTitle: Admin set up
summary: Get the most out of Docker by streamlining workflows, standardizing development environments, and ensuring smooth deployments across your company.
description: Learn how to onboard your company and take advantage of all of the Docker products and features.
keywords: admin, onboarding, deployment, organization setup, docker business, rollout
aliases:
- /guides/admin-set-up/comms-and-info-gathering/
- /guides/admin-set-up/deploy/
- /guides/admin-set-up/finalize-plans-and-setup/
- /guides/admin-set-up/testing/
params:
tags: [admin]
time: 20 minutes
image:
---
Docker's tools provide a scalable, secure platform that empowers your
developers to create, ship, and run applications faster. As an administrator,
you can streamline workflows, standardize development environments, and ensure
smooth deployments across your organization.
By configuring Docker products to suit your company's needs, you can optimize
performance, simplify user management, and maintain control over resources.
This guide helps you set up and configure Docker products to maximize
productivity and success for your team while meeting compliance and security
policies.
## Who’s this for?
- Administrators responsible for managing Docker environments within their
organization
- IT leaders looking to streamline development and deployment workflows
- Teams aiming to standardize application environments across multiple users
- Organizations seeking to optimize their use of Docker products for greater
scalability and efficiency
- Organizations with a
[Docker Business subscription](https://www.docker.com/pricing?ref=DocsGuides&refAction=DocsGuidesCTAClicked)
## What you’ll learn
- Why signing into your company's Docker organization provides access to usage
data and enhanced functionality
- How to standardize Docker Desktop versions and settings to create a consistent
baseline for all users, while allowing flexibility for advanced developers
- Strategies for implementing Docker's security configurations to meet company
IT and software development security requirements without hindering developer productivity
## Features covered
This guide covers the following Docker features:
- [Organizations](/manuals/accounts/organization/_index.md): The core structure
for managing your Docker environment, grouping users, teams, and image
repositories. Your organization was created with your subscription and is
managed by one or more owners. Users signed into the organization are
assigned seats based on the purchased subscription.
- [Enforce sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md):
By default, Docker Desktop doesn't require sign-in. You can configure
settings to enforce this and ensure your developers sign in to your
Docker organization.
- [SSO](/manuals/security/authentication/single-sign-on/_index.md): Without SSO,
user management in a Docker organization is manual. Setting
up an SSO connection between your identity provider and Docker ensures
compliance with your security policy and automates user provisioning. Adding
SCIM further automates user provisioning and de-provisioning.
- General and security settings: Configuring key settings ensures smooth
onboarding and usage of Docker products within your environment. You can also
enable security features based on your company's specific security needs.
## Who needs to be involved
- Docker organization owner: Must be involved in the process and is required
for several key steps
- DNS team: Needed during the SSO setup to verify the company domain
- MDM team: Responsible for distributing Docker-specific configuration files to
developer machines
- Identity Provider team: Required for configuring the identity provider and
establishing the SSO connection during setup
- Development lead: A development lead with knowledge of Docker configurations
to help establish a baseline for developer settings
- IT team: An IT representative familiar with company desktop policies to
assist with aligning Docker configuration to those policies
- Infosec: A security team member with knowledge of company development
security policies to help configure security features
- Docker testers: A small group of developers to test the new settings and
configurations before full deployment
## Tools integration
This guide covers integration with:
- Okta
- Entra ID SAML 2.0
- Azure Connect (OIDC)
- MDM solutions like Intune
## Communication and information gathering
### Communicate with your developers and IT teams
Before rolling out Docker Desktop across your organization, coordinate with key stakeholders to ensure a smooth transition.
#### Notify Docker Desktop users
You may already have Docker Desktop users within your company. Some steps in
this onboarding process may affect how they interact with the platform.
Communicate early with users to inform them that:
- They'll be upgraded to a supported version of Docker Desktop as part of the subscription onboarding
- Settings will be reviewed and optimized for productivity
- They'll need to sign in to the company's Docker organization using their
business email to access subscription benefits
#### Engage with your MDM team
Device management solutions, such as Intune and Jamf, are commonly used for
software distribution across enterprises. These tools are typically managed by a dedicated MDM team.
Engage with this team early in the process to:
- Understand their requirements and lead time for deploying changes
- Coordinate the distribution of configuration files
Several setup steps in this guide require JSON files, registry keys, or .plist
files to be distributed to developer machines. Use MDM tools to deploy these configuration files and ensure their integrity.
### Identify Docker organizations
Some companies may have more than one
[Docker organization](/manuals/accounts/organization/_index.md) created. These
organizations may have been created for specific purposes, or may not be
needed anymore.
If you suspect your company has multiple Docker organizations:
- Survey your teams to see if they have their own organizations
- Contact your Docker Support to get a list of organizations with users whose
emails match your domain name
### Gather requirements
[Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md) lets you preset numerous configuration parameters for Docker Desktop.
Work with the following stakeholders to establish your company's baseline
configuration:
- Docker organization owner
- Development lead
- Information security representative
Review these areas together:
- Security features and
[enforcing sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md)
for Docker Desktop users
- Additional Docker products included in your subscriptions
To view the parameters that can be preset, see [Configure Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md#step-two-configure-the-settings-you-want-to-lock-in).
### Optional: Meet with the Docker Implementation team
The Docker Implementation team can help you set up your organization,
configure SSO, enforce sign-in, and configure Docker Desktop.
To schedule a meeting, email successteam@docker.com.
## Finalize plans and begin setup
### Send finalized settings files to the MDM team
After reaching an agreement with the relevant teams about your baseline and
security configurations as outlined in the previous section, configure Settings Management either via [Docker Home](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md) or with an
[`admin-settings.json` file](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md).
Once the file is ready, collaborate with your MDM team to deploy your chosen
settings, along with your chosen method for [enforcing sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md).
> [!IMPORTANT]
>
> Test this first with a small number of Docker Desktop developers to verify the functionality works as expected before deploying more widely.
### Manage your organizations
If you have more than one organization, consider either [consolidating them
into one organization](/manuals/accounts/organization/setup/orgs.md) or creating a
[Docker company](/manuals/accounts/company/_index.md) to manage multiple
organizations.
### Begin setup
#### Set up single sign-on and domain verification
Single sign-on (SSO) lets developers authenticate using their identity
providers (IdPs) to access Docker. SSO is available for a whole company and all associated organizations, or an individual organization that has a Docker
Business subscription. For more information, see the
[documentation](/manuals/security/authentication/single-sign-on/_index.md).
You can also enable [SCIM](/manuals/security/provisioning/scim/_index.md)
for further automation of provisioning and deprovisioning of users.
#### Set up Docker product entitlements included in the subscription
[Docker Build Cloud](/manuals/build-cloud/_index.md) significantly reduces
build times, both locally and in CI, by providing a dedicated remote builder
and shared cache. Powered by the cloud, developer time and local resources are
freed up so your team can focus on more important things, like innovation.
To get started, [set up a cloud builder](https://app.docker.com/build/).
[Docker Scout](manuals/scout/_index.md) is a solution for proactively enhancing
your software supply chain security. By analyzing your images, Docker Scout
compiles an inventory of components, also known as a Software Bill of Materials
(SBOM). The SBOM is matched against a continuously updated vulnerability
database to pinpoint security weaknesses. To get started, see
[Quickstart](/manuals/scout/quickstart.md).
[Testcontainers Cloud](https://testcontainers.com/cloud/docs/) allows
developers to run containers in the cloud, removing the need to run heavy
containers on your local machine.
[Docker Hardened Images](/manuals/dhi/_index.md) are minimal, secure, and production-ready container base and application images maintained by Docker.
Designed to reduce vulnerabilities and simplify compliance, DHIs integrate
easily into your existing Docker-based workflows with little to no retooling
required.
#### Ensure you're running a supported version of Docker Desktop
> [!WARNING]
>
> This step could affect the experience for users on older versions of Docker
> Desktop.
Existing users may be running outdated or unsupported versions of
Docker Desktop. All users should update to a supported version. Docker Desktop
versions released within the past 6 months from the latest release are supported.
Use an MDM solution to manage the version of Docker Desktop for users. Users
may also get Docker Desktop directly from Docker or through a company software
portal.
## Testing
### SSO and SCIM testing
Test SSO and SCIM by signing in to Docker Desktop or Docker Hub with the email
address linked to a Docker account that is part of the verified domain.
Developers who sign in using their Docker usernames remain unaffected by the
SSO and SCIM setup.
> [!IMPORTANT]
>
> Some users may need CLI based logins to Docker Hub, and for this they will
> need a [personal access token (PAT)](/manuals/security/access-tokens/personal-access-tokens.md).
### Test Registry Access Management and Image Access Management
> [!WARNING]
>
> Communicate with your users before proceeding, as this step will impact all
> existing users signing into your Docker organization.
If you plan to use [Registry Access Management (RAM)](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md) and/or [Image Access Management (IAM)](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md):
1. Ensure your test developer signs in to Docker Desktop using their
organization credentials
2. Have them attempt to pull an unauthorized image or one from a disallowed
registry via the Docker CLI
3. Verify they receive an error message indicating that the registry is
restricted by the organization
### Deploy settings and enforce sign in to test group
Deploy the Docker settings and enforce sign-in for a small group of test users
via MDM. Have this group test their development workflows with containers on
Docker Desktop and Docker Hub to ensure all settings and the sign-in enforcement
function as expected.
### Test Docker Build Cloud capabilities
Have one of your Docker Desktop testers [connect to the cloud builder you created and use it to build](/manuals/build-cloud/usage.md).
### Test Testcontainers Cloud
Have a test developer [connect to Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started) and run a container in
the cloud to verify the setup is working correctly.
### Verify Docker Scout monitoring of repositories
Check the [Docker Scout dashboard](https://scout.docker.com/) to confirm that
data is being properly received for the repositories where Docker Scout has
been enabled.
### Verify access to Docker Hardened Images
Have a test developer attempt to [pull a Docker Hardened Image](/manuals/dhi/get-started.md) to confirm that
the team has proper access and can integrate these images into their workflows.
## Deploy your Docker setup
> [!WARNING]
>
> Communicate with your users before proceeding, and confirm that your IT and
> MDM teams are prepared to handle any unexpected issues, as these steps will
> affect all existing users signing into your Docker organization.
### Enforce SSO
Enforcing SSO means that anyone who has a Docker profile with an email address
that matches your verified domain must sign in using your SSO connection. Make
sure the Identity provider groups associated with your SSO connection cover all
the developer groups that you want to have access to the Docker subscription.
For instructions on how to enforce SSO, see [Enforce SSO](/manuals/security/authentication/single-sign-on/connect.md).
### Deploy configuration settings and enforce sign-in to users
Have the MDM team deploy the configuration files for Docker to all users.
### Next steps
Congratulations, you've successfully completed the admin implementation process
for Docker.
To continue optimizing your Docker environment:
- Review your [organization's usage data](/manuals/accounts/organization/insights.md) to track adoption
- Monitor [Docker Scout findings](/manuals/scout/explore/analysis.md) for security insights
- Explore [additional security features](/manuals/desktop/enterprise/hardened-desktop/_index.md) to enhance your configuration
content/guides/admin-user-management.md
-198
View File
@@ -1,198 +0,0 @@
---
title: Mastering user and access management
summary: Simplify user access while ensuring security and efficiency in Docker.
description: A guide for managing roles, provisioning users, and optimizing Docker access with tools like SSO and activity logs.
keywords: admin, user management, roles, permissions, sso, provisioning, access control
aliases:
- /guides/admin-user-management/audit-and-monitor/
- /guides/admin-user-management/onboard/
- /guides/admin-user-management/setup/
params:
tags: [admin]
featured: false
time: 20 minutes
image:
---
Managing roles and permissions is key to securing your Docker environment while enabling easy collaboration and operational efficiency. This guide walks IT administrators through the essentials of user and access management, offering strategies for assigning roles, provisioning users, and using tools like activity logs and Insights to monitor and optimize Docker usage.
## Who's this for?
- IT teams tasked with configuring and maintaining secure user access
- Security professionals focused on enforcing secure access practices
- Project managers overseeing team collaboration and resource management
## What you'll learn
- How to assess and manage Docker user access and align accounts with organizational needs
- When to use team configurations for scalable access control
- How to automate and streamline user provisioning with SSO, SCIM, and JIT
- How to get the most out of Docker's monitoring tools
## Tools integration
This guide covers integration with:
- Okta
- Entra ID SAML 2.0
- Azure Connect (OIDC)
## Setting up roles and permissions in Docker
With the right configurations, you can ensure your developers have easy access to necessary resources while preventing unauthorized access. This page guides you through identifying Docker users so you can allocate subscription seats efficiently within your Docker organization, and assigning roles to align with your organization's structure.
### Identify your Docker users and accounts
Before setting up roles and permissions, it's important to have a clear understanding of who in your organization requires Docker access. Focus on gathering a comprehensive view of active users, their roles within projects, and how they interact with Docker resources. This process can be supported by tools like device management software or manual assessments. Encourage all users to update their Docker accounts to use organizational email addresses, ensuring seamless integration with your subscription.
For steps on how you can do this, see [step 1 of onboarding your organization](/manuals/accounts/organization/setup/onboard.md).
### Assign roles strategically
When you invite members to join your Docker organization, you assign them a role.
Docker's predefined roles offer flexibility for various organizational needs. Assigning roles effectively ensures a balance of accessibility and security.
- Member: Non-administrative role. Members can view other members that are in the same organization.
- Editor: Partial administrative access to the organization. Editors can create, edit, and delete repositories. They can also edit an existing team's access permissions.
- Owner: Full organization administrative access. Owners can manage organization repositories, teams, members, settings, and billing.
For more information, see [Roles and permissions](/manuals/security/roles-and-permissions.md).
#### Enhance with teams
Teams in Docker provide a structured way to manage member access and they provide an additional level of permissions. They simplify permission management and enable consistent application of policies.
- Organize users into teams aligned with projects, departments, or functional roles. This approach helps streamline resource allocation and ensures clarity in access control.
- Assign permissions at the team level rather than individually. For instance, a development team might have "Read & Write" access to certain repositories, while a QA team has "Read-only" access.
- As teams grow or responsibilities shift, you can easily update permissions or add new members, maintaining consistency without reconfiguring individual settings.
For more information, see [Create and manage a team](/manuals/accounts/organization/manage/manage-a-team.md).
#### Example scenarios
- Development teams: Assign the member role to developers, granting access to the repositories needed for coding and testing.
- Team leads: Assign the editor role to team leads for resource management and repository control within their teams.
- Organizational oversight: Restrict the organization owner or company owner roles to a select few trusted individuals responsible for billing and security settings.
#### Best practices
- Apply the principle of least privilege. Assign users only the minimum permissions necessary for their roles.
- Conduct regular reviews of role assignments to ensure they align with evolving team structures and organizational responsibilities.
## Onboarding and managing roles and permissions in Docker
This page guides you through onboarding owners and members, and using tools like SSO and SCIM to future-proof onboarding going forward.
### Invite owners
When you create a Docker organization, you automatically become its sole owner. While optional, adding additional owners can significantly ease the process of onboarding and managing your organization by distributing administrative responsibilities. It also ensures continuity and prevents blockers if the primary owner is unavailable.
For detailed information on owners, see [Roles and permissions](/manuals/security/roles-and-permissions.md).
### Invite members and assign roles
Members are granted controlled access to resources and enjoy enhanced organizational benefits. When you invite members to join your Docker organization, you immediately assign them a role.
#### Benefits of inviting members
- Enhanced visibility: Gain insights into user activity, making it easier to monitor access and enforce security policies.
- Streamlined collaboration: Help members collaborate effectively by granting access to shared resources and repositories.
- Improved resource management: Organize and track users within your organization, ensuring optimal allocation of resources.
- Access to enhanced features: Members benefit from organization-wide perks, such as increased pull limits and access to premium Docker features.
- Security control: Apply and enforce security settings at an organizational level, reducing risks associated with unmanaged accounts.
For detailed information, see [Manage organization members](/manuals/accounts/organization/manage/members.md).
### Future-proof user management
A robust, future-proof approach to user management combines automated provisioning, centralized authentication, and dynamic access control. Implementing these practices ensures a scalable, secure, and efficient environment.
#### Secure user authentication with single sign-on (SSO)
Integrating Docker with your identity provider streamlines user access and enhances security.
SSO:
- Simplifies sign in, as users sign in with their organizational credentials.
- Reduces password-related vulnerabilities.
- Simplifies onboarding as it works seamlessly with SCIM and group mapping for automated provisioning.
For more information, see the [SSO documentation](/manuals/security/authentication/single-sign-on/_index.md).
#### Automate onboarding with SCIM and JIT provisioning
Streamline user provisioning and role management with [SCIM](/manuals/security/provisioning/scim/_index.md) and [Just-in-Time (JIT) provisioning](/manuals/security/provisioning/just-in-time.md).
With SCIM you can:
- Sync users and roles automatically with your identity provider.
- Automate adding, updating, or removing users based on directory changes.
With JIT provisioning you can:
- Automatically add users upon first sign in based on [group mapping](#simplify-access-with-group-mapping).
- Reduce overhead by eliminating pre-invite steps.
#### Simplify access with group mapping
Group mapping automates permissions management by linking identity provider groups to Docker roles and teams.
It also:
- Reduces manual errors in role assignments.
- Ensures consistent access control policies.
- Help you scale permissions as teams grow or change.
For more information on how it works, see [Group mapping](/manuals/security/provisioning/scim/group-mapping.md).
## Monitoring and insights
Activity logs and Insights are useful tools for user and access management in Docker. They provide visibility into user actions, team workflows, and organizational trends, helping enhance security, ensure compliance, and boost productivity.
### Activity logs
Activity logs track events at the organization and repository levels, offering a clear view of activities like repository changes, team updates, and billing adjustments.
Activity logs are available for Docker Team or Docker Business plans, with data retained for three months.
#### Key features
- Change tracking: View what changed, who made the change, and when.
- Comprehensive reporting: Monitor critical events such as repository creation, deletion, privacy changes, and role assignments.
#### Example scenarios
- Audit trail for security: A repository’s privacy settings were updated unexpectedly. The activity logs reveal which user made the change and when, helping administrators address potential security risks.
- Team collaboration review: Logs show which team members pushed updates to a critical repository, ensuring accountability during a development sprint.
- Billing adjustments: Track who added or removed subscription seats to maintain budgetary control and compliance.
For more information, see [Activity logs](/manuals/accounts/organization/activity-logs.md).
### Insights
Insights provide data-driven views of Docker usage to improve team productivity and resource allocation.
#### Key benefits
- Standardized environments: Ensure consistent configurations and enforce best practices across teams.
- Improved visibility: Monitor metrics like Docker Desktop usage, builds, and container activity to understand team workflows and engagement.
- Optimized resources: Track license usage and feature adoption to maximize the value of your Docker subscription.
#### Example scenarios
- Usage trends: Identify underutilized licenses or resources, allowing reallocation to more active teams.
- Build efficiency: Track average build times and success rates to pinpoint bottlenecks in development processes.
- Container utilization: Analyze container activity across departments to ensure proper resource distribution and cost efficiency.
For more information, see [Insights](/manuals/accounts/organization/insights.md).
### Next steps
Now that you've mastered user and access management in Docker, you can:
- Review your [activity logs](/manuals/accounts/organization/activity-logs.md) regularly to maintain security awareness
- Check your [Insights dashboard](/manuals/accounts/organization/insights.md) to identify opportunities for optimization
- Explore [advanced security features](/manuals/desktop/enterprise/hardened-desktop/_index.md) to further enhance your Docker environment
- Share best practices with your team to ensure consistent adoption of security policies
content/guides/azure-pipelines.md
+2 -1
View File
@@ -1,5 +1,6 @@
---
title: Introduction to Azure Pipelines with Docker
description: Automate Docker image builds and publishing with Azure Pipelines.
linkTitle: Azure Pipelines and Docker
summary: |
Learn how to automate Docker image build and push using Azure Pipelines.
@@ -308,5 +309,5 @@ With this Azure Pipelines CI setup, you get:
- [Azure Pipelines Documentation](https://learn.microsoft.com/en-us/azure/devops/pipelines/?view=azure-devops): Comprehensive guide to configuring and managing CI/CD pipelines in Azure DevOps.
- [Docker Task for Azure Pipelines](https://learn.microsoft.com/en-us/azure/devops/pipelines/tasks/build/docker): Detailed reference for using the Docker task in Azure Pipelines to build and push images.
- [Docker Buildx Bake](/manuals/build/bake/_index.md): Explore Docker's advanced build tool for complex, multi-stage, and multi-platform build setups. See also the [Mastering Buildx Bake Guide](/guides/bake/) for practical examples and best practices.
- [Bake targets](/manuals/build/bake/targets.md): Group builds, run checks, and export artifacts.
- [Docker Build Cloud](/manuals/build-cloud/_index.md): Learn about Docker's managed build service for faster, scalable, and multi-platform image builds in the cloud.
content/guides/bake.md
-515
View File
@@ -1,515 +0,0 @@
---
title: Mastering multi-platform builds, testing, and more with Docker Buildx Bake
linkTitle: Mastering Docker Buildx Bake
description: >
Learn how to manage simple and complex build configurations with Buildx Bake.
summary: >
Learn to automate Docker builds and testing with declarative configurations using Buildx Bake.
keywords: bake, buildx, multi-platform, build configuration, hcl, automation
params:
tags: [cicd]
time: 30 minutes
image: /images/guides/bake.webp
---
This guide demonstrates how to simplify and automate the process of building
images, testing, and generating build artifacts using Docker Buildx Bake. By
defining build configurations in a declarative `docker-bake.hcl` file, you can
eliminate manual scripts and enable efficient workflows for complex builds,
testing, and artifact generation.
## Assumptions
This guide assumes that you're familiar with:
- Docker
- [Buildx](/manuals/build/concepts/overview.md#buildx)
- [BuildKit](/manuals/build/concepts/overview.md#buildkit)
- [Multi-stage builds](/manuals/build/building/multi-stage.md)
- [Multi-platform builds](/manuals/build/building/multi-platform.md)
## Prerequisites
- You have a recent version of Docker installed on your machine.
- You have Git installed for cloning repositories.
- You're using the [containerd](/manuals/desktop/features/containerd.md) image store.
## Introduction
This guide uses an example project to demonstrate how Docker Buildx Bake can
streamline your build and test workflows. The repository includes both a
Dockerfile and a `docker-bake.hcl` file, giving you a ready-to-use setup to try
out Bake commands.
Start by cloning the example repository:
```bash
git clone https://github.com/dvdksn/bakeme.git
cd bakeme
```
The Bake file, `docker-bake.hcl`, defines the build targets in a declarative
syntax, using targets and groups, allowing you to manage complex builds
efficiently.
Here's what the Bake file looks like out-of-the-box:
```hcl
target "default" {
target = "image"
tags = [
"bakeme:latest",
]
attest = [
"type=provenance,mode=max",
"type=sbom",
]
platforms = [
"linux/amd64",
"linux/arm64",
"linux/riscv64",
]
}
```
The `target` keyword defines a build target for Bake. The `default` target
defines the target to build when no specific target is specified on the command
line. Here's a quick summary of the options for the `default` target:
- `target`: The target build stage in the Dockerfile.
- `tags`: Tags to assign to the image.
- `attest`: [Attestations](/manuals/build/metadata/attestations/_index.md) to attach to the image.
> [!TIP]
> The attestations provide metadata such as build provenance, which tracks
> the source of the image's build, and an SBOM (Software Bill of Materials),
> useful for security audits and compliance.
- `platforms`: Platform variants to build.
To execute this build, run the following command in the root of the
repository:
```console
$ docker buildx bake
```
With Bake, you avoid long, hard-to-remember command-line incantations,
simplifying build configuration management by replacing manual, error-prone
scripts with a structured configuration file.
For contrast, here's what this build command would look like without Bake:
```console
$ docker buildx build \
--target=image \
--tag=bakeme:latest \
--provenance=true \
--sbom=true \
--platform=linux/amd64,linux/arm64,linux/riscv64 \
.
```
## Testing and linting
Bake isn't just for defining build configurations and running builds. You can
also use Bake to run your tests, effectively using BuildKit as a task runner.
Running your tests in containers is great for ensuring reproducible results.
This section shows how to add two types of tests:
- Unit testing with `go test`.
- Linting for style violations with `golangci-lint`.
In Test-Driven Development (TDD) fashion, start by adding a new `test` target
to the Bake file:
```hcl
target "test" {
target = "test"
output = ["type=cacheonly"]
}
```
> [!TIP]
> Using `type=cacheonly` ensures that the build output is effectively
> discarded; the layers are saved to BuildKit's cache, but Buildx will not
> attempt to load the result to the Docker Engine's image store.
>
> For test runs, you don't need to export the build output — only the test
> execution matters.
To execute this Bake target, run `docker buildx bake test`. At this time,
you'll receive an error indicating that the `test` stage does not exist in the
Dockerfile.
```console
$ docker buildx bake test
[+] Building 1.2s (6/6) FINISHED
=> [internal] load local bake definitions
...
ERROR: failed to solve: target stage "test" could not be found
```
To satisfy this target, add the corresponding Dockerfile target. The `test`
stage here is based on the same base stage as the build stage.
```dockerfile
FROM base AS test
RUN --mount=target=. \
--mount=type=cache,target=/go/pkg/mod \
go test .
```
> [!TIP]
> The [`--mount=type=cache` directive](/manuals/build/cache/optimize.md#use-cache-mounts)
> caches Go modules between builds, improving build performance by avoiding the
> need to re-download dependencies. This shared cache ensures that the same
> dependency set is available across build, test, and other stages.
Now, running the `test` target with Bake will evaluate the unit tests for this
project. If you want to verify that it works, you can make an arbitrary change
to `main_test.go` to cause the test to fail.
Next, to enable linting, add another target to the Bake file, named `lint`:
```hcl
target "lint" {
target = "lint"
output = ["type=cacheonly"]
}
```
And in the Dockerfile, add the build stage. This stage will use the official
`golangci-lint` image on Docker Hub.
> [!TIP]
> Because this stage relies on executing an external dependency, it's generally
> a good idea to define the version you want to use as a build argument. This
> lets you manage version upgrades in the future by collocating
> dependency versions to the beginning of the Dockerfile.
```dockerfile {hl_lines=[2,"6-8"]}
ARG GO_VERSION="1.23"
ARG GOLANGCI_LINT_VERSION="1.61"
#...
FROM golangci/golangci-lint:v${GOLANGCI_LINT_VERSION}-alpine AS lint
RUN --mount=target=.,rw \
golangci-lint run
```
Lastly, to enable running both tests simultaneously, you can use the `groups`
construct in the Bake file. A group can specify multiple targets to run with a
single invocation.
```hcl
group "validate" {
targets = ["test", "lint"]
}
```
Now, running both tests is as simple as:
```console
$ docker buildx bake validate
```
## Building variants
Sometimes you need to build more than one version of a program. The following
example uses Bake to build separate "release" and "debug" variants of the
program, using [matrices](/manuals/build/bake/matrices.md). Using matrices lets
you run parallel builds with different configurations, saving time and ensuring
consistency.
A matrix expands a single build into multiple builds, each representing a
unique combination of matrix parameters. This means you can orchestrate Bake
into building both the production and development build of your program in
parallel, with minimal configuration changes.
The example project for this guide is set up to use a build-time option to
conditionally enable debug logging and tracing capabilities.
- If you compile the program with `go build -tags="debug"`, the additional
logging and tracing capabilities are enabled (development mode).
- If you build without the `debug` tag, the program is compiled with a default
logger (production mode).
Update the Bake file by adding a matrix attribute which defines the variable
combinations to build:
```diff {title="docker-bake.hcl"}
target "default" {
+ matrix = {
+ mode = ["release", "debug"]
+ }
+ name = "image-${mode}"
target = "image"
```
The `matrix` attribute defines the variants to build ("release" and "debug").
The `name` attribute defines how the matrix gets expanded into multiple
distinct build targets. In this case, the matrix attribute expands the build
into two workflows: `image-release` and `image-debug`, each using different
configuration parameters.
Next, define a build argument named `BUILD_TAGS` which takes the value of the
matrix variable.
```diff {title="docker-bake.hcl"}
target = "image"
+ args = {
+ BUILD_TAGS = mode
+ }
tags = [
```
You'll also want to change how the image tags are assigned to these builds.
As written, both matrix paths would generate the same image tag names, and
overwrite each other. Update the `tags` attribute use a conditional operator to
set the tag depending on the matrix variable value.
```diff {title="docker-bake.hcl"}
tags = [
- "bakeme:latest",
+ mode == "release" ? "bakeme:latest" : "bakeme:dev"
]
```
- If `mode` is `release`, the tag name is `bakeme:latest`
- If `mode` is `debug`, the tag name is `bakeme:dev`
Finally, update the Dockerfile to consume the `BUILD_TAGS` argument during the
compilation stage. When the `-tags="${BUILD_TAGS}"` option evaluates to
`-tags="debug"`, the compiler uses the `configureLogging` function in the
[`debug.go`](https://github.com/dvdksn/bakeme/blob/75c8a41e613829293c4bd3fc3b4f0c573f458f42/debug.go#L1)
file.
```diff {title=Dockerfile}
# build compiles the program
FROM base AS build
-ARG TARGETOS TARGETARCH
+ARG TARGETOS TARGETARCH BUILD_TAGS
ENV GOOS=$TARGETOS
ENV GOARCH=$TARGETARCH
RUN --mount=target=. \
--mount=type=cache,target=/go/pkg/mod \
- go build -o "/usr/bin/bakeme" .
+ go build -tags="${BUILD_TAGS}" -o "/usr/bin/bakeme" .
```
That's all. With these changes, your `docker buildx bake` command now builds
two multi-platform image variants. You can introspect the canonical build
configuration that Bake generates using the `docker buildx bake --print`
command. Running this command shows that Bake will run a `default` group with
two targets with different build arguments and image tags.
```json {collapse=true}
{
"group": {
"default": {
"targets": ["image-release", "image-debug"]
}
},
"target": {
"image-debug": {
"attest": ["type=provenance,mode=max", "type=sbom"],
"context": ".",
"dockerfile": "Dockerfile",
"args": {
"BUILD_TAGS": "debug"
},
"tags": ["bakeme:dev"],
"target": "image",
"platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"]
},
"image-release": {
"attest": ["type=provenance,mode=max", "type=sbom"],
"context": ".",
"dockerfile": "Dockerfile",
"args": {
"BUILD_TAGS": "release"
},
"tags": ["bakeme:latest"],
"target": "image",
"platforms": ["linux/amd64", "linux/arm64", "linux/riscv64"]
}
}
}
```
Factoring in all of the platform variants as well, this means that the build
configuration generates 6 different images.
```console
$ docker buildx bake
$ docker image ls --tree
IMAGE ID DISK USAGE CONTENT SIZE USED
bakeme:dev f7cb5c08beac 49.3MB 28.9MB
├─ linux/riscv64 0eae8ba0367a 9.18MB 9.18MB
├─ linux/arm64 56561051c49a 30MB 9.89MB
└─ linux/amd64 e8ca65079c1f 9.8MB 9.8MB
bakeme:latest 20065d2c4d22 44.4MB 25.9MB
├─ linux/riscv64 7cc82872695f 8.21MB 8.21MB
├─ linux/arm64 e42220c2b7a3 27.1MB 8.93MB
└─ linux/amd64 af5b2dd64fde 8.78MB 8.78MB
```
## Exporting build artifacts
Exporting build artifacts like binaries can be useful for deploying to
environments without Docker or Kubernetes. For example, if your programs are
meant to be run on a user's local machine.
> [!TIP]
> The techniques discussed in this section can be applied not only to build
> output like binaries, but to any type of artifacts, such as test reports.
With programming languages like Go and Rust where the compiled binaries are
usually portable, creating alternate build targets for exporting only the
binary is trivial. All you need to do is add an empty stage in the Dockerfile
containing nothing but the binary that you want to export.
First, let's add a quick way to build a binary for your local platform and
export it to `./build/local` on the local filesystem.
In the `docker-bake.hcl` file, create a new `bin` target. In this stage, set
the `output` attribute to a local filesystem path. Buildx automatically detects
that the output looks like a filepath, and exports the results to the specified
path using the [local exporter](/manuals/build/exporters/local-tar.md).
```hcl
target "bin" {
target = "bin"
output = ["build/bin"]
platforms = ["local"]
}
```
Notice that this stage specifies a `local` platform. By default, if `platforms`
is unspecified, builds target the OS and architecture of the BuildKit host. If
you're using Docker Desktop, this often means builds target `linux/amd64` or
`linux/arm64`, even if your local machine is macOS or Windows, because Docker
runs in a Linux VM. Using the `local` platform forces the target platform to
match your local environment.
Next, add the `bin` stage to the Dockerfile which copies the compiled binary
from the build stage.
```dockerfile
FROM scratch AS bin
COPY --from=build "/usr/bin/bakeme" /
```
Now you can export your local platform version of the binary with `docker
buildx bake bin`. For example, on macOS, this build target generates an
executable in the [Mach-O format](https://en.wikipedia.org/wiki/Mach-O) — the
standard executable format for macOS.
```console
$ docker buildx bake bin
$ file ./build/bin/bakeme
./build/bin/bakeme: Mach-O 64-bit executable arm64
```
Next, let's add a target to build all of the platform variants of the program.
To do this, you can [inherit](/manuals/build/bake/inheritance.md) the `bin`
target that you just created, and extend it by adding the desired platforms.
```hcl
target "bin-cross" {
inherits = ["bin"]
platforms = [
"linux/amd64",
"linux/arm64",
"linux/riscv64",
]
}
```
Now, building the `bin-cross` target creates binaries for all platforms.
Subdirectories are automatically created for each variant.
```console
$ docker buildx bake bin-cross
$ tree build/
build/
└── bin
├── bakeme
├── linux_amd64
│ └── bakeme
├── linux_arm64
│ └── bakeme
└── linux_riscv64
└── bakeme
5 directories, 4 files
```
To also generate "release" and "debug" variants, you can use a matrix just like
you did with the default target. When using a matrix, you also need to
differentiate the output directory based on the matrix value, otherwise the
binary gets written to the same location for each matrix run.
```hcl
target "bin-all" {
inherits = ["bin-cross"]
matrix = {
mode = ["release", "debug"]
}
name = "bin-${mode}"
args = {
BUILD_TAGS = mode
}
output = ["build/bin/${mode}"]
}
```
```console
$ rm -r ./build/
$ docker buildx bake bin-all
$ tree build/
build/
└── bin
├── debug
│ ├── linux_amd64
│ │ └── bakeme
│ ├── linux_arm64
│ │ └── bakeme
│ └── linux_riscv64
│ └── bakeme
└── release
├── linux_amd64
│ └── bakeme
├── linux_arm64
│ └── bakeme
└── linux_riscv64
└── bakeme
10 directories, 6 files
```
## Conclusion
Docker Buildx Bake streamlines complex build workflows, enabling efficient
multi-platform builds, testing, and artifact export. By integrating Buildx Bake
into your projects, you can simplify your Docker builds, make your build
configuration portable, and wrangle complex configurations.
Experiment with different configurations and extend your Bake files to suit
your project's needs. You might consider integrating Bake into your CI/CD
pipelines to automate builds, testing, and artifact deployment. The flexibility
and power of Buildx Bake can significantly improve your development and
deployment processes.
### Further reading
For more information about how to use Bake, check out these resources:
- [Bake documentation](/manuals/build/bake/_index.md)
- [Matrix targets](/manuals/build/bake/matrices.md)
- [Bake file reference](/manuals/build/bake/reference.md)
- [Bake GitHub Action](https://github.com/docker/bake-action)
content/guides/compose-bake.md
-402
View File
@@ -1,402 +0,0 @@
---
title: Building Compose projects with Bake
description: Learn how to build Docker Compose projects with Docker Buildx Bake
summary: |
This guide demonstrates how you can use Bake to build production-grade images for Docker Compose projects.
keywords: docker compose, bake, buildx, multi-service, production builds, build configuration
params:
tags: [cicd]
time: 20 minutes
---
This guide explores how you can use Bake to build images for Docker Compose
projects with multiple services.
[Docker Buildx Bake](/manuals/build/bake/_index.md) is a build orchestration
tool that enables declarative configuration for your builds, much like Docker
Compose does for defining runtime stacks. For projects where Docker Compose is
used to spin up services for local development, Bake offers a way of seamlessly
extending the project with a production-ready build configuration.
## Prerequisites
This guide assumes that you're familiar with
- Docker Compose
- [Multi-stage builds](/manuals/build/building/multi-stage.md)
- [Multi-platform builds](/manuals/build/building/multi-platform.md)
## Orientation
This guide will use the
[dvdksn/example-voting-app](https://github.com/dvdksn/example-voting-app)
repository as an example of a monorepo using Docker Compose that can be
extended with Bake.
```console
$ git clone https://github.com/dvdksn/example-voting-app.git
$ cd example-voting-app
```
This repository uses Docker Compose to define the runtime configurations for
running the application, in the `compose.yaml` file. This app consists of the
following services:
| Service | Description |
| -------- | ---------------------------------------------------------------------- |
| `vote` | A front-end web app in Python which lets you vote between two options. |
| `result` | A Node.js web app which shows the results of the voting in real time. |
| `worker` | A .NET worker which consumes votes and stores them in the database. |
| `db` | A Postgres database backed by a Docker volume. |
| `redis` | A Redis instance which collects new votes. |
| `seed` | A utility container that seeds the database with mock data. |
The `vote`, `result`, and `worker` services are built from code in this
repository, whereas `db` and `redis` use pre-existing Postgres and Redis images
from Docker Hub. The `seed` service is a utility that invokes requests against
the front-end service to populate the database, for testing purposes.
## Build with Compose
When you spin up a Docker Compose project, any services that define the `build`
property are automatically built before the service is started. Here's the
build configuration for the `vote` service in the example repository:
```yaml {title="compose.yaml"}
services:
vote:
build:
context: ./vote # Build context
target: dev # Dockerfile stage
```
The `vote`, `result`, and `worker` services all have a build configuration
specified. Running `docker compose up` will trigger a build of these services.
Did you know that you can also use Compose just to build the service images?
The `docker compose build` command lets you invoke a build using the build
configuration specified in the Compose file. For example, to build the `vote`
service with this configuration, run:
```console
$ docker compose build vote
```
Omit the service name to build all services at once:
```console
$ docker compose build
```
The `docker compose build` command is useful when you only need to build images
without running services.
The Compose file format supports a number of properties for defining your
build's configuration. For example, to specify the tag name for the images, set
the `image` property on the service.
```yaml
services:
vote:
image: username/vote
build:
context: ./vote
target: dev
#...
result:
image: username/result
build:
context: ./result
#...
worker:
image: username/worker
build:
context: ./worker
#...
```
Running `docker compose build` creates three service images with fully
qualified image names that you can push to Docker Hub.
The `build` property supports a [wide range](/reference/compose-file/build.md)
of options for configuring builds. However, building production-grade images
are often different from images used in local development. To avoid cluttering
your Compose file with build configurations that might not be desirable for
local builds, consider separating the production builds from the local builds
by using Bake to build images for release. This approach separates concerns:
using Compose for local development and Bake for production-ready builds, while
still reusing service definitions and fundamental build configurations.
## Build with Bake
Like Compose, Bake parses the build definition for a project from a
configuration file. Bake supports HashiCorp Configuration Language (HCL), JSON,
and the Docker Compose YAML format. When you use Bake with multiple files, it
will find and merge all of the applicable configuration files into one unified
build configuration. The build options defined in your Compose file are
extended, or in some cases overridden, by options specified in the Bake file.
The following section explores how you can use Bake to extend the build options
defined in your Compose file for production.
### View the build configuration
Bake automatically creates a build configuration from the `build` properties of
your services. Use the `--print` flag for Bake to view the build configuration
for a given Compose file. This flag evaluates the build configuration and
outputs the build definition in JSON format.
```console
$ docker buildx bake --print
```
The JSON-formatted output shows the group that would be executed, and all the
targets of that group. A group is a collection of builds, and a target
represents a single build.
```json
{
"group": {
"default": {
"targets": [
"vote",
"result",
"worker",
"seed"
]
}
},
"target": {
"result": {
"context": "result",
"dockerfile": "Dockerfile",
},
"seed": {
"context": "seed-data",
"dockerfile": "Dockerfile",
},
"vote": {
"context": "vote",
"dockerfile": "Dockerfile",
"target": "dev",
},
"worker": {
"context": "worker",
"dockerfile": "Dockerfile",
}
}
}
```
As you can see, Bake has created a `default` group that includes four targets:
- `seed`
- `vote`
- `result`
- `worker`
This group is created automatically from your Compose file; it includes all of
your services containing a build configuration. To build this group of services
with Bake, run:
```console
$ docker buildx bake
```
### Customize the build group
Start by redefining the default build group that Bake executes. The current
default group includes a `seed` target — a Compose service used solely to
populate the database with mock data. Since this target doesn't produce a
production image, it doesn't need to be included in the build group.
To customize the build configuration that Bake uses, create a new file at the
root of the repository, alongside your `compose.yaml` file, named
`docker-bake.hcl`.
```console
$ touch docker-bake.hcl
```
Open the Bake file and add the following configuration:
```hcl {title=docker-bake.hcl}
group "default" {
targets = ["vote", "result", "worker"]
}
```
Save the file and print your Bake definition again.
```console
$ docker buildx bake --print
```
The JSON output shows that the `default` group only includes the targets you
care about.
```json
{
"group": {
"default": {
"targets": ["vote", "result", "worker"]
}
},
"target": {
"result": {
"context": "result",
"dockerfile": "Dockerfile",
"tags": ["username/result"]
},
"vote": {
"context": "vote",
"dockerfile": "Dockerfile",
"tags": ["username/vote"],
"target": "dev"
},
"worker": {
"context": "worker",
"dockerfile": "Dockerfile",
"tags": ["username/worker"]
}
}
}
```
Here, the build configuration for each target (context, tags, etc.) is picked
up from the `compose.yaml` file. The group is defined by the `docker-bake.hcl`
file.
### Customize targets
The Compose file currently defines the `dev` stage as the build target for the
`vote` service. That's appropriate for the image that you would run in local
development, because the `dev` stage includes additional development
dependencies and configurations. For the production image, however, you'll want
to target the `final` image instead.
To modify the target stage used by the `vote` service, add the following
configuration to the Bake file:
```hcl
target "vote" {
target = "final"
}
```
This overrides the `target` property specified in the Compose file with a
different value when you run the build with Bake. The other build options in
the Compose file (tag, context) remain unmodified. You can verify by inspecting
the build configuration for the `vote` target with `docker buildx bake --print
vote`:
```json
{
"group": {
"default": {
"targets": ["vote"]
}
},
"target": {
"vote": {
"context": "vote",
"dockerfile": "Dockerfile",
"tags": ["username/vote"],
"target": "final"
}
}
}
```
### Additional build features
Production-grade builds often have different characteristics from development
builds. Here are a few examples of things you might want to add for production
images.
Multi-platform
: For local development, you only need to build images for your local platform,
since those images are just going to run on your machine. But for images that
are pushed to a registry, it's often a good idea to build for multiple
platforms, arm64 and amd64 in particular.
Attestations
: [Attestations](/manuals/build/metadata/attestations/_index.md) are manifests
attached to the image that describe how the image was created and what
components it contains. Attaching attestations to your images helps ensure that
your images follow software supply chain best practices.
Annotations
: [Annotations](/manuals/build/metadata/annotations.md) provide descriptive
metadata for images. Use annotations to record arbitrary information and attach
it to your image, which helps consumers and tools understand the origin,
contents, and how to use the image.
> [!TIP]
> Why not just define these additional build options in the Compose file
> directly?
>
> The `build` property in the Compose file format does not support all build
> features. Additionally, some features, like multi-platform builds, can
> drastically increase the time it takes to build a service. For local
> development, you're better off keeping your build step simple and fast,
> saving the bells and whistles for release builds.
To add these properties to the images you build with Bake, update the Bake file
as follows:
```hcl
group "default" {
targets = ["vote", "result", "worker"]
}
target "_common" {
annotations = ["org.opencontainers.image.authors=username"]
platforms = ["linux/amd64", "linux/arm64"]
attest = [
"type=provenance,mode=max",
"type=sbom"
]
}
target "vote" {
inherits = ["_common"]
target = "final"
}
target "result" {
inherits = ["_common"]
}
target "worker" {
inherits = ["_common"]
}
```
This defines a new `_common` target that defines reusable build configuration
for adding multi-platform support, annotations, and attestations to your
images. The reusable target is inherited by the build targets.
With these changes, building the project with Bake produces three sets of
multi-platform images for the `linux/amd64` and `linux/arm64` architectures.
Each image is decorated with an author annotation, and both SBOM and provenance
attestation records.
## Conclusions
The pattern demonstrated in this guide provides a useful approach for managing
production-ready Docker images in projects using Docker Compose. Using Bake
gives you access to all the powerful features of Buildx and BuildKit, and also
helps separate your development and build configuration in a reasonable way.
### Further reading
For more information about how to use Bake, check out these resources:
- [Bake documentation](/manuals/build/bake/_index.md)
- [Building with Bake from a Compose file](/manuals/build/bake/compose-file.md)
- [Bake file reference](/manuals/build/bake/reference.md)
- [Mastering multi-platform builds, testing, and more with Docker Buildx Bake](/guides/bake/)
- [Bake GitHub Action](https://github.com/docker/bake-action)
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/guides/gha.md
-257
View File
@@ -1,257 +0,0 @@
---
title: Introduction to GitHub Actions with Docker
linkTitle: GitHub Actions and Docker
summary: |
Learn how to automate image build and push with GitHub Actions.
keywords: github actions, ci/cd, docker hub, build and push, automation, workflows
params:
tags: [cicd]
time: 10 minutes
---
This guide provides an introduction to building CI pipelines using Docker and
GitHub Actions. You will learn how to use Docker's official GitHub Actions to
build your application as a Docker image and push it to Docker Hub. By the end
of the guide, you'll have a simple, functional GitHub Actions configuration for
Docker builds. Use it as-is, or extend it further to fit your needs.
## Prerequisites
If you want to follow along with the guide, ensure you have the following:
- A verified Docker account.
- Familiarity with Dockerfiles.
This guide assumes basic knowledge of Docker concepts but provides explanations
for using Docker in GitHub Actions workflows.
## Get the sample app
This guide is project-agnostic and assumes you have an application with a
Dockerfile.
If you need a sample project to follow along, you can use [this sample
application](https://github.com/dvdksn/rpg-name-generator.git), which includes
a Dockerfile for building a containerized version of the app. Alternatively,
use your own GitHub project or create a new repository from the template.
{{% dockerfile.inline %}}
{{ $data := resources.GetRemote "https://raw.githubusercontent.com/dvdksn/rpg-name-generator/refs/heads/main/Dockerfile" }}
```dockerfile {collapse=true}
{{ $data.Content }}
```
{{% /dockerfile.inline %}}
## Configure your GitHub repository
The workflow in this guide pushes the image you build to Docker Hub. To do
that, you must authenticate with your Docker credentials (username and access
token) as part of the GitHub Actions workflow.
For instructions on how to create a Docker access token, see
[Create and manage access tokens](/manuals/security/access-tokens/personal-access-tokens.md).
Once you have your Docker credentials ready, add the credentials to your GitHub
repository so you can use them in GitHub Actions:
1. Open your repository's **Settings**.
2. Under **Security**, go to **Secrets and variables > Actions**.
3. Under **Secrets**, create a new repository secret named `DOCKER_PASSWORD`,
containing your Docker access token.
4. Next, under **Variables**, create a `DOCKER_USERNAME` repository variable
containing your Docker Hub username.
## Set up your GitHub Actions workflow
GitHub Actions workflows define a series of steps to automate tasks, such as
building and pushing Docker images, in response to triggers like commits or
pull requests. In this guide, the workflow focuses on automating Docker builds
and testing, ensuring your containerized application works correctly before
publishing it.
Create a file named `docker-ci.yml` in the `.github/workflows/` directory of
your repository. Start with the basic workflow configuration:
```yaml
name: Build and Push Docker Image
on:
push:
branches:
- main
pull_request:
```
This configuration runs the workflow on pushes to the main branch and on pull
requests. By including both triggers, you can ensure that the image builds
correctly for a pull request before it's merged.
## Extract metadata for tags and annotations
For the first step in your workflow, use the `docker/metadata-action` to
generate metadata for your image. This action extracts information about your
Git repository, such as branch names and commit SHAs, and generates image
metadata such as tags and annotations.
Add the following YAML to your workflow file:
```yaml
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@{{% param "checkout_action_version" %}}
- name: Extract Docker image metadata
id: meta
uses: docker/metadata-action@{{% param "metadata_action_version" %}}
with:
images: ${{ vars.DOCKER_USERNAME }}/my-image
```
These steps prepare metadata to tag and annotate your images during the build
and push process.
- The **Checkout** step clones the Git repository.
- The **Extract Docker image metadata** step extracts Git metadata and
generates image tags and annotations for the Docker build.
## Authenticate to your registry
Before you build the image, authenticate to your registry to ensure that you
can push your built image to the registry.
To authenticate with Docker Hub, add the following step to your workflow:
```yaml
- name: Log in to Docker Hub
uses: docker/login-action@{{% param "login_action_version" %}}
with:
username: ${{ vars.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
```
This step uses the Docker credentials [configured in the repository settings](#configure-your-github-repository).
## Build and push the image
Finally, build the final production image and push it to your registry. The
following configuration builds the image and pushes it directly to a registry.
```yaml
- name: Build and push Docker image
uses: docker/build-push-action@{{% param "build_push_action_version" %}}
with:
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
annotations: ${{ steps.meta.outputs.annotations }}
```
In this configuration:
- `push: ${{ github.event_name != 'pull_request' }}` ensures that images are
only pushed when the event is not a pull request. This way, the workflow
builds and tests images for pull requests but only pushes images for commits
to the main branch.
- `tags` and `annotations` use the outputs from the metadata action to apply
consistent tags and [annotations](/manuals/build/metadata/annotations.md) to
the image automatically.
## Attestations
SBOM (Software Bill of Materials) and provenance attestations improve security
and traceability, ensuring your images meet modern software supply chain
requirements.
With a small amount of additional configuration, you can configure
`docker/build-push-action` to generate Software Bill of Materials (SBOM) and
provenance attestations for the image, at build-time.
To generate this additional metadata, you need to make two changes to your
workflow:
- Before the build step, add a step that uses `docker/setup-buildx-action`.
This action configures your Docker build client with additional capabilities
that the default client doesn't support.
- Then, update the **Build and push Docker image** step to also enable SBOM and
provenance attestations.
Here's the updated snippet:
```yaml
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
- name: Build and push Docker image
uses: docker/build-push-action@{{% param "build_push_action_version" %}}
with:
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
annotations: ${{ steps.meta.outputs.annotations }}
provenance: true
sbom: true
```
For more details about attestations, refer to
[the documentation](/manuals/build/metadata/attestations/_index.md).
## Conclusion
With all the steps outlined in the previous section, here's the full workflow
configuration:
```yaml
name: Build and Push Docker Image
on:
push:
branches:
- main
pull_request:
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@{{% param "checkout_action_version" %}}
- name: Extract Docker image metadata
id: meta
uses: docker/metadata-action@{{% param "metadata_action_version" %}}
with:
images: ${{ vars.DOCKER_USERNAME }}/my-image
- name: Log in to Docker Hub
uses: docker/login-action@{{% param "login_action_version" %}}
with:
username: ${{ vars.DOCKER_USERNAME }}
password: ${{ secrets.DOCKER_PASSWORD }}
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
- name: Build and push Docker image
uses: docker/build-push-action@{{% param "build_push_action_version" %}}
with:
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
annotations: ${{ steps.meta.outputs.annotations }}
provenance: true
sbom: true
```
This workflow implements best practices for building and pushing Docker images
using GitHub Actions. This configuration can be used as-is or extended with
additional features based on your project's needs, such as
[multi-platform](/manuals/build/building/multi-platform.md).
### Further reading
- Learn more about advanced configurations and examples in the [Docker Build GitHub Actions](/manuals/build/ci/github-actions/_index.md) section.
- For more complex build setups, you may want to consider [Bake](/manuals/build/bake/_index.md). (See also the [Mastering Buildx Bake guide](/guides/bake/).)
- Learn about Docker's managed build service, designed for faster, multi-platform builds, see [Docker Build Cloud](/manuals/build-cloud/_index.md).
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/_index.md
+5
View File
@@ -84,6 +84,11 @@ access to many people at once. Use a team when several members need the
same repositories. Members can belong to the organization without joining
a team.
For a deployment across your organization, start with
[Plan and roll out Docker](/manuals/accounts/organization/setup/rollout.md).
For ongoing membership and permissions decisions, use
[Plan and maintain user access](/manuals/accounts/organization/manage/user-access.md).
## Next steps
Learn how to manage organizations in the following sections.
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/accounts/organization/manage/_index.md
+4
View File
@@ -5,6 +5,10 @@ weight: 20
description: Learn how to manage your Docker organization, including members, teams, licenses, seats, product access, and settings.
keywords: manage organization, members, teams, licenses, seats, product access, organization management, docker home, organization settings, deactivate organization
grid:
- title: User access workflow
description: Plan roles, provisioning, and ongoing access reviews.
icon: user-group
link: /accounts/organization/manage/user-access/
- title: Information
description: Update your organization's general information and settings.
icon: pencil-square
content/manuals/accounts/organization/manage/manage-licenses.md
+4 -4
View File
@@ -117,11 +117,11 @@ card.
When the toggle is on:
- Docker Team or Business: members receive a license when they sign in to
- Docker Team or Business: members receive a license when they use
Docker Desktop.
- AI Governance: members receive a license when they sign in to
[Docker Sandboxes](/manuals/ai/sandboxes/_index.md). The `sbx login`
command provisions licenses on a first-come, first-served basis.
- AI Governance: members receive a license when they use
[Docker Sandboxes](/manuals/ai/sandboxes/_index.md).
- Licenses are provisioned on a first-come, first-served basis.
- Licenses are assigned until exhausted.
- Once the available licenses are exhausted, automatic license assignment
stops until more licenses are available.
content/manuals/accounts/organization/manage/manage-products.md
+206 -86
View File
@@ -2,8 +2,14 @@
title: Manage usage and access for Docker products
linkTitle: Products
weight: 60
description: Learn how to manage access and usage for Docker products for your organization
keywords: organization, product access, product usage, access control, docker desktop, docker hub, docker scout, docker build cloud, docker offload, testcontainers cloud
description: >-
Control which Docker products organization members can use, and find
where to check usage
keywords: organization, product access, product usage, access control, seats,
licenses, docker desktop, docker hub, docker scout, docker build cloud,
docker offload, docker offload v1, testcontainers cloud, docker sandboxes,
ai governance
toc_max: 2
aliases:
- /admin/organization/manage/manage-products/
- /admin/organization/manage-products/
@@ -12,17 +18,38 @@ aliases:
{{< summary-bar feature_name="Admin orgs" >}}
Use this page to learn how to control and monitor product access and usage
for your organization's members. If you're looking for setup and
configuration instructions, see each product's manual under
[Next steps](#next-steps).
for your organization's members.
## Control access for your organization
## How product access and usage works
Organization members can access Docker products that your organization is
subscribed to by default. When signed in as an organization owner, you can
use the following procedures to control access for all members.
Members receive access to products through seats, licenses, and the controls
you configure:
### Docker Desktop access
- A member uses one seat on a Docker Team or Business
[subscription](/manuals/subscription-billing/plans/_index.md). The seat
includes the products in the plan, such as Docker Desktop and Docker Hub.
- Some products need a separate
[license](/manuals/accounts/organization/manage/manage-licenses.md) that
you assign to teams or members.
- After a member has a seat or license, the controls on this page set what
they can do in each product, such as which Hub images they can pull,
which repositories Scout analyzes, or whether Docker Offload v1 is
available in Docker Desktop.
Where a product has a usage allowance, the **Usage** section shows where to
check how much of it the organization has used. Products measure that
allowance in different units, such as build minutes, Hub pulls, or runtime
minutes.
This page covers product access, but does not cover access tokens.
For organization access tokens,
see [Access tokens](/manuals/security/access-tokens/_index.md).
## Docker Desktop
For setup and configuration, see the [Docker Desktop manual](../../../desktop/_index.md).
### Access
To manage Docker Desktop access:
@@ -30,12 +57,12 @@ To manage Docker Desktop access:
1. Manage members [manually](./members.md) or use
[provisioning](../../../security/provisioning/_index.md).
With sign-in enforced, only users who are a member of your organization can
use Docker Desktop after signing in.
With sign-in enforced, only members of your organization can use Docker
Desktop after they sign in.
### Docker Hub access
To manage Docker Hub access:
Image Access and Registry Access are Docker Desktop controls. Image Access
limits which images members can pull from Docker Hub. Registry Access
limits which registries Docker Desktop can reach.
1. Sign in to [Docker Home](https://app.docker.com/) and select your
organization, then select **Docker Desktop**.
@@ -44,113 +71,206 @@ To manage Docker Hub access:
1. Select **Image Access** to control
[Image Access Management](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md).
### Docker Build Cloud access
### Usage
To initially set up and configure Docker Build Cloud, sign in to
[Docker Build Cloud](https://app.docker.com/build) and follow the
on-screen instructions.
Desktop insights shows how members use Docker Desktop, including active
users, builds, containers, images, and extensions.
1. Sign in to [Docker Home](https://app.docker.com/) and select your
organization.
1. Select **Docker Desktop**, then
[**Desktop insights**](/manuals/accounts/organization/insights.md).
## Docker Hub
For setup and configuration, see the [Docker Hub manual](../../../docker-hub/_index.md).
### Usage
Hub usage counts how many times members pull images and how much space
your organization's repositories take up.
1. Sign in to [Docker Home](https://app.docker.com/) and select your
organization.
1. Select **Go to Hub**.
1. Select **Usage**, then **Pulls** or **Storage**. For example,
`https://hub.docker.com/orgs/{namespace}/usage`.
## Docker Build Cloud
For setup and configuration, see the [Docker Build Cloud manual](../../../build-cloud/_index.md).
### Access
To set up Docker Build Cloud, sign in to
[Docker Build Cloud](https://app.docker.com/build) and follow the on-screen
instructions.
To manage Docker Build Cloud access:
1. Sign in to [Docker Home](https://app.docker.com/), then select
[Docker Build Cloud](http://app.docker.com/build).
1. Select **Account settings**.
1. Sign in to [Docker Home](https://app.docker.com/) and select your
organization.
1. Select **Build Cloud**, then **Account settings**.
1. Select **Lock access to Docker Build Account**.
### Docker Scout access
> [!WARNING]
>
> **Lock access to Docker Build Account** removes the ability to use cloud
> builders or build minutes, and it purges build data.
To initially set up and configure Docker Scout, sign in to
[Docker Scout](https://scout.docker.com/) and follow the on-screen
instructions.
### Usage
Build minutes are the time your organization spends on cloud builds.
1. Sign in to [Docker Home](https://app.docker.com/) and select your
organization.
1. Select **Build Cloud**, then **Build minutes**.
## Docker Scout
For setup and configuration, see the [Docker Scout manual](../../../scout/_index.md).
### Access
To set up Docker Scout, sign in to [Docker Scout](https://scout.docker.com/)
and follow the on-screen instructions.
To manage Docker Scout access:
1. Sign in to [Docker Home](https://app.docker.com/), then select
[Docker Scout](https://scout.docker.com/).
1. Select your organization, then **Settings**.
1. To manage what repositories are enabled for Docker Scout analysis, select
**Repository settings**. For more information, see
[repository settings](../../../scout/explore/dashboard.md#repository-settings).
1. To manage access to Docker Scout for use on local images with Docker
Desktop, use
1. To manage which repositories Docker Scout analyzes, select
**Repository settings**. See
[Repository settings](../../../scout/explore/dashboard.md#repository-settings).
1. To manage Docker Scout for local images in Docker Desktop, use
[Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md)
and set `sbomIndexing` to `false` to disable, or to `true` to enable.
and set **SBOM indexing** (`sbomIndexing`) to **Enabled**, **Disabled**,
or **User defined**. **Enabled** indexes images when they are inspected
in Docker Desktop or with Docker Scout CLI commands.
### Testcontainers Cloud access
### Usage
To initially set up and configure Testcontainers Cloud, sign in to
[Repository settings](../../../scout/explore/dashboard.md#repository-settings)
lists the repositories Docker Scout analyzes. Follow the access steps above
and select **Repository settings**.
## Testcontainers Cloud
For setup and configuration, see
[Get started with Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started).
### Access
To set up Testcontainers Cloud, sign in to
[Testcontainers Cloud](https://app.testcontainers.cloud/) and follow the
on-screen instructions.
To manage access to Testcontainers Cloud:
1. Sign in to the [Testcontainers Cloud](https://app.testcontainers.cloud/),
1. Sign in to [Testcontainers Cloud](https://app.testcontainers.cloud/),
then select the menu icon.
1. Select **Account**, then **Settings**.
1. Choose **Lock access to Testcontainers Cloud**.
1. Select **Lock access to Testcontainers Cloud**.
### Docker Offload access
### Usage
> [!NOTE]
>
> Docker Offload isn't included in the core Docker subscription plans. To
> make Docker Offload available, you must
> [contact sales](https://www.docker.com/products/docker-offload/) and
> subscribe.
Billing shows the Testcontainers Cloud runtime minutes included with your
subscription.
To manage Docker Offload access for your organization, use [Settings
1. Sign in to [Docker Home](https://app.docker.com/) and select your
organization.
1. Select **Go to Testcontainers Cloud**.
1. Select the menu icon, then
[**Billing**](https://app.testcontainers.cloud/dashboard/billing).
## Docker Offload v1
For setup and configuration, see the [Docker Offload v1 manual](../../../offload/v1/_index.md).
Docker Offload v1 uses its own [license](./manage-licenses.md). Assign it to
teams or members, or turn on automatic assignment so members receive a
license the first time they use Docker Offload v1.
### Access
**Offload access** turns Docker Offload v1 on or off for the organization.
**Disabled** removes the ability for anybody in the organization, including
CI/CD, to use Offload resources or consume Offload minutes.
1. Sign in to [Docker Home](https://app.docker.com/) and select your
organization.
1. Select **Docker Offload**, then **Offload access**.
1. Set **Enable Docker Offload** to **Enabled** or **Disabled**.
1. When Offload is enabled, select **Allow GPU access** to let members run
GPU workloads in cloud mode.
To set the Docker Offload v1 default inside Docker Desktop, use [Settings
Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md):
1. Sign in to [Docker Home](https://app.docker.com/), then select **Docker
Desktop**.
1. Select **Settings Management**.
1. Configure the **Enable Docker Offload** setting to control whether
Docker Offload features are available in Docker Desktop. You can
configure this setting in five states:
- **Always enabled**: Docker Offload is always enabled and users cannot
disable it. The Offload toggle is always visible in the Docker Desktop
header. Recommended for VDI environments where local Docker execution
is not possible.
- **Enabled**: Docker Offload is enabled by default but users can
disable it in Docker Desktop settings. Suitable for hybrid
environments.
- **Disabled**: Docker Offload is disabled by default but users can
enable it in Docker Desktop settings.
- **Always disabled**: Docker Offload is disabled and users cannot
enable it. The option is visible but locked. Use when Docker Offload
is not approved for organizational use.
- **User defined**: No enforced default. Users choose whether to enable
or disable Docker Offload in their Docker Desktop settings.
1. Select **Docker Desktop**, then **Settings Management**.
1. Set **Enable Docker Offload** to one of these configurations:
- **Always enabled**: Offload stays on, and members cannot turn it off.
- **Enabled**: Offload is on by default, and members can turn it off.
- **Disabled**: Offload is off by default, and members can turn it on.
- **Always disabled**: Offload stays off, and members cannot turn it on.
- **User defined**: Docker Desktop does not enforce a default. Members
choose whether to turn Offload on.
1. Select **Save**.
For more details on Settings Management, see the [Settings
reference](/manuals/desktop/enterprise/hardened-desktop/settings-management/settings-reference.md#enable-docker-offload).
## Monitor product usage for your organization
### Usage
You can monitor usage for Docker products across your organization. Use the
following table to learn where you can monitor organization usage:
[Offload activity](../../../offload/v1/usage.md) shows Docker Offload v1
sessions, including how long they ran and which images they used.
| Product | Monitor usage |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Docker Desktop | From [Docker Home](https://app.docker.com/), view the [**Insights**](/manuals/accounts/organization/insights.md) page. |
| Docker Hub | From Docker Hub, view the [**Usage** page](https://hub.docker.com/usage). |
| Docker Build Cloud | From [Docker Build Cloud](http://app.docker.com/build), view the **Build minutes** page. |
| Docker Scout | From [Docker Home](https://app.docker.com/), select **Go to Scout** to view the [**Repository settings** page](https://scout.docker.com/settings/repos). |
| Testcontainers Cloud | From [Docker Home](https://app.docker.com/), select **Go to Testcontainers Cloud**, then select the menu icon. Go to the [**Billing** page](https://app.testcontainers.cloud/dashboard/billing). |
| Docker Offload | From [Docker Home](https://app.docker.com/), select **Offload**, then **Offload activity**. See [Docker Offload usage and billing](../../../offload/usage.md) for more details. |
1. Sign in to [Docker Home](https://app.docker.com/) and select your
organization.
1. Select **Docker Offload**, then **Offload activity**.
If your usage or seat count exceeds your subscription amount, you can
[add seats](./manage-seats.md) or [view available Docker plans](../../../subscription-billing/plans/_index.md) to meet your needs.
## AI Governance
For setup and configuration, see
[Docker Sandboxes](../../../ai/sandboxes/_index.md) and
[AI Governance](../../../ai/governance/_index.md).
AI Governance is the separate paid subscription that adds the
organization-level controls to
[Docker Sandboxes](../../../ai/sandboxes/_index.md): policies for what
members' local sandboxes can reach on the network, mount from the filesystem,
or call through MCP, plus sign-in enforcement and audit logs.
### Access
Organization policies govern only members who hold an AI Governance license.
- [Manage licenses](./manage-licenses.md): assign AI Governance licenses to
teams or members, or turn on **Automatic license assignment** so members
receive a license when they run `sbx login`.
- [Organization policies](../../../ai/governance/organization/policies/create-manage.md):
create network, filesystem, and MCP policies under **AI Platform** in Docker
Home, and scope them to the whole organization or to specific teams.
- [Sign-in enforcement](../../../ai/governance/organization/sign-in-enforcement.md):
deploy a configuration through your endpoint management tooling so
`sbx login` succeeds only for members of your organization.
### Usage
- [View licenses](./manage-licenses.md#view-licenses): the **Licenses** page
shows how many AI Governance licenses you have, how many are assigned, and
whether the assignments go to teams or to individual members.
- [View and export audit events](../../../ai/governance/organization/audit/view-export.md):
**AI Platform** > **Audit logs** shows the policy decisions Docker recorded
for members' sandboxes, including who made the request, which resource it
targeted, and whether Docker allowed or denied it.
## Next steps
For more detailed information about each product, including how to set up
and configure them, see the following manuals:
- [Docker Desktop](../../../desktop/_index.md)
- [Docker Hub](../../../docker-hub/_index.md)
- [Docker Build Cloud](../../../build-cloud/_index.md)
- [Docker Scout](../../../scout/_index.md)
- [Testcontainers Cloud](https://testcontainers.com/cloud/docs/#getting-started)
- [Docker Offload](../../../offload/_index.md)
- [Manage subscription seats](./manage-seats.md) to add seats, and
[Manage licenses](./manage-licenses.md) to assign product licenses.
- [Invite and manage organization members](./members.md) to invite people
and assign roles.
- [Plan and maintain user access](./user-access.md) to choose roles,
provisioning, and how you review access.
content/manuals/accounts/organization/manage/user-access.md
+130
View File
@@ -0,0 +1,130 @@
---
title: Plan and maintain user access
linkTitle: User access workflow
weight: 15
description: Identify Docker users, choose roles and provisioning methods, and review access and adoption across your organization.
keywords: admin, user management, roles, permissions, SSO, provisioning, access control
aliases:
- /guides/admin-user-management/
- /guides/admin-user-management/audit-and-monitor/
- /guides/admin-user-management/onboard/
- /guides/admin-user-management/setup/
---
Use this workflow to decide who needs access to your Docker organization,
assign appropriate permissions, and keep membership aligned with changing
responsibilities. It links to the procedures for onboarding, provisioning,
and monitoring so you can apply those decisions.
## Setting up roles and permissions in Docker
### Identify your Docker users and accounts
Inventory the people who need Docker access, the projects they work on, and
the resources they need. Use device management records or ask development
teams to identify existing Docker Desktop users. Ask users to use their
business email for their Docker accounts.
Follow [organization onboarding](/manuals/accounts/organization/setup/onboard.md)
for the identification procedure and seat planning. Keep this inventory as
the starting point for access reviews.
### Assign roles strategically
Choose the minimum permissions each person needs. Compare the built-in
Member, Editor, and Owner roles with
[Roles and permissions](/manuals/security/roles-and-permissions/_index.md).
If you need a combination of permissions that the built-in roles don't
provide, consider custom roles, which require Docker Business.
#### Enhance with teams
Group members by project, department, or shared repository needs. A member's
role determines organization-wide access, while team permissions apply to
specific repositories. Avoid granting an administrative role solely because
a developer needs access to a project's repositories.
Use [Create and manage a team](/manuals/accounts/organization/manage/manage-a-team.md)
to apply repository permissions to groups of members. Review team membership
when projects or responsibilities change.
## Onboarding and managing roles and permissions in Docker
### Invite owners
Decide who needs to administer membership, settings, and billing. Additional
owners can share these responsibilities and provide continuity when another
owner is unavailable. Review the permissions before assigning the role.
### Invite members and assign roles
Use your access inventory to assign roles and teams. Follow
[Onboard a Docker organization](/manuals/accounts/organization/setup/onboard.md)
for initial setup and
[Manage organization members](/manuals/accounts/organization/manage/members.md)
for invitations and membership changes.
### Choose a provisioning method {#future-proof-user-management}
Decide who will maintain membership as people join, move between teams, or
leave. Manual invitations can suit a small organization. For Docker Business
organizations using an identity provider, compare the
[provisioning methods](/manuals/security/provisioning/_index.md) before
choosing how to automate membership.
#### Secure user authentication with single sign-on (SSO)
[SSO](/manuals/security/authentication/single-sign-on/_index.md) authenticates
users through your identity provider. Plan it together with provisioning,
which controls account creation, updates, and removal.
#### Automate onboarding with SCIM and JIT provisioning
Choose a method based on the user lifecycle you need to manage:
- [Just-in-Time (JIT) provisioning](/manuals/security/provisioning/just-in-time.md)
creates and updates accounts during SSO sign-in. It doesn't deprovision users,
so plan how to remove access when users leave.
- [SCIM](/manuals/security/provisioning/scim/_index.md) synchronizes users
with your identity provider and supports deprovisioning. If you enable SCIM,
choose how it will work with JIT so the intended source manages user attributes.
Test adding a user, changing their team, and removing access before relying
on automated provisioning for the whole organization.
#### Simplify access with group mapping
Use [group mapping](/manuals/security/provisioning/scim/group-mapping.md)
to assign identity provider groups to Docker organizations and teams.
Group mapping works with SAML SSO or SCIM. For Microsoft Entra ID OIDC
connections, use SCIM to synchronize groups. Review the mappings when your
identity provider groups change.
## Monitoring and insights
Schedule access reviews with organization owners and team leads. Compare
membership with your access inventory, remove users who no longer need
access, and adjust roles and teams when responsibilities change.
### Activity logs
Use [activity logs](/manuals/accounts/organization/activity-logs.md) to review
organization and repository changes, including repository privacy changes
and subscription seat changes. Check who made an unexpected change and when
it happened. Docker Home retains logs for 90 days; plan exports if your audit
process needs a longer history.
### Insights
If your organization meets the subscription and configuration requirements,
use [Insights](/manuals/accounts/organization/insights.md) to review Docker
Desktop adoption, versions, builds, and container usage. Active user counts
include only users who send analytics. Compare usage with your membership
inventory before deciding whether to change access or subscription seats.
### Next steps
- Review [members](/manuals/accounts/organization/manage/members.md) and
[teams](/manuals/accounts/organization/manage/manage-a-team.md) on a regular schedule.
- Use [rollout planning](/manuals/accounts/organization/setup/rollout.md)
before deploying changes to Docker Desktop settings or sign-in requirements.
content/manuals/accounts/organization/setup/_index.md
+4
View File
@@ -13,6 +13,10 @@ keywords:
- organization namespace
- Docker Home
grid:
- title: Plan your rollout
description: Coordinate settings, pilot testing, and deployment.
icon: magnifying-glass-plus
link: /accounts/organization/setup/rollout/
- title: Create your organization
description: Choose a new namespace and subscription.
icon: building-storefront
content/manuals/accounts/organization/setup/onboard.md
+3
View File
@@ -170,6 +170,9 @@ Use these features to manage your organization's security posture:
## Next steps
- [Plan your rollout](/manuals/accounts/organization/setup/rollout.md) to
coordinate pilot testing and deployment with your IT teams.
- [Manage Docker products](../manage/manage-products.md) to configure
access and view usage.
- Configure
content/manuals/accounts/organization/setup/rollout.md
+158
View File
@@ -0,0 +1,158 @@
---
title: Plan and roll out Docker
linkTitle: Plan your rollout
weight: 40
description: Coordinate stakeholders, define Docker Desktop settings, test with a pilot group, and roll out Docker across your organization.
keywords: admin, onboarding, deployment, organization setup, Docker Desktop, rollout
aliases:
- /guides/admin-set-up/
- /guides/admin-set-up/comms-and-info-gathering/
- /guides/admin-set-up/deploy/
- /guides/admin-set-up/finalize-plans-and-setup/
- /guides/admin-set-up/testing/
---
Use this workflow to plan a Docker rollout across your organization, test its
settings with a pilot group, and coordinate deployment with your IT teams.
For invitations and sign-in configuration, follow
[Onboard a Docker organization](/manuals/accounts/organization/setup/onboard.md).
## Who needs to be involved
Identify the people responsible for each part of the rollout:
- Organization owners to manage membership and organization settings
- DNS and identity provider teams to verify domains and configure single sign-on (SSO)
- IT and mobile device management (MDM) teams to distribute Docker Desktop and configuration files
- Development leads and security representatives to agree on settings and security requirements
- A small group of developers to test the configuration before wider deployment
## Communication and information gathering
### Communicate with your developers and IT teams
Notify existing Docker Desktop users before changing versions, settings, or
sign-in requirements. Explain which changes they should expect, when the pilot
and wider rollout will happen, and where to report problems. Ask users to use
their business email for their Docker accounts.
Engage your MDM team early to understand deployment requirements and lead
times. Agree on how to distribute configuration files, registry keys, or
`.plist` files for your chosen deployment method.
### Identify Docker organizations
Survey teams to find existing Docker organizations and decide which ones
should be part of the rollout. If you need to administer multiple
organizations together, consider a
[Docker company](/manuals/accounts/company/_index.md). A company groups Docker
organizations; it is separate from the business deploying Docker Desktop.
### Gather requirements
Work with organization owners, development leads, and security representatives
to define a baseline that supports development workflows and company policies.
Agree on:
- Docker Desktop versions and update policies
- Settings developers can change and settings administrators must control
- Sign-in requirements, identity provider integration, and user provisioning
- Approved image sources and registries
- Additional Docker products your teams need and the subscriptions they require
Review [Settings Management](/manuals/desktop/enterprise/hardened-desktop/settings-management/_index.md)
and [Hardened Docker Desktop](/manuals/desktop/enterprise/hardened-desktop/_index.md)
to choose controls available with your subscription.
## Finalize plans and begin setup
### Send finalized settings files to the MDM team
Record the agreed baseline and configure it through
[Docker Home](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-admin-console.md)
or an [`admin-settings.json` file](/manuals/desktop/enterprise/hardened-desktop/settings-management/configure-json-file.md),
as appropriate for your subscription and deployment method. Coordinate with
your MDM team to prepare the configuration and your chosen method for
[enforcing sign-in](/manuals/desktop/enterprise/enforce-sign-in/_index.md).
Deploy to the pilot group before applying the settings more widely.
### Begin setup
Follow [organization onboarding](/manuals/accounts/organization/setup/onboard.md)
to identify users, invite owners and members, and configure sign-in and
provisioning. SSO and SCIM require Docker Business. Plan authentication and
provisioning together: SSO authenticates users, while provisioning controls
how users are added, updated, and removed.
Choose a supported Docker Desktop version and agree with IT on how users will
receive it through MDM, a software portal, or direct installation. See
[Docker Desktop deployment](/manuals/desktop/enterprise/enterprise-deployment.md).
If your rollout includes other Docker products, confirm access and complete
their setup before the pilot. For example, follow the setup documentation for
[Docker Build Cloud](/manuals/build-cloud/setup/_index.md),
[Docker Scout](/manuals/scout/quickstart.md), or
[Docker Hardened Images](/manuals/dhi/get-started.md).
## Testing
### SSO and SCIM testing
If you configure SSO or SCIM, test sign-in, provisioning, role assignments,
and team membership with pilot accounts. Include a user joining the
organization and a user leaving it. Follow the
[provisioning documentation](/manuals/security/provisioning/_index.md)
for the behavior of your chosen method. Check CLI authentication as well as
Docker Desktop and browser sign-in.
### Test Registry Access Management and Image Access Management
If your subscription and rollout include
[Registry Access Management](/manuals/desktop/enterprise/hardened-desktop/registry-access-management.md)
or [Image Access Management](/manuals/desktop/enterprise/hardened-desktop/image-access-management.md),
verify that pilot users can pull approved images and that configured
restrictions block disallowed sources. Tell pilot users about these
restrictions before testing them.
### Deploy settings and enforce sign in to test group
Apply the baseline settings and sign-in requirements to the pilot group.
Have developers run their normal projects on Docker Desktop and Docker Hub.
Confirm that required settings apply and that developers can still build,
pull, and run the containers they need. Use the
[pilot rollout tutorial](/get-started/tutorials/admin-set-up.md) for a focused
settings policy test.
For each additional product in your rollout, have a pilot developer complete
a representative task: build with a cloud builder, review Scout results, or
pull a Hardened Image. Record problems and adjust the baseline before wider
deployment.
## Deploy your Docker setup
Communicate the rollout schedule and expected changes to users. Confirm that
IT and MDM teams are ready to distribute the tested configuration and support
users who encounter problems.
### Enforce SSO
If your plan includes SSO enforcement, verify that your identity provider
configuration covers all intended users before enforcing it. Follow
[Configure SSO](/manuals/security/authentication/single-sign-on/connect.md)
for setup and enforcement. Enforcing SSO and enforcing Docker Desktop sign-in
are separate controls.
### Deploy configuration settings and enforce sign-in to users
Have the MDM team distribute the tested Docker configuration to the remaining
users. Provide instructions for sign-in and a support contact. Review feedback
after each deployment group before expanding the rollout.
### Next steps
- Review [organization Insights](/manuals/accounts/organization/insights.md),
if available for your subscription, to track Docker Desktop adoption and versions.
- Use the [user access workflow](/manuals/accounts/organization/manage/user-access.md)
to review membership and permissions after rollout.
- Monitor [Docker Scout findings](/manuals/scout/explore/analysis.md) for
repositories where you've configured Scout.
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
+212
View File
@@ -0,0 +1,212 @@
---
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
default-deny-all local all network: deny when no rule decides
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.
The `default-deny-all` row represents the built-in fallback: access is blocked
when no applicable policy decides a request. It never overrides an allow rule.
Its summary describes this condition instead of counting it as an explicit
deny. For how unmatched requests are handled under each preset, see
[How rules combine](_index.md#how-rules-combine).
## 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 groups rules by type. For example, the network section for a sandbox
with 42 allowed hosts and one explicitly denied host in its local policy shows:
```text
NETWORK
• allow 42 hosts from local-policy
• deny 1 host from local-policy
• fallback: deny when no rule decides from default-deny-all
```
The fallback appears on its own line, so `deny 1 host` counts only the explicit
deny. Other policies, such as those provided by kits, also contribute to the
sandbox's summary. 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/_index.md
+3
View File
@@ -29,6 +29,9 @@ each approach.
- [Build an agent workload](/manuals/ai/sandboxes/customize/author/build-an-agent.md)
to control the base environment, agent installation, and launch command.
You can also [use an existing agent image](/manuals/ai/sandboxes/customize/author/base-images.md#use-an-image-in-a-v3-workload).
- [Debug a kit](/manuals/ai/sandboxes/customize/author/debug.md) when one of its
install or startup commands fails. Read the progress output and the logs
inside the sandbox.
For complete kits you can study and adapt, see
[Kit examples](https://github.com/docker/sandbox-kit-spec/tree/main/examples)
content/manuals/ai/sandboxes/customize/author/debug.md
+169
View File
@@ -0,0 +1,169 @@
---
title: Debug a kit
linkTitle: Debug a kit
description: Read the setup progress output, find install and startup logs inside the sandbox, and fix a kit whose install or startup command fails.
keywords: sandboxes, sbx, kits, debug, troubleshooting, install, startup, logs
weight: 36
---
{{< summary-bar feature_name="Docker Sandboxes sbx" >}}
When a kit's install or startup command fails, `sbx` shows you which command
failed, in which kit, and where the full output is. This page shows how to read
that output, find the logs inside the sandbox, and fix the common causes.
## Read the progress output
During `sbx create` and `sbx run`, the configure agent phase prints one row for
each kit operation: install commands, init files, file copies, environment
variables, and the startup commands it registers. A finished row shows ✓ with
the elapsed time, or ✗ with the exit code.
Each command row shows the command's `description` when the kit sets one.
Otherwise it shows the first 60 characters of the command. It also shows the
kit that owns the command (`kit=<name>`) and the user it runs as (`user=<uid>`).
Set `description` on every install and startup command so the row says what the
command is for. Keep it short: a row shows at most 60 characters of it.
```yaml {title="my-kit/my-kit.yaml"}
capabilities:
- type: com.docker.sandbox/lifecycle@1
config:
install:
- command: apt-get update && apt-get install -y ripgrep
user: "0"
description: Install ripgrep
startup:
- command: rg --version > /tmp/rg-version
description: Record the ripgrep version
```
The rows for this kit look like this:
```text
AGENT
running 1 install command
✓ Install ripgrep (kit=my-kit, user=0, 12.4s)
view install logs: ls /var/log/sbx-kits
registering 1 startup command, run on every container start
○ Record the ripgrep version (kit=my-kit, user=agent)
view startup log: cat /var/log/sbx-kit-startup.log
```
## Read a failed install command
A failed install command prints the last 40 lines of its output under the row,
followed by a `docker run` line that runs the same command against the kit's
base image:
```text
✗ Install ripgrep (kit=my-kit, user=0, exit 100)
── captured output ──
E: Failed to fetch http://deb.debian.org/debian/dists/bookworm/InRelease 403 Forbidden
E: Unable to locate package ripgrep
──────────────────────
hint: reproduce locally with:
docker run --rm -u 0 <base-image> sh -c 'apt-get update && apt-get install -y ripgrep'
```
Copy the `docker run` line to iterate on the command without recreating the
sandbox each time. Change the command, run it again, and copy the working
version back into the kit. The reproduction runs in plain Docker, outside the sandbox, so the sandbox's
network policy doesn't apply. If the command works there but fails in the
sandbox, check the kit's network rules first.
## Find the logs inside the sandbox
The progress output shows only the end of a failed command. The sandbox keeps
the full record:
| Log | Contents |
| --- | --- |
| `/var/log/sbx-kits/<kit>/install-<n>.log` | Full output of one install command. `<n>` is the command's position in that kit's `install` list, starting at 0. |
| `/var/log/sbx-kit-startup.log` | Output of every startup command, from every container start. |
Read either log with `sbx exec`:
```console
$ sbx exec my-sandbox cat /var/log/sbx-kits/my-kit/install-0.log
$ sbx exec my-sandbox cat /var/log/sbx-kit-startup.log
```
Startup commands run on every container start. Each one writes these lines to
the startup log:
```text
> <script>
# <kit>: <description or command>
<the command's output>
ok <script>
```
A failing command ends with `fail <script> exit=<code>` instead of `ok`. It
also stops the startup commands after it, and the command that started the
sandbox (`sbx create`, `sbx run`, `sbx exec` after `sbx stop`, or
`sbx kit add`) prints a warning that points at the startup log with its last
lines. The sandbox stays usable.
After the create phase, the agent takes over the terminal. The logs in the
sandbox are the record you can come back to.
## Show everything with -D
Pass the global debug flag to `sbx create` or `sbx run`:
```console
$ sbx -D create --name my-sandbox shell --kit ./my-kit
```
With `-D`, each successful install command also streams its full output under
its row, and `sbx` prints the startup log after the sandbox starts.
### What `sbx` redacts
Everything a kit command prints reaches your terminal through one filter. It
removes terminal escape sequences and replaces known credential shapes, such as
GitHub, GitLab, OpenAI, Anthropic and AWS tokens, JSON Web Tokens, private keys
and `Authorization` headers, with a placeholder like `<GITHUB_TOKEN>`. The
filter protects you from a command that accidentally echoes your own secrets,
for example a token in `env` output or a key in a configuration dump. It is not
a defence against output written to defeat it, and it does not change a secret
you wrote into the kit's own command text. The install log inside the sandbox
keeps the raw output.
## Common causes
### The install command can't reach its package source
The log shows names that don't resolve, or HTTP 403 responses from the
sandbox proxy, from `apt`, `pip`, or `npm`. The kit's install-phase network
rules don't include the package mirror. Add it to `install.allow` in the
`com.docker.sandbox/network-policy@1` capability. The `apt` mirrors, for
example, can live on a different host than the one the command names.
### Two kits run `apt` at the same time
The log shows `Could not get lock /var/lib/dpkg/lock-frontend`. Another
install command, or the base image setup, holds the dpkg lock. Retry the
package command in the kit, for example with `-o DPkg::Lock::Timeout=120`
on `apt-get`.
### A startup command needs a tool that didn't install
The startup log shows `exec: <tool>: not found` after an install command for
that tool failed. Fix the install command first. Check its
`install-<n>.log`, then rerun the sandbox.
### The command needs root
The log shows `Permission denied` when the command writes to a system path or
installs a package, and the row shows `user=1000`. Set `user: "0"` on the
install command, or write to a location the agent user owns.
## Next steps
- [Kit authoring patterns](/manuals/ai/sandboxes/customize/author/patterns.md)
shows setup commands in context.
- [Sandbox troubleshooting](/manuals/ai/sandboxes/troubleshooting.md) covers
other sandbox problems.
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
-261
View File
@@ -1,261 +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
default-deny-all local all network: deny when no rule decides
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).
The `default-deny-all` row represents the built-in fallback: access is blocked
when no applicable policy decides a request. It never overrides an allow rule.
Its summary describes this condition instead of counting it as an explicit
deny. For how unmatched requests are handled under each preset, see
[Default preset](../access-controls/local.md#default-preset).
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).
### Listing rules for a sandbox
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
```
The output groups rules by type. For example, the network section for a sandbox
with 42 allowed hosts and one explicitly denied host in its local policy shows:
```text
NETWORK
• allow 42 hosts from local-policy
• deny 1 host from local-policy
• fallback: deny when no rule decides from default-deny-all
```
The fallback appears on its own line, so `deny 1 host` counts only the explicit
deny. Other policies, such as those provided by kits, also contribute to the
sandbox's summary.
### 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
+23 -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
@@ -156,6 +135,23 @@ $ sbx settings set kit.allowedSources '["docker.io/","github.com/docker/"]'
Then run the command again. For details, including how to allow local kits or
any remote source, see [Restrict kit sources](/manuals/ai/sandboxes/customize/use-kits.md#restrict-kit-sources).
## Kit install or startup command fails
If `sbx create` or `sbx run` shows ✗ on a kit's install command, or warns that a
startup command failed, the full output is inside the sandbox. Read it with
`sbx exec`:
```console
$ sbx exec <sandbox-name> cat /var/log/sbx-kits/<kit>/install-<n>.log
$ sbx exec <sandbox-name> cat /var/log/sbx-kit-startup.log
```
`<n>` is the install command's position in the kit's `install` list, starting
at 0. To stream every install command's output and the startup log while the
sandbox is created, run `sbx -D create` or `sbx -D run`. See
[Debug a kit](/manuals/ai/sandboxes/customize/author/debug.md) for how to read
the output and fix the common causes.
## SSH and other non-HTTP connections fail
Non-HTTP TCP connections such as SSH can be allowed by adding a policy rule for
@@ -174,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
@@ -212,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/ai/skills/_index.md
+5 -4
View File
@@ -9,10 +9,11 @@ params:
---
Docker Skills are Docker's official, open-source guidance for compatible AI
coding agents. They help agents with Docker tasks, such as improving a Dockerfile
or setting up a Compose application. The collection evolves and doesn't cover
every Docker product. Browse the [repository catalog](https://github.com/docker/skills#readme)
for available skills and their descriptions.
coding agents. They help agents with Docker tasks, such as improving a Dockerfile,
setting up a Compose application, or answering questions using official Docker
documentation. The collection evolves and doesn't cover every Docker product.
Browse the [repository catalog](https://github.com/docker/skills#readme) for
available skills and their descriptions.
## Get started
content/manuals/build/bake/_index.md
+5
View File
@@ -1,5 +1,6 @@
---
title: Bake
description: Define and run concurrent builds, checks, and artifact exports with Docker Buildx Bake.
weight: 50
keywords: build, buildx, bake, buildkit, hcl, json, compose
aliases:
@@ -54,3 +55,7 @@ targets concurrently.
## Get started
To learn how to get started with Bake, head over to the [Bake introduction](./introduction.md).
For practical workflows, see [Run tests and lint checks](targets.md#run-tests-and-lint-checks),
[Export build artifacts](targets.md#export-build-artifacts), and
[Extend Compose builds with HCL](compose-file.md#extend-compose-builds-with-hcl).
content/manuals/build/bake/compose-file.md
+65
View File
@@ -4,6 +4,7 @@ description: Build your compose services with Bake
keywords: build, buildx, bake, buildkit, compose, yaml
aliases:
- /build/customize/bake/compose-file/
- /guides/compose-bake/
---
Bake supports the [Compose file format](/reference/compose-file/_index.md)
@@ -98,6 +99,70 @@ The compose format has some limitations compared to the HCL format:
- `inherits` service field is not supported, but you can use [YAML anchors](/reference/compose-file/fragments.md)
to reference other services, as demonstrated in the previous example with `&build-dev`.
## Extend Compose builds with HCL
You can keep development settings in Compose and layer release build settings in
`docker-bake.hcl`. This is useful when release builds need different stages or
platforms from local development builds. Compose can also build release images;
separating the settings is a workflow choice.
For example, this Compose file builds an application and a utility service that
seeds development data:
```yaml {title=compose.yaml}
services:
app:
image: docker.io/username/app:latest
build:
context: ./app
target: dev
seed:
build:
context: ./seed
```
Create `docker-bake.hcl` alongside `compose.yaml`:
```hcl {title=docker-bake.hcl}
group "default" {
targets = ["app"]
}
target "_release" {
platforms = ["linux/amd64", "linux/arm64"]
attest = ["type=provenance,mode=max", "type=sbom"]
annotations = ["org.opencontainers.image.authors=username"]
}
target "app" {
inherits = ["_release"]
target = "release"
}
```
Bake automatically loads and merges both files. The HCL file replaces the
`default` group's target list, so `docker buildx bake` builds only `app`.
The `seed` target remains available with `docker buildx bake seed`.
See [Default file lookup](overrides.md#default-file-lookup) for file precedence.
The `app` target keeps its context and image tag from Compose, overrides the
Dockerfile stage from `dev` to `release`, and inherits the shared platforms,
attestations, and annotations. The application's Dockerfile must define both
stages. Other release targets can inherit the same settings; see
[Common reusable targets](inheritance.md#common-reusable-targets).
Inspect the merged configuration or select a target to inspect:
```console
$ docker buildx bake --print
$ docker buildx bake --print app
```
Check the `group.default.targets` list to see what runs by default. Omitting
`seed` from that group doesn't delete its definition from the merged
configuration. Selecting `app` limits the printed targets to that selection
and its dependencies.
## `.env` file
You can declare default environment variables in an environment file named
content/manuals/build/bake/matrices.md
+45
View File
@@ -61,6 +61,51 @@ $ docker buildx bake --print app
}
```
## Release and debug variants
Use a matrix value in build arguments and tags to produce distinct image
variants. For a Dockerfile that accepts a `BUILD_MODE` argument:
```hcl {title=docker-bake.hcl}
target "app" {
name = "app-${mode}"
matrix = {
mode = ["release", "debug"]
}
args = {
BUILD_MODE = mode
}
tags = ["docker.io/username/app:${mode}"]
}
```
For file exports, also give each variant a separate output directory to avoid
overwriting files from another variant. Using the `bin` target and Dockerfile
from [Export build artifacts](targets.md#export-build-artifacts), add:
```hcl {title=docker-bake.hcl}
target "bin-all" {
inherits = ["bin"]
name = "bin-${mode}"
matrix = {
mode = ["release", "debug"]
}
args = {
BUILD_MODE = mode
}
output = ["type=local,dest=build/bin/${mode}"]
}
```
```console
$ docker buildx bake --print app
$ docker buildx bake bin-all
```
The `app-release` and `app-debug` targets use the tags
`docker.io/username/app:release` and `docker.io/username/app:debug`, respectively.
The artifact targets write `build/bin/release/app` and `build/bin/debug/app`.
## Multiple axes
You can specify multiple keys in your matrix to fork a target on multiple axes.
content/manuals/build/bake/targets.md
+96
View File
@@ -4,6 +4,8 @@ linkTitle: Targets
weight: 20
description: Learn how to define and use targets in Bake
keywords: bake, target, targets, buildx, docker, buildkit, default
aliases:
- /guides/bake/
---
A target in a Bake file represents a build invocation. It holds all the
@@ -108,6 +110,100 @@ command.
$ docker buildx bake all
```
### Run tests and lint checks
Bake targets can run checks without producing an image. For a Go project with a
`go.mod` file, source code, and tests, define matching Dockerfile stages:
```dockerfile {title=Dockerfile}
FROM --platform=$BUILDPLATFORM golang:{{% param "example_go_version" %}} AS base
WORKDIR /src
COPY . .
FROM base AS test
RUN go test ./...
FROM base AS lint
RUN go vet ./...
```
Map each Bake target to its Dockerfile stage and group the checks:
```hcl {title=docker-bake.hcl}
group "validate" {
targets = ["test", "lint"]
}
target "test" {
target = "test"
output = ["type=cacheonly"]
}
target "lint" {
target = "lint"
output = ["type=cacheonly"]
}
```
```console
$ docker buildx bake validate
```
Both checks run concurrently. A failing check causes the command to fail.
The `cacheonly` output keeps the build cache without exporting an image.
## Export build artifacts
A target can export files, such as compiled binaries, to your local filesystem.
For the Go project in the previous example, append these stages to the Dockerfile:
```dockerfile {title=Dockerfile}
FROM base AS build
ARG TARGETOS
ARG TARGETARCH
ARG BUILD_MODE=release
RUN if [ "$BUILD_MODE" = "debug" ]; then \
CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -gcflags="all=-N -l" -o /out/app .; \
else \
CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/app .; \
fi
FROM scratch AS export
COPY --from=build /out/ /
```
The `scratch` stage contains only the files to export. Add these Bake targets
to save the binary locally or build it for multiple platforms:
```hcl {title=docker-bake.hcl}
target "bin" {
target = "export"
platforms = ["local"]
output = ["type=local,dest=build/bin"]
}
target "bin-cross" {
inherits = ["bin"]
platforms = ["linux/amd64", "linux/arm64"]
}
```
```console
$ docker buildx bake bin
$ docker buildx bake bin-cross
```
The `bin` target builds for the client's platform and writes `build/bin/app`.
The `bin-cross` target writes separate `build/bin/linux_amd64/app` and
`build/bin/linux_arm64/app` files. See [Inheritance](inheritance.md) and
[Local and tar exporters](/manuals/build/exporters/local-tar.md) for reuse and
output options.
The base stage uses `BUILDPLATFORM` to run the Go compiler on the builder's
native platform. `TARGETOS` and `TARGETARCH` select the output platform, so this
example cross-compiles without emulation. For other toolchains, see
[Multi-platform build strategies](/manuals/build/building/multi-platform.md#strategies).
## Pattern matching for targets and groups
Bake supports shell-style wildcard patterns when specifying target or grouped targets.
content/manuals/build/building/variables.md
+23
View File
@@ -331,6 +331,7 @@ They're used to configure the Buildx client, or the BuildKit daemon.
| [BUILDX_NO_DEFAULT_ATTESTATIONS](#buildx_no_default_attestations) | Boolean | Turn off default provenance attestations. |
| [BUILDX_NO_DEFAULT_OCI_ARTIFACT](#buildx_no_default_oci_artifact) | Boolean | Turn off OCI artifact storage for attestations by default. |
| [BUILDX_NO_DEFAULT_LOAD](#buildx_no_default_load) | Boolean | Turn off loading images to image store by default. |
| [BUILDX_SEND_GIT_QUERY_AS_INPUT](#buildx_send_git_query_as_input) | Boolean | Resolve Git URL queries in Buildx for frontend compatibility. |
| [EXPERIMENTAL_BUILDKIT_SOURCE_POLICY](#experimental_buildkit_source_policy) | String | Specify a BuildKit source policy file. |
BuildKit also supports a few additional configuration parameters. Refer to
@@ -808,4 +809,26 @@ Usage:
$ export BUILDX_NO_DEFAULT_LOAD=1
```
### BUILDX_SEND_GIT_QUERY_AS_INPUT
Set `BUILDX_SEND_GIT_QUERY_AS_INPUT=1` to use Git URL queries with a BuildKit
daemon or Dockerfile frontend that doesn't support the Git query-string
format. Buildx resolves the Git URL into a source input instead of requiring
the frontend to interpret the query. The default is `false`.
For example, select a tag and verify its commit while using an older builder:
```console
$ BUILDX_SEND_GIT_QUERY_AS_INPUT=1 docker buildx build \
'https://github.com/moby/buildkit.git?tag=v0.21.1&checksum=66735c67'
```
This applies to the main Git context and additional Git contexts that use
URL queries. It changes how the context is represented in provenance:
the context is supplied as a source input instead of the usual context
string. If you consume provenance, account for that difference before
enabling the setting in your workflow.
See [Git URL queries](../concepts/context.md#url-queries) for query syntax.
<!-- vale Docker.HeadingSentenceCase = YES -->
content/manuals/build/ci/github-actions/_index.md
+102 -6
View File
@@ -4,6 +4,7 @@ linkTitle: GitHub Actions
description: Docker maintains a set of official GitHub Actions for building Docker images.
keywords: ci, github actions, gha, build, introduction, tutorial
aliases:
- /guides/gha/
- /ci-cd/github-actions/
- /build/ci/github-actions/examples/
---
@@ -39,15 +40,110 @@ The following GitHub Actions are available:
Using Docker's actions provides an easy-to-use interface, while still allowing
flexibility for customizing build parameters.
> [!NOTE]
> For an alternative to configuring individual actions, see
> [Docker GitHub Builder](/manuals/build/ci/github-actions/github-builder/_index.md).
> It provides Docker-maintained reusable workflows for building images and artifacts
> with BuildKit.
## Get started
Build an image from your GitHub repository and push it to Docker Hub with the
following workflow.
### Prerequisites
- A GitHub repository with your application and a `Dockerfile` at its root.
- A Docker Hub account and a
[personal access token](/manuals/security/access-tokens/personal-access-tokens.md)
with permission to push images.
### Configure your GitHub repository
Add your Docker Hub credentials to your GitHub repository:
1. Open your repository's **Settings**.
2. Under **Security**, go to **Secrets and variables > Actions**.
3. Under **Secrets**, create a repository secret named `DOCKERHUB_TOKEN`
containing your Docker access token.
4. Under **Variables**, create a repository variable named `DOCKERHUB_USERNAME`
containing your Docker Hub username.
### Set up your GitHub Actions workflow
Create `.github/workflows/docker-ci.yml` in your repository with the following
contents. Replace `my-image` with the name of your Docker Hub repository, and
change `main` if your default branch has a different name.
```yaml
name: Build and push Docker image
on:
push:
branches:
- main
pull_request:
permissions:
contents: read
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Extract Docker image metadata
id: meta
uses: docker/metadata-action@{{% param "metadata_action_version" %}}
with:
images: ${{ vars.DOCKERHUB_USERNAME }}/my-image
- name: Sign in to Docker Hub
if: github.event_name != 'pull_request'
uses: docker/login-action@{{% param "login_action_version" %}}
with:
username: ${{ vars.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@{{% param "setup_buildx_action_version" %}}
- name: Build and push Docker image
uses: docker/build-push-action@{{% param "build_push_action_version" %}}
with:
push: ${{ github.event_name != 'pull_request' }}
tags: ${{ steps.meta.outputs.tags }}
labels: ${{ steps.meta.outputs.labels }}
annotations: ${{ steps.meta.outputs.annotations }}
```
Commit the workflow file and push it to your default branch to run it. The
workflow also runs on pull requests. Pull-request builds skip signing in to
Docker Hub and pushing the image, so they don't require registry secrets,
including for pull requests from forks.
The build action uses Git context by default: BuildKit fetches your repository
directly at the Git reference for the event that triggered the workflow, so no
checkout step is needed. Changes to files made by earlier workflow steps are
ignored because the build uses files from Git.
The metadata action generates tags, labels, and
annotations from the GitHub event and passes them to the build step. For
example, a push to `main` publishes `DOCKERHUB_USERNAME/my-image:main`.
See [Manage tags and labels](/manuals/build/ci/github-actions/manage-tags-labels.md)
and [Annotations](/manuals/build/ci/github-actions/annotations.md) to customize
this metadata.
This workflow builds images but doesn't run application tests. To add tests,
see [Test before push](/manuals/build/ci/github-actions/test-before-push.md).
For additional build options, see
[Multi-platform images](/manuals/build/ci/github-actions/multi-platform.md) and
[SBOM and provenance attestations](/manuals/build/ci/github-actions/attestations.md),
which covers default provenance and how to add SBOM attestations when pushing
to a registry.
## Examples
If you're looking for examples on how to use the Docker GitHub Actions,
refer to the following sections:
{{% sectionlinks %}}
## Get started with GitHub Actions
The [Introduction to GitHub Actions with Docker](/guides/gha.md) guide walks
you through the process of setting up and using Docker GitHub Actions for
building Docker images, and pushing images to Docker Hub.
content/manuals/build/concepts/context.md
+5
View File
@@ -289,6 +289,11 @@ $ docker buildx build 'https://github.com/user/myrepo.git?tag=v0.1.0&commit=dead
> Short commit hash is supported with `checksum` (alias `commit`) query but for
> `ref`, only the full hash of the commit is supported.
If your BuildKit daemon or Dockerfile frontend doesn't support URL queries,
set `BUILDX_SEND_GIT_QUERY_AS_INPUT=1` to let Buildx resolve them. This changes
the context's provenance representation; see the
[compatibility setting](../building/variables.md#buildx_send_git_query_as_input).
#### Keep `.git` directory
By default, BuildKit doesn't keep the `.git` directory when using Git contexts.
Loaded 100 of 156 files, more files were not shown because too many files have changed in this diff. Show more