Skip to content

DSH 插件(二):在工具执行前拦下危险操作 ​

Agent 跑得越顺,越容易出现这样的时刻:你让它清理构建产物,它拼出一条 rm -rf,路径里少了一个变量。命令执行完你才看到删了什么。

tool-guard 想做的事很直接:在每次工具执行前拦一道。但它不能是一个“弹窗确认器”——每条命令都问,人会关掉它;只做黑名单,又挡不住换一种写法的同一条命令。

这篇讲它的规则怎么排、路径怎么算、失败时站哪一边,以及一个把测试拖住 120 秒的计时器 bug。

一、它挂在哪个位置 ​

DSH 的工具调度器在真正执行前会发出 tools/pre-execute,这是原生 waterfall:插件可以返回 allow、deny 或 ask。ask 会被调度器映射成审批请求。

ts
ctx.on('tools/pre-execute', async (exec, next) => {
  try {
    const result = runGuardEngine({ /* 会话、工具名、入参、规则 */ })
    if (result.decision === 'reject') {
      return { kind: 'deny', reason: result.reason }
    }
    if (result.decision === 'approve') {
      return await requestApproval(exec, result)
    }
    return next()
  } catch (error) {
    return { kind: 'deny', reason: `安全守卫异常,已拒绝执行: ${message}` }
  }
})

注意 catch 里的选择:守卫自己出错时返回 deny,不是 next()。这就是“失败关闭”。它会让守卫的 bug 变成误杀,但另一种选择是——守卫挂了,所有命令照常执行,而且没人知道。

为什么不每条命令都问

高频确认会让人形成“看到就点允许”的肌肉记忆,等于没有守卫。规则引擎先把明显危险的直接拒绝,只把“有风险但可能合理”的操作交给审批,审批才有意义。

二、五条规则,顺序不能换 ​

规则按固定顺序执行,命中即返回:

顺序规则作用对象结果
1危险命令黑名单shell直接拒绝
2敏感文件黑名单读类工具直接拒绝
3路径白名单读 / 写 / 编辑 / 删除直接拒绝
4写入保护写 / 编辑 / 删除审批或放行
5严格模式所有 shell审批

顺序的关键在第 2 条和第 3 条:敏感文件必须在白名单之前判断。否则用户把整个盘加进白名单,.env 也会被一起放行。白名单是“允许在哪里操作”,敏感文件是“无论在哪都不能读”,后者优先级更高。

还有一个容易被忽略的分支:宽松级别只跑第 1 条就返回。这是有意的——宽松模式下文件操作全放行,但仍要挡住极危险命令。

三、路径:resolve 不够,必须 realpath ​

路径白名单最容易被绕过的写法不是 ../../,而是符号链接:项目里一个指向 C:\Users 的软链,resolve 之后仍然在白名单目录下。

ts
export function resolveRealPath(rawPath: string, cwd?: string): string {
  const resolved = path.resolve(cwd ?? process.cwd(), rawPath)
  if (existsSync(resolved)) return realpathSync.native(resolved)

  // 目标还不存在:对最近的已存在祖先做 realpath,再把剩余部分拼回去
  let existing = resolved
  const tail: string[] = []
  while (!existsSync(existing)) {
    const parent = path.dirname(existing)
    if (parent === existing) break
    tail.unshift(path.basename(existing))
    existing = parent
  }
  return path.join(realpathSync.native(existing), ...tail)
}

“目标不存在”这段是必需的:写文件时目标通常还不存在,如果只对存在的路径做 realpath,攻击者可以用一个软链父目录加一个不存在的文件名逃逸。

白名单比较本身也有细节:用 path.sep 做目录边界,C:/project 不能匹配 C:/project-other。字符串 startsWith 不加分隔符,就会把相邻目录当成子目录。

四、审批:优先用宿主的,别自己造一套 ​

命中 approve 后,最省事的做法是插件自己弹一个 Web 卡片。但 DSH 已经有 approval 服务,Web GUI 的审批卡、超时、取消都接好了。插件应该先走原生通道:

ts
const approvalService = ctx.get?.('approval')
if (approvalService && exec.agent) {
  const outcome = await approvalService.request({ /* 风险说明 */ })
  if (outcome === 'allowed-once') return allow()
  return { kind: 'deny', reason: '用户拒绝或审批不可用' }
}
// 没有 approval 服务时,才退回内置 ApprovalManager

四种返回值都要有明确归宿:allowed-once 放行,rejected 拒绝,cancelled 拒绝,unavailable 也拒绝。最后一种最容易写错——审批服务不可用时如果放行,等于守卫在最需要它的时候失效。

内置回退路径还有一个聊天兜底:用户在对话里回“允许”“拒绝”,插件用正则匹配最近一条待审批项。中文没有单词边界,\b 在这里不生效,所以正则写成 ^(允许|同意|放行|批准|可以)(?:\s|$),而不是 \b允许\b。

五、那个拖住测试 120 秒的计时器 ​

内置审批默认 120 秒超时。最初的实现是 setTimeout 和决策 promise 做 Promise.race,逻辑看起来没问题,但 npm test 全绿之后进程不退出,每次都要等满 120 秒。

原因有两层:

  1. 审批挂起时进程不能退出,所以计时器不能 unref();
  2. 但用户先做了决策时,必须 clearTimeout(),否则已决审批仍然拖着一个 120 秒的计时器。
ts
decisionPromise.then((result) => {
  if (timeoutTimer) clearTimeout(timeoutTimer) // 关键:决策先到就释放计时器
  return toOutcome(result)
})

这类 bug 不会让断言失败,只会让 CI 变慢。如果不是某次本地跑测试时去倒了杯水,可能很久都发现不了。

六、审计:能记,但不能把秘密记进去 ​

每次决策都会写审计:会话、轮次、工具名、脱敏后的入参、决策、命中规则、原因。入参在落盘前递归脱敏,字段名大小写不敏感,api_key、apiKey、API_KEY 都会替换成 [REDACTED],数组和嵌套对象也会走到。

审计的价值不是“事后追责”,而是调规则:哪条规则误杀最多、哪个目录被反复拒绝,看一周记录就知道该放宽还是收紧。

七、代价与边界 ​

这套规则是字符串和路径匹配,不是 shell 解析器。它挡不住 python -c "..." 里动态拼出来的删除,也挡不住把命令写进脚本再执行。它能做的是提高“手滑”和“明显越界”的成本,不是对抗刻意绕过。

另外,严格模式下所有 shell 都要审批,长任务会被打断很多次。默认级别放在中间,是这个原因。

踩坑:规则名和事件名以代码为准

PRD 里写的是 tool:before,真实事件是 tools/pre-execute;PRD 里的决策叫 reject,调度器要的是 deny。这类命名差异不会在文档评审时暴露,只会在联调时以“插件没生效”的形式出现。写插件前先对照宿主源码,别照抄 PRD。

下一篇换一个位置:不再拦截单次调用,而是旁路整条事件流——把 Agent 的每一步实时转发出去,并在会话结束后导出一份能读的复盘报告。

本文阅读--次|全站访问--次|访客--人