From a12f5fd34c361ab955e044af799335c84efdf0c4 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 6 May 2026 10:14:30 +0200 Subject: [PATCH] docs: document sandbox-scoped kit network policies Kit network policy docs did not cover sandbox-scoped rules or kit-level deniedDomains. Update the Sandboxes policy and kits pages with scoped policy examples, deniedDomains guidance, and a small policy page formatting fix. Co-Authored-By: Codex --- .../ai/sandboxes/customize/build-an-agent.md | 17 ++++-- .../manuals/ai/sandboxes/customize/kits.md | 16 +++++- .../ai/sandboxes/customize/templates.md | 2 +- content/manuals/ai/sandboxes/get-started.md | 2 +- .../manuals/ai/sandboxes/security/defaults.md | 2 +- .../manuals/ai/sandboxes/security/policy.md | 55 +++++++++++++------ .../manuals/ai/sandboxes/troubleshooting.md | 6 +- content/manuals/ai/sandboxes/usage.md | 2 +- data/sbx_cli/sbx_policy_allow_network.yaml | 26 ++++++--- data/sbx_cli/sbx_policy_deny_network.yaml | 20 +++++-- data/sbx_cli/sbx_policy_ls.yaml | 6 ++ data/sbx_cli/sbx_policy_rm_network.yaml | 21 ++++--- data/sbx_cli/sbx_policy_set-default.yaml | 2 +- 13 files changed, 125 insertions(+), 52 deletions(-) diff --git a/content/manuals/ai/sandboxes/customize/build-an-agent.md b/content/manuals/ai/sandboxes/customize/build-an-agent.md index 735590297d9f..a874385a4de0 100644 --- a/content/manuals/ai/sandboxes/customize/build-an-agent.md +++ b/content/manuals/ai/sandboxes/customize/build-an-agent.md @@ -113,10 +113,10 @@ agent can't reach it. ## Allow network access -The network block does two things: it lists the hosts the sandbox is -allowed to reach (`allowedDomains`), and it wires the kit-side half of -the auth flow from [Plan authentication](#plan-authentication) -(`serviceDomains` + `serviceAuth`). +The network block does two things: it lists the hosts the sandbox can +reach (`allowedDomains`), and it wires the kit-side half of the auth flow +from [Plan authentication](#plan-authentication) with `serviceDomains` and +`serviceAuth`. ```yaml network: @@ -136,6 +136,10 @@ install/CDN subdomains (`*.ampcode.com`). Treat it as a starting point; Amp may reach other domains (model providers, analytics, updates) that you'll discover by watching `sbx policy log` while testing. +Kits can also declare `deniedDomains` for hosts the sandbox should not +reach, such as telemetry endpoints. Deny rules take precedence over +allow rules and apply only to sandboxes that use the kit. + For the auth wiring, when the agent makes an outbound request to `ampcode.com`, the proxy looks up the host in `serviceDomains` to find the service id `amp`, then uses `serviceAuth.amp` to inject an @@ -279,6 +283,8 @@ Two loops help: - Watch the network policy log (`sbx policy log`) to catch blocked requests, then add their domains to `allowedDomains`. +- Add domains to `deniedDomains` when the agent should stay blocked from + a host even if another policy permits it. - Edit the spec and re-run `sbx run --kit ./amp/ amp` to pick up changes. Remove the sandbox first (`sbx rm `) for a clean start. @@ -304,7 +310,8 @@ the same decisions for your agent: into a custom image. Pick install if it's a one-line script; bake if the install is slow or you need a pinned version. - **Network mapping**: list only the API host in `serviceDomains`, not - a wildcard. Keep install/CDN paths out of TLS-intercepting mode. + a wildcard. Keep install/CDN paths out of TLS-intercepting mode. Use + `deniedDomains` for hosts the agent should not reach. - **Credential injection**: if the agent validates the API key's format locally, register with `sbx secret set-custom` and pick a matching placeholder. If it accepts the env var as-is, declare diff --git a/content/manuals/ai/sandboxes/customize/kits.md b/content/manuals/ai/sandboxes/customize/kits.md index b37997d8ec5b..b67466026605 100644 --- a/content/manuals/ai/sandboxes/customize/kits.md +++ b/content/manuals/ai/sandboxes/customize/kits.md @@ -18,7 +18,7 @@ A kit packages a set of capabilities a sandbox can use, such as: - Tools to install - Environment variables to set - Credentials to inject -- Domains to allow +- Network rules to allow or deny domains - Files to drop in - Startup commands to run @@ -26,7 +26,7 @@ You declare these in a single `spec.yaml` file, point the CLI at the directory (or a ZIP, OCI artifact, or Git URL), and the sandbox applies and enforces them at runtime. Credentials stay on the host and go through a proxy instead of entering the VM, and outbound traffic is restricted to -the domains the kit allows. +the domains permitted by the kit's network rules. A kit is either a mixin or an agent: @@ -113,15 +113,23 @@ be visible inside the sandbox VM. ### Control network access -Network rules define which domains the sandbox can reach: +Network rules define which domains the sandbox can reach or block. Kit +network rules apply only to sandboxes that use the kit: ```yaml network: allowedDomains: - api.example.com - "*.cdn.example.com" + deniedDomains: + - telemetry.example.com ``` +Use `allowedDomains` for hosts the agent needs, such as package +registries, install endpoints, or external APIs. Use `deniedDomains` for +hosts the agent should not reach, such as telemetry endpoints. If a domain +matches both an allow rule and a deny rule, the deny rule wins. + For authenticated services, see [Authenticate to external services](#authenticate-to-external-services). @@ -441,6 +449,7 @@ Service identifiers link credentials to [network rules](#network). ```yaml network: allowedDomains: [, ...] + deniedDomains: [, ...] serviceDomains: : serviceAuth: @@ -452,6 +461,7 @@ network: | Field | Description | | ------------------------- | ---------------------------------------------------------------- | | `allowedDomains` | Domains the sandbox can reach. Wildcards supported. | +| `deniedDomains` | Domains the sandbox can't reach. Deny rules take precedence. | | `serviceDomains` | Map of domain to service identifier from `credentials.sources`. | | `serviceAuth.headerName` | HTTP header the proxy sets (for example, `Authorization`). | | `serviceAuth.valueFormat` | Format string for the header value (for example, `"Bearer %s"`). | diff --git a/content/manuals/ai/sandboxes/customize/templates.md b/content/manuals/ai/sandboxes/customize/templates.md index 25367ae0e0d7..c6ca13a2421b 100644 --- a/content/manuals/ai/sandboxes/customize/templates.md +++ b/content/manuals/ai/sandboxes/customize/templates.md @@ -142,7 +142,7 @@ Unless you use the permissive `allow-all` network policy, you may also need to allow-list any domains that your custom tools depend on: ```console -$ sbx policy allow network "*.example.com:443,example.com:443" +$ sbx policy allow network -g "*.example.com:443,example.com:443" ``` Then run a sandbox with your template. The agent you specify must match diff --git a/content/manuals/ai/sandboxes/get-started.md b/content/manuals/ai/sandboxes/get-started.md index 337fc159cda5..10c5262c0569 100644 --- a/content/manuals/ai/sandboxes/get-started.md +++ b/content/manuals/ai/sandboxes/get-started.md @@ -230,7 +230,7 @@ $ sbx policy ls To allow a specific host: ```console -$ sbx policy allow network registry.npmjs.org +$ sbx policy allow network -g registry.npmjs.org ``` With **Locked Down**, even your model provider API is blocked unless you diff --git a/content/manuals/ai/sandboxes/security/defaults.md b/content/manuals/ai/sandboxes/security/defaults.md index 49d62355b872..d1e80da6d602 100644 --- a/content/manuals/ai/sandboxes/security/defaults.md +++ b/content/manuals/ai/sandboxes/security/defaults.md @@ -18,7 +18,7 @@ it (deny-by-default). All non-HTTP protocols (raw TCP, UDP including DNS, and ICMP) are blocked at the network layer. Traffic to private IP ranges, loopback addresses, and link-local addresses is also blocked. -Run `sbx policy ls` to see the active allow rules for your installation. To +Run `sbx policy ls` to see the active network rules for your installation. To customize network access, see [Policies](policy.md). ## Workspace defaults diff --git a/content/manuals/ai/sandboxes/security/policy.md b/content/manuals/ai/sandboxes/security/policy.md index 3e0eb16fbb82..c5c9821647fd 100644 --- a/content/manuals/ai/sandboxes/security/policy.md +++ b/content/manuals/ai/sandboxes/security/policy.md @@ -11,7 +11,8 @@ Sandboxes are [network-isolated](isolation.md) from your host and from each other. A policy system controls what a sandbox can access over the network. Use the `sbx policy` command to configure network access rules. Rules apply -to all sandboxes on the machine. +to all sandboxes on the machine when you use the global scope. Network allow, +deny, list, and remove commands can also target one sandbox. ## Network policies @@ -20,7 +21,7 @@ your host, which enforces access rules on every outbound request. Non-HTTP TCP traffic, including SSH, can be allowed by adding a policy rule for the destination IP address and port (for example, -`sbx policy allow network "10.1.2.3:22"`). UDP and ICMP traffic is blocked +`sbx policy allow network -g "10.1.2.3:22"`). UDP and ICMP traffic is blocked at the network layer and can't be unblocked with policy rules. ### Initial policy selection @@ -40,7 +41,7 @@ Choose a default network policy: | Policy | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Open | All outbound traffic is allowed. No restrictions. Equivalent to adding a wildcard allow rule with `sbx policy allow network "**"`. | +| Open | All outbound traffic is allowed. No restrictions. Equivalent to adding a wildcard allow rule with `sbx policy allow network -g "**"`. | | Balanced | Default deny, with a baseline allowlist covering AI provider APIs, package managers, code hosts, container registries, and common cloud services. You can extend this with `sbx policy allow`. | | Locked Down | All outbound traffic is blocked, including model provider APIs (for example, `api.anthropic.com`). You must explicitly allow everything you need. | @@ -72,35 +73,56 @@ services. Run `sbx policy ls` to see the active rules for your installation. Use [`sbx policy allow`](/reference/cli/sbx/policy/allow/) and [`sbx policy deny`](/reference/cli/sbx/policy/deny/) to add network access -rules. Changes take effect immediately and apply to all sandboxes: +rules. Changes take effect immediately. Pass `-g` to apply a rule to all +sandboxes: ```console -$ sbx policy allow network api.anthropic.com -$ sbx policy deny network ads.example.com +$ sbx policy allow network -g api.anthropic.com +$ sbx policy deny network -g ads.example.com +``` + +Pass a sandbox name to scope a rule to one sandbox: + +```console +$ sbx policy allow network my-sandbox api.example.com +$ sbx policy deny network my-sandbox 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" +$ sbx policy allow network -g "api.anthropic.com,*.npmjs.org,*.pypi.org" ``` List all active policy rules with `sbx policy ls`: ```console $ sbx policy ls -ID TYPE DECISION RESOURCES -a1b2c3d4-e5f6-7890-abcd-ef1234567890 network allow api.anthropic.com, *.npmjs.org -f9e8d7c6-b5a4-3210-fedc-ba0987654321 network deny ads.example.com +NAME TYPE ORIGIN DECISION STATUS RESOURCES +balanced-dev network local allow active api.anthropic.com +ads-block network local deny active ads.example.com +kit:my-sandbox network sandbox:my-sandbox allow active api.example.com +kit:my-sandbox:deny network sandbox:my-sandbox deny active telemetry.example.com ``` -Use `--type network` to show only network policies. +Use `--type network` to show only network policies. Use `--sandbox` to show +global rules plus rules scoped to one sandbox: + +```console +$ sbx policy ls --sandbox my-sandbox +``` Remove a policy 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 +$ sbx policy rm network -g --resource ads.example.com +$ sbx policy rm network -g --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 +``` + +To remove a sandbox-scoped policy, include the sandbox name: + +```console +$ sbx policy rm network my-sandbox --resource api.example.com ``` ### Resetting to defaults @@ -127,7 +149,7 @@ If you prefer a permissive policy where all outbound traffic is allowed, add a wildcard allow rule: ```console -$ sbx policy allow network "**" +$ sbx policy allow network -g "**" ``` This lets agents install packages and call any external API without additional @@ -146,7 +168,7 @@ match the root domain. Specify both to cover both. Allow access to package managers so agents can install dependencies: ```console -$ sbx policy allow network "*.npmjs.org,*.pypi.org,files.pythonhosted.org,github.com" +$ sbx policy allow network -g "*.npmjs.org,*.pypi.org,files.pythonhosted.org,github.com" ``` The **Balanced** policy already includes AI provider APIs, package managers, @@ -202,7 +224,8 @@ machine-readable output, or `--type network` to filter by policy type. All outbound traffic is blocked by default unless an explicit rule allows it. If a domain matches both an allow and a deny rule, the deny rule wins -regardless of specificity. +regardless of specificity. A sandbox-scoped deny rule can block a domain for +one sandbox even when a global rule permits the same domain. To unblock a domain, find the deny rule with `sbx policy ls` and remove it with `sbx policy rm`. diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md index d0a592040c40..a56098c0adf4 100644 --- a/content/manuals/ai/sandboxes/troubleshooting.md +++ b/content/manuals/ai/sandboxes/troubleshooting.md @@ -43,13 +43,13 @@ $ sbx policy log Then allow the domains your workflow needs: ```console -$ sbx policy allow network "*.npmjs.org,*.pypi.org,files.pythonhosted.org" +$ sbx policy allow network -g "*.npmjs.org,*.pypi.org,files.pythonhosted.org" ``` To allow all outbound traffic instead: ```console -$ sbx policy allow network "**" +$ sbx policy allow network -g "**" ``` ## SSH and other non-HTTP connections fail @@ -59,7 +59,7 @@ the destination IP address and port. For example, to allow SSH to a specific host: ```console -$ sbx policy allow network "10.1.2.3:22" +$ sbx policy allow network -g "10.1.2.3:22" ``` Hostname-based rules (for example, `myhost:22`) don't work for non-HTTP diff --git a/content/manuals/ai/sandboxes/usage.md b/content/manuals/ai/sandboxes/usage.md index 62ea8590487d..86a4ccc1148e 100644 --- a/content/manuals/ai/sandboxes/usage.md +++ b/content/manuals/ai/sandboxes/usage.md @@ -361,7 +361,7 @@ forwarding the request, so you must add the `localhost` address with the specific port to your network policy allowlist: ```console -$ sbx policy allow network localhost:11434 +$ sbx policy allow network -g localhost:11434 ``` Then use `host.docker.internal` in any configuration or request that points at diff --git a/data/sbx_cli/sbx_policy_allow_network.yaml b/data/sbx_cli/sbx_policy_allow_network.yaml index 6ec52fe69207..c77592bc09eb 100644 --- a/data/sbx_cli/sbx_policy_allow_network.yaml +++ b/data/sbx_cli/sbx_policy_allow_network.yaml @@ -6,8 +6,15 @@ description: |- RESOURCES is a comma-separated list of hostnames, domains, or IP addresses. Supports exact domains (example.com), wildcard subdomains (*.example.com), and optional port suffixes (example.com:443). Use "**" to allow all hosts. -usage: sbx policy allow network RESOURCES [flags] + + Use -g/--global to apply the rule globally to all sandboxes, or provide + SANDBOX before RESOURCES to scope the rule to a specific sandbox. +usage: sbx policy allow network [-g | SANDBOX] RESOURCES [flags] options: + - name: global + shorthand: g + default_value: "false" + usage: Apply the rule globally to all sandboxes - name: help shorthand: h default_value: "false" @@ -18,16 +25,19 @@ inherited_options: default_value: "false" usage: Enable debug logging example: |4- - # Allow access to a single host - sbx policy allow network api.example.com + # Allow access to a single host globally + sbx policy allow network -g api.example.com + + # Allow access to multiple hosts globally + sbx policy allow network -g "api.example.com,cdn.example.com" - # Allow access to multiple hosts - sbx policy allow network "api.example.com,cdn.example.com" + # Allow a host only for a specific sandbox + sbx policy allow network my-sandbox api.example.com # Allow all subdomains of a host - sbx policy allow network "*.npmjs.org" + sbx policy allow network -g "*.npmjs.org" - # Allow all outbound traffic - sbx policy allow network "**" + # Allow all outbound traffic globally + sbx policy allow network -g "**" see_also: - sbx policy allow - Add an allow policy for sandboxes diff --git a/data/sbx_cli/sbx_policy_deny_network.yaml b/data/sbx_cli/sbx_policy_deny_network.yaml index b26ceffba332..94f26da25ae9 100644 --- a/data/sbx_cli/sbx_policy_deny_network.yaml +++ b/data/sbx_cli/sbx_policy_deny_network.yaml @@ -5,8 +5,15 @@ description: |- RESOURCES is a comma-separated list of hostnames, domains, or IP addresses. Deny rules always take precedence over allow rules. -usage: sbx policy deny network RESOURCES [flags] + + Use -g/--global to apply the rule globally to all sandboxes, or provide + SANDBOX before RESOURCES to scope the rule to a specific sandbox. +usage: sbx policy deny network [-g | SANDBOX] RESOURCES [flags] options: + - name: global + shorthand: g + default_value: "false" + usage: Apply the rule globally to all sandboxes - name: help shorthand: h default_value: "false" @@ -17,10 +24,13 @@ inherited_options: default_value: "false" usage: Enable debug logging example: |4- - # Block access to a host - sbx policy deny network ads.example.com + # Block access to a host globally + sbx policy deny network -g ads.example.com + + # Block a host only for a specific sandbox + sbx policy deny network my-sandbox ads.example.com - # Block all outbound traffic - sbx policy deny network "**" + # Block all outbound traffic globally + sbx policy deny network -g "**" see_also: - sbx policy deny - Add a deny policy for sandboxes diff --git a/data/sbx_cli/sbx_policy_ls.yaml b/data/sbx_cli/sbx_policy_ls.yaml index 87493267f7cd..f55b15ade1f3 100644 --- a/data/sbx_cli/sbx_policy_ls.yaml +++ b/data/sbx_cli/sbx_policy_ls.yaml @@ -11,6 +11,9 @@ options: shorthand: h default_value: "false" usage: help for ls + - name: sandbox + usage: | + Show only policies that apply to a specific sandbox (global + sandbox-scoped) - name: type default_value: all usage: 'Filter policies by type: "all" or "network" (default "all")' @@ -25,5 +28,8 @@ example: |4- # List only network policies sbx policy ls --type network + + # List policies that apply to a specific sandbox + sbx policy ls --sandbox my-sandbox see_also: - sbx policy - Manage sandbox policies diff --git a/data/sbx_cli/sbx_policy_rm_network.yaml b/data/sbx_cli/sbx_policy_rm_network.yaml index 9ee220aee5ed..d7a51bfa603d 100644 --- a/data/sbx_cli/sbx_policy_rm_network.yaml +++ b/data/sbx_cli/sbx_policy_rm_network.yaml @@ -3,9 +3,16 @@ synopsis: Remove a network policy description: |- Remove a network policy by rule ID, resource, or both. + Use -g/--global to remove from the global policy, or provide SANDBOX to + remove from a sandbox-scoped policy. + Use "sbx policy ls" to see active policies and their IDs/resources. -usage: sbx policy rm network [flags] +usage: sbx policy rm network [-g | SANDBOX] [flags] options: + - name: global + shorthand: g + default_value: "false" + usage: Remove from the global policy - name: help shorthand: h default_value: "false" @@ -23,13 +30,13 @@ example: |4- # List policies to find the ID or resource to remove sbx policy ls - # Remove a rule by resource - sbx policy rm network --resource api.example.com + # Remove a global rule by resource + sbx policy rm network -g --resource api.example.com - # Remove a rule by ID - sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 + # Remove a global rule by ID + sbx policy rm network -g --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 - # Remove by ID and resource using one filter - sbx policy rm network --id 2d3c1f0e-4a73-4e05-bc9d-f2f9a4b50d67 --resource "api.example.com,cdn.example.com" + # Remove a sandbox-scoped rule by resource + sbx policy rm network my-sandbox --resource api.example.com see_also: - sbx policy rm - Remove a policy diff --git a/data/sbx_cli/sbx_policy_set-default.yaml b/data/sbx_cli/sbx_policy_set-default.yaml index 1fce7a945e25..35b19e702dc7 100644 --- a/data/sbx_cli/sbx_policy_set-default.yaml +++ b/data/sbx_cli/sbx_policy_set-default.yaml @@ -33,6 +33,6 @@ example: |4- # Block everything, then allow specific sites sbx policy set-default deny-all - sbx policy allow network api.example.com:443 + sbx policy allow network -g api.example.com:443 see_also: - sbx policy - Manage sandbox policies