DeepSeeker-Code源码导读07-安全防线

读懂工具安全防线：一个 tool_call 要闯过多少道闸门

这篇讲什么

上一篇拆了 CustomTool 协议------它告诉系统一个工具"声明"了什么安全需求（safetyLevel、requireApproval）。这篇讲这些声明怎么被执行层消费：一个 tool_call 从模型产出到执行完，要经过多少道闸门。

这是整个 agent 最不能出错的地方。模型可能会被 prompt injection 诱导去执行恶意命令、去读密钥外泄、去改 .git 篡改版本库。DeepSeeker-Code 的应对是纵深防御（defense in depth） ------单点防护不可靠，多重闸门按优先级串联，任一道拦住都安全。而且有个核心原则贯穿始终：安全后盾独立于用户授权，即用户 allow 了的工具，遇到灾难命令照样硬拒。

这篇拆 toolExecution.ts（processToolCall 管线）、autoPermission.ts（分类器审批）、guard.ts（底层物理防线）。对着源码读。

一、先看全貌：闸门优先级表

读这篇的钥匙，是下面这两张表------一个 tool_call 执行前 和执行后 各要过哪些闸门，按 processToolCall 的实际顺序排列：

执行前的拦截闸门（按优先级从高到低）：

| 闸门 | 拦截什么 | 优先级特点 |
|----------------------|-------------------------------------|------------------------|------------------|
| 计划模式门禁 | 计划期的一切白名单外工具 | 最高段位，不弹审批不加锁直接拒 |
| pre-hook（改写档） | 用户自定义拦截/改写 | 门禁链之前，改写后的 args 才是评估对象 |
| 保护路径硬规则 | 写 .git/.ssh/.aws/.deepseeker-code | 无论授权都拒 |
| 权限规则 checkPermission | 用户 settings.json 的 deny/ask/allow | deny>ask>allow |
| 灾难命令硬闸门 | rm -rf /、`curl | sh`、外传密钥 | 不可被 allow 绕过 |
| 互斥锁 | 后台工具占着锁 | 快速失败，免无谓弹窗 |
| 分类器审批 | 辅助模型判 safe/risky | safe 免审，risky 转人工 |
| 人工审批 | 用户三态决策 | allow-always 写持久规则 |
| pre-hook（兼容档） | 用户自定义拦截 | 审批后、仅 deny（回退开关档位） |
| undo 备份 | 写前快照 | 失败则阻断写入 |

执行后的处理闸门：

闸门	干什么
verifyResult	硬编码判定失败，防模型乐观幻觉
post-hook	执行后观察（不拦截）
脱敏	密钥替换 [MASKED_SECRET]，防云端读到
截断	结果超长去中间留头尾
outputFilter	toModel/toUser 双通道分流

核心认知只有一条：这些闸门是串联的，按优先级从高到低依次过。任一道判 denied，后面的闸门全跳过，工具不执行。 拿几个场景盘一下：

• 场景 A：模型想 rm -rf /。 用户之前对这个项目 allow 了 run_command（"总是允许"）。但灾难命令硬闸门在 allow 规则之后独立判定 ------rm -rf / 命中清单，直接硬拒，allow 规则救不了它。

• 场景 B：模型想改 .git/config。 即使用户 allow 了 edit_file，保护路径硬规则优先级最高------.git 目录无论授权与否一律禁碰，挡住"改 git 钩子实现持久化 RCE"。

• 场景 C：模型想跑 npm test。 默认模式下，这是只读命令（无 shell 元字符 + 命令头在只读清单），直接免审放行------消除审批疲劳。但 git status; rm -rf / 不行，因为有 ; 元字符。

• 场景 D：模型想 edit 一个普通源文件。 过保护路径（不在禁区）→ 过权限规则（无显式配置）→ 过灾难命令（非命令类）→ 分类器判定 safe（工作区内常规编辑）→ 免审放行 + undo 备份。

• 场景 E：模型 read_file 读到 .env。 执行成功（读操作 SAFE 免审），但执行后的脱敏 闸门把密钥替换成 [MASKED_SECRET]------模型拿到的是脱敏后的内容，云端看不到真密钥。

• 场景 F：计划模式里模型手痒调了 write_file。 工具表恒定（第 5 篇讲的 P0-A），模型看得见写工具，但计划模式门禁在 processToolCall 最前段就拒了------返回"❌ 当前为只读调研阶段，禁止 write_file"，不弹审批、不加锁、不进 hook 流水线。一次零成本的软拒绝，配合提示词静态引导，实测整个计划循环零试探。

理解了闸门的串联和优先级，再读 processToolCall，那一长串 if (!denied) 就不是冗余，而是一道道纵深防线。下面逐层拆。

二、执行前防线：拦截链

第零道：计划模式门禁 + pre-hook 改写位（链条之前）

进入正式闸门链之前，有两段"链前"逻辑值得单独点名。

计划模式门禁 （toolExecution.ts :143）在终结类判定之后、matchedTool 匹配之前：planMode === true 且工具名不在 PLAN_ALLOWED_TOOLS 白名单 → 直接返回拒绝文案。它比保护路径还靠前，而且刻意不走审批/锁/hook 流水线------计划期的写操作试探不配消耗这些重型资源，一条引导文案就够了。这是第 5 篇 P0-A（工具表恒定）在执行层的落点。

pre-hook 的改写位 （:169，开关 hookRewrite 开启时）也在全部门禁之前------这不是 bug 是设计：

改写后的 args 才是被保护路径/权限规则/灾难命令/互斥锁/审批/undo 备份评估的对象（否则 hook 改写会绕过门禁，或用户批了 X 而 hook 已改成 Y）。deny 亦前置（省无谓审批弹窗，对齐 Claude Code 顺序）。

想象 pre-hook 放在审批之后会发生什么：hook 把 path: "src/a.ts" 改写成 .git/hooks/pre-commit，审批早就按旧参数通过了------门禁全部失效。所以改写必须前置到一切安全评估之前，让后面的每道闸门评估的都是"最终会执行的那个 args"。关闭改写开关时，pre-hook 回退到旧位（审批后、仅 deny），行为与改造前逐字节一致。

第一道：保护路径硬规则（优先级最高）

processToolCall :149，写工具碰受保护目录，无论授权都拒：

const protectedPaths = calledName === 'move_file'
    ? [calledArgs?.source, calledArgs?.destination]
    : (isUndoTrigger(calledName) ? [calledArgs?.path] : []);
const hitProtected = protectedPaths.find(p => isProtectedWrite(p, toolCtx.cwd));
if (hitProtected) {
    denied = true;
    result = `❌ [保护路径] 禁止修改受保护目录...`;
}

受保护目录（guard.ts :266）：.git/.hg/.svn（VCS）、.ssh/.aws（凭证）、.deepseeker-code（项目配置，防 agent 自我篡改提权）。注意它优先级高于 checkPermission------即使用户 allow 了 edit_file，也禁改这些目录 。注释点明了一个具体威胁（:147）：

move_file 可 move 进 .git/hooks/、.deepseeker-code/settings.json 实现持久化 RCE / 配置注入。

所以 move_file 的双路径都要查------它能"移动"文件进禁区，等于变相写入。

第二道：权限规则 checkPermission（deny>ask>allow）

用户在 settings.json 配的细粒度规则（:158）：

perm = checkPermission(calledName, calledArgs);
if (perm === 'deny') { denied = true; }
else if (perm === 'allow') { needApproval = false; }  // 免审
else if (perm === 'ask') { needApproval = true; }      // 强制审批

三态语义：deny 直拒、allow 免审、ask 强制审。未匹配走默认 safetyLevel。注意一个 fail-safe（:164）：权限裁决异常 → 走默认行为，不静默放行。

第三道：灾难命令硬闸门（不可被 allow 绕过）★

这是最关键的一道，也是全篇核心设计的体现（:174）：

// ★ P0-2 灾难命令硬闸门：与 needApproval / allow 规则解耦------堵住「裸 allow 规则让
//   checkPermission='allow' 跳过 runAutoCheck（含 COMMAND_DENY）」的审批绕过路径。
//   即使用户 allow 了 run_command，rm -rf /、curl|sh、外传密钥等灾难命令仍硬拒。
if ((calledName === 'run_command' || calledName === 'run_in_background')
    && matchCommandDeny(...)) {
    denied = true;
}

注意它的判定独立于 allow 规则 。为什么必须独立？因为如果"用户 allow 了 run_command"就能跳过灾难命令检查，那一个 allow 规则就把所有安全后盾废了------prompt injection 诱导模型跑 rm -rf / 时，allow 规则反而成了帮凶。所以灾难命令检查是独立的安全后盾，授权归授权、安全归安全，两者解耦。

灾难命令清单（autoPermission.ts :65）覆盖：递归删根/家/通配、格式化、fork bomb、dd 写设备、关机重启、chmod 777、curl|sh 远程执行、外传敏感文件。这道清单的正则还专门做了换行绕过对抗（难点一详讲）。

第四道：互斥锁快速失败

后台工具（isSync:false）占着锁时，新的相同锁调用快速失败（:184）：

const lockKey = isBgTool ? computeLockKey(matchedTool.function.exclusiveLock, calledArgs, toolCtx) : null;
if (lockKey && isLockHeld(lockKey)) {
    denied = true;
    result = `🔒 [互斥锁阻塞]...`;
}

放在审批前判断------锁住了就不弹窗，免得用户审批了却执行不了。

第五道：分类器审批（减少打扰的启发式）

runAutoCheck（autoPermission.ts :199）是"减少审批疲劳"的关键。它跑一个轻量辅助模型，对工具调用判 safe/risky：

const auto = await runAutoCheck(calledName, calledArgs, toolCtx, permissionMode === 'auto');
if (auto === 'allow') { needApproval = false; }     // safe → 免审
else if (auto === 'deny') { denied = true; }         // 高危清单 → 硬拒
// 'ask' → 落入下方 requestApproval 转人工

但注释反复强调一个定位（autoPermission.ts :18）：

分类器是「减少打扰的启发式」，非安全边界------既有后盾（checkPermission 规则、guard 审批网关、工具内部 resolveSafePath/SSRF/undo 备份）全部保留。

这是个清醒的设计：分类器会误判，所以它只能"减少打扰"（safe 免审），不能当安全边界。 真正的安全靠它前面的硬闸门（保护路径、灾难命令）和它后面的人工审批兜底。而且分类器是 fail-closed------异常/超时一律 ask（转人工），绝不静默放行（难点三详讲）。

第六道：人工审批（三态 + allow-always 持久规则）

分类器说"转人工"或默认 safetyLevel 要求审批时，走 requestApproval（guard.ts :411）。宿主回传三态：

const decision = await ctx.requestApproval(safeDetail, { toolName, toolCallId, sessionId });
const approved = decision !== 'deny';
if (decision === 'allow-always') {
    const ruleStr = buildScopedAllowRule(toolName, args);  // 保守作用域
    if (ruleStr) await addPermissionRule('project', 'allow', ruleStr);
}

allow-always 会写持久 allow 规则------但作用域是保守 的（难点四详讲）：命令类落精确串（run_command(npm test)），路径类落顶层目录（edit_file(src/*)）。绝不像旧版那样回退"裸工具名"------裸放 edit_file 等于把这个工具所有后续调用静默放行，对 DANGER 工具尤其危险。

第七、八道：pre-hook（兼容档）+ undo 备份

pre-hook 出现了两次------第零道讲过，改写开关（DEEP_SEEK_HOOK_REWRITE，默认开）开启时它前置到全部门禁之前，可 deny 也可改写 args；开关关闭时回退到这里的旧位（审批后、仅 deny），双位行为与改造前逐字节一致。为什么要保留旧位？回退开关的完整性------关掉新特性后，系统必须能一字不差地回到老路，否则开关就成了"伪开关"。

最后一道是 undo 备份（:224）：写前快照原文件，失败则阻断写入------"凡改必可回退"原则。它是执行前的最后一道闸门，也是下一篇（第 8 篇）的主角。

三、执行后防线

工具执行完，结果回灌前还有几道处理：

verifyResult 防幻觉 （:241）：上一章讲过，工具硬编码判定成败，FAILED 时在结果置顶插警告"系统判定失败，别盲目乐观"。

脱敏 （:264）：applyPrivacyMasking 把 privacyMaskingRules 声明的密钥模式替换成 [MASKED_SECRET]。只影响发往云端模型的视图------本地执行的是真内容，发给 DeepSeek 的是脱敏后的。这是"本地工具 + 云端模型"的隐私护城河。

截断 + outputFilter （:265/271）：truncateToolResult 去中间留头尾；outputFilter 分流 toModel/toUser。这两道是上一章讲的上下文优化，在执行后统一施加。

post-hook 改写（resultOverride） ：PostToolUse hook 现在还能改写 resultForModel------在 outputFilter 分流之后套用（用户视图 resultForUser 永远不动，用户始终看到真实输出）。用途比如"工具输出太啰嗦，hook 把给模型的版本压缩成一行结论"。transcript 落盘的是 resultForModel，所以回放/压缩/分叉看到的就是模型当时看到的------一致性免费保住。细节在第 12 篇 Hooks 展开。

四、底层物理防线（guard.ts）

除了 processToolCall 这条执行链，还有几道更底层的物理防线，独立于审批流程：

沙箱围栏 resolveSafePath / assertWithinWorkspace ：写/删工具的路径，先 realpath 解析物理路径（防 symlink 跨界逃逸），再判是否在工作区内。还有写操作前的 TOCTOU 复检 （guard.ts :232）------检查与写之间的竞争窗口，软链接可能在这间隙被替换。注释诚实承认"完全闭环需 O_NOFOLLOW，Node 无直接 API"，工作区根围栏兜底最严重后果。

命令环境凭证剔除 scrubCommandEnv （:281）：run_command 的子进程 env 剔除敏感变量------硬编码 denylist（agent 自身密钥）+ 模式匹配（key 名含 KEY/TOKEN/SECRET/PASSWORD 等一律剔）。防 LLM 经 env/printenv//proc/self/environ 读取宿主凭证外泄到云端。

只读命令免审的安全基石 hasShellMetachars （autoPermission.ts :109）：检测 ;&|<>\``、$(、换行。这是"只读命令免审"能成立的地基------**只有无元字符的单条命令，才没有拼接第二条命令的空间。** git status; rm -rf /因为有;` 被挡，落回人工审批。

五、四个关键设计决策

决策一：纵深防御，多道闸门串联

单点防护不可靠------任何一道闸门都可能有漏洞（正则漏匹配、分类器误判、用户配错规则）。所以闸门串联，纵深配置 ，任一道拦住都安全。processToolCall 那一长串 if (!denied) 就是这个思想的代码化。读源码时，每个 if (!denied) 都是一道独立防线，别嫌它啰嗦。

决策二：安全后盾独立于用户授权 ★

这是全篇最重要的设计。灾难命令硬闸门、保护路径硬规则，都独立于 checkPermission 的 allow 规则 。用户可以授权"总是允许 run_command"，但这不代表"允许 rm -rf /"。授权管的是"烦不烦"，安全管的是"危不危险"，两者解耦。 这个设计堵死了"一个 allow 规则废掉所有安全"的路径。

决策三：分类器是启发式，不是安全边界

分类器会误判，所以它只能减少打扰（safe 免审），不能当安全边界。真正的安全靠硬闸门（不可绕过）+ 人工审批（兜底）。分类器 fail-closed（异常转人工）。这个定位很清醒------不把一个会出错的启发式当防线，是安全设计的基本素养。

决策四：分波调度，SAFE 并发、写串行

toolScheduling.ts 的分波调度（:68）：连续的 SAFE 只读工具并发执行（Promise.all），写工具/ask/deny/后台/终结类一律串行。串行屏障保证写工具的 undo 备份读到未改原文件、appendMessage 不并发写 JSONL。这是个"在安全前提下抢性能"的设计------只读工具并发安全（不互踩），写工具必须串行（保一致性）。

六、五个技术难点

难点一：灾难命令清单的正则对抗

COMMAND_DENY 清单的正则，处处可见"防换行绕过"的增强（autoPermission.ts :65）：

// 增强：加上 s 修饰符，防止利用多行或反斜杠换行绕过空格匹配
/rm\s+-[a-z]*r[a-z]*f?\s+([\s\S]*\s+)?(\/|~|\*)/is,
// 增强：将 .* 改为 [\s\S]*，防止 if=xxx 换行后接 of=/dev/xxx 绕过
/\bdd\b[\s\S]*of=\/dev\//i,

rm -rf / 写成 rm -rf\n/（换行）能绕过 naïve 的 \s+ 匹配吗？加 s 修饰符让 . 匹配换行，用 [\s\S]* 代替 .* 跨行。这是和"绕过手法"的持续对抗------安全正则永远在被试探，必须考虑换行、引号、转义各种伪装。

难点二：只读命令免审的安全基石

"只读命令免审"听着危险------怎么保证 git status 后面没跟个 rm -rf？基石就是 hasShellMetachars（:109）：

命令串含 ; & | < > 反引号 $( 换行任一即 true。只读免审仅在「无元字符」时生效：此时命令是单条简单命令，其余 token 都是该命令的参数，无法拼接第二条命令。

这个逻辑很严密：无元字符 = 没有命令分隔符 = 只有一条命令 。git status; rm 有 ; 被挡，ls | evil 有 | 被挡，$(evil) 有 $( 被挡。在这个前提下，再校验命令头是不是只读清单（git status/ls/npm test 等），就安全了。而且刻意保守------echo "a && b" 因引号内有 && 也判含元字符、不免审，宁可多问，绝不静默放行。

还有两道配套：hasWriteModifier（挡 sed -i、find -delete）和 hasSensitiveFileArg（挡 cat .env、grep id_rsa）。只读免审要过这三道闸，才成立。

难点三：分类器 fail-closed

分类器调辅助模型，可能超时、可能异常、可能返回乱码。每一类都不能静默放行（:221）：

const v = await classifyToolRisk(name, args, '', ctx.abortSignal);
return v === 'safe' ? 'allow' : 'ask';  // 只有显式 safe 才放行，其余全 ask

而且 classifyToolRisk 内部（第 3 篇讲过）也是 fail-closed------超时 10s、异常、中止，一律返回 risky。两层 fail-closed：辅助模型层 fail-closed + runAutoCheck 层只认显式 safe。这种"不确定就不放行"的保守，是分类器能被信任地用于"减少打扰"的前提。

难点四：allow-always 的安全作用域

用户点"总是允许"，不能裸放工具名（:446）：

旧版回退裸工具名会把该工具所有后续调用静默放行，对 MCP DANGER 工具尤其危险。

buildScopedAllowRule 生成保守作用域：命令类落精确串（run_command(npm test) 只免审这一条命令）、路径类落顶层目录（edit_file(src/*)）。无法安全生成作用域时（MCP、缺主参数）返回 null → 不持久化，降级 allow-once。"总是允许"必须落到具体的作用域，不能是整个工具。 这是个容易被忽略但极重要的安全细节------一个粗心的 allow-always 能让 DANGER 工具永远免审。

难点五：终结类工具的占位补全

分波调度里有个隐蔽的坑（toolScheduling.ts :49）：模型一轮里同时调了 exit_plan_mode 和别的并行工具。exit_plan_mode 是终结类，会让本轮直接 return。但它后面的并行 tool_call 如果不补占位，会留下孤儿 tool_call_id------会话恢复重建上下文时 API 因配对缺失报 400。

const fillRestPlaceholders = async (fromIdx) => {
    for (let j = fromIdx + 1; j < tcs.length; j++) {
        message.push({ role: 'tool', tool_call_id: tcs[j].id, content: "（已跳过...）" });
        await appendMessage(...);
    }
};

这个细节的教训是：任何提前 return 的路径，都要保证 tool_call 和 tool result 的配对完整。 这和第 4 篇压缩的"批次不破坏工具配对"是同一类约束------OpenAI 协议要求 tool_calls 后必跟 tool 消息，任何截断、跳过、提前结束都不能破坏这个配对。

七、推荐的源码阅读顺序

1. 先读 toolExecution.ts 的 processToolCall ：对着第一节的闸门表，从计划模式门禁（:143）和 pre-hook 改写位（:169）开始，往下逐个 if (!denied) 标注这是第几道闸门。这是全篇的主干。
2. 读 autoPermission.ts：重点看 COMMAND_DENY 清单（正则对抗）、hasShellMetachars（只读免审基石）、runAutoCheck（分类器 fail-closed）、isReadOnlyCommand（三道闸合一）。
3. 读 guard.ts 的 requestApproval（三态审批 + allow-always 作用域）、resolveSafePath/assertWithinWorkspace（沙箱围栏 + TOCTOU）、scrubCommandEnv（凭证剔除）。
4. 读 toolScheduling.ts 的分波调度：canParallelize（什么能并发）、屏障语义（写串行）、fillRestPlaceholders（配对补全）。
5. 回头读 type.ts：现在再看 safetyLevel/requireApproval/verifyResult/privacyMaskingRules/outputFilter 这些字段，就能看到它们在 processToolCall 里各自被哪段代码消费------声明与执行的对应关系全通了。

八、关联：防线与上下游

这套安全防线和很多模块咬合：

• CustomTool 字段（第 6 篇） → processToolCall 是这些字段的消费者：safetyLevel 决定 needApproval、requireApproval 生成审批说明、verifyResult 判失败、privacyMaskingRules 脱敏、outputFilter 分流、maxOutputCharacters 截断。
• 计划模式（第 5 篇） → enter/exit_plan_mode 是 processToolCall 最先拦截的终结类（优先于 abort）。
• undo 备份（下一篇） → 是执行前的最后一道闸门，"凡改必可回退"。
• 分类器（第 3 篇的 classifyRisk） → 是 runAutoCheck 的引擎，走辅助模型 + fail-closed。
• 分波调度 → 复用第 6 篇的 safetyLevel 判并发性（SAFE 并发，其余串行）。

你会看到，"安全"不是单独一块，它是一张横跨工具协议、执行管线、底层文件操作的纵深网络。每个模块都为这张网贡献一段，processToolCall 把它们按优先级串成一条拦截链。

最后

给一个会自主执行命令、改文件、跑代码的 agent 做安全，没有银弹。DeepSeeker-Code 的答案是纵深防御------一道道闸门按优先级串联，保护路径、灾难命令这些硬闸门独立于用户授权，分类器只减少打扰不当边界，执行后还有 verify/脱敏/截断兜底，底层还有沙箱围栏。

读这段源码，最值得带走的是两个判断：一是"安全后盾独立于授权" ------用户 allow 了不代表 rm -rf / 能跑，授权管烦不烦、安全管危不危险；二是"分类器是启发式不是边界"------会误判的东西只能减少打扰，不能当防线，而且必须 fail-closed。这两个判断，是这套防线能被信任的根基。

下一篇，我们读执行前的最后一道闸门------Undo 系统，看"凡改必可回退"是怎么用写前备份实现的。

项目源码开源在 github.com/xnk/deepSee... ，文章里提到的文件都在 src/core/src/agent/ 和 src/core/src/tool/ 下，欢迎对着源码读。觉得这个导读系列有点意思，点个 star 是对我最大的鼓励。

总结

1. 纵深防御是主线：一个 tool_call 执行前过拦截闸门链（计划模式门禁→pre-hook 改写位→保护路径→权限规则→灾难命令→互斥锁→分类器→人工审批→pre-hook 兼容档→undo 备份），执行后过处理闸门（verify/脱敏/截断/outputFilter/post-hook 改写），任一道 denied 则不执行；改写型 pre-hook 必须前置到全部门禁之前------改写后的 args 才是被评估对象；
2. 核心原则：安全后盾独立于授权------灾难命令硬闸门、保护路径硬规则都独立于 allow 规则，用户 allow 了 run_command 不代表 rm -rf / 能跑；
3. 分类器是减少打扰的启发式、非安全边界------只 safe 免审，risky/异常/超时一律 fail-closed 转人工；底层安全靠硬闸门 + 人工兜底；
4. 分波调度：SAFE 只读工具并发（Promise.all），写/ask/deny/后台/终结类串行（屏障保 undo 读到未改文件 + JSONL 不并发写）；
5. 五个技术难点：灾难命令正则的换行绕过对抗（s 修饰符/\\s\\S*）、只读免审的安全基石（hasShellMetachars + 三道闸）、分类器双层 fail-closed、allow-always 的保守作用域（不裸放工具名）、终结类工具的配对占位补全（防孤儿 tool_call_id 致 400）。