Docker Sandbox Kit：把 AI Agent 的权限声明变成可审查的 OCI 制品

09/25/2026 10:34:16 | China Standard Time

Docker Sandbox Kit Spec v3 如何用 OCI 镜像描述 Agent 的工作负载、网络、凭据和其他权限，并通过确定性组合、权限差异审查与一致性测试改善沙箱治理。

# Docker Sandbox Kit：把 AI Agent 的权限声明变成可审查的 OCI 制品
运行一个 AI Agent，真正需要考虑的不只是“它能不能在沙箱里执行代码”，还包括：它运行哪个 Agent、能访问哪些工具、需要哪些凭据、允许读写哪些目录、能访问哪些网络，以及这些授权如何审查、复现和撤销。
Docker 发布的 **Sandbox Kit Specification v3**，试图把这部分“运行环境与权限声明”跟软件内容一起打包。它的核心不是再发明一种容器镜像，而是让一个 Kit 成为普通 OCI 镜像：镜像层承载工作负载或扩展内容，OCI manifest annotation 承载声明。这样，镜像、声明与内容可以通过同一个 digest 固定、分发、扫描、签名和审查。
本文介绍 Kit 的模型、权限语义、组合规则和更新审查机制，并重点讨论一个容易被营销表达掩盖的事实：**Kit 描述的是请求的能力，不会自行强制执行权限；真正的安全性依赖符合规范的宿主执行环境。**
## 为什么 Agent 沙箱不只是容器隔离
传统容器非常适合运行边界清晰的工作负载。容器把应用、依赖和启动方式打包起来，并通过命名空间、控制组等机制隔离进程、文件系统视图和资源使用。但容器通常共享宿主机内核。
Agent 的行为方式与固定服务不同。它会根据上下文选择下一步行动，可能安装软件、运行构建脚本、访问 API、修改文件或尝试新的工具。若它获得了过宽的挂载目录、长期有效的令牌或开放的网络权限，即使没有利用内核漏洞，也可能按授权范围造成损害。
因此需要同时考虑两层边界：
1. **执行隔离**：恶意或失控代码能否越过工作负载边界影响宿主机？
2. **权限治理**：Agent 被明确授予了什么访问能力？授权能否被审查、限制和撤销？
Docker Sandbox 的产品架构使用带独立内核的 microVM 作为隔离边界；Kit 规范解决的是另一半问题：把 Agent 工作负载需要的环境、工具和权限要求变成可读、可版本化的声明。两者不能混为一谈：microVM 不会自动让授权变窄，Kit 声明也不会自动提供硬件或虚拟机隔离。
## Dockerfile 没有描述的那一半
Dockerfile 主要描述应用如何构建、包含哪些文件以及如何启动；OCI 镜像则定义了构建后镜像的标准格式和分发方式。
但一个 Agent 工作环境还依赖很多“镜像外部”的信息：网络访问规则、凭据绑定、持久化卷、工具、技能文件、执行钩子，以及运行时需要的上下文。这些信息往往散落在 `docker run` 参数、Compose 文件、CI 配置、控制台设置和个人记忆中。它们未必跟应用版本一起审查，也不容易复现。
Sandbox Kit 的目标是把这些声明跟工作负载内容关联起来，让权限和环境要求进入同一套构建、发布、审计流程。
## v3 的关键变化：Kit 是普通 OCI 镜像
Sandbox Kit v3 最重要的变化，是 Kit 不再是一个需要单独注册的特殊制品格式，而是普通 OCI 镜像。规范把 Kit 描述写入 OCI manifest annotation：
```text
vnd.docker.sandbox.kit.descriptor
```
镜像的 layers 放置工作负载或 mixin 内容，manifest annotation 携带 Kit descriptor。因为两者属于同一个 OCI image manifest，镜像 digest 可以同时固定内容和声明。
这带来几个实际好处：
- 可通过 `docker buildx build` 构建；
- 可通过常规 OCI registry 和 `docker pull` 分发；
- 可使用既有的镜像扫描、签名和供应链工具；
- 可以在其他镜像构建流程中通过 `FROM` 使用；
- digest 变化时，内容、权限声明和元数据的变化会一起进入审查范围。
这不是说“签了镜像就自动安全”，而是让授权变更可以与镜像内容绑定，降低声明和实际工作负载脱节的机会。
## Workload 与 Mixin：主体和扩展
Kit 分为两类：
### Workload
Workload 提供运行环境的根文件系统，是实际执行任务的主体。一次启动只允许一个 workload，因为一个沙箱需要有明确的主工作负载来源。
### Mixin
Mixin 是叠加在 workload 上的扩展，可以附带某项工具、网络策略、凭据声明、指导文档、持久化配置或生命周期钩子。一次启动可以组合多个 mixin。
例如，可以把 Agent 本身作为 workload，把 GitHub CLI 及其网络和凭据要求作为 mixin。工作负载回答“运行什么”，mixin 回答“给它补充哪些能力和配置”。
## Capability 是请求，不是自动授权
Kit 通过带类型和版本的 capability 描述自己需要什么。示例中，GitHub CLI mixin 可以请求网络访问规则和一个可选凭据：
```yaml
capabilities:
  - type: com.docker.sandbox/network-policy@2
    config:
      runtime:
        allow:
          - github.com
          - hosts: [api.github.com]
            methods: [GET, HEAD, POST, PATCH, PUT, DELETE]
        deny:
          - hosts: [api.github.com]
            methods: [DELETE]
            paths: [/repos/**]
  - type: com.docker.sandbox/credential@1
    optional: true
    config:
      service: github
      phase: runtime
      apiKey:
        name: GH_TOKEN
        proxyManaged: true
        inject:
          - domain: api.github.com
            header: Authorization
            format: "Bearer %s"
```
可以把这段理解为一份“权限申请单”：允许访问 GitHub 相关域名，并对 GitHub API 的删除操作施加更窄的拒绝规则。示例中的拒绝规则优先于允许规则，因此即便 `DELETE` 在较宽的 allow 列表中，`/repos/**` 下的删除仍会被拒绝。
更关键的是，Kit **只提出请求**，不会自行授予权限。符合规范的宿主运行环境负责解释这些声明并实施策略。若运行环境不支持相应 capability，annotation 可能只是静态元数据，不会产生任何拦截效果。若规范要求某项能力，而宿主不能满足，规范设计要求应拒绝启动，而不是悄悄以不完整或意外放宽的权限运行。
因此要分别验证两件事：
- descriptor 是否正确描述了所需权限；
- 实际使用的执行环境是否实现并强制执行对应 capability。
## 代理管理凭据：沙箱内不直接放真实令牌
示例里的凭据使用 `proxyManaged`。在这种模式下，宿主的代理负责把真实凭据注入发往指定服务的请求；Agent 在沙箱里拿到的可以是占位值，而不是可随意复制到其他位置的真实令牌。
这种设计减少了凭据直接暴露在 Agent 文件系统或进程环境中的机会，但并不代表凭据可以无限授权。仍需检查：
- 凭据能否被代理限制到指定域名和请求路径；
- 权限范围是否只满足当前任务所需；
- 沙箱能否通过获准的服务把数据外传；
- 日志、错误和调试输出是否泄露秘密；
- 凭据是否可撤销、轮换并审计使用情况。
“沙箱里看不到真实令牌”是保护措施之一，不等同于“Agent 无法滥用令牌所代表的权限”。
## 组合不是命令行参数顺序，而是依赖图
传统容器镜像构建通常只有一个 `FROM` 作为阶段基础。若扩展按命令行中输入的先后顺序覆盖配置，结果可能依赖调用顺序，难以复现。
Kit 的 mixin 通过 `provides` 和 `requires` 声明能力依赖，组合时由依赖图决定顺序，而不是由用户输入参数的顺序决定。相同的一组 Kit 应得到一致结果。
规范采用严格的解析策略：
- 每一个 `requires` 必须在组合集合内部得到满足，否则解析失败；不会为了填补缺口而暗中下载一个新 Kit；
- 只能有一个 workload；
- 多个 Kit 声明同一个 `provides` 名称时，解析失败，而不是让其中一个静默覆盖另一个；
- 网络规则按规范规则合并；钩子按依赖顺序执行；指导文档合并为一份；许可证声明合并；
- 无法兼容的请求应报错，而不是随机选择一个结果。
例如，Claude workload 与同名 Claude mixin 若发生 capability 名称冲突，解析器会拒绝这种组合。这种失败看起来严格，却比“最后加载的配置悄悄覆盖前一个”更容易审计。
规范还支持 `kind: set` 描述一组 Kit。它在构建或发布时使用同一套一致性规则解析成普通 Kit；不一致的集合会在发布阶段失败，而不是等到用户启动时才暴露问题。
## 权限差异应该像代码差异一样审查
Kit 把授权声明放进版本控制和制品后，可以在 Pull Request 中审查权限变化。例如，下一版 Agent 新增一个访问域名，或者要求第二个凭据，这不仅是程序升级，也是授权范围变化。
规范描述的更新门禁思路是：运行环境把 descriptor 归一化为需要授予的能力集合，再与之前已批准的集合比较。
- 新版本的请求仍在既有授权范围内，可以按策略自动更新；
- 请求扩展权限时暂停并要求审批；
- 收窄权限通常是减权；
- 删除拒绝规则也可能意味着权限扩大，因此同样要拦截并审查。
例如，旧版本明确禁止 `DELETE /repos/**`，新版本如果删除这条 deny 规则，即使 allow 列表没有变化，实际权限也扩大了。只审查新增 allow 项是不够的，必须比较归一化后的有效权限集合。
## 规范、实现与安全保证是三件事
Docker Sandbox Kit Spec 是一个规范，不是单独的隔离机制。规范采用 Apache 2.0 开源，能力类型独立版本化，例如网络策略可以有 `@1`、`@2`。仓库提供两类一致性测试：一类验证制品是否符合 Kit 格式，另一类验证运行环境是否按规范执行能力。
这有利于其他厂商实现兼容运行环境，降低 Kit 被单一平台锁定的风险。但规范发布并不自动证明每个实现都安全，也不能仅凭“镜像里有 annotation”就认定权限已经生效。上线前至少要确认：
1. 运行环境是否声明支持相应的 Kit 版本和 capability 版本；
2. 各 capability 是否被强制实施，而非仅被解析或展示；
3. 拒绝策略是否优先于允许策略；
4. 不满足 required capability 时是否 fail closed；
5. 制品和授权扩大是否都进入审批、签名和审计链路；
6. 运行环境是否通过规范对应的 conformance suite。
Docker 文章称 Docker Sandboxes 是该规范的首个符合规范的运行环境，并介绍了 Docker Cloud Sandboxes 对相同 Kit 的支持。这属于产品实现状态；做平台选型时仍应针对所用版本实际运行一致性测试和负向测试。
## 从安全工程角度看，Kit 解决什么、不解决什么
Kit 的主要价值，是把过去隐含在部署脚本和人为操作中的外部依赖变成可审查的声明。它改善的是授权的可见性、可复现性和变更治理。
它不能替代完整的威胁建模。工程团队仍要考虑：
- workload 依赖是否可信、镜像是否固定到 digest；
- 授权的挂载目录是否包含宿主机秘密；
- 获准访问的 API 是否可被滥用来外传数据；
- 网络策略是否覆盖重定向、代理、DNS 和 IPv6 等真实路径；
- 生命周期钩子是否会安装未知代码或修改环境；
- 沙箱执行环境是否真正提供预期隔离，更新后是否回归测试；
- 令牌代理、日志和审计系统本身是否构成新的敏感边界。
尤其要注意，Agent 不需要“突破沙箱”才能造成损害。只要权限申请本身过宽，它就可以在规则内做出错误操作。因此 Kit 的价值不只是写 YAML，而是让“为什么授予这些能力”能够被审查，并在每次版本升级时重新验证。
## 试用方式
规范仓库包含 descriptor、各 capability 页面、示例和一致性测试。文章给出的基础试用流程是安装 `sbx` CLI，然后运行示例：
```bash
brew install docker/tap/sbx
git clone https://github.com/docker/sandbox-kit-spec.git
cd sandbox-kit-spec/examples
sbx run ./hello --kit ./gh .
```
修改某个 Kit 的 descriptor 后，可以只重建相应 Kit；通过 `docker buildx build` 发布到普通 OCI registry。落地时建议先从低风险工作负载开始，针对网络、凭据、挂载和升级门禁分别设计正向与负向测试，不要一开始就把高权限 Agent 放进生产账户。
## 总结
Docker Sandbox Kit 想解决的不是“再做一个容器镜像”，而是让软件对外部环境和权限的要求也成为可版本化的制品内容。
它的主要设计点是：
- Kit v3 使用普通 OCI 镜像和 manifest annotation；
- 一个 digest 同时固定内容与权限声明；
- workload 表示主工作负载，mixin 负责叠加工具和能力；
- capability 是向宿主提出的请求，必须由符合规范的运行环境执行；
- `provides/requires` 让组合基于依赖图并保持确定性；
- 权限升级通过规范化差异进行审批，删除 deny 规则也会被视为潜在扩权；
- descriptor 一致性与执行环境一致性需要分别验证。
对平台团队而言，最值得借鉴的不是某个 YAML 字段，而是把权限声明纳入镜像构建、版本控制、签名、审批和运行时验证的完整链路。**可读的权限声明是治理的起点；只有经过验证的执行器真正实施了它，才构成安全边界。**
参考：
- [Docker Sandbox Kit Spec: Authority as Code](https://www.docker.com/blog/docker-sandbox-kit-spec/)
- [docker/sandbox-kit-spec（Apache-2.0）](https://github.com/docker/sandbox-kit-spec)