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 行,精读过)
语义骨架其实很小,大的是规则库:
- 引擎
ToolGuardEngine.guard(tool_name, params)→ 返回 findings 列表,空 = 安全。 - 三模式 × 严重度阈值决定拦不拦:
| 模式 | 拦截的严重度 | 语义 |
|---|---|---|
block |
CRITICAL / HIGH | 硬拦,工具不执行 |
require_approval |
+ MEDIUM | 暂停,等人裁决 |
warn |
无 | 亮黄牌但放行 |
- 规则是 YAML 里的正则签名表(
dangerous_shell_commands.yaml,约 300 行):rm/mv、mkfs/dd 写裸设备、 fork 炸弹、curl|bash、反弹 shell、Unicode 空白、/proc/*/environ、jqsystem()、zsh 危险内建…… 每条带 severity、remediation、exclude_patterns(比如注释行不报警)。 - 审批用
langgraph.types.interrupt:图整个暂停,人批准后从断点继续。
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)
Severity五级:CRITICAL / HIGH / MEDIUM / LOW / INFO。Rule:限定Tools与Params,用Patterns找危险特征,Excludes放过误报。DefaultRules从 harness 的危险命令表里提炼 10 条(安全知识与语言无关,直接借):规则 ID 严重度 抓什么 TOOL_CMD_DANGEROUS_RMHIGH rm/del/Remove-Item(排除注释行)TOOL_CMD_DANGEROUS_MVHIGH mv(意外移动/覆盖)TOOL_CMD_FS_DESTRUCTIONCRITICAL mkfs*、mke2fs、dd of=/dev/*、> /dev/sd*TOOL_CMD_DOS_FORK_BOMBCRITICAL fork 炸弹、 kill -9 -1/1TOOL_CMD_PIPE_TO_SHELLCRITICAL curl/wget ... | bash/sh/zsh/...TOOL_CMD_REVERSE_SHELLCRITICAL /dev/tcp/、nc -e、ncat -e、socat EXEC:TOOL_CMD_UNICODE_WHITESPACEHIGH 非 ASCII 空白(解析歧义绕过) TOOL_CMD_PROC_ENVIRONHIGH /proc/{self,数字}/environ(泄露环境变量)TOOL_CMD_JQ_SYSTEMHIGH jq ... system((把数据处理变成命令通道)TOOL_CMD_SUDOMEDIUM sudo/doas模式 → 可拦级别是一张表(
blocking):block拦 CRITICAL+HIGH,require_approval连 MEDIUM 也拦,warn一张空表(永不拦)。Engine.Configure(mode)支持运行时热切换(REPL 里/mode ...)。Engine.Guard(tool, params)只扫规则声明的参数(命令守卫看bash/execute的command), 命中片段截前后各 40 字给人判读;ShouldBlock按当前模式判断该不该拦。写坏的规则直接
regexp.MustCompile在启动时炸掉,不留到运行期。
3.2 文件守卫:路径三态裁决(guard/filesystem.go)
文件工具按读/写分类:
ls/read_file/glob/grep是读,write_file/edit_file/delete是写。裁决顺序(先命中先返回):
用户规则(
Options.Rules),支持allow显式放行;默认规则(
defaultFsRules):路径 操作 处置 **/.env、**/.env.*、**/.git/**、**/.ssh/**、**/id_rsa*读 + 写 deny(密钥/凭据/版本库内部) /etc/**、/private/etc/**、/System/**、/usr/**、/bin/**、/sbin/**写 deny(系统目录没有合法写理由) 工作区内 →
allow;区外 →
Options.OutsideWorkspace(留空默认ask,摆成deny即回到"一律拒"的旧行为)。
路径先做
filepath.Abs+Clean,再取 realpath 作为第二个候选项(符号链接/etc→/private/etc那类坑)。glob 匹配自己写了 30 行
globToRegExp:**/→(?:.*/)?、**→.*、*→[^/]*,~展开成$HOME; 模式以/**结尾时,目录本身也算命中(/etc/**命中/etc)。关键取舍:能问的不拒,该拒的不问。全用 ask 会把审批弹窗变成噪音,人就会无脑点 y; 全用 deny 会逼 agent 绕道(自己去 bash 里
cat),反而丧失可观测性。
3.3 PII:出口打码(guard/pii.go)
- 7 条正则,顺序与 harness 的检测器一致:
sk-proj-、sk-ant-、sk-、AKIA/ASIA、AIza、hf_、 以及api_key=... / secret_key=... / access_token=...赋值形式。 Go 正则没有负向前瞻,sk-那条靠"起点已被更具体的规则占住"来避开sk-proj-/sk-ant-。 maskToken保留头尾各 4 位、中间打星;MaskSecrets去重区间后从后往前替换,幂等(再跑一遍结果不变)。- 两个挂载点:
BeforeModelRewriteState:把历史消息里的密钥打码后再喂模型。这里是就地改 state, 而state.Messages与事件流、调用方的 history 共享指针,所以改写会写穿回 REPL 历史—— 当前语义下正是想要的(历史同样脱敏);若哪天要"只对模型脱敏、历史留原文",得先浅拷贝消息再改。WrapInvokableToolCall:工具输出打码后再交回给模型(cat .env这类绕道读到的 key 也挡一下)。
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,不调工具
细节:
savedCall.Kind(tool_guard/fs_guard)用来分辨嵌套守卫里这次中断归谁,ownInterrupt靠它认领。ApprovalInfo与savedCall都用schema.RegisterName[类型]("tako_*")注册了名字——checkpoint 走 gob, 类型名要稳定。- resume 值用
"approve"/"reject"字符串,不用布尔(falsy 的 resume 在 LangGraph 侧会炸, Eino 侧同样避免这种退化写法)。 - 硬拒为什么返回 string 而不是 error:抛 error 模型只看到"tool execution failed",不知道为什么错, 容易傻重试;返回"用户拒绝了这次调用,不要重试相同命令,如需类似操作先和用户商量替代方案", 模型就能改道或收手。当前这次工具调用从未发生,但整个思考循环没有中断。
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 上游还有两个我们暂时没抄的设计点,记在这里备用:
- 策略与审批解耦:fs 守卫只做纯策略判定,interrupt 规则由映射函数转成 HITL 配置,审批逻辑不污染守卫。
- 批量工具的锚定:
ls/glob/grep的中断按"搜索子树是否与规则锚定前缀重叠"触发; 全通配(/**/secrets)会收敛到/,保守过度触发。我们目前只有单路径工具,还没这个问题, 以后加批量工具必须补。
5. 中间件模式在 agent 场景的真实代价
中间件不止放 guard:官方自带的还有上下文中和(compaction)、重试、限流、能力增强等十几种。 和 Gin 的中间件类比很准,但有个关键差异:Gin 包的是一次请求-响应(几百毫秒、进栈出栈); agent 中间件包的是一个多轮循环——一次用户输入可能触发 N 轮"模型→工具→模型",每个钩子每轮都触发, 消息历史在循环里持续累积。HTTP 请求不会"聊着聊着上下文爆了",agent 会;HTTP handler 不会 "失败了自己决定重试",模型调用会抖。所以需要照顾的方面天然多,"杂"是场景决定的。
杂有真实的代价,三条:
- 顺序变成语义。PII 脱敏放在压缩前还是后,结果不同;Handlers 数组的顺序就是包裹顺序。 本层三个守卫顺序无关是运气好(互相独立),不是普遍规律。
- 隐式交互。两个中间件各自单测都过,组合起来可能互相干扰——例如重试把审批又触发一遍, 人要看两次弹窗。
- 调试变难。行为分散在 N 个中间件里,出问题要沿链条逐个排查。
应对办法不是"少放",是约定 + 可见性:
- 顺序约定:安全类最前、压缩类靠后;本仓库固定
[taskboard] + guard 三件套。 - 可见性:拒绝/审批的理由都拼成人读的文本(
formatFindings最多列 5 条命中, 含 severity、snippet、remediation),既能回给模型,也能直接打印给人看。 - 保持互相独立:判断逻辑抽纯函数(
Decide不碰interrupt和工具),把"组合爆炸"的基数压小。
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 的工作区边界—— 并主动声明不这么做。两点结论:
- 逐工具的守卫 ≠ 沙箱。bash 能读任意路径,文件守卫只管文件工具。Codex 的
workspace-write是 seatbelt/landlock 在系统调用层兜底,agent 无论从哪个工具发起都逃不掉;我们的守卫只在工具调用边界生效, 属于"可观测、可协商"的软约束。harness 的解法是纵深防御:文件守卫拦路径、命令守卫拦/proc/environ这类高危路径、更上层还有沙箱 backend。守卫分层,每层都有自己看得见和看不见的东西。 - 把拦截原因写清楚,模型会配合。ToolMessage 里带拒绝理由("超出工作区"),模型不仅理解了, 还内化了策略意图;模糊的错误只会让模型乱试。
副产物:ask 态把"区外访问"升格成了用户可见事件。以前 agent 用 bash 绕道读系统文件,我们永远不知道; 现在只要它走文件工具,就会弹出来问一句。软约束的收益不在拦截率,在于让越界行为变得可见。
8. 与 harness 的差距(有意留下的)
- 规则只有 10 条代表性规则;harness 有 ~25 条 + YAML 热加载 + 用户自定义
rules_dir。 补齐是体力活,随时可做;当前换来了"规则即代码、可单测"的确定性。 - 审批是 REPL 的 y/n;harness 是
HITLRequest结构(action_requests / review_configs),为 Web 审批 UI 预留。 等"多入口统一路由"那一层再对齐。 - harness 的 guardian 接口支持插件化(规则 guardian 之外还能接 LLM guardian),我们只留了
Rules数组注入。 - 没有系统调用层沙箱(Codex 有 seatbelt/landlock)。要真堵 bash 绕道,得等沙箱能力落地, 或者把 bash 本身纳入"参数级路径解析"——后者不可靠,不划算。
9. 与其他层的关系
- 入口:三件套挂在唯一入口的
Handlers链上,与任务看板 middleware 并列(见《01》§5、《02》Task 6)。 - 下一层:任务看板(见《07》)——看板让任务变长,长任务的上下文膨胀问题随后就到, 那才是上下文管理(《05》§4 能力路线第 4 项)的入场时机。