tako 文档 GitHub

06 · 工具安全层

性质:能力记录。新系列第六篇,改写自旧《04-L1-工具安全层》:机制分析(三态裁决、规则引擎、 审批回路、守卫分层)与踩坑记录保留,删掉 TS 时代残留的对照句,入口统一改成 cmd/yktako (旧演示入口 cmd/l1guard 已由《02》Task 7 删除),行号锚点与文件清单按当前代码重写。 参照对象:harness-agent 的 security/tool_guard/ 与 middleware/{tool_guard,filesystem_guard,pii}.py。

0. 这一层解决什么

主循环回答了"agent 怎么用工具",这一层回答一个更现实的问题:agent 有了手(bash、文件读写)之后,怎么防止它闯祸?

落点(全在 yk-tako-eino/internal/):

guard/toolguard.go     命令守卫:危险命令规则表 + 模式 × 严重度阈值 + 命中判定
guard/filesystem.go    文件守卫:路径规则、工作区内外的三态裁决(纯函数 Decide)
guard/pii.go           出口脱敏:API Key 打码(幂等)
guard/middleware.go    挂载点:三个 ADK middleware + interrupt 载荷 + resume 判定
tools/                 被守卫的对象:bash、read_file / write_file(故意不防护)

装配方式(cmd/yktako):Handlers = [taskboard] + guard.Handlers(engine, guard.Options{WorkspaceRoot: cwd})。

1. 三件套各管一件事

用户输入 ──→ [PII 脱敏] ──→ 模型 ──→ 决定调工具
                                    │
        ┌───────────────────────────┤
        ▼                           ▼
[ToolGuard 查命令参数]      [FilesystemGuard 查文件路径]
        │                           │
  放行/拒绝/审批                放行/拒绝/问人
        └──────────→ 工具执行 ←──────┘
                      │
            [PII 脱敏工具结果] ──→ 回到模型

两个守卫都是三态:allow 直接放行、deny 把解释性 string 当结果挡回给模型(不抛 error)、 ask 用 compose.StatefulInterrupt 暂停整张图等人裁决,人回答后 Runner.ResumeWithParams 接着跑。

2. 从 harness 读到了什么

2.1 tool_guard(约 620 行,精读过)

语义骨架其实很小,大的是规则库:

模式 拦截的严重度 语义
block CRITICAL / HIGH 硬拦,工具不执行
require_approval + MEDIUM 暂停,等人裁决
warn 无 亮黄牌但放行

2.2 filesystem_guard

当 deepagents 自带的权限机制不可用时(sandbox backend),在工具调用边界补一层路径策略: 有序规则表先命中先生效,路径要展开 realpath(macOS /etc → /private/etc 的符号链接坑), /etc/** 这种模式也要匹配 /etc 本身。

重要:这层是 deny-only 的降级版。 deepagents 上游的 permissions 本来是三态(含 interrupt 审批), 但因为 shell backend 下会抛 NotImplementedError 被整个禁用;harness 只在工具边界补回了 deny 半边, interrupt 只剩一个抄来的注解(详见 §4)。

2.3 pii

它自己也不是从零写的:框架自带 PIIMiddleware 检测 email/信用卡/IP,但不认识 API Key。 harness 补了一个自定义检测器,专抓 sk-...、sk-ant-...、AKIA...、AIzaSy...、hf_... 和 api_key=... 赋值形式,配 mask 策略(留头尾、中间打星)。

3. 我们的实现

三件套语义与 harness 一致,挂载点换成 Eino 的 ADK middleware。判断逻辑全部抽成不依赖框架的纯函数, 可以脱离 agent 单测(Decide、Engine.Guard、MaskSecrets)。

3.1 命令守卫:规则引擎(guard/toolguard.go)

3.2 文件守卫:路径三态裁决(guard/filesystem.go)

3.3 PII:出口打码(guard/pii.go)

3.4 挂载点与审批回路(guard/middleware.go)

三个 handler 都是 adk.ChatModelAgentMiddleware 的实现(内嵌 adk.BaseChatModelAgentMiddleware 拿其余钩子的空实现,各自带 var _ adk.ChatModelAgentMiddleware = (*Type)(nil) 编译期断言):

handler 覆盖的钩子 干什么
toolGuardHandler WrapInvokableToolCall 命令规则命中 → 按模式放行 / 打断(拒绝 string)/ 审批
filesystemHandler WrapInvokableToolCall 路径三态 → 放行 / 拒绝 string / 审批
piiHandler BeforeModelRewriteState + WrapInvokableToolCall 入模型与出工具双向打码

Handlers() 返回的顺序就是包裹顺序:命令守卫在外 → 文件守卫居中 → PII 最贴工具。

审批回路(Eino 版,比 LangGraph 清爽):

中间件里 compose.StatefulInterrupt(ctx, 载荷, savedCall)   REPL 里:
   │ 图暂停,整个 runContext gob 进 CheckPointStore          adkrun.Run 收 Action.Interrupted
   │                                                        → 回调 ask(info) 打印工具与参数
   └────────── resume 值 "approve" / "reject" ◄──────────── runner.ResumeWithParams(targets)
        恢复后中间件用 ownInterrupt(ctx, kind) 认出"是自己那笔",
        读 compose.GetResumeContext[string] 拿到人的决定:
          批准 → endpoint(ctx, stored.Args, ...) 原样重放
          拒绝 → 返回解释性 string,不调工具

细节:

4. 溯源纠错:三态注解 + 两态实现

写这一层时曾误以为"harness 原版也有 ask 态",核源码(orcakit_harness_agent 1.0.14, deepagents 0.7.18 / GitHub main,两者一致)后更正:

harness 自研 fs guard deepagents 上游 我们
规则 mode 类型 Literal["allow","deny"] Literal["allow","deny","interrupt"] allow | deny | ask
interrupt 态实现 无。返回注解里有 "interrupt",是从 deepagents 私有函数抄来的签名;树里只有这一处,中间件无分支、无 interrupt 导入 完整:_fs_interrupt.py 把 interrupt 规则转成 HITL 配置(含 when 谓词),审批人有 4 个决策 interrupt() 内联在中间件里,审批只有批准/拒绝
死签名的后果 配置里写 mode: interrupt → 加载时被静默丢弃;程序内直接构造则 "interrupt" != "deny" → 放过(fail-open) —— ——
为什么 harness 这么弱 deepagents 在 backend 支持命令执行时直接抛 NotImplementedError,整套 permissions(含审批)被禁用;只好在工具边界重做一个只留 deny 的降级版 —— ——

这是个教训:一个三态的类型注解配一个两态的实现,比没有更危险——它给人「这里有审批」的错觉, 实际是静默丢弃或静默放行。读上游代码要顺注解一路查到 return,别信签名。

deepagents 上游还有两个我们暂时没抄的设计点,记在这里备用:

  1. 策略与审批解耦:fs 守卫只做纯策略判定,interrupt 规则由映射函数转成 HITL 配置,审批逻辑不污染守卫。
  2. 批量工具的锚定:ls/glob/grep 的中断按"搜索子树是否与规则锚定前缀重叠"触发; 全通配(/**/secrets)会收敛到 /,保守过度触发。我们目前只有单路径工具,还没这个问题, 以后加批量工具必须补。

5. 中间件模式在 agent 场景的真实代价

中间件不止放 guard:官方自带的还有上下文中和(compaction)、重试、限流、能力增强等十几种。 和 Gin 的中间件类比很准,但有个关键差异:Gin 包的是一次请求-响应(几百毫秒、进栈出栈); agent 中间件包的是一个多轮循环——一次用户输入可能触发 N 轮"模型→工具→模型",每个钩子每轮都触发, 消息历史在循环里持续累积。HTTP 请求不会"聊着聊着上下文爆了",agent 会;HTTP handler 不会 "失败了自己决定重试",模型调用会抖。所以需要照顾的方面天然多,"杂"是场景决定的。

杂有真实的代价,三条:

  1. 顺序变成语义。PII 脱敏放在压缩前还是后,结果不同;Handlers 数组的顺序就是包裹顺序。 本层三个守卫顺序无关是运气好(互相独立),不是普遍规律。
  2. 隐式交互。两个中间件各自单测都过,组合起来可能互相干扰——例如重试把审批又触发一遍, 人要看两次弹窗。
  3. 调试变难。行为分散在 N 个中间件里,出问题要沿链条逐个排查。

应对办法不是"少放",是约定 + 可见性:

6. 有意偏离 harness 的一处语义(exclude_patterns)

harness 原版:exclude_patterns 任何一条命中整段参数,整条规则放弃。副作用是 # 注释\nrm -rf / 这类"注释行 + 危险命令"的多行输入会绕过所有带注释排除的规则(漏报)。

我们的版本(textForRule):/^\s*#/ 这类注释行模式只剥掉注释行后继续扫剩余文本; 其它排除模式仍保持整段排除。单测覆盖了注释 + rm、纯注释、普通命令三个边界。

已知脆弱点:isCommentLineExclude 靠正则源码逐字符相等来识别"注释行模式", 改写法(如 /^ *#/)会静默退化为整段排除。规则表扩大时应改成规则上的显式开关(例如 StripCommentLines: true)。

7. 实测记录

(当时用 go run ./cmd/l1guard 实测;该演示入口已随《02》Task 7 的单入口收敛删除,行为现已并入 cmd/yktako。)

输入 结果
用 bash 执行 echo hello-l1 无命中,直接放行,输出 hello-l1
用 bash 执行 rm -rf /tmp/l1test 命中 TOOL_CMD_DANGEROUS_RM:HIGH → 图暂停 → 审批 UI → 输入 n → 工具不执行,模型收到"用户拒绝"并主动给出替代方案
用 read_file 读取 /etc/passwd 的第一行 区外 → 暂停问人 → 输入 y → 工具真的执行;模型随后自己说明"read_file 不支持只读前 N 行,要精确用 bash head"
用 read_file 读取 .env 规则级 deny,不弹窗,直接返回"敏感文件"拒绝理由
/mode block / /mode warn 热切换模式;warn 模式下命中只打印 ⚠️ 报告,不拦

单元测试(不打模型):internal/guard/guard_test.go 三个测试函数—— TestToolGuard(rm、curl | bash、注释行混淆、纯注释不误报、echo 放行、sudo 在 block 与 require_approval 下的差异)、TestFilesystemGuard(工作区内读放行、.env deny、/etc/passwd ask、 写 /etc/hosts deny、区外 OutsideWorkspace: deny)、TestMaskSecrets(sk- 打码、幂等、api_key= 赋值形式)。

7.1 一个值得记录的观察

被文件守卫拦下后,模型自己指出了防御缺口:bash cat /etc/passwd 可以绕过 read_file 的工作区边界—— 并主动声明不这么做。两点结论:

  1. 逐工具的守卫 ≠ 沙箱。bash 能读任意路径,文件守卫只管文件工具。Codex 的 workspace-write 是 seatbelt/landlock 在系统调用层兜底,agent 无论从哪个工具发起都逃不掉;我们的守卫只在工具调用边界生效, 属于"可观测、可协商"的软约束。harness 的解法是纵深防御:文件守卫拦路径、命令守卫拦 /proc/environ 这类高危路径、更上层还有沙箱 backend。守卫分层,每层都有自己看得见和看不见的东西。
  2. 把拦截原因写清楚,模型会配合。ToolMessage 里带拒绝理由("超出工作区"),模型不仅理解了, 还内化了策略意图;模糊的错误只会让模型乱试。

副产物:ask 态把"区外访问"升格成了用户可见事件。以前 agent 用 bash 绕道读系统文件,我们永远不知道; 现在只要它走文件工具,就会弹出来问一句。软约束的收益不在拦截率,在于让越界行为变得可见。

8. 与 harness 的差距(有意留下的)

9. 与其他层的关系