docker-sandboxes-network-credentials

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docker Sandboxes: Network Policy & Credentials

Docker Sandboxes：网络策略与凭据

Overview

概述

This skill owns

sbx policy

(network egress) and

sbx secret

(service secrets and registry credentials). The proxy enforces egress policy and injects stored credentials on matching domains. Proxy-managed sentinels are not usable upstream credentials, but OAuth passthrough can expose real tokens to the sandbox. Egress policy does not protect a real credential once leaked outside the sandbox; revoke or rotate a leaked credential.

本技能涵盖

sbx policy

（网络出站）和

sbx secret

（服务密钥和注册表凭据）。代理强制实施出站策略，并在匹配的域上注入已存储的凭据。代理管理的哨兵（sentinel）值不能直接作为上游凭据使用，但 OAuth 透传可能会将真实令牌暴露给沙箱。出站策略无法在真实凭据泄露到沙箱之外后保护它；泄露的凭据应被撤销或轮换。

When to use this skill

何时使用此技能

Activate this skill when:

The user wants to allow, deny, or inspect which hosts a sandbox (or all sandboxes) can reach.
The user wants to give an agent an API key, OAuth token, or other service credential without exposing the raw value inside the sandbox.
The user wants to pull a private template image or kit from a registry that requires authentication.
The user is debugging a blocked network request or a credential that isn't being injected.

在以下情况下激活此技能：

用户想要允许、拒绝或检查某个沙箱（或所有沙箱）可以访问哪些主机。
用户想要给Agent一个 API 密钥、OAuth 令牌或其他服务凭据，但不想在沙箱内暴露原始值。
用户想要从需要身份验证的注册表拉取私有模板镜像或工具包（kit）。
用户正在调试被阻止的网络请求或未被注入的凭据。

Do not use this skill when

何时不使用此技能

Do not use this skill when:

The task is running
```
docker agent run --sandbox
```
or managing its
```
docker agent sandbox
```
allowlist — use
```
docker-agent-run
```
. If the CLI is unclear, establish whether the user runs Docker Agent or standalone
```
sbx
```
before choosing commands.
The task is creating, reattaching to, or removing a sandbox itself — use
```
docker-sandboxes-lifecycle
```
.
The task is declaring secrets/registries/bindings inside a checked-in
```
sbxenv.yaml
```
file — use
```
docker-sandboxes-env
```
for the file format (this skill's rules on precedence and injection scope still apply to what that file provisions).
The task is declaring a kit's own
```
credentials:
```
/
```
permissions.network:
```
block in a
```
spec.yaml
```
— use
```
docker-sandboxes-kits
```
for the schema (this skill's model of what those declarations mean at runtime still applies).

在以下情况下不要使用此技能：

任务是运行
```
docker agent run --sandbox
```
或管理其
```
docker agent sandbox
```
允许列表 —— 请使用
```
docker-agent-run
```
。如果 CLI 不明确，请先确认用户运行的是 Docker Agent 还是独立的
```
sbx
```
，再选择命令。
任务是创建、重新附加或移除沙箱本身 —— 请使用
```
docker-sandboxes-lifecycle
```
。
任务是在已检入的
```
sbxenv.yaml
```
文件中声明密钥/注册表/绑定 —— 请使用
```
docker-sandboxes-env
```
了解文件格式（本技能关于优先级和注入范围的规则仍然适用于该文件所配置的内容）。
任务是在
```
spec.yaml
```
中声明工具包自身的
```
credentials:
```
/
```
permissions.network:
```
块 —— 请使用
```
docker-sandboxes-kits
```
了解模式（本技能关于这些声明在运行时含义的模型仍然适用）。

Core guidance

核心指导

Network policy: global, per-sandbox, and precedence

网络策略：全局、每个沙箱及优先级

The global network policy must be initialized once before creating the first sandbox:
```
sbx policy init <allow-all|balanced|deny-all>
```
.
```
balanced
```
is the recommended starting point (typical dev traffic — AI services, package registries — allowed). This is a one-time setup.
sbx policy reset
is destructive: it deletes the entire local policy store and stops the daemon and every currently running sandbox. The daemon restarts on the next daemon-backed command. It is not a lightweight way to "start over" or a routine diagnostic step — never propose it as a first troubleshooting move for a single misbehaving rule. Use targeted
```
sbx policy rm network
```
(by
```
--id
```
or
```
--resource
```
) to remove one rule instead; reserve
```
sbx policy reset
```
for when the policy store itself needs to be rebuilt from scratch, and warn the user that it will stop running sandboxes before running it.

Add rules with

sbx policy allow network RESOURCES

sbx policy deny network RESOURCES

RESOURCES

is a comma-separated list of exact hosts,

*.example.com

single-label wildcards,

**.example.com

multi-label wildcards, optional

:port

suffixes, CIDR prefixes, or

**

for "all hosts".

bash

sbx policy init balanced
sbx policy allow network "api.example.com,cdn.example.com"
sbx policy deny network ads.example.com

Deny always wins over allow for the same hostname/CIDR when both match. An allowed hostname is not checked against CIDR deny rules for its resolved IP.
A rule applies globally by default. Pass
```
--sandbox NAME
```
to scope it to one sandbox's local policy instead:
bash
```
sbx policy allow network --sandbox my-sandbox api.example.com
```
At creation time only,
```
sbx create
```
/
```
sbx run
```
accept
```
--deny-network RESOURCE
```
(repeatable) to add a per-sandbox deny rule. This is safe to expose even under centralized (org) governance because a local deny can only narrow, never widen, egress — it can never override an org-level allow into a broader grant.

Use

sbx policy check network [--sandbox NAME] TARGET

to test what the current policy would do for a host/URL before it matters, and

sbx policy log [SANDBOX]

to see what was actually allowed or blocked historically, with the matching rule.

bash

sbx policy check network --sandbox my-sandbox api.example.com:443
sbx policy log my-sandbox --json

```
sbx policy ls [SANDBOX] [--wide]
```
lists active policies/rules;
```
--wide
```
adds rule IDs (needed for
```
sbx policy rm network --id
```
) and per-resource status.
```
sbx policy inspect <policy-or-rule>
```
gives full detail including each rule's exact removal command or the reason it is read-only (e.g. org-managed). To remove a sandbox-scoped rule, retain
```
--sandbox NAME
```
; omitting it targets the global policy instead:
bash
```
sbx policy rm network --sandbox my-sandbox --resource api.example.com
sbx policy check network --sandbox my-sandbox api.example.com
```
Removing one rule does not determine the final decision; other matching rules still apply.

在创建第一个沙箱之前，必须先初始化一次全局网络策略：
```
sbx policy init <allow-all|balanced|deny-all>
```
。推荐从
```
balanced
```
开始（允许典型的开发流量——AI 服务、软件包注册表）。这是一次性设置。
sbx policy reset
具有破坏性：它会删除整个本地策略存储，并停止守护进程和所有当前正在运行的沙箱。守护进程会在下一个由守护进程支持的命令时重新启动。它不是一种轻量级的“重新开始”方式，也不是常规的诊断步骤——切勿将其作为单个规则行为异常时的首选故障排查手段。请使用有针对性的
```
sbx policy rm network
```
（通过
```
--id
```
或
```
--resource
```
）来删除单个规则；只有在策略存储本身需要从头重建时才使用
```
sbx policy reset
```
，并在运行之前警告用户它将停止正在运行的沙箱。

使用

sbx policy allow network RESOURCES

sbx policy deny network RESOURCES

添加规则。

RESOURCES

是以逗号分隔的列表，包含精确主机、

*.example.com

单标签通配符、

**.example.com

多标签通配符、可选的

:port

后缀、CIDR 前缀，或用于表示“所有主机”的

**

。

bash

sbx policy init balanced
sbx policy allow network "api.example.com,cdn.example.com"
sbx policy deny network ads.example.com

当主机名/CIDR 同时匹配时，deny 始终优先于 allow。一个被允许的主机名不会被检查其解析出的 IP 是否匹配 CIDR deny 规则。
默认情况下，规则是全局生效的。传入
```
--sandbox NAME
```
可将其限定到单个沙箱的本地策略：
bash
```
sbx policy allow network --sandbox my-sandbox api.example.com
```
仅在创建时，
```
sbx create
```
/
```
sbx run
```
接受
```
--deny-network RESOURCE
```
（可重复）来添加每沙箱的 deny 规则。即使在集中式（组织）治理下，这也是安全的，因为本地 deny 只会缩小出站范围，绝不会扩大——它永远不能覆盖组织级别的 allow 并使其变成更宽泛的授权。

使用

sbx policy check network [--sandbox NAME] TARGET

在实际影响发生前测试当前策略对某个主机/URL 会做什么；使用

sbx policy log [SANDBOX]

查看历史上实际被允许或阻止的内容以及匹配的规则。

bash

sbx policy check network --sandbox my-sandbox api.example.com:443
sbx policy log my-sandbox --json

```
sbx policy ls [SANDBOX] [--wide]
```
列出活动的策略/规则；
```
--wide
```
添加规则 ID（
```
sbx policy rm network --id
```
需要）和每个资源的状态。
```
sbx policy inspect <policy-or-rule>
```
提供完整详情，包括每条规则的确切删除命令或其为只读的原因（例如由组织管理）。要删除沙箱范围的规则，请保留
```
--sandbox NAME
```
；省略它则针对全局策略：
bash
```
sbx policy rm network --sandbox my-sandbox --resource api.example.com
sbx policy check network --sandbox my-sandbox api.example.com
```
删除一条规则并不能确定最终决策；其他匹配的规则仍然适用。

Service secrets: how injection works

服务密钥：注入的工作方式

```
sbx secret set [SERVICE]
```
stores a credential the proxy uses to authenticate outbound requests on behalf of the agent. In the normal proxy-managed flow, the sandbox sees a sentinel rather than the raw secret; the proxy substitutes the real value on requests to the domains the matching kit/binding declares.
bash
```
sbx secret set github                       # interactive
printf '%s' "$ANTHROPIC_API_KEY" | sbx secret set anthropic
```
Storing a secret does not grant network access. Egress is governed separately by
```
sbx policy
```
; check the target domain in the intended scope before debugging authentication:
bash
```
sbx policy check network --sandbox my-sandbox api.anthropic.com
```
OAuth passthrough is an exception, not a no-secret-exposure guarantee. When a kit sets
```
oauth.passthrough: true
```
without a refresh sentinel, the proxy forwards the real token response to the sandbox. The built-in
```
devin
```
kit uses this mode. Review the agent's credential configuration before promising that it cannot read a token; do not enable passthrough merely to bypass an authentication failure. Even with sentinels, the agent can exercise the credential's permissions on allowed services — restrict token privileges as well as network access.
Service secrets are global by default;
```
--sandbox NAME
```
scopes one to a single sandbox.
Dynamic secrets resolve the value on the host at use time instead of storing it directly:
```
--ref
```
(1Password
```
op://...
```
or an AWS Secrets Manager ARN — requires an authenticated
```
op
```
/
```
aws
```
CLI) or
```
--command
```
(runs a shell command and uses its stdout).
```
--refresh
```
controls the resolution/cache policy (default
```
55m
```
, or
```
on-demand
```
).
bash
```
sbx secret set anthropic --ref 'op://Private/Anthropic/api-key'
sbx secret set github --command 'gh auth token'
```
--command
and
--ref
are resolved on the host, with your own privileges, and treated as trusted execution — never point
```
--command
```
at anything an untrusted file or an agent's own output could influence.
Never pass a secret as a plain
--env
value or as a
--kit-arg
/
--env-arg
value. Both land as literal, unmasked text — in the sandbox's environment, in
```
sbx env plan
```
's state file, and potentially in shell history — defeating the entire point of the credential store. Use
```
sbx secret set
```
(or
```
sbxenv.yaml
```
's
```
secrets:
```
/
```
registries:
```
blocks, which route through the same store) instead.
```
sbx secret set-custom
```
(experimental) covers a service sbx has no built-in support for: the sandbox sees a placeholder value in an env var you name (
```
--env
```
), and the proxy swaps in the real secret only on requests to the
```
--host
```
pattern(s) you declare.

sbx secret ls [--global|--sandbox NAME] [--service NAME] [--json]

lists what is stored, without revealing values.

sbx secret rm [SERVICE] [--sandbox NAME] [--all|--registry HOST] [--force]

removes it.

```
sbx secret import [SERVICE] [--all] [--dry-run] [--force]
```
offers to import secrets already sitting in host environment variables (e.g.
```
OPENAI_API_KEY
```
,
```
GH_TOKEN
```
) into the global store, prompting per entry unless
```
--all
```
/
```
--force
```
. A service with an OAuth token already configured is skipped — OAuth takes precedence at runtime over an imported API key.

```
sbx secret set [SERVICE]
```
存储凭据，代理使用它代表Agent对出站请求进行身份验证。在正常的代理管理流程中，沙箱看到的是哨兵值而不是原始密钥；代理在匹配的工具包/绑定声明的域名的请求上替换真实值。
bash
```
sbx secret set github                       # 交互式
printf '%s' "$ANTHROPIC_API_KEY" | sbx secret set anthropic
```
存储密钥并不授予网络访问权限。 出站访问由
```
sbx policy
```
单独控制；在调试身份验证之前，先在预期作用域中检查目标域名：
bash
```
sbx policy check network --sandbox my-sandbox api.anthropic.com
```
OAuth 透传是一个例外，而不是“不暴露密钥”的保证。 当工具包设置
```
oauth.passthrough: true
```
且没有刷新哨兵时，代理会将真实的令牌响应转发给沙箱。内置的
```
devin
```
工具包使用此模式。在承诺Agent无法读取令牌之前，请先审查Agent的凭据配置；不要仅仅为了绕过身份验证失败而启用透传。即使使用哨兵，Agent也可以在允许的服务上行使凭据的权限——请同时限制令牌权限和网络访问。
服务密钥默认是全局的；
```
--sandbox NAME
```
可将其限定到单个沙箱。
动态密钥在使用时于主机上解析值，而不是直接存储：
```
--ref
```
（1Password
```
op://...
```
或 AWS Secrets Manager ARN——需要已认证的
```
op
```
/
```
aws
```
CLI）或
```
--command
```
（运行一个 shell 命令并使用其标准输出）。
```
--refresh
```
控制解析/缓存策略（默认
```
55m
```
，或
```
on-demand
```
）。
bash
```
sbx secret set anthropic --ref 'op://Private/Anthropic/api-key'
sbx secret set github --command 'gh auth token'
```
--command
和
--ref
在主机上以你自己的权限解析，并被视为可信执行——切勿将
```
--command
```
指向任何可能被不可信文件或Agent自身输出影响的内容。
切勿将密钥作为普通的
--env
值或
--kit-arg
/
--env-arg
值传递。两者都会作为字面量、未掩码的文本存在——在沙箱的环境中、在
```
sbx env plan
```
的状态文件中，以及可能在 shell 历史中——从而完全违背了凭据存储的意义。请改用
```
sbx secret set
```
（或
```
sbxenv.yaml
```
中的
```
secrets:
```
/
```
registries:
```
块，它们会路由到同一个存储）。
```
sbx secret set-custom
```
（实验性）适用于 sbx 没有内置支持的服务：沙箱在你指定的环境变量（
```
--env
```
）中看到一个占位符值，代理仅在你声明的
```
--host
```
模式上的请求中替换为真实密钥。

sbx secret ls [--global|--sandbox NAME] [--service NAME] [--json]

列出已存储的内容，但不会显示值。

sbx secret rm [SERVICE] [--sandbox NAME] [--all|--registry HOST] [--force]

将其移除。

```
sbx secret import [SERVICE] [--all] [--dry-run] [--force]
```
提供将已存在于主机环境变量中的密钥（例如
```
OPENAI_API_KEY
```
、
```
GH_TOKEN
```
）导入全局存储，除非使用
```
--all
```
/
```
--force
```
，否则会逐个提示。已配置 OAuth 令牌的服务会被跳过——OAuth 在运行时优先于导入的 API 密钥。

Registry credentials: host-pulls-only by default, two distinct injection scopes

注册表凭据：默认仅主机拉取，两种不同的注入范围

```
sbx secret set --registry HOST --password-stdin
```
(optionally
```
--username
```
) stores pull credentials for a container registry, used to pull private template images and kit artifacts. Unlike service secrets, registry credentials are host-only by default: they authenticate pulls on the host and are never injected into any sandbox.
bash
```
gh auth token | sbx secret set --registry ghcr.io --password-stdin
```
--all-sandboxes
and
--sandbox
widen this differently — do not confuse them:
- ```
--all-sandboxes
```
  : credentials are used for host pulls and injected by the proxy into every new sandbox's registry login (the credential itself never enters the sandbox filesystem).
- ```
--sandbox NAME
```
  : credentials are injected into that one sandbox only.
- Neither flag: host-pulls-only, injected nowhere.
bash
```
gh auth token | sbx secret set --all-sandboxes --registry ghcr.io --password-stdin
gh auth token | sbx secret set --sandbox my-sandbox --registry ghcr.io --password-stdin
```
For a registry whose Bearer auth endpoint lives on a different hostname than the registry itself, pass
```
--registry-auth-endpoint
```
naming the exact trusted HTTPS URL — otherwise the cross-host token exchange is rejected.
```
sbx secret rm --registry HOST --sandbox NAME
```
removes only that sandbox's registry credential; host-only and global (all-sandboxes) entries are untouched. This does not revoke the upstream token or prevent use of another applicable credential.
bash
```
sbx secret rm --registry ghcr.io --sandbox my-sandbox
```
Without
```
--sandbox
```
,
```
sbx secret rm --registry HOST
```
removes both the host-only and global entries. Add
```
--all-sandboxes
```
to remove only the global entry instead.

```
sbx secret set --registry HOST --password-stdin
```
（可选
```
--username
```
）存储用于容器注册表的拉取凭据，用于拉取私有模板镜像和工具包制品。与服务密钥不同，注册表凭据默认仅限主机：它们用于在主机上验证拉取请求，绝不会被注入到任何沙箱中。
bash
```
gh auth token | sbx secret set --registry ghcr.io --password-stdin
```
--all-sandboxes
和
--sandbox
以不同方式扩大此范围——不要混淆：
- ```
--all-sandboxes
```
  ：凭据用于主机拉取并且由代理注入到每个新沙箱的注册表登录中（凭据本身绝不会进入沙箱文件系统）。
- ```
--sandbox NAME
```
  ：凭据仅注入到那一个沙箱。
- 两个标志都不加：仅限主机拉取，不注入任何地方。
bash
```
gh auth token | sbx secret set --all-sandboxes --registry ghcr.io --password-stdin
gh auth token | sbx secret set --sandbox my-sandbox --registry ghcr.io --password-stdin
```
对于 Bearer 认证端点位于与注册表不同主机名的注册表，请传入
```
--registry-auth-endpoint
```
并指定确切的受信任 HTTPS URL——否则跨主机令牌交换将被拒绝。
```
sbx secret rm --registry HOST --sandbox NAME
```
仅移除该沙箱的注册表凭据；仅主机和全局（所有沙箱）条目不受影响。这不会撤销上游令牌，也不会阻止使用其他适用的凭据。
bash
```
sbx secret rm --registry ghcr.io --sandbox my-sandbox
```
不带
```
--sandbox
```
时，
```
sbx secret rm --registry HOST
```
会同时移除仅主机和全局条目。加
```
--all-sandboxes
```
则只移除全局条目。

Related skills

References

参考资料

```
references/sources.md
```
— provenance for every rule above (help captures, source paths, docs URLs).

```
references/sources.md
```
— 上述每条规则的来源（帮助捕获、源路径、文档 URL）。

Assets

资产

None.

无。

Checks

检查

```
checks/verification.md
```
— Verification runbook for network policy and secret commands (unexecuted runbook; run manually with an isolated
```
--app-name
```
, no real secret values).

```
checks/verification.md
```
— 网络策略和密钥命令的验证运行手册（未执行的运行手册；请使用隔离的
```
--app-name
```
手动运行，不要使用真实的密钥值）。

docker-sandboxes-network-credentials

Original

Translation

Docker Sandboxes: Network Policy & Credentials

Docker Sandboxes：网络策略与凭据

Overview

概述

When to use this skill

何时使用此技能

Do not use this skill when

何时不使用此技能

Core guidance

核心指导

Network policy: global, per-sandbox, and precedence

网络策略：全局、每个沙箱及优先级

Service secrets: how injection works

服务密钥：注入的工作方式

Registry credentials: host-pulls-only by default, two distinct injection scopes

注册表凭据：默认仅主机拉取，两种不同的注入范围

Related skills

相关技能

References

参考资料

Assets

资产

Checks

检查