ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 沙箱:逐调用策略、argv 包装与 fail-closed 到底怎么落

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness沙箱ConfinedArgvfail-closed
沙箱模式开了但命令仍能越界,或自定义提供方失败后没有拒绝执行。本文讲 SandboxMode 只管文件效果、逐调用策略的解析优先级、ConfinedArgv 的两种 stderr 分类器,以及 fail-closed 的边界。

“沙箱开了却还能越界”,通常不是后端没生效,而是你把它当成了网络与进程隔离。 DSH plugin 的 SandboxMode 只管控文件系统效果;网络访问与进程可见性根本不在这个词汇里。先把边界认清,再谈策略解析。 DSH插件 开沙箱时要记住:它只管文件效果,网络与进程可见性不在其中。

沙箱只管文件效果

三种模式的差异全部落在“能不能写”。(来源)

dsh-sandbox 把与配套子进程提供方共享执行环境的子进程 argv 包装在文件效果策略中,而不将消费方耦合到特定平台运行器。dsh-sandbox-local 提供 Linux bwrap/Landlock、macOS Seatbelt 与 Windows ACL 受限令牌后端;dsh-bash-sandbox 与 dsh-pwsh-sandbox 是消费方;dsh-sandbox-ssh 通过配套的远端后端执行同一策略。

三种模式的承诺:

  1. read-only — 要求后端拒绝写入。POSIX runner 还会授予其 shell 所需的 /dev/null 接收器;Windows ACL runner 不授予任何显式可写根目录,并因环境 ACL 缺口报告部分强制执行。
  2. workspace-write — 允许在工作区根目录、受支持的额外目录及后端承诺的临时区域下写入。
  3. danger-full-access — 绕过隔离。

网络与进程可见性不在此处的定义范围内。所以“沙箱能防止模型 curl 内网”是错误预期,那要靠网络隔离或策略层。

danger-full-access 根本不进 ctx.sandbox

只有前两种模式可以发送给提供方。(来源)

danger-full-access 的消费方直接 spawn 原始 argv,不调用 ctx.sandbox。这解释了为什么“完全访问模式下沙箱插件没被调用”是正常现象,而不是失效。

Enforcement 是后端报告的事实,只有两档:

  • full — 后端管控了该模式承诺的所有文件效果;
  • partial — 活跃后端或较旧的内核 ABI 仅管控其中一个子集。

官方要求很硬:要求绝对保证的消费方必须拒绝 partial,或者把它向上暴露,不能当成 full 用。当前已知的部分强制执行情形包括较旧的 Landlock ABI,以及 Windows ACL runner 的硬链接、读取不受限与 AppContainer ACL 边界。

逐调用策略:一次解析,再决定是否绕过

策略按调用携带,不是固定在提供方身上。(来源)

完整执行策略会按每次能力调用解析并携带,而且包含 danger-full-access——这样消费方可以只解析一次策略,再决定是否绕过约束。

普通工具调用从调用会话的不可变 cwd 派生 workspaceRoot;部署配置提供无 agent 调用的回退值与共享的额外写入授权;存活 Session 的注册会为后续解析添加 effect 生命周期内的目录授权。

解析器保留执行环境中的绝对路径写法;执行限制的提供方则在文件实际存在的位置规范化根目录。所以包含 symlink 或 .. 的 cwd,最终标识的是配套子进程提供方实际运行的目录。

SandboxExecutionPolicy 有四个字段:mode、workspaceRoot、可选 additionalWritableRoots 与可选 sessionId。sessionId 是不透明的调用会话身份,后端用它区分逐会话状态——例如 Windows ACL 给每个存活会话与工作区对分配随机私有临时目录与 SID,而工作区 SID 与常驻授权仍按工作区管理;无 agent 调用缺失该字段,回退到按调用状态。

resolve 的优先级

已批准的显式模式压过会话日志,会话日志压过部署默认值。(来源)

ctx.sandboxPolicy.resolve() 接收活跃会话;对于已批准的重试,还接收显式模式。该服务拥有优先级与 root 回退规则,使 bash 与 fs 不必重复实现。

SandboxPolicyRequest 只有两个字段:可选 session 与可选 mode。优先级顺序是:已批准的显式模式 > 会话最后一条 sandbox/mode 事件 > 部署默认值。

工作区根的口径:会话 cwd 就是 workspace-write 的边界;配置的根是无 agent 调用与没有 cwd 的会话的回退。配置的额外根与该 Session 的活跃注册会被一起快照;已存在的操作与进程保留它们自己的策略。

registerWritableRoot(session, directory) 有一条常被忽略的限制:授权是运行时的,恢复或 fork 后必须重新注册。Windows 上只有 Harness 文件工具会遵守额外授权,进程权限保持不变。记录 cwd 为相对路径或含 NUL 字节时,resolve 抛 SANDBOX_INVALID_ROOT。

ConfinedArgv 的三样东西

包装后的 argv、强制执行事实,以及两种正交的 stderr 分类器。(来源)

ConfinedArgv 的 argv 是“runner、profile、分隔符,再接调用方自己的 argv”。消费方应当 spawn 它,而不是原始 argv。

denialSignatures 是所选后端的拒绝方言:bwrap 只读绑定下的 EROFS 文本、Landlock 的 EACCES、Seatbelt 的 EPERM。消费方若从失败运行的 stderr 推断拒绝,必须只匹配这份方言,而不是跨后端并集——并集会声称某个后端根本不会产生的拒绝。

runnerFailureRules 是沙箱基础设施失败的证据规则。RunnerFailureRule 包含可选 allowedExitCodes、必填 fatalSignatures 与可选 informationalLines。分类顺序固定:先按不区分大小写的整行精确匹配移除信息性排除项,再在余下每行里不区分大小写地匹配致命签名。退出状态本身永远不能证明 runner 失败。

这两种失败含义完全不同:runner 失败意味着命令根本没跑;拒绝意味着约束生效并挡住了它。消费方应先查 runner 失败,把它作为沙箱基础设施故障上报,而不是普通任务失败。

fail-closed:静默无隔离透传永远不合法

没有后端就报错,不许悄悄降级成裸跑。(来源)

await ctx.sandbox.confine(argv, policy, signal) 在执行环境中解析策略路径并返回 ConfinedArgv。没有可用后端时以 SandboxUnavailableError(SANDBOX_UNAVAILABLE)拒绝;提供方无法为该模式准备主机状态时以 SandboxPreparationError(SANDBOX_PREPARATION_FAILED、SANDBOX_INVALID_TEMP_ROOT)拒绝。可选信号可在启动前取消解析。

官方那句最该抄下来:对于受限策略,静默的无隔离透传永远不合法。

提供方选取、探测、缓存与后端特定的强制执行报告归本地提供方所有;功能探测用于裁决多 runner 链,只有单一候选时可以跳过,该候选自身的拒绝仍是失败闭合的终点。沙箱化 bash 消费方拥有 spawn 与结果归因,提供方只负责把 runner 方言映射成规则。

验证:越界命令与失败提供方

验证要分别覆盖“被拒绝”与“runner 挂了”两条路径。(来源) 六步:

  1. 用 read-only 策略跑一个写文件命令,断言 stderr 命中 denialSignatures 中的方言,且退出码非零。
  2. 用 workspace-write 在 cwd 内写文件,断言成功;再写到 cwd 外,断言被拒。
  3. 调 registerWritableRoot 授权额外目录,断言该目录可写;恢复会话后重试,断言授权已失效。
  4. 构造一个 runner 启动即失败的场景,断言按 runnerFailureRules 判定为基础设施失败,而不是任务失败。
  5. 移除所有可用后端后调 confine,断言抛 SANDBOX_UNAVAILABLE,且没有任何命令被 spawn。
  6. 在 partial 强制执行的后端上跑安全敏感命令,断言消费方拒绝或显式上报该状态。

如果第 4 步被当成普通失败,用户会去改命令,而实际上该修的是沙箱环境。

三种模式的整体差异,可以对照沙箱模式;提权重试的严格更宽校验见提权必须严格更宽。

一句话收束: 模式只管文件、full access 不进 seam、策略按调用携带、拒绝方言只用本后端、runner 失败先于拒绝判断、没有后端就失败闭合。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的沙箱模式会不会限制网络访问和进程可见性?

不会,DSH plugin 的 SandboxMode 只管文件系统效果。DSH plugin 明确把网络与进程可见性排除在这套词汇之外。

DSH plugin 的 danger-full-access 会调用 ctx.sandbox 吗?

不会,DSH plugin 让该模式的消费方直接 spawn 原始 argv。DSH plugin 只把前两种受限模式发送给提供方。

DSH plugin 的 partial 强制执行能当 full 用吗?

不能,DSH plugin 明确要求区分。DSH plugin 的 partial 表示活跃后端或较旧内核 ABI 只管控了子集,要求绝对保证的消费方必须拒绝或向上暴露这一区别。

DSH plugin 的 denialSignatures 能用所有后端的并集吗?

不能,DSH plugin 要求只用所选后端的方言。DSH plugin 指出并集会声称某个后端根本不会产生的拒绝,导致误判。

相关术语

SandboxMode
SandboxMode 是受限进程的文件效果策略,取值为 read-only、workspace-write 与 danger-full-access。— packages/sandbox/sandbox/src/index.ts
SandboxExecutionPolicy
SandboxExecutionPolicy 是为一次能力调用解析出的完整文件效果策略,含模式、工作区根与可选额外可写根。— packages/sandbox/sandbox/src/index.ts
ConfinedArgv
ConfinedArgv 是 confine 的结果,含包装后的 argv、强制执行完整度与两类 stderr 分类器。— packages/sandbox/sandbox/src/index.ts
RunnerFailureRule
RunnerFailureRule 是判定沙箱 runner 在命令执行前失败的结构化证据规则,含退出码门控与致命签名。— packages/sandbox/sandbox/src/index.ts

来源