实现篇第7章 在执行前设一道卡——Approval ​

小A和老Z守着一道拦住命令小车的闸门,却看着装有钥匙的文件夹从工作区传送带畅通无阻地进入思维云,呈现安全护栏的局限。

本章导读: 你会写 BeforeToolCall 审批策略和 denyBashByDefault 默认拒绝。这一步要诚实面对:当前只有有限的应用层护栏,read/write 默认放行、提示注入能通过文件内容越权,这些缺口不能用 prompt 里的安全规则填补。

入口能调用真实工具了。小A松了口气,问老Z:“我配了 denyBashByDefault,那是不是就安全了?”

“先别高兴。”老Z说,“它只是一条运行时策略。这一章要把参考实现真正提供的控制和生产化缺口写清楚。有一句话请你先记住:提示词不是安全边界。”

小A:“那我手里到底有哪几道控制?”

老Z列了一张控制能力矩阵:

控制 当前实现 能限制 不能限制
BeforeToolCall 已实现 一次 tool call 的允许/拒绝 绕过 loop 的进程
approval denyBashByDefault 只拒绝 bash;read/write 默认允许 数据读取、文件覆盖或外发安全
path boundary workspacePath 当前符号链接逃逸 TOCTOU、网络、其他进程
process/container/VM 未实现 无 文件、内核或网络隔离

小A:“这张表里‘能限制’和‘不能限制’分得这么细,为什么不直接说‘安全’或‘不安全’?”

“因为安全不是二值的,是分层的。”老Z说,“denyBashByDefault 挡得住模型直接调 bash 外传,这是‘能限制’;但它挡不住模型用 read 把工作区里的密钥读出来塞进上下文,这是‘不能限制’。你要是把这两件事笼统叫‘部分安全’,补 read 审批的时候就会想,反正 bash 挡住了,问题不大。矩阵的每一格,对应一个你能对用户说清楚的边界:‘这个我管,那个我不管’。生产化要做的事,就是把‘不能限制’的格子一个个挪到‘能限制’那边,前提是先知道哪些格子还没挪。”

Hook 是一次决策,不是授权系统 ​

小A:“denyBashByDefault 具体是怎么写的?”

老Z打开 approval.ts:

ts
if (call.name === "bash") return {
  approved: false, reason: "bash requires an explicit approval policy",
};
return { approved: true };

“再看执行前的分支。”老Z又打开 agent.ts:

ts
const approval = (await options.beforeToolCall?.(call)) ?? { approved: true };
if (!approval.approved) { await record({ role: "tool", toolCallId: call.id,
  content: approval.reason ?? "tool call rejected", isError: true }); continue; }

“拒绝被记录成模型可见的 tool error,正常路径则继续查找工具并执行。若未提供 hook,默认允许;main 显式装配默认拒绝,其他调用者必须自己选择策略。所以 BeforeToolCall 是扩展缝,不是全局强制安全策略。”

小A:“默认允许?有人忘了传 beforeToolCall,岂不是裸跑?”

“对,就是裸跑,而且这是有意的设计。”老Z说,“agent.ts 里那行 approval = (await options.beforeToolCall?.(call)) ?? { approved: true },默认放行就藏在 ?? 后面。runAgent 是库函数,它不知道调用方的安全策略是什么。main.ts 装配 denyBashByDefault 是应用层的选择;测试里很多用例不传 beforeToolCall(见 agent.test.ts),因为它们测的是循环逻辑,不是安全策略。库提供扩展缝,应用装配策略,混在一起,库就绑死了一种用法。代价是每个新调用方都得记得自己装配审批。”

小A:“把策略做成配置对象呢?比如 { allowBash: false },不是更直观吗?”

“配置对象是数据,函数是策略。”老Z说,“denyBashByDefault 是函数,因为策略要读 call 才能决定:你现在只看 call.name,将来可能要看参数、看预算、要问用户,数据对象表达不了‘读参数再决定’。函数还能组合,compose(denyBashByDefault, requireApprovalFor('rm')) 就是在外层再套一条规则;配置对象只能靠字段枚举,每加一条规则就加一个字段。代价是清单不可枚举,你没法静态列出当前生效的所有规则,只能靠测试和文档补。三种常见形状摆一起对比:”

策略形状 形状 适合 代价
默认拒绝 除 allowlist 外全拒 高权限工具(bash) 误伤合法调用
默认放行 除 denylist 外全放 低风险工具(read) 依赖每一条规则补全
参数级策略 按参数内容决定 高风险动作(删除、外发) 需要懂参数语义

“当前实现是前两种的组合:bash 默认拒绝,其余默认放行。参数级策略没有实现,BeforeToolCall 只收到 call,没人教它‘什么叫危险参数’。后果就是 write 到任意路径、read 任何文件,都是放行的。”

小A:“hook 自己抛错了呢?放行还是拒绝?”

“向上抛,整轮停,既不放行也不‘软拒绝’。”老Z说,“看 agent.ts:try { approval = await options.beforeToolCall?.(call) } catch (error) { ... await recordFailedCallAndSkippedCalls(...); throw error }。测试 approval hook failures close every persisted call before rethrowing(见 tool-failure-session.test.ts)验证了这条:hook 抛错时,当前 call 记成 'tool approval failed',后面的记成 'not executed after an earlier failure',然后错误原样抛给调用方。审批逻辑出错时,你不能假设它本会放行,那等于绕过策略;也不能假设它本会拒绝,那可能冤枉合法调用,停下来让人处理。这跟 bash 默认拒绝不一样:默认拒绝是‘已知危险,主动挡’;抛错是‘未知状态,不敢猜’。”

把整个审批分支画成决策图:

一个 tool call 进入审批分支(agent.ts)

  approval = await beforeToolCall?.(call)
      │
      ├─ hook 抛错 ─────────────► "tool approval failed" 记入 session
      │                            throw error ──► 整轮停(既不放行也不拒绝)
      ├─ 未装 hook ── ?? {approved:true} ──► 放行,直接执行
      ├─ approved=false ─────────► 记 tool error(approval.reason)
      │                            continue ──► 下一个 call
      └─ approved=true ──────────► tool.execute(input, signal)
                                    ├─ 正常 ──► 记 result,下一个 call
                                    └─ 抛错 ──► "tool execution failed"
                                                  throw error ──► 整轮停

小A:“它到底能挡住什么?”

“这里的‘默认拒绝’只针对名称为 bash 的调用。denyBashByDefault 对 read 和 write 返回允许:read 可以读取工作区内任意可按 UTF-8 解码的文件,其 tool result 会进入后续模型上下文;write 可以覆盖工作区内文件,且没有逐次人工确认。”老Z说,“当前没有针对 .env、密钥文件或其他敏感路径的 allowlist/denylist,也没有内容分级和脱敏。路径位于工作区,只说明路径检查通过,推不出数据可以外发,也推不出写入安全。”

工具仍要自校验路径 ​

小A:“路径检查呢?它不是一直守着的吗?”

“它守着,但守的是它该守的那一段。”老Z打开 tools.ts:

ts
const rootReal = await realpath(root);
const requested = resolve(rootReal, candidate);
const checkedReal = await realpath(checked);
if (!isInside(rootReal, checkedReal)) throw new Error("path escapes workspace");

“read 与 write 都先经此路径;正常路径允许工作区内文件和新建父目录,符号链接逃逸返回 error result。测试覆盖了已存在目标的 symlink 逃逸。”老Z说,“注释已声明它不能消除 TOCTOU:检查之后到 writeFile 之前,攻击者仍可能替换路径。路径校验更不能限制 bash 的网络、子进程、环境变量或 shell 解释。”

小A:“realpath 加 isInside,这套检查的逻辑是什么?”

“解析到真实路径再比。”老Z说,“realpath 把符号链接展开成真实位置:工作区里 escape 指向 /tmp/outside,realpath('escape/secret') 解析出来就是 /tmp/outside/secret。isInside 用 relative() 算相对路径,以 .. 开头就说明在工作区外,拒绝。测试 rejects symlink escapes(见 agent.test.ts)构造的就是这个场景。write 多一个分支:新建文件时目标还不存在,realpath 会失败,所以先用 nearestExistingAncestor 检查最近的已存在祖先目录(见 tools.ts),检查的是父目录,不是目标本身。”

“TOCTOU 到底怎么攻?”小A追问。

“检查和写入之间留了窗口。”老Z说,“workspacePath 检查完返回路径,writeFile 才真正写。这中间攻击者把工作区内的普通文件换成指向外面的 symlink,写入就跟着 symlink 跑出去。这是‘先检查后操作’的通病,缓解要 OS 级原子操作(如 openat + O_NOFOLLOW),超出应用层范围。所以注释诚实写了 cannot eliminate TOCTOU。”

整个检查流程画出来:

workspacePath(root, candidate, creating)   (tools.ts)

  rootReal = realpath(root)            ── 工作区真实路径,展开一次
  requested = resolve(rootReal, candidate)
      │
      ├─ creating ── lstat(requested) ── 已存在? ──否──► nearestExistingAncestor
      │                                  (目标不存在时     (向上找最近已存在祖先,
      │                                    realpath 会失败)   检查它而非目标本身)
      ▼
  checkedReal = realpath(checked)      ── 把符号链接展开成真实位置
      │
      ├─ isInside(rootReal, checkedReal) ──否──► throw "path escapes workspace"
      │                                            → 工具 catch 后转 error result
      └─ 是 ──► return requested(放行,返回原始请求路径)

小A:“为什么用 relative() 算,不用 startsWith 比前缀?”

“前缀比较有个坑:相似前缀会误放行。”老Z说,“工作区是 /tmp/work,恶意路径 /tmp/work-other/secret.txt 确实以 /tmp/work 开头,但它在工作区外。startsWith 会放行,relative() 不会:relative('/tmp/work', '/tmp/work-other/secret.txt') 得到 ../work-other/secret.txt,以 .. 开头,判定逃逸。测试 reads a workspace file and rejects an absolute similar-prefix directory(见 session-tools-cli.test.ts)构造的就是这个场景:root 叫 work,旁边放一个 work-other,读里面的 secret.txt 必须被拒。这里用相对路径而不用前缀比较,是因为‘工作区内’的语义是相对位置在根下,不是字符串以根开头。”

小A:“symlink 逃逸为什么测试两次,一次 read 一次 write?”

“因为两个工具的目标状态不一样。”老Z说,“read 的目标已存在,realpath 直接解析到 /tmp/outside/secret,拒;write 的目标可能不存在,测试里 write-link 是个已存在的 symlink、指向外面,creating 分支走 lstat 发现已存在,直接 realpath 解析,同样拒(见 agent.test.ts 的 reads, truncates, writes nested paths, and rejects symlink escapes)。read 和 write 复用同一个 workspacePath,差的只是 creating 参数。”

本章其余小节为付费内容

登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。