文章

给 Agent 的上下文加一道闸门:pi-key-protector

给 Agent 的上下文加一道闸门:pi-key-protector

前言

用 Agent 写代码久了,会习惯一个很容易被忽略的事实:工具打印出来的任何东西,都会成为对话的一部分。它被写进会话记录,交给模型提供商,并且常常在之后的每一轮对话里被反复发送。

于是当工具执行 env、cat .env、docker inspect,或者一条带着 token 的 curl 时,里面的凭证就跟着一起走了。而 agent 完全不知道自己刚刚泄露了什么:

1
2
3
$ env | grep -Ei 'key|token|password'
OPENAI_API_KEY=sk-proj-...
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE

这条结果会原封不动地进入 transcript,然后被发往模型提供商的服务器——这已经越过了”本机”这条信任边界。

权限插件管不到的地方

Pi 本身不包含权限系统:拦住危险命令的是第三方扩展 pi-permission-system(@gotgenes/pi-permission-system),它在命令执行前按 allow/ask/deny 策略做门控,这是”事前”的防线。但 echo $OPENAI_API_KEY 本身一点都不危险,危险的是它的输出。而且大多数泄露并不是人类主动要求打印的:

  • npm run build 报错时,把 .npmrc 的内容连同 registry 认证信息一起打进了日志;
  • agent 为了排查连接问题,顺手 kubectl get secret -o yaml;
  • agent 想看看端口配置,cat .env 之后又把整个文件贴进了总结里。

这些都属于”正常运行”的范畴,权限插件不该拦,拦了也没法用。所以需要另一道防线:在工具结果返回模型的途中,把凭证片段遮掉。

拦截 env 反而会挡掉安全做法

想把凭证泄露彻底堵死,最直接的想法是把所有”碰环境变量”的命令都拦掉:env、printenv、printenv *KEY*、cat .env*。问题是,其中相当一部分正是安全实践本身——它们的共同特征是:密钥只在管道、重定向或子进程环境里流动,从未出现在工具结果里,也就从未进入会话。

1
2
3
4
5
6
7
8
9
10
11
12
# 1. 把 key 写进另一个程序自己的配置:重定向后 stdout 是空的
printf '%s\n' "$OPENAI_API_KEY" > ~/.config/mytool/api_key

# 2. 用标准输入把 token 交给 CLI,不经过命令行参数,也不上屏幕
printf '%s' "$GH_TOKEN" | gh auth login --with-token
docker login -u "$USER" --password-stdin < ~/.config/docker/token

# 3. 只给子进程注入变量,工具仅回报成功或失败
env OPENAI_API_KEY="$OPENAI_API_KEY" ./mytool --self-check

# 4. 只取状态码,key 留在请求头里
curl -s -o /dev/null -w '%{http_code}\n' -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/models

这四条命令的工具结果里没有任何凭证字符:第一条输出为空,第二条只打印登录成功,第三条是 ok,第四条是 200。它们恰恰是最该被鼓励的写法——比”让 agent 把 key 读进上下文再拼进命令”安全得多。

而一旦把这类命令拦掉,用户通常只有两条路:整体关掉门控,或者绕回来把 key 贴进对话、放进一个模型会读的文件。后者才是真正把凭证送进 transcript 的动作——过度拦截会把密钥推回它本想避开的那条路。

所以判据是”结果里有没有密钥字符”,而不是”命令里有没有 env“。这也正是本项目的第二条设计目标:误报的代价不只是烦人,它会诱导出更不安全的替代做法。

这就是 pi-key-protector 做的事情。

三条设计目标

按优先级排列:

  1. 日常失误不能漏。 echo $API_KEY、env、cat .env 这类最常见的操作必须百分百命中。
  2. 误报必须接近零。 工具结果里绝大部分内容不是秘密:源码、构建日志、哈希、时间戳、数字表格。一旦开始涂改普通文本,agent 就没法正常工作,用户也会立刻关掉这个功能。
  3. 要快。 每一条工具结果都要付这个成本,它就压在 agent 循环的关键路径上。

这三条互相矛盾,整个项目的技术选择基本都是在它们之间找平衡。

什么算凭证

凭证有三个来源,会话启动时读取一次,只存在于内存中:

一、变量名像凭证载体。 名字匹配 (KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL)(大小写不敏感),且值通过一个形状过滤:至少 8 个字符、不含空白、不像路径、不是 true/production/localhost 这类常见配置字面量,也不是 aaaaaaaaaa 这种低多样性字符串。

这个过滤器看着琐碎,作用却很大:没有它,SOMETHING_SECRET=production 会让 production 这个词在全文范围内被涂掉。

二、值命中已知格式。 不管变量叫什么都保护。目前覆盖 OpenAI(sk-、sk-proj-)、Anthropic(sk-ant-)、OpenRouter、AWS access key(AKIA…)、GitHub(ghp_…、github_pat_…)、GitLab、npm、PyPI、Slack、Google API key、Stripe、Hugging Face、JWT、PEM 私钥头,以及 scheme://user:password@host 形式的连接串。命中格式的值跳过上面那层形状过滤。

三、项目里的 dotenv 文件。 .env 及其变体(.env.local、.env.production……)在启动时读取。这一条是后来补上的:没有它,cat .env 交给模型的是一个从未出现在进程环境里的值,再好的匹配算法也保护不了它没见过的字符串。

dotenv 的发现过程是有界的——从会话目录开始,向下最多 3 层,跳过隐藏目录和 node_modules/dist/vendor 之类的构建目录,不跟随符号链接,最多读 50 个文件,超过 256 KB 就放弃。因为这段逻辑跑在启动路径上,而且读的是用户没有主动指向的文件。

其余的 PATH、HOME、LANG 之类一律忽略。

匹配:一次扫描找出所有片段

这是整个项目最核心的问题。给定:

  • 一个不大的凭证集合 S(几十个,每个通常 20–200 字符);
  • 任意长度的文本 T(从几百字节到几 MB 的构建日志)。

找出 T 中每一段”暴露了足够多某个 s ∈ S“的区域,同时保持其余部分逐字节不变。

最直接的实现是 for each secret: indexOf(secret)。它同时失败在三条目标上:

  • 只能抓住完整的连续出现。sk-123 456 这种被空格打断的、只泄露了前缀的、只泄露了后缀的,全都漏掉;
  • 每条结果都要重新搜索一遍;
  • 复杂度 O(|S| · |T|)。

那 Aho–Corasick 呢?它在线性时间内找出模式集合的精确出现,能完美解决”整把 key 被打印”的情形。但它不做部分匹配:一个 39 字符的 key 里那 13 个字符的前缀,不构成任何模式的匹配。常规的补丁是把每个凭证的所有前缀和后缀都塞进模式集,模式数量立刻膨胀到 O(Σ|s|²)——而且仍然会漏掉内部片段(比如 key 中间的 api03-abcdefghij),以及被分隔符打断后才出现的片段。

所以这里用的是后缀自动机:用凭证集合建一个自动机,它恰好接受这些字符串的全部子串,状态数 O(Σ|s|)。让 T 从中走过,对每个位置 i 就能得到”以 i 结尾、且在某个凭证中出现过的最长子串长度” best[i],均摊 O(1) 每字符。

这一个数组回答了策略需要的所有问题:有哪些片段、每个多长、在文本的哪里、以及归因之后它在凭证内部的哪个位置。

每条工具结果的成本是 O(|S| + |T|) 时间和 O(|S|) 内存,外加一个长度为 |T| 的 Int32Array。自动机只在凭证集合变化时(会话启动或 /key-protector reload)构建一次,不是每条结果都建。

遮蔽:保留多少才不至于白遮

全部遮掉最安全,但也最没用:读 transcript 的人再也分不清到底是哪把 key 出了问题。

折中方案是有界且结构化的保留。以 ANTHROPIC_API_KEY=sk-ant-api03-abcdefghijklmnopqrstuvwxyz 为例:

模型本会收到模型实际收到
sk-ant-api03-abcdefghijklmnopqrstuvwxyzsk-ant-api**************************xyz
sk-ant-api03-abcdefgh(前缀泄露)sk-ant-api***********
ghijklmnopqrstuvwxyz(后缀泄露)*****************xyz
api03-abcdefghijklmn(从实质部分开始)api*****************
ant-api03-abcdefghijklmn(从公开前缀中间开始)ant-api*****************
sk -ant -api03 -abcdefghijklmnopqrstuvwxyz(被空格打断)sk -ant -api** ************************xyz

有几个规则值得说明。

公开前缀免费。 sk-ant- 不是秘密,它写在 Anthropic 的文档里,每个客户都一样。把 13 个可保留字符中的 6 个花在它身上是浪费,所以已知格式的值免费保留前缀,只在实质部分的两端各保留 3 个字符。只靠变量名识别的凭证(SERVICE_PASSWORD=hunter2-S3cr3t-Pa55w0rd)没有这种结构,就保留更宽的 6 + 3——那里的开头字符是唯一能告诉运维”是哪一条”的线索。

保留窗口属于凭证,不属于匹配。 这一点是后来才想明白的。窗口在凭证坐标系里定义:头部窗口截止到 公开前缀长度 + 3,尾部窗口从 凭证长度 - 3 开始。匹配只能拿到它与窗口的交集。这样所有形态的泄露行为都一致:完整值显示 sk-ant-api,从实质部分开始的泄露显示 api,从公开前缀中间开始的泄露显示它自己那段 ant-api。窗口之外的字符永远不会被凭空造出来。

至少遮 4 个字符。 这是一个下限,保证短凭证永远不会因为”预算裁剪”而被完整暴露。裁剪顺序是先尾后头,因为前缀对人类的提示价值更高。

遮罩保持长度和格式:空白、引号、标点原样保留,只有凭证字符变成 *。

两道通知

除了遮文字,结果末尾还会追加通知,因为模型必须知道自己看到的不是原始输出,否则它可能基于被改过的内容做出错误判断。

  • 发生了遮蔽 → 告诉模型这段输出已被改过、涉及哪几个变量名(值永不出现在通知里)、替换规则是什么;
  • 单条结果内某个凭证的暴露比例 ≥ 90% → 升级为安全警告。这里的覆盖率是”所有匹配在凭证内的偏移并集 ÷ 凭证长度”,所以一条输出里的两半能累加成 100%。并集不跨结果,通知可以升级而遮蔽策略仍然无状态。

刻意不防御的东西

项目文档里专列了一节,因为把边界讲清楚比宣称”什么都防”更有用。

跨结果的逐字符泄露。 一个模型如果每条工具结果只打印一个字符,就能一个字符一个字符地把凭证走出来,全程没有任何匹配——每条结果都远低于阈值。要抓它需要跨结果状态。这个方案设计过,也被否决了:

  • 它无法区分”恶意地一点点挤”和”一份恰好跨几百条结果提到了凭证碎片的普通长日志”(比如 grep 一个常见子串、构建日志回显片段)。一旦账本说”这把 key 已经出去 40%”,正常文本就开始消失,而用户没有任何办法解释为什么;
  • 它用一条清晰的保证(”没有任何一条结果暴露 ≥ 10 个连续凭证字符”)去换一条模糊的保证(”最终、也许、如果模型是恶意的”),而模糊的那条恰好会制造这个项目最想避免的误报;
  • 它要防的是有针对性的外泄攻击,那属于权限插件的门控策略问题,以及”凭证已越界就轮换”的问题。

其他刻意留白:大小写和编码变体(SK-PROJ-…、base64、hex dump)不做归一化;图片块和结构化的 details 字段不处理;! 开头的 shell 命令不保护——Pi 交给扩展的是命令本身而不是它的输出,要覆盖它就得重写命令执行,而且还会把你屏幕上正在读的东西一起遮掉。让 agent 去执行命令就行了,那条路走工具结果,会被遮蔽。

还有一条必须说清楚:已经发出去的值就是发出去了。遮蔽发生在工具结果返回的路上,扩展加载之前打印的内容已经在 transcript 里了。如果一把 key 完整地出现过,正确的处理是轮换它,而不是指望事后补救。

安装与使用

1
pi install git:github.com/Davidasx/pi-key-protector

没有构建步骤,没有运行时依赖——Pi 直接加载 TypeScript。

验证是否生效:

1
2
3
/key-protector status     # 加载了哪些凭证、当前策略、本次会话统计
/key-protector scan sk-ant-api03-abcdefghijklmnopqrstuvwxyz
/key-protector reload     # 在 Pi 的环境里 export 了新 key 之后

scan 是纯演练:它显示会被怎么遮,不碰任何模型上下文。也是最快的自检方式——如果你在意某个值到底算不算凭证,用它试一下就知道。

想临时关掉可以用 pi --no-key-protector。配置写在 ~/.pi/agent/key-protector.json,项目里还可以放 <project>/.pi/key-protector.json(只在受信任的项目中读取)。数组取并集、标量覆盖,所以项目配置能加凭证,但不能悄悄取消保护你自己的凭证。

结语

这个工具解决的问题很具体:让”不小心打印了凭证”变成一次可见的、被处理过的事件,而不是一次静默的越界。它不试图当一个对抗恶意模型的沙箱——那需要完全不同的假设和代价。

实现上比较有意思的部分是那个后缀自动机:原本以为 indexOf 加几个特判就够了,真正把”前缀泄露、后缀泄露、内部片段、被空格打断”四种情况列出来之后,才发现需要的是”所有子串的匹配”这个能力,而它恰好有一个线性时间的标准解法。

代码和完整的算法文档都在 Davidasx/pi-key-protector。docs/ALGORITHM.md 记录了每个阈值的来历和被否决的替代方案——包括上面那些”刻意不做”的分析,如果你要改动策略,建议先读它。

本文由作者按照 CC BY 4.0 进行授权