沙箱设成只读,文件还是被写了?分清进程沙箱、文件提供者与宿主权限这三层边界

简介: 在 DeepSeek Harness 中将沙箱设为 `read-only`,写入操作却仍然成功,这类「策略没生效」的困惑,往往源于把三层边界混为一谈。需要分别核对:策略解析器选中了哪种模式、子进程使用哪个沙箱后端,以及直接文件操作的提供者是否真正执行了该策略。此外,`partial` 执行、`danger-full-access` 绕过隔离,以及符号链接规范化,都会让「工作区名称」这一表面线索失去判断价值。本文依次梳理「策略管什么 → 子进程路径 → 文件提供者路径 → 三层错误如何区分 → 排查与安全边界」。

把沙箱设为 read-only,Agent 却仍然写入了文件——这是 DSH 权限排查中最容易令人困惑的现象之一。 根因通常不是「策略没生效」,而是同一份策略进入了两条不同的执行路径,其中一条根本没有校验它。

排查时,常见的误判主要有六类:

  1. 以为「设了只读模式」就等于所有文件操作都被拦住;
  2. 以为 --workspace /path/to/repo 就是文件访问边界,因此工作区外的路径自然安全;
  3. 看到 SANDBOX_UNAVAILABLE 或运行器报错,就认为沙箱已经生效并拦住了命令;
  4. 把 FS_STALE_VERSION 这类版本冲突当成沙箱拒绝写入;
  5. 把 FS_SANDBOX_DENIED 与 FS_PERMISSION_DENIED 混为一谈,于是去查错了层;
  6. 只凭路径字符串前缀判断「在不在工作区内」,忽略了符号链接与规范化。

明确排查方向,关键在于一句话:策略解析、进程沙箱、文件提供者是三件不同的事,必须分别核对。 相关教程见DeepSeek Harness 沙箱与文件系统访问限制如何配合?。

一、这份策略到底管什么?

沙箱参考列出了三种文件影响模式:

模式 文档描述的行为
read-only 要求受限后端拒绝写入
workspace-write 允许在工作区根目录和后端承诺的临时区域内写入
danger-full-access 绕过隔离

第一条必须牢记的边界:这套词汇只描述「文件影响」,不涵盖网络和进程可见性。 因此,「设了只读,为什么还能联网」不是 bug,因为模式本身没有描述这一层。

第二条边界与平台差异有关:

  • POSIX 运行器在只读模式下,仍然允许 shell 所需的 /dev/null;
  • Windows ACL 运行器会因文档提到的环境 ACL 缺口而报告「部分执行」。

也就是说,同名模式在不同后端上的实际保证并不相同。这一点后文还会多次提到。

模式从哪来、根目录怎么定

普通工具调用以调用会话不可变的 cwd为根目录;没有 agent 时,则以部署配置为后备。

模式按以下优先顺序确定:

  1. 经批准的显式覆盖;
  2. 会话最后一个 sandbox/mode 事件;
  3. 部署默认值。

另一个容易忽略的语义是:策略属于「当前调用」。不同调用可以各自携带不同的边界,无须修改提供者的全局状态。所以,「我明明设了只读」这句话,必须先问清楚是哪一次调用的只读。

二、子进程这条路径: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. 五步排查顺序

  1. 记录四个要素:操作、目标、会话、实际提供者。确认根目录,以及这次调用是子进程还是直接文件工具。
  2. 检查解析出的模式,以及是否存在经批准的本次覆盖。受限子进程还要检查所选后端及其完整 / 部分执行报告。
  3. 按错误所属层判断:
    • FS_SANDBOX_DENIED → 执行沙箱策略的文件后端拒绝;
    • FS_PERMISSION_DENIED → 宿主内核拒绝;
    • 运行器本身失败 → 不同于沙箱成功阻止了命令。
  4. 如果是 FS_NOT_OBSERVED 或 FS_STALE_VERSION,重新检查或读取目标,再评估修改。不要把版本错误解释成沙箱拒绝写入。
  5. 确实需要更大范围时,先核对影响范围及适用的审批,再重试;检查最终变更,并通过部署已有的恢复流程处理意外结果。

2. 「同一路径不同结果」是正常线索

以下两种情况都可能发生:

  • 执行策略的文件后端拒绝根目录之外的写入,即使同一个用户在另一个进程里有权限写入;
  • 反过来,宿主 ACL 也可能拒绝根目录之内的文件。

同一条路径在不同层得到不同结果,是正常的调查线索,并不矛盾。 另外,沙箱初始化失败也不能说明「原本的编辑会不会通过策略」——它根本没走到策略那一步。

3. 一次批准之后的重试要重新判断

策略解析器允许经批准的显式模式优先于会话模式;但这并不说明原调用已经成功,也不自动改变后续每次调用。

记录时必须写清批准的具体范围、实际目标和结果,以便区分「一次例外」与「会话默认行为」。

4. 远程路径要确认两端在同一环境

对于远程文件系统和远程进程,应先确认两者属于同一执行环境,再判断「同一个根目录」在两条路径中分别指什么。否则,比较的就是两台不同的机器。

五、为什么两种操作会给出不同答案

举一个具体例子:在同一个项目中,agent 可能通过 shell 运行程序生成报告,也可能直接调用文件编辑工具。

  • 前者依赖进程运行器返回的受限参数和执行程度报告;
  • 后者经过文件系统提供者及传入的策略参数。

即使两次调用使用同一个根目录,也要分别确认各自的后端和保证;一次调用的成功或失败,不能替代另一次的证据。

版本检查是独立的第三条判断线

假设文件读取后,目标被另一方修改:

  • 带保护的编辑会先检查预期版本,再匹配字面文本,所以「针对新内容匹配失败」不会掩盖过期错误;
  • 若原先确认文件不存在,带保护的创建也可能拒绝后来出现的文件。

这些规则有助于避免覆盖未观察到的改动,但不负责判断目标是否位于沙箱边界内。

符号链接:别用字符串前缀判断边界

有些路径表面上位于工作区内,实际解析时可能涉及符号链接和规范化。

沙箱参考说明:执行策略保留执行环境中的绝对路径写法,而执行约束的提供者会在实际文件存在的环境中规范化根目录。

因此,排查时应确认提供者的执行环境和解析结果,不能只凭字符串前缀断定访问是否位于边界内。

工作区路径重复、软链导致同一目录出现两条记录的现象,可参考加了软链后工作区列表没多一条;而「工作区是运行目录而不是访问边界」这件事在 bash 命令的沙箱边界与工作区文件工具的实际限制里也有具体展开。

六、记录调查结果的正确姿势

请将以下五项一并记录;缺少任何一项,后续排查时就得从头梳理:

  1. 策略模式;
  2. 根目录;
  3. 操作类型(子进程 / 直接文件工具);
  4. 实际提供者;
  5. 原始错误。

对比时一次只改变一个因素。例如,只有确认「直接编辑」与「子进程操作」确实指向同一目标后,两者的结果才有比较意义。

最后还要遵守一条原则:在能通过只读检查确认配置的情况下,不要把「无约束重试」当作诊断捷径。

七、限制与安全边界

  • 模式描述文件影响,不代表网络隔离: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 官方沙箱参考与文件系统参考整理,由 DSH Plugin 社区(dsh-plugin.com)维护者撰写,首发于阿里云开发者社区。
插件与文档收录于:https://dsh-plugin.com/zh/blog

目录
相关文章
|
5天前
|
安全 开发者
装完子智能体插件却找不到工具:先分清「包在不在」和「这一层选没选」
`dsh plugin add` 成功、插件页显示已安装,并不代表当前 agent 一定能看到对应工具。本文依据官方 CLI 参考与两份提供方 README,将问题拆成三层:包是否已安装、当前 profile 是否选中了这一层,以及本次 agent 请求是否注册了宿主工具。文中也解释两份文档对「要不要改 preset」的描述为何不同,以及工具出现后调用失败该从哪里排查。
77 1
|
2天前
|
人工智能 Linux 测试技术
Claude Fable5.2杀疯了!分享4个神仙玩法(附稳定使用方案)
Claude Fable5.2正在用代码吞噬一切,太🐂🍺了...
144 0
|
1月前
|
人工智能 自然语言处理 机器人
2026年趋势前瞻:企业如何应用智能客服迎接大模型技术变革
2026年,智能客服正经历范式跃迁:从关键词匹配迈向意图理解,AI Agent实现“能答”更“能干”。多模型调度、人机协同国标落地、情感计算预判化成四大趋势。瓴羊Quick Service以三层架构与闭环执行,助力企业服务效能提升50%+。
|
1月前
|
网络协议 应用服务中间件 网络安全
阿里云SSL证书免费申请流程:个人测试证书(原免费证书)有效期3个月
阿里云免费SSL证书由DigiCert提供,单域名、有效期3个月,每年可申领20张。流程含控制台申请、DNS验证(TXT记录)、一键下载多格式证书,全程零费用,适合个人网站及测试环境快速启用HTTPS。(239字)
|
4月前
|
人工智能 分布式计算 大数据
活动报名 | Agentic Lakehouse Meetup · 北京站,从开源技术创新到多模态数据智能化
8月14日,阿里云在北京举办“Agentic Lakehouse”技术活动,聚焦开源大数据生态如何支撑AI Agent全生命周期。
666 2
活动报名 | Agentic Lakehouse Meetup · 北京站,从开源技术创新到多模态数据智能化
|
3月前
|
人工智能 自然语言处理 监控
GEO搜索优化:大模型引用率提升的六大实战策略
本文详解生成式引擎优化(GEO)六大实战策略:构建AI可理解的内容结构、主题聚类、权威可信度、机器可读性、高价值FAQ库及引用监控体系,助力企业从SEO转向成为大模型答案的权威来源。
491 4
|
存储 传感器 人工智能
中小制造工厂数字化瓶颈破局:AI 流程精细化 + 工业自动化一体化落地架构实践
离散制造企业普遍存在产线自动化与管理系统数据割裂、管理颗粒粗放、人工流程成本高的痛点。本文基于产学研落地项目,介绍AI 驱动企业管理流程自动化整套技术架构,结合AI 精细化分析细化管理颗粒度能力,联动现场工业自动化设备,搭建工业自动化与企业管理流程一体化云边协同方案,给出轻量化分步落地路径与真实工厂量化收益数据,面向制造 IT、智能制造架构师提供可复用落地思路。
|
3月前
|
SQL 数据采集 监控
别再堆工具了!从 0 到 1 搭建小型生产级数据平台,只需要这份落地清单
别再堆工具了!从 0 到 1 搭建小型生产级数据平台,只需要这份落地清单
237 1
|
3月前
|
SQL 分布式计算 大数据
数据工程师为什么越做越值钱?一份从入门到高级的数据工程技能树、项目实战与简历升级指南
数据工程师为什么越做越值钱?一份从入门到高级的数据工程技能树、项目实战与简历升级指南
406 1
|
3月前
|
消息中间件 分布式计算 大数据
别再闭眼堆技术栈!企业大数据开源工具选型清单,看懂这张表少走3年弯路
别再闭眼堆技术栈!企业大数据开源工具选型清单,看懂这张表少走3年弯路
336 2