依赖版本一变，安全规则就失效？用 Security Cards 给编码 Agent 建立“按版本取证”的审查流程
让编码 Agent 做安全审查，最常见的失败不是它完全不知道安全常识，而是它把泛化建议套到了错误的依赖版本上。比如项目已经锁定某个框架的小版本，Agent 却引用了另一代 API 的配置方式；又或者它只给出“注意输入校验”之类的结论，既无法追溯依据，也无法让开发者据此修改和复验。
Security Cards 提供了一个更窄但更可操作的路径：把安全指导组织成与语言、库、版本和安全类别关联的卡片。它不是扫描器，也不替代人工安全评审；它解决的是编码与审查时“该用哪一份规则、这份规则是否适用于当前依赖”的取证问题。项目以 Apache-2.0 开源，仓库提供可安装给编码 Agent 使用的 securitycards skill。
这篇文章不把它当成一个“自动找漏洞”的黑盒，而是演示如何把它接进一个可审计的改动流程：先锁定事实，再选择精确规则，最后把规则与验证结果一起留在 PR 中。
为什么“版本”是安全审查的第一道门
开发团队常把依赖版本当作构建层面的细节：锁文件能让安装可复现，升级时跑一遍测试即可。但安全规则经常与版本绑定。框架的默认行为、弃用 API、配置字段、转义策略和中间件顺序都可能变化；一条针对旧版的建议即使理念正确，复制到新版本中也可能无效，甚至让读者误以为自己已经完成了防护。
传统的通用提示词还有三个问题：
- 适用范围不清楚。 Agent 可能根据印象引用某个库的最佳实践，却没有确认项目实际解析到的版本。
- 结论不可复核。 “存在潜在注入风险”并不告诉审阅者具体对照了什么规则，也不便于在下一次修改时重新检查。
- 缺少不确定性处理。 当规则库没有覆盖当前版本时，许多自动化流程会悄悄退回到相近版本的建议，产生貌似专业的错误确定性。
Security Cards 的说明刻意规定了相反的行为：skill 读取项目的 manifest 和 lockfile，寻找匹配的库与版本；如果目录中没有该精确版本的卡片，就停止，而不是静默借用另一个版本的规则。这个“宁可没有结论，也不要伪造适配”原则，特别适合放在 Agent 的改动前检查里。
先安装，再把技能限定为审查证据源
该项目提供的安装方式如下。-g 表示全局安装；如果只希望当前仓库使用，可以去掉这个参数。
npx skills add Reware-Labs/securitycards --skill securitycards -g
安装并不等于让 Agent 自动拥有正确结论。建议在项目的协作说明中明确它的职责边界：Security Cards 用于检索有版本依据的安全指导；代码是否满足规则，仍要由 Agent 结合仓库源码、测试和人工审阅做判断。
一个适合放进 Agent 任务描述的约束可以是：先读取 lockfile，确认涉及的库和解析版本；只使用目录中与该版本完全匹配的卡片；每个安全结论都链接回所用卡片；如果没有精确版本覆盖，明确输出“未覆盖”，不要替代为近似版本。这样可以避免把工具变成又一个只会输出泛化 checklist 的入口。
从锁文件到卡片：一条可复现的取证链
官方的 Agent 使用指南把流程拆得很清楚，落到工程实践里可以整理为四步。
1. 先识别真实依赖，而不是相信口头描述
先查看项目的 manifest 与 lockfile。原因很简单：package.json、pyproject.toml 或其他清单写的是意图，锁文件记录的才是当前解析结果。一个 PR 也可能通过间接依赖引入了需要关注的库。
这一步的产出最好是一张极小的清单：库名、精确版本、改动涉及的文件和场景。例如“本次修改接触到认证回调，实际安装的库版本为 X”，而不是笼统写“项目使用某框架”。不要手工猜版本，也不要从博客文章里抄一个看似接近的版本号。
2. 在公开目录中寻找精确版本
Security Cards 的在线目录提供了面向 Agent 的入口：llms.txt 是总索引，按语言分组的目录再列出库、版本、类别和卡片地址。对特定任务，应沿着“语言 → 库 → 精确版本 → 类别”逐层缩小，而不是一次性抓取整个大目录后让模型自行联想。
类别选择也应当由改动面驱动。新建服务可以从该库的 Security Blueprint 开始；处理上传、认证、反序列化或外部请求时，则优先找与这次变更最贴近的类别卡片。这样审查重点来自真实代码路径，而不是从一长串通用安全名词里随机挑选。
3. 把卡片转成可检查的改动项
拿到卡片后，不要让 Agent 原样复述。应把其中的 secure rules 转换成当前 PR 可验证的断言：对应哪个文件、预期代码形态是什么、用什么测试或静态检查证明。
例如，若一张卡片的规则要求某类输入在进入敏感 API 前经过特定处理，审查产物应该落到“在调用点前建立校验/编码边界，并新增一个覆盖恶意输入的测试”，而不是只在评论中写“已注意安全”。如果一条规则与当前改动无关，也应记录“已查阅但不适用”的理由，避免下次审查重复讨论。
4. 在 PR 中保留规则、改动与验证的连接
最终 PR 描述至少应包含三样东西：实际依赖版本、使用的卡片链接、验证方式与结果。卡片不是替你背书的标签，而是让其他人能重新执行推理过程的证据。
可以使用这样的结构：
安全审查记录 - 依赖：<库名> <锁文件解析出的精确版本> - 依据：- 改动：<对应文件与实现边界> - 验证：<测试、检查命令及结果> - 未覆盖项：<没有精确版本卡片时的说明>
这段记录的价值在于可维护性。当依赖升级或代码路径变化时，下一位开发者能立即知道哪些假设必须重新确认，而不是把上一次的“已审查”当成永久结论。
让 Agent 在“不支持”时停下来
自动化安全流程最危险的输出之一是过度自信。Security Cards 的文档明确建议：如果当前版本不在目录中，应解释未支持的原因，并展示可用版本，而不是借用不同版本的指导。这个分支不要被当作失败；它是触发人工安全决策、补充测试或等待规则覆盖的信号。
在团队流程中，可以把它分为两类处理。对低风险、局部改动，记录未覆盖原因并按已有安全基线继续；对认证、权限、文件处理、支付或外部副作用等高风险改动，则把“无精确版本卡片”设为需要人工安全复核的条件。重点不是强迫所有 PR 都被同一工具放行，而是让缺少依据的地方显式可见。
还要避免把卡片当成运行时防护。它没有替代依赖更新、SAST、动态测试、权限隔离、密钥管理或独立安全评估的能力。它的最佳位置是编码 Agent 与代码审阅之间的知识层：为“为什么这样实现”提供可追溯、按版本收敛的参考。
适合从哪里开始
如果团队刚引入编码 Agent，不必一开始就要求每一次提交都走完整卡片流程。可以先选择一个高频且边界清晰的场景，例如新增 HTTP 接口、处理文件上传，或修改认证相关逻辑：让 Agent 读取锁文件、检索精确版本卡片、在 PR 中附上规则链接与测试结果。跑过几轮后，再把稳定的记录模板固化为仓库规范。
Security Cards 的关键贡献不是“多一套安全建议”，而是把建议的版本前提和来源暴露出来。对依赖迭代很快、又越来越依赖 Agent 写代码的团队而言，这种可追溯性比一份看起来无所不包的提示词更实用：规则知道自己适用于什么，Agent 也知道什么时候应该停止猜测。