自学教程

DeepSeek Harness 沙箱与审批

DeepSeek Harness

DeepSeek Harness 沙箱与审批

前置阅读：《DeepSeek Harness 工具执行流水线与权限门禁》

沙箱（Sandbox）与审批（Approval）是 DeepSeek Harness 安全体系里两套互补的核心组件：沙箱定义「执行能触达哪些资源」，审批定义「执行前是否需要人工确认」。沙箱是执行环境的物理边界，审批是操作前的决策开关。二者独立配置，配合权限门禁，共同构成 Agent 工具调用的双层安全防线。

一句话区分：沙箱=围栏，限制操作的影响范围；审批=刹车，高危动作执行前等待用户确认。

一、沙箱 Sandbox：执行环境隔离边界

沙箱负责对文件读写、进程、命令执行做资源隔离，控制工具能访问的目录与系统资源。遵循**关闭即拒绝（fail-closed）**原则：如果沙箱后端无法正常初始化，直接拒绝执行，不会裸机运行。

1. 三种内置沙箱模式

沙箱提供三档文件隔离策略，在 Profile 的 cordis.patch.yml 中配置：

  1. read-only 只读模式
    默认安全兜底策略。禁止任何文件写入操作，仅允许读取文件。适合查询、读取文档类任务，不存在文件修改风险。
  2. workspace-write 工作区可写（默认推荐）
    仅允许在当前会话工作目录、临时目录内写入文件；禁止修改工作区以外的系统目录（/etc、C:\Windows等）。日常编码、文件编辑任务首选。
  3. danger-full-access 完全访问
    关闭沙箱文件隔离，工具可访问主机全部文件系统。高风险，仅用于本地完全可信环境，生产环境不推荐启用。

注意：沙箱主要管控文件系统。网络访问、进程可见性、密钥凭据不属于文件沙箱管控范围，需要搭配独立权限策略。

2. 跨平台沙箱后端

Harness 沙箱使用操作系统原生隔离能力，不同平台底层实现不同：

  • Linux：bwrap / Landlock
  • macOS：Seatbelt
  • Windows：受限令牌 + ACL 权限控制（Windows 平台隔离能力为部分生效）

沙箱能力本身是可替换插件，支持自定义沙箱后端，例如 Docker 容器沙箱。

3. 沙箱升级（权限升级）机制

当工具需要从低权限沙箱切换到更高权限沙箱（例如从 workspace-write 升级到 danger-full-access），属于沙箱权限升级（escalation），必须触发审批流程，不允许静默自动升级。

只能由低权限向高权限升级；无法降级。单次审批仅授予一次性临时权限，不会永久修改会话沙箱策略。

二、审批 Approval：高危操作的人工确认机制

审批机制在工具流水线的权限门禁之后、沙箱执行之前触发。当操作命中审批策略，流水线暂停，抛出审批事件，等待用户做出放行/拒绝决定，Agent 进入等待状态，不会继续执行。

2.1 审批策略四种模式

可在 Profile 配置内为工具/权限单独指定策略：

  1. allow：自动放行，无需确认
  2. ask：需要弹窗确认（标准高危操作，如文件写入、shell命令）
  3. ask_with_confirm：双重确认，用于极高风险操作（删除文件、sudo 命令）
  4. deny：直接拒绝，禁止执行

2.2 审批事件与审计

每次审批动作都会生成完整审计日志，记录：

  • 会话ID、工具名称、调用参数、操作理由（justification）
  • 触发时间、审批策略、用户选择（同意/拒绝）
  • 沙箱模式变更记录

插件可以订阅审批事件，实现自定义审批面板、远程审批、自动审批逻辑。

2.3 审批事件流

  1. 工具调用到达权限门禁，校验发现需要审批；
  2. 触发 approval/asked 事件，暂停流水线；
  3. WebUI/桌面版弹出审批弹窗，展示工具动作、参数、风险提示；
  4. 用户选择同意/拒绝，抛出 approval/decided 事件；
  5. 同意：继续进入沙箱执行；拒绝：直接终止流水线，返回拒绝信息。

SDK 模式下，不会自动弹出弹窗，会向外抛出审批事件，由上层业务自行实现交互。

三、沙箱、审批与工具流水线联动关系

承接上一篇《工具执行流水线与权限门禁》，完整链路：

工具请求解析 → 前置钩子 → 权限门禁 → 审批校验 → 参数校验 → 沙箱实例化执行 → 后置钩子 → 返回结果

关键点：

  1. 权限门禁：判断工具是否拥有对应 scope；
  2. 审批：判断是否需要人工确认；沙箱升级必须经过审批；
  3. 沙箱：在执行阶段，限制本次操作的资源访问范围。

三者联动规则：

  • 权限拒绝：直接终止，不触发审批、不启动沙箱；
  • 需要审批：暂停等待用户决定，此时还未启动沙箱；
  • 用户同意：创建对应等级沙箱环境，执行工具；
  • 用户拒绝：直接终止，不启动沙箱。

四、配置示例（cordis.patch.yml）

sandbox:
  defaultMode: workspace-write
permissions:
  "scope:shell.exec": ask
  "scope:fs.write": ask
  "scope:fs.delete": ask_with_confirm

含义：默认沙箱为工作区可写；执行shell、文件写入需要确认；文件删除需要双重确认。

五、预设安全配置集

Harness 内置三套安全预设，快速切换沙箱+审批组合：

  1. restricted 严格模式：沙箱 read-only，大部分高危操作 deny
  2. standard 标准模式（默认）：沙箱 workspace-write，高危操作 ask
  3. trusted 可信模式：自动放行，可配置沙箱 full-access，仅本地完全可信环境使用

启动命令快速加载预设：

dsh web --preset trusted

六、开发：在 defineTool 中声明沙箱相关约束

开发自定义工具时，可以在工具定义中声明沙箱能力要求：

defineTool({
  name: "shell_run",
  description: "执行Shell命令 Run shell command",
  permission: ["scope:shell.exec"],
  sandboxPermissions: "workspace-write",
  // ...参数定义
})

当工具需要更高沙箱权限，会自动触发升级审批流程。

七、常见问题排查

  1. 执行命令总是弹出审批弹窗
    原因：当前profile的权限策略设置为ask，属于标准安全行为。
    解决：确认环境可信，修改patch配置为allow，或切换trusted预设。
  2. 提示 SANDBOX_UNAVAILABLE，工具无法运行
    原因：当前操作系统沙箱后端无法初始化，沙箱不可用，框架拒绝裸跑。
    解决：检查系统环境，或更换沙箱插件。
  3. 已经审批一次，后续同类型命令仍需要确认
    原因：审批默认是一次性授权，单次生效，不会永久授予权限，这是安全设计。
  4. 沙箱设置为 workspace-write，但依然可以修改外部文件
    排查：确认没有触发沙箱升级，检查是否开启danger-full-access。

八、最佳实践

  1. 遵循最小权限原则：日常场景使用 workspace-write，尽量不使用 danger-full-access。
  2. 删除、高危shell命令，配置ask_with_confirm双重确认。
  3. 沙箱+审批配置统一放在Profile的patch，不要硬编码写进插件代码。
  4. 生产环境不要启用trusted预设，避免自动放行高危操作。
  5. 重要会话开启审计日志，留存所有审批记录。
  6. 不可信第三方插件，优先使用只读沙箱隔离。

重要提示：沙箱与审批可以大幅降低风险，但无法做到绝对安全。即使开启沙箱，依然建议做好文件备份，不要在隔离环境中存放核心敏感凭据。

小结

  • 沙箱 Sandbox：资源隔离层，控制工具能访问的文件与环境，分为只读、工作区可写、完全访问三档；沙箱升级必须审批。
  • 审批 Approval：人工决策层，在工具执行前拦截高危动作，支持自动放行、单次确认、双重确认、直接拒绝。
  • 二者嵌入在工具执行流水线，和权限门禁协同，形成完整安全链路，是控制Agent破坏力的核心安全组件。

标签：

0 条笔记