把AI Agent接进密码库前必读：keypaste威胁模型与信任边界全面拆解

keypaste 是一款 KeePass 兼容的密码与密钥管理工具，它把登录凭证和项目环境变量存在本地 KDBX 密码库中，并只在人类批准之后才把密钥交给 AI Agent。项目自带的 THREATS.md 文档把从"提示词注入"到"审计日志篡改"的 43 个攻击路径逐条拆解，是普通用户把 AI Agent 接进密码库前最值得通读的一份威胁模型。本文带你快速理解它的信任边界，并给出可落地的安全使用建议。

为什么必须先读威胁模型

让 AI Agent 直接读取.env文件是许多人的第一反应——密钥随即进入聊天记录的文本。而 keypaste 的思路相反：

• 🗝️密钥不出本地：一切存放在一个 KDBX 4 加密文件中，KeePassXC 可以打开同一个文件，没有账号、没有云服务；
• 🤝人在环上（Human in the loop）：Agent 每请求一个字段，都要经过你的 Deny / Allow once / Allow for 1 hour 决策，或你事先确认过的 Automatic 设置；
• 📜全程留痕：每次调用（无论批准还是拒绝）都会追加到哈希链审计日志中。

问题在于：Agent 读取的上下文（网页、代码、issue）可能是攻击者写给你的，也就是说模型本身就是不可信的一方。keypaste 官方文档对此的态度非常诚实——它在 THREATS.md 中逐条列出了"已缓解"和"仍然存在"的差距。理解这些差距，比任何营销文案都重要。

全景：一个桥、一个主人、一个人

keypaste 的 Agent 通道（keypaste mcp）由 MCP 客户端启动，它不持有密码库，只负责验证请求并把合格请求转发给"主人"——桌面应用或你自己在终端启动的keypaste approve。只有主人握着已解锁的库，并在回复前把每次请求写进自己的审计日志。

你的终端 你的 MCP 客户端 │ │ keypaste approve ◄─── 本地命名管道 ─── keypaste mcp • 持有已解锁的密码库 • 校验请求、拒绝越权 • 向你询问决策 • 只返回被批准的单个字段 • 写入审计日志 • 返回结果

这个架构有三个关键安全性质：

1. Agent 永远无法触发主密码输入框——密码只在你自己打开的终端里输入，杜绝了"另一个本地程序伪造密码框"的钓鱼路径；
2. 一个密码库只有一个主人：桌面应用与keypaste approve不能同时持有同一个库（T-29），杜绝两个快照、两条锁边界；
3. 锁 = 撤回：任何一次锁定都会撤走在途请求、清零所有授权。

审批流程长这样（真实演示动画，约 60 秒走完全程）：

注意提示里那句"That sentence was written by the agent, not by keypaste. Treat it as a claim."——Agent 给出的理由永远是"它的声明"，不是事实。

信任边界一览：谁可信，谁不可信

这是 THREATS.md 信任边界表 的简化版，是整个威胁模型的骨架：

一句话总结：模型说什么都不可信，程序名可以随便填，唯一可信的是你和加密库本身。

核心威胁拆解：7 个你必须知道的设计取舍

1️⃣ 提示词注入：条目名可以"看起来像指令"（T-1 / T-2）

任何有库写权限的人，都可以把ignore previous instructions…写进条目标题、组路径或自定义字段名——共享库、KeePassXC 里随手一编辑就够。keypaste 的缓解：

• 展示前统一做显示净化（EntryNameSanitizer）：控制字符、双向控制符、零宽字符、模板定界符全部替换成空格，ig<NUL>nore这类"拆分指令"无法拼回原样；
• 列表结果带 BEGIN/END 数据横幅，明确告诉模型"这是数据，不是指令"；
• 协议层限制单帧 64 KiB，装不下的整条丢弃并声明"不完整"，而不是静默截断。

但官方坦承一条无法缓解的残余风险：净化后的自然语言指令依然可读，模型可能照做。keypaste 自己从不执行条目文本——能否拿到密钥，仍然由曝光范围、Agent 设置和审批三关共同把关。

Agent 请求时附带的自由文本reason同理：限 2000 字符、展示截到 400 字符、去掉换行和双向控制符，且审批窗口布局完全固定——按钮位置、默认键、倒计时都无法被 reason 重绘，焦点永远落在 Deny 上。有专门的测试AReasonCannotRedrawThePrompt守着这一点。

2️⃣ 未认证客户端与"混淆代理"（T-3 / T-14）

MCP 客户端自己报上"我叫 claude-code"——没有任何认证。同一台机器上任何进程都能以这个名字启动桥接，甚至用另一个 Agent 的--client-label去继承它的设置。

这就是信任边界里最重要的一句话：Agent 的设置只约束"以该标签启动的桥接"，而标签是启动者自己选的。同用户进程的攻击在本模型中被明确划到范围外（见后文），Automatic 模式的真正价值是：把"每次按键确认"换成"人预先确认过的、有小时限额的、全程记录的"静默放行——并且每一次 Automatic 放行都以automatic身份记入日志，绝不冒充人工批准（T-16）。

3️⃣ 过度曝光：Agent 能看到什么（T-4）

条目名本身就泄露信息——它可能暴露你的银行、雇主和恢复账号。因此：

• 曝光默认收窄到tag:env:*：只看被打上项目标签的条目里"长得像环境变量"的字段，从不带出密码、用户名、URL 和备注；
• list_entry_names没有任何参数，Agent 无法自行扩大视野或翻页，它只能"请求人批准"；
• 标签选择器按项目成员关系匹配，畸形标签什么都够不到；env/dev下的../../prod/ROOT_TOKEN无法伪装成env/prod组的成员。

宽曝光 + Automatic 会静默放行其覆盖的一切——官方文档明确写着这二者组合的后果，把决策权留给你。

4️⃣ 审批疲劳：点"Yes"只为让它闭嘴（T-11）

恶意的重试客户端可以用凭证请求耗尽你的注意力。对策是一套组合拳：

• 并发请求立即返回BUSY，不排队；
• 拒绝后该字段冷却 60 秒，换连接、换名字、换变量数都无效；
• 45 秒不回答 = 拒绝；桥接挂断则请求直接撤回；
• 桌面端的"允许"按钮在窗口出现 1 秒后才生效，防止误点穿透到底层窗口；
• Automatic 可设每小时上限和截止时间，触顶后退回人工询问，而不是拒绝。

5️⃣ 授权缓存复用：为 A 目的批准的，被拿去干 B（T-12）

如果你选了 Allow for 1 hour，同一连接在 TTL 内再次请求同一条目同一字段时不再询问。官方立场很清醒：复用时不会比较两次理由的语义（这种启发式会被绕过，也能被用来逼你频繁弹窗）。能做的只有——授权按连接隔离、重启即失效、保护环境永不缓存、缩短--max-ttl即可压缩复用窗口。审计日志会记下每次复用的理由哈希，keypaste log能标出"理由变了"的记录。

6️⃣ 审计日志：唯一能证明"人参与过"的证据（T-5 / T-16）

~/.keypaste/audit.jsonl以追加模式打开，每条记录携带上一条的哈希（SHA-256 哈希链）。改一条，哈希断；删一条，下一条链断；插入外来记录同样断链。keypaste log verify按原始字节校验，AuditChainTests用真实文件覆盖了改、删、插、截断等全部路径。

但官方措辞是tamper-evident（篡改可证），不是 tamper-proof（防篡改）：链没有秘密密钥，删除链尾留下的文件内部依然自洽。所以--expect <hash>支持你把锚点哈希存到攻击者改不到的地方——这是唯一能发现尾部截断的办法，keypaste 自己从不替你存锚点。

日志写不进去时，行为是拒绝放行而不是跳过记录：没有审计行的访问不存在（T-6，PRODUCT 法律 3.3 / 3.7）。

7️⃣ 本地数据与"锁"的真实含义（T-18 / T-19 / T-20 / T-23）

• 🧠内存：主密码用可清零缓冲，派生密钥用完即擦；但 GC 会搬家、swap 会留痕、调试器随便看——官方直言不承诺内存机密性；
• 📋剪贴板：keypaste get复制的值 20 秒后自动清除（前提是没被改过），并在 Windows/macOS/KDE 上请求"机密"标记——但第三方管理器可以无视，崩溃和断电留不住它；
• 🔐锁屏：桌面端默认 5 分钟空闲锁定，锁定时销毁库、清空屏幕并清除已复制的密钥，Agent 请求绝不计为"活动"。锁保护的是无人值守的界面，擦不掉已读入内存的副本，也追不回已交付给客户端的值；
• 💾被盗的库文件：KDBX4 + Argon2 是你的全部防线，离线爆破没有任何限速和审计——主密码弱，什么都白搭。

它不保护什么：范围外的诚实声明

威胁模型最值钱的部分是"Out of scope"一节。keypaste 明确声明以下攻击不在防护范围内，理由而非沉默：

• 🕵️同用户进程：以你身份运行的进程能读内存、键入、剪贴板，并与管道对话——操作系统层面的失陷超出工具能力；
• 🤖模型行为本身：keypaste 管住自己的授权与审计路径，但管不住客户端拿到密钥之后把它写进 transcript、发给模型提供商；
• ☁️尚不存在的功能：云端同步库、团队项目——官方写明"在它们存在之前不做任何安全承诺"。

这份"拒绝承诺"的坦诚，正是它值得信任的原因。

安全使用建议：落地清单

结合 docs/safe-agents.md 与 docs/approvals.md，给普通用户 6 条建议：

1. prod 永不 Automatic：把生产环境打标签为受保护环境（如env:billing:prod）——受保护环境的集合每次都被真人询问，任何模式都无法静默放行；
2. 给 Automatic 加上限：--per-hour小时限额 + 截止时间，把静默放行变成"有预算的静默放行"；
3. 缩短缓存窗口：不想被授权复用消耗，就把--max-ttl调小（默认 1 小时）；
4. 隔离 Agent 的写权限：Agent 的 shell 以你的身份运行，它能改自己的 MCP 配置、换掉 PATH 里的keypaste。用 Claude Code / Codex / Cursor 的沙箱，把~/.keypaste、库文件和keypaste可执行文件都列为不可写，详见 safe-agents 指南；
5. 别让库躺在 Agent 的工作目录里：在哪个目录启动 Agent，它就能写哪个目录——永远从项目目录启动，把库和KEYPASTE_HOME放在外面；
6. 定期验链：keypaste log verify，并把锚点哈希用--expect记在别处。

如何验证这份信任

• 每条威胁项都标注了证据：对应的测试文件（如SecretHygieneTests用真实库、真实桥接和植入的哨兵值验证"只有被请求的字段离开"）与端到端脚本（如 scripts/verify-approval-e2e.sh）；
• 下载的二进制带 SHA-256 校验和与 Sigstore 构建证明（v0.3.0起），SECURITY.md 给出了完整的验证步骤与"校验和能证明什么、不能证明什么"；
• 漏洞走 SECURITY.md 中的私邮通道，72 小时内确认，协调披露最长 90 天。

总结

keypaste 的威胁模型可以浓缩成四句话：

• 模型不可信——它说什么都按数据/声明处理，净化展示，永不执行；
• 客户端未认证——名字随便填，授权只认你确认过的设置和你按下的 Deny/Allow；
• 人在环上是硬约束——没有审计记录就不放行，锁定即撤回，主密码框永远只出现在你自己的终端；
• 边界之外不撒谎——同用户进程、内存残留、模型后续行为，全部白纸黑字写在范围外。

把它当作"给 AI Agent 用的密码管家"来用之前，先读一遍 THREATS.md 原文——那 43 条威胁项里，每一条的"残余风险"都比它的"缓解措施"更值得记住。