把沙箱设为 read-only,Agent 却仍然写入了文件——这是 DSH 权限排查中最容易令人困惑的现象之一。 根因通常不是「策略没生效」,而是同一份策略进入了两条不同的执行路径,其中一条根本没有校验它。
排查时,常见的误判主要有六类:
- 以为「设了只读模式」就等于所有文件操作都被拦住;
- 以为
--workspace /path/to/repo就是文件访问边界,因此工作区外的路径自然安全; - 看到
SANDBOX_UNAVAILABLE或运行器报错,就认为沙箱已经生效并拦住了命令; - 把
FS_STALE_VERSION这类版本冲突当成沙箱拒绝写入; - 把
FS_SANDBOX_DENIED与FS_PERMISSION_DENIED混为一谈,于是去查错了层; - 只凭路径字符串前缀判断「在不在工作区内」,忽略了符号链接与规范化。
明确排查方向,关键在于一句话:策略解析、进程沙箱、文件提供者是三件不同的事,必须分别核对。 相关教程见DeepSeek Harness 沙箱与文件系统访问限制如何配合?。
一、这份策略到底管什么?
沙箱参考列出了三种文件影响模式:
| 模式 | 文档描述的行为 |
|---|---|
read-only |
要求受限后端拒绝写入 |
workspace-write |
允许在工作区根目录和后端承诺的临时区域内写入 |
danger-full-access |
绕过隔离 |
第一条必须牢记的边界:这套词汇只描述「文件影响」,不涵盖网络和进程可见性。 因此,「设了只读,为什么还能联网」不是 bug,因为模式本身没有描述这一层。
第二条边界与平台差异有关:
- POSIX 运行器在只读模式下,仍然允许 shell 所需的
/dev/null; - Windows ACL 运行器会因文档提到的环境 ACL 缺口而报告「部分执行」。
也就是说,同名模式在不同后端上的实际保证并不相同。这一点后文还会多次提到。
模式从哪来、根目录怎么定
普通工具调用以调用会话不可变的 cwd为根目录;没有 agent 时,则以部署配置为后备。
模式按以下优先顺序确定:
- 经批准的显式覆盖;
- 会话最后一个
sandbox/mode事件; - 部署默认值。
另一个容易忽略的语义是:策略属于「当前调用」。不同调用可以各自携带不同的边界,无须修改提供者的全局状态。所以,「我明明设了只读」这句话,必须先问清楚是哪一次调用的只读。
二、子进程这条路径:ctx.sandbox.confine
在受限模式下,进程消费者会向 ctx.sandbox.confine 传入两项内容:参数数组和已解析的策略。提供者再返回待启动的包装后参数数组以及强制执行结果。
本地提供者支持的后端包括:
- Linux:bwrap / Landlock;
- macOS:Seatbelt;
- Windows:ACL 受限令牌后端。
远程提供者也可以配合相应的远程执行环境使用。
需要特别注意:这些后端虽然实现同一个接口,但各操作系统提供的保证并不完全相同。
full 与 partial:必须读的那两个字段
结果中的 full 表示后端能管理该模式承诺的全部文件影响;partial 表示只能管理其中一部分。
参考文档列出的部分执行情形有:
- 旧版 Landlock ABI;
- Windows 的硬链接;
- 非受限读取;
- AppContainer ACL 边界。
文档对这类情形的要求很明确:需要绝对保证的调用方,必须拒绝这种情形,或者明确暴露这一区别,不能把部分执行当作完整执行。
后端找不到时会怎样
受限策略找不到可用后端时,文档要求报告 SANDBOX_UNAVAILABLE,不能悄悄以无约束方式透传。
这一点很重要:「失败了」和「放行了」是两种完全不同的结果,前者是可观测的错误,后者是静默的风险。
此外,运行器也可能在目标命令开始之前失败。分类时要结合非零退出和匹配的诊断信息;「拒绝签名」则描述「运行中的沙箱阻止了命令」。
因此仅凭退出码,无法判断属于哪一种。 这也是第四节要专门拆开的第一种混淆。
还要注意:danger-full-access 与上述路径都不同——消费者直接启动原始参数,根本不调用限制服务。 它没有「部分执行」状态,也就是不执行限制。
三、直接文件操作走的是另一条路
文件系统参考介绍的是一套独立的服务、提供者、可选观察策略和模型工具。
输入路径会先解析成后端目标。其中有两个概念:
targetKey:不透明的身份标识;displayPath:可能显示为本地路径、工作区相对路径,或远程 URI。
「显示名称」不能证明操作实际落在哪个执行环境中。 看到 ./src/index.ts 并不等于操作发生在你本机的那个目录。
sandboxPolicy 参数:传了,不等于执行了
writeText 和 editText 接口接受每次调用的 sandboxPolicy,但传入该参数不等于后端执行了它。
关键在于:能够执行沙箱策略的后端,才可以限制这些修改;裸后端会直接忽略这个参数。
因此,必须明确这一点:「存在策略解析器」或「存在进程沙箱」,都不能证明直接文件提供者也执行了同一策略。
排查时应当:找出实际处理这次操作的提供者,不要假设它一定执行了策略。
这一点也解释了为什么「同样的 read-only 会话,shell 写不进去,但文件工具写进去了」——两条路径的提供者不同。至于 Agent 平时怎么读写和编辑工作区文件,可延伸阅读Agent 怎样读写和编辑工作区文件。
观察策略解决的是另一个问题
可选观察插件检查的是「调用方是否观察过目标」以及「版本是否仍然一致」,它处理的是观察状态和版本一致性。
启用后:
- 未观察目标 → 可能产生
FS_NOT_OBSERVED; - 版本变化 → 可能产生
FS_STALE_VERSION。
它可以阻止特定的「未观察」或「过期」修改,但不负责阻止所有未经授权的文件影响。
没有这个插件时,裸接口允许无条件创建或覆盖,以及无版本保护的字面文本编辑。
这是三层之外的一层防护,别把它当成沙箱。
四、三层错误,三种解法
编辑被拒绝后,应先判断错误来自哪一层,再确定排查方向。
1. 五步排查顺序
- 记录四个要素:操作、目标、会话、实际提供者。确认根目录,以及这次调用是子进程还是直接文件工具。
- 检查解析出的模式,以及是否存在经批准的本次覆盖。受限子进程还要检查所选后端及其完整 / 部分执行报告。
- 按错误所属层判断:
FS_SANDBOX_DENIED→ 执行沙箱策略的文件后端拒绝;FS_PERMISSION_DENIED→ 宿主内核拒绝;- 运行器本身失败 → 不同于沙箱成功阻止了命令。
- 如果是
FS_NOT_OBSERVED或FS_STALE_VERSION,重新检查或读取目标,再评估修改。不要把版本错误解释成沙箱拒绝写入。 - 确实需要更大范围时,先核对影响范围及适用的审批,再重试;检查最终变更,并通过部署已有的恢复流程处理意外结果。
2. 「同一路径不同结果」是正常线索
以下两种情况都可能发生:
- 执行策略的文件后端拒绝根目录之外的写入,即使同一个用户在另一个进程里有权限写入;
- 反过来,宿主 ACL 也可能拒绝根目录之内的文件。
同一条路径在不同层得到不同结果,是正常的调查线索,并不矛盾。 另外,沙箱初始化失败也不能说明「原本的编辑会不会通过策略」——它根本没走到策略那一步。
3. 一次批准之后的重试要重新判断
策略解析器允许经批准的显式模式优先于会话模式;但这并不说明原调用已经成功,也不自动改变后续每次调用。
记录时必须写清批准的具体范围、实际目标和结果,以便区分「一次例外」与「会话默认行为」。
4. 远程路径要确认两端在同一环境
对于远程文件系统和远程进程,应先确认两者属于同一执行环境,再判断「同一个根目录」在两条路径中分别指什么。否则,比较的就是两台不同的机器。
五、为什么两种操作会给出不同答案
举一个具体例子:在同一个项目中,agent 可能通过 shell 运行程序生成报告,也可能直接调用文件编辑工具。
- 前者依赖进程运行器返回的受限参数和执行程度报告;
- 后者经过文件系统提供者及传入的策略参数。
即使两次调用使用同一个根目录,也要分别确认各自的后端和保证;一次调用的成功或失败,不能替代另一次的证据。
版本检查是独立的第三条判断线
假设文件读取后,目标被另一方修改:
- 带保护的编辑会先检查预期版本,再匹配字面文本,所以「针对新内容匹配失败」不会掩盖过期错误;
- 若原先确认文件不存在,带保护的创建也可能拒绝后来出现的文件。
这些规则有助于避免覆盖未观察到的改动,但不负责判断目标是否位于沙箱边界内。
符号链接:别用字符串前缀判断边界
有些路径表面上位于工作区内,实际解析时可能涉及符号链接和规范化。
沙箱参考说明:执行策略保留执行环境中的绝对路径写法,而执行约束的提供者会在实际文件存在的环境中规范化根目录。
因此,排查时应确认提供者的执行环境和解析结果,不能只凭字符串前缀断定访问是否位于边界内。
工作区路径重复、软链导致同一目录出现两条记录的现象,可参考加了软链后工作区列表没多一条;而「工作区是运行目录而不是访问边界」这件事在 bash 命令的沙箱边界与工作区文件工具的实际限制里也有具体展开。
六、记录调查结果的正确姿势
请将以下五项一并记录;缺少任何一项,后续排查时就得从头梳理:
- 策略模式;
- 根目录;
- 操作类型(子进程 / 直接文件工具);
- 实际提供者;
- 原始错误。
对比时一次只改变一个因素。例如,只有确认「直接编辑」与「子进程操作」确实指向同一目标后,两者的结果才有比较意义。
最后还要遵守一条原则:在能通过只读检查确认配置的情况下,不要把「无约束重试」当作诊断捷径。
七、限制与安全边界
- 模式描述文件影响,不代表网络隔离:
read-only不阻止联网,沙箱模式的词汇中不包含网络和进程可见性。 - 部分执行是需要正视的限制:
partial意味着后端无法兑现该模式承诺的全部文件影响,需要绝对保证时应拒绝或明确暴露这个区别。 danger-full-access明确绕过隔离:它不调用限制服务,也没有「部分执行」这个中间状态。- 应检查实际后端、平台和进程环境:不能只凭预设名称判断效果。
read-only在 POSIX 与 Windows ACL 运行器上的实际保证并不相同。 - 不要为了消除尚未解释的错误就直接扩大为完全访问:先定位到具体哪一层,再决定是否调整。
- 观察策略不能证明文件内容可信,也不判断编辑是否符合用户意图。它只处理「是否观察过」和「版本是否一致」。
- 写入成功不能证明选择了正确的工作区或目标:这只能说明「这一步没被拦住」。
- 分享日志前要先脱敏:日志里可能含路径、文件内容和其他敏感信息。
八、术语速查
- 文件影响模式:
read-only/workspace-write/danger-full-access三种,只描述文件影响。 ctx.sandbox.confine:受限模式下,进程消费者交出参数数组和已解析策略,并换回包装后的参数与强制执行结果。full/partial:后端能管理该模式承诺的全部 / 部分文件影响。targetKey/displayPath:不透明的后端身份 / 可能经过展示加工的可读路径。- 策略解析器:决定本次调用采用哪种模式、以哪个目录为根目录的那一层;它只负责选,不负责执行。
- 观察策略:可选的
fs/*层保护,处理未观察目标与版本变化,不替代沙箱。
相关阅读
- DeepSeek Harness 沙箱与文件系统访问限制如何配合?
- bash 命令的沙箱边界
- 工作区文件工具的实际限制
- Agent 怎样读写和编辑工作区文件
- 加了软链后工作区列表没多一条
- 更多 DSH 实践文章
本文依据 DeepSeek Harness 官方沙箱参考与文件系统参考整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog