docker-sandboxes-network-credentials

Docker Sandboxes：网络策略与凭据

概述

此技能负责 sbx policy（网络出口）和 sbx secret（服务密钥与注册表凭据）。代理会执行出口策略，并在匹配的域名上注入已存储的凭据。由代理管理的哨兵值不能用作上游凭据，但 OAuth 透传可能会将真实令牌暴露给沙箱。出口策略无法保护已泄露到沙箱外的真实凭据；如果凭据泄露，请将其撤销或轮换。

何时使用此技能

在以下情况下启用此技能：

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

何时不使用此技能

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

• 任务涉及运行 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 了解架构（此技能关于这些声明在运行时含义的说明仍然适用）。

核心指南

网络策略：全局、按沙箱配置及优先级

• 创建第一个沙箱前，必须初始化一次全局网络策略：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 前缀，或表示“所有主机”的 **。

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

• 对于同时匹配的同一主机名/CIDR，拒绝规则始终优先于允许规则。允许的主机名不会针对其解析出的 IP 检查 CIDR 拒绝规则。
• 默认情况下，规则全局生效。传入 --sandbox NAME 可将规则限定为单个沙箱的本地策略：

  sbx policy allow network --sandbox my-sandbox api.example.com
  

• 仅在创建时，sbx create/sbx run 接受可重复使用的 --deny-network RESOURCE，用于添加按沙箱配置的拒绝规则。即使在集中式（组织）治理下，公开此选项也是安全的，因为本地拒绝规则只能收紧出站访问权限，不能放宽；它绝不会将组织级允许规则扩大为更广泛的授权。
• 使用 sbx policy check network [--sandbox NAME] TARGET，提前测试当前策略对某个主机/URL 的处理方式；使用 sbx policy log [SANDBOX] 查看历史上实际允许或拦截的内容以及匹配的规则。

  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 需要此 ID）和各资源的状态。sbx policy inspect <policy-or-rule> 会显示完整详情，包括每条规则对应的精确移除命令，或其只读原因（例如由组织管理）。移除按沙箱配置的规则时，请保留 --sandbox NAME；省略该参数则会操作全局策略：

  sbx policy rm network --sandbox my-sandbox --resource api.example.com
  sbx policy check network --sandbox my-sandbox api.example.com
  

  移除单条规则不会决定最终结果；其他匹配的规则仍会生效。

服务密钥：注入方式

• sbx secret set [SERVICE] 会存储一个凭证，供代理代表 Agent 对出站请求进行身份验证。在常规的代理管理流程中，沙盒看到的是一个哨兵值，而不是原始密钥；代理会在向匹配的工具包／绑定所声明的域发送请求时替换为真实值。

  sbx secret set github                       # interactive
  printf '%s' "$ANTHROPIC_API_KEY" | sbx secret set anthropic
  

  存储密钥并不会授予网络访问权限。 出站流量由 sbx policy 单独管理；在排查身份验证问题之前，请先检查目标域是否位于预期范围内：

  sbx policy check network --sandbox my-sandbox api.anthropic.com
  

• OAuth 直通是一种例外，并不保证密钥不会暴露。 当工具包设置 oauth.passthrough: true 且没有刷新哨兵值时，代理会将真实令牌响应转发给沙盒。内置的 devin 工具包使用此模式。在承诺 Agent 无法读取令牌之前，请先检查其凭证配置；不要仅为绕过身份验证失败而启用直通。即使使用哨兵值，Agent 仍可在允许的服务上使用凭证权限——请同时限制令牌权限和网络访问。
• 服务密钥默认是全局的；使用 --sandbox NAME 可将密钥限定到单个沙盒。
• 动态密钥会在使用时从主机上解析值，而不是直接存储：--ref（1Password op://... 或 AWS Secrets Manager ARN——需要已通过身份验证的 op／aws CLI）或 --command（运行 shell 命令并使用其标准输出）。--refresh 控制解析／缓存策略（默认值为 55m，也可以设为 on-demand）。

  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 凭据：默认仅用于主机拉取，两个不同的注入范围

• sbx secret set --registry HOST --password-stdin（可选添加 --username）会存储容器 Registry 的拉取凭据，用于拉取私有模板镜像和 kit 构件。与服务密钥不同，Registry 凭据默认仅用于主机：它们会在主机上对拉取操作进行身份验证，绝不会注入任何沙箱。

  gh auth token | sbx secret set --registry ghcr.io --password-stdin
  

• --all-sandboxes 和 --sandbox 会以不同方式扩大范围——请勿混淆：
  • --all-sandboxes：凭据既用于主机拉取，也由代理注入每个新沙箱的 Registry 登录信息中（凭据本身不会进入沙箱文件系统）。
  • --sandbox NAME：凭据仅注入指定的一个沙箱。
  • 不添加这两个标志：仅用于主机拉取，不注入任何位置。

  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
  

• 如果 Registry 的 Bearer 身份验证端点与 Registry 本身位于不同主机名下，请传入 --registry-auth-endpoint，指定确切的可信 HTTPS URL；否则跨主机令牌交换会被拒绝。
• sbx secret rm --registry HOST --sandbox NAME 仅移除该沙箱的 Registry 凭据；仅用于主机的条目和全局（适用于所有沙箱的）条目不会受到影响。这不会撤销上游令牌，也不会阻止使用其他适用的凭据。

  sbx secret rm --registry ghcr.io --sandbox my-sandbox
  

• 不使用 --sandbox 时，sbx secret rm --registry HOST 会同时移除仅用于主机的条目和全局条目。添加 --all-sandboxes 则只移除全局条目。

相关技能

• 对于 docker agent run --sandbox 和 docker agent sandbox 命令， 请使用 docker-agent-run。

• 对于创建、重新连接到和移除这些策略与密钥所适用的沙箱， 请使用 docker-sandboxes-lifecycle。

• 对于在已签入的 sbxenv.yaml 文件中声明 secrets:/registries:/bindings:，以便在创建环境时配置它们，请使用 docker-sandboxes-env。

• 对于 kit 自身的 credentials: 和 permissions.network: 声明（即 kit 请求的内容，而非用户已批准的内容），请使用 docker-sandboxes-kits。

参考资料

• references/sources.md — 上述每条规则的来源（帮助信息记录、源代码路径、文档 URL）。

资源

• 无。

检查

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