DSH plugin 沙箱:逐调用策略、argv 包装与 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 通过配套的远端后端执行同一策略。
三种模式的承诺:
read-only— 要求后端拒绝写入。POSIX runner 还会授予其 shell 所需的/dev/null接收器;Windows ACL runner 不授予任何显式可写根目录,并因环境 ACL 缺口报告部分强制执行。workspace-write— 允许在工作区根目录、受支持的额外目录及后端承诺的临时区域下写入。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 挂了”两条路径。(来源) 六步:
- 用
read-only策略跑一个写文件命令,断言 stderr 命中denialSignatures中的方言,且退出码非零。 - 用
workspace-write在 cwd 内写文件,断言成功;再写到 cwd 外,断言被拒。 - 调
registerWritableRoot授权额外目录,断言该目录可写;恢复会话后重试,断言授权已失效。 - 构造一个 runner 启动即失败的场景,断言按
runnerFailureRules判定为基础设施失败,而不是任务失败。 - 移除所有可用后端后调
confine,断言抛SANDBOX_UNAVAILABLE,且没有任何命令被 spawn。 - 在
partial强制执行的后端上跑安全敏感命令,断言消费方拒绝或显式上报该状态。
如果第 4 步被当成普通失败,用户会去改命令,而实际上该修的是沙箱环境。
三种模式的整体差异,可以对照沙箱模式;提权重试的严格更宽校验见提权必须严格更宽。
一句话收束: 模式只管文件、full access 不进 seam、策略按调用携带、拒绝方言只用本后端、runner 失败先于拒绝判断、没有后端就失败闭合。
常见问题
不会,DSH plugin 的 SandboxMode 只管文件系统效果。DSH plugin 明确把网络与进程可见性排除在这套词汇之外。
不会,DSH plugin 让该模式的消费方直接 spawn 原始 argv。DSH plugin 只把前两种受限模式发送给提供方。
不能,DSH plugin 明确要求区分。DSH plugin 的 partial 表示活跃后端或较旧内核 ABI 只管控了子集,要求绝对保证的消费方必须拒绝或向上暴露这一区别。
不能,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
来源
- DeepSeek Harness 官方参考 - 进程沙箱· deepseek-ai
- packages/sandbox/sandbox/src/index.ts· deepseek-ai