AI编码代理安全审计技能包设计：从SKILL.md到CI集成的完整实践

每次代码评审最怕的不是看不懂代码而是看到一处“好像有问题”的逻辑又拿不准它到底能不能被利用。更麻烦的是如今 AI 编码工具一天能生成几千行代码提交频率越来越高安全团队根本不可能逐条 commit 去审。我做过一段时间安全工程师之后最大的感受是安全审计不是找 bug而是找“可被利用的路径”。一条路径往往横跨好几个文件涉及数据流、权限边界和框架行为靠人肉翻代码效率太低靠传统扫描器又容易淹没在误报里。这就是我最近在折腾security-audit-skill的原因。简单说它是一个面向 AI 编码代理的安全审计技能包把安全审计这件事做成代理可以反复调用的专业流程让 Claude Code、Codex、OpenCode 这类工具在开发过程中就能介入代码审查。它不是一段提示词也不是某个插件而是真正意义上的 agent skill包含入口定义、审计规则、风险分级、修复建议模板和验证流程。这篇文章会把设计思路、文件结构、接入方式和实测结果都拆开讲适合正在用 AI 编程工具、又对代码安全有要求的团队参考。1. 安全审计为什么逐渐开始“技能化”1.1 skill 和提示词、插件、agent 的边界先把概念理清楚。很多人问过我和“skill 和 agent 的区别”类似的问题因为这几个词在 AI 工具生态里确实容易混。提示词是一次性输入你问了就结束了没有固定流程插件是外部工具集成比如接一个扫描器、接一个数据库它本身没有判断逻辑agent 是能自主拆解任务、调用工具、做决策的完整系统而 skill 介于提示词和 agent 之间它是一种“可复用的专业操作手册”代理在合适的时候把它加载进来按里面定义的流程执行。security-audit-skill走的就是 skill 这个定位它不自己跑一个扫描器也不替代安全工程师做最终决策而是告诉代理“安全审计应该按什么步骤做、看哪些文件、怎么判断风险、怎么输出报告”。这让整个审计过程可预期、可复制不会因为换了模型、换了工具就变成瞎聊。1.2 传统安全审计流程的痛点我经历过典型的传统审计流程开发提交 MR - 安全工程师人工 review - 发现问题 - 打回去修改 - 重新 review。这个过程有几个结构性矛盾。第一安全工程师数量永远不够。一个安全团队往往同时对接十几个业务线的代码根本审不过来最后只能抽样。第二人工审代码的速度和 AI 辅助编程的速度差距越来越大。以前一个开发一天写几百行现在 AI 编码代理一小时就能产出几百行安全侧全靠堆人力显然不现实。第三传统 SAST 工具误报率很高每次扫描出来几百条问题其中大部分是“理论上有点风险但实际利用链根本走不通”。安全工程师花大量时间做误报筛选真正有价值的漏洞反而被淹没。1.3 审计技能能直接解决的问题把安全审计做成 skill 之后我实际感受到的变化是审计这件事从“安全团队的后置关卡”变成了“开发过程中的伴随行为”。开发者在把代码交给安全团队之前就可以让代理按统一标准先审一遍把低质量的问题直接挡在提交前。具体能解决四类问题代码评审会上的争论。过去评审会上经常为“这段逻辑算不算漏洞”吵半天技能里有明确的风险定义和证据链要求代理会把完整的进入点、数据流、影响面列出来争议自然变少。漏洞修复不彻底。很多安全问题被人为修了一半比如解决了 SQL 注入却忘了同文件里的另一条拼接语句。技能会要求代理在修复后重新追踪数据流确保同类问题被系统性清理。新人审计经验不足。刚转岗的安全工程师容易只盯着 OWASP Top 10 的常见套路遇到业务逻辑漏洞就抓瞎。技能里沉淀的规则和案例可以弥补这部分经验断层。安全工程师跟不上需求迭代。有了技能兜底安全团队可以把精力集中在真正复杂的架构风险上不用每天陷入重复性的“查注入、查越权、查硬编码密钥”里。2. security-audit-skill 的完整设计文件结构、SKILL.md 和规则库2.1 技能包完整目录我这里给出一个经过多次调整后的目录结构可以直接照搬security-audit-skill/ ├── SKILL.md ├── rules/ │ ├── injection.md │ ├── authz.md │ ├── secrets.md │ ├── dependencies.md │ ├── xss.md │ ├── file-upload.md │ └── business-logic.md ├── data/ │ ├── cwe-mappings.json │ ├── risky-patterns.yaml │ └── severity-levels.yaml ├── scripts/ │ ├── scan_dependencies.py │ └── format_report.py └── templates/ ├── audit_report.md └── remediation_pr.mdSKILL.md是入口文件代理最先读它rules/目录放每种漏洞的检测规则和修复指引data/目录放结构化数据比如 CWE 编号、风险等级、依赖黑名单scripts/存放辅助脚本templates/是输出报告和修复 PR 的模板。把辅助数据单独抽出来是刻意为之为了让规则文件保持人类可读性而不是把一堆 JSON 塞进 Markdown 里。2.2 SKILL.md 的元数据与执行逻辑工具生态目前对技能目录的约定各不相同但SKILL.md这个命名在 Claude Code、OpenCode 等几个主流工具里基本形成了事实标准。文件顶部是 YAML 元数据正文是执行的详细指令--- name: security-audit description: 对指定代码路径执行安全审计识别注入、越权、敏感信息泄露等风险 输出包含证据链和修复建议的报告。当用户要求“检查安全性”“审计代码” “review 安全”“看下有没有漏洞”时使用。 ---元数据里的description要写清楚触发条件和适用场景因为代理就是靠它来判断“什么时候该用这个技能”。正文部分我会分成几个固定步骤确认审计范围。让用户明确是只审一个文件、一个目录还是整个 MR 的变更内容。收集上下文。要求代理先读取目标文件的 imports、路由注册、数据库模型、用户权限模型建立基本的数据流。按风险优先级逐项检查。输出结构化报告。报告必须包含漏洞名称、风险等级、CWE 编号、证据链、影响范围、修复方案。生成修复建议或直接起草修复补丁。这套流程的价值在于它把“安全审计”从一个开放性任务变成了有边界的执行协议。2.3 规则库怎么分层为什么不能写成一堆清单我最开始犯过的一个错误是把所有漏洞特征写进同一个 document越写越长代理执行起来反而混乱。后来改成按“检测 - 验证 - 决策 - 修复”四层来组织。检测层定义必须关注的安全风险类型。对每种风险列出触发模式但刻意不给完整结论。比如injection.md里写关注所有字符串拼接进入数据库查询、命令行执行、模板渲染、文件路径的场景。这些场景要结合项目实际使用的框架来分析。验证层是最关键的。规则明确要求代理不能因为看到类似 SQL 拼接就报告漏洞必须先追踪输入来源确认用户可控输入是否真的能流到危险函数。这条规则直接把大量误报挡在了入口处。决策层把漏洞按风险等级分成严重、高危、中危、低危四个档位每档对应不同的处理动作后面会详细讲。修复层给出通用修复模式和具体代码示例比如参数化查询、白名单校验、最小权限、内容安全策略等。规则里还要求代理在给出修复建议时说明原代码为什么存在风险以及修复后的代码如何切断了利用链。2.4 辅助数据让规则不再靠感觉纯 Markdown 规则有一个问题不同代理判断时可能给出不一致的结果因为“严重”“高危”这类词缺乏硬性边界。所以我在data/目录里放了结构化数据让规则在判断时能参照统一标准。cwe-mappings.json用来把安全风险映射到 CWE 编号方便跟企业内部漏洞管理系统对接。severity-levels.yaml定义了每个等级对应的危害程度和处置时限severity: critical: score: 9.0-10.0 description: 可被远程利用无需特殊条件即可造成数据泄露或系统接管 action: 阻止合并立即修复 high: score: 7.0-8.9 description: 利用条件有限制但实际环境中大概率可利用 action: 本次迭代必须修复 medium: score: 4.0-6.9 description: 有理论风险或需要内部权限配合 action: 记录并安排修复 low: score: 0.1-3.9 description: 违反安全规范但实际利用难度高 action: 记录持续跟踪risky-patterns.yaml则是长期维护的黑名单我经常往里加“高危依赖版本”“已知弱加密算法”“危险函数名”这类机器可读的记录。有了这套数据代理在判断时就能给出相对一致的结论。3. 编写审计技能时的关键技巧上下文确认、风险分级和处理误报3.1 让代理先理解上下文再动笔刚开始做技能的时候我发现代理很容易犯一个毛病拿到一个文件就开始找问题完全不看这个文件在项目里的位置。这会导致两种后果一是把正常的旧代码当成漏洞报出来二是因为不了解业务模型漏掉真正的越权和业务逻辑漏洞。所以我在 SKILL.md 里强行加了一步“上下文收集”并且规定了必须收集哪些内容。审计前必须先弄清楚三个问题这个模块处理什么业务数据谁调用它以及数据从哪里来。我让代理先画出一条从入口到出口的数据流再开始逐段检查。这一步虽然会增加单次审计的时间但报告质量明显提升。3.2 基于风险的决策矩阵规则可以有很多条但代理在不同风险条件下该做什么动作必须唯一明确。风险决策矩阵是我用过最可靠的方式它避免代理在“看到可疑点时应该继续深挖还是直接报告”之间反复纠结。风险等级证据条件代理动作严重已验证完整数据流外部输入到达敏感操作且无需特权立刻中断当前任务生成高优先级报告并直接给出修复补丁高危存在明确危险模式但数据流链路缺一环在报告中标注“疑似高危”请求用户补充上下文或允许代理进一步追踪中危违反安全最佳实践但当前场景下利用路径不明确写入报告标记为“建议改进”不强制阻塞流程低危代码风格层面涉及的安全问题如注释泄露信息汇总到报告末尾作为长期维护建议这个矩阵还解决了一个经常被忽略的问题代理不会被一个“疑似漏洞”困住。以前用普通提示词做审计时代理经常对某个可疑点无限深挖导致整个任务跑偏。现在矩阵规定如果链路缺一环要么向用户确认要么标记为疑似并继续其他检查项不允许卡死。3.3 误报处理报告必须包含证据链安全领域的误报问题本质上是“判断依据不透明”的问题。代理只说“这里存在 SQL 注入风险”开发者没法快速确认只能自己再查一遍那这个技能就完全没有意义。因此我在规则里强制要求任何风险条目都必须包含五个要素缺少任意一个都视为无效报告。进入点用户输入或外部数据从哪里进来对应的路由、参数、文件位置。数据流输入经过哪些函数、变量、文件最终到了哪里。具体位置触发点的文件路径和行号。影响面这个漏洞可能造成什么实际危害。修复建议具体的代码改动方向最好能给出示例。这个要求直接把误报率压下去了大半。很多情况下代理在写证据链的过程中就会发现所谓的“漏洞”根本走不通它就会自动降级或撤回结论。3.4 审计任务的终止条件写技能时容易被忽略的一个问题是什么时候该停止审计如果不设边界代理可能会把整个项目翻一遍耗时又耗 token产出却不聚焦。我设置的终止条件有三个第一用户指定的范围已经完成审计第二运行时间或上下文预算超出正常范围这时候要求用户确认是否继续第三遇到需要人工决策的业务逻辑技能只负责标记问题并说明原因不强行给出最终结论。让技能学会“停下来”和“向上汇报”它才能真正在真实开发流程里长期用下去。4. 在 Claude Code、Codex、OpenCode 中的接入实操4.1 Claude Code安装与验证步骤Claude Code 的 Agent Skills 原生支持技能目录接入最简单。全局安装和项目级安装选一个就行。# 全局安装所有项目都可用 mkdir -p ~/.claude/skills/security-audit cp -r ./security-audit-skill/* ~/.claude/skills/security-audit/ # 项目级安装只对当前仓库生效 # 把 security-audit-skill 复制到项目的 .claude/skills/security-audit/验证是否安装成功在项目根目录直接启动 Claude Code然后输入用 security-audit 技能审查 src/auth/login.ts如果代理正确读取了 SKILL.md并且按照元数据里定义的步骤执行说明接入成功。第一次接入时我踩过一个坑目录名和 SKILL.md 里的name不一致导致代理有时候识别不到这个技能。建议目录名和name字段保持完全一致可以减少很多不必要的排查时间。4.2 Codex 的配置差异Codex 对技能目录的约定没有其他工具那么统一。官方更常见的方式是通过AGENTS.md文件注入项目级指令而不是直接读取 SKILL.md。我试过两种方案。第一种是把审计规则精简后写进AGENTS.md。这个方案适合规则量不大的团队直接把关键原则、检查清单、输出格式写进去Codex 每次运行时都会自动加载。缺点是AGENTS.md如果太长会影响所有对话的效率。第二种是用命令行传入上下文。在调用 Codex 执行任务时直接把技能的核心指令作为参数带进去codex exec --full-auto 按照 docs/security/audit-guide.md 中的步骤 审查 src/user/profile.ts 的安全性输出包含证据链的报告这种方式最灵活技能文件放在文档仓库里独立维护要用的时候动态指定。缺点是每次都要手动把关少了自动触发那一层。4.3 OpenCode 上的变通方案OpenCode 的技能支持也在快速演进。当前比较稳定的做法是把技能目录放到.opencode/skills/security-audit/下或者配置在全局的~/.config/opencode/skills/里。它同样通过 SKILL.md 来识别技能。如果某个版本对技能目录支持不完善退而求其次的方案是把 SKILL.md 的核心内容转换成自定义 prompt 或 agent 配置文件在使用时手动加载。这个变通方案的缺点是失去了“代理自动判断何时调用技能”的能力但对于团队内部统一审计规范来说已经够用。4.4 和 CI 流水线的串联技能的最终价值不只是“开发者主动调用”还有机会融入 CI在 MR 提交时自动触发审计。我后来做了一件很简单但有成效的事写了一个脚本在 CI 的 MR 检查步骤里调用 Codex 执行技能定义好的审计流程然后把报告输出为 Markdown 评论。实际串联链路大致是MR 创建或更新 - CI 触发 - 提取变更文件列表 - 调用代理执行审计 - 输出 markdown 评论到 MR 页面。这样一来每个 MR 都会自动收到一份安全审计意见不需要任何人在评审前去手动跑一遍。注意给代理设置合理的超时时间和最大输出长度否则碰到大改动的 MR 容易超时。5. 实测记录技能能发现哪些问题又漏了哪些5.1 一个可复现的测试样例我拿了一个故意埋了漏洞的 Node.js 项目做回归测试。比如这样一个典型的登录接口const sql SELECT * FROM users WHERE username ${req.body.username} AND password ${md5(req.body.password)}; db.query(sql, (err, rows) { if (rows.length 0) { req.session.user rows[0]; res.json({ ok: true }); } });技能输出的审计结论里有几处我比较满意。它找出了进入点是req.body.username追踪到了db.query判定为 SQL 注入并给出了参数化查询的修复代码。它同时指出了md5密码哈希方式不符合现代安全实践。这些都不意外厉害的地方在于它能结合整个上下文说明问题之间的关联同一个接口既存在 SQL 注入又存在弱哈希攻击者一旦注入成功拿到的还是 MD5 哈希安全性大幅下降。5.2 实战中发现的高价值问题真正让我觉得值得继续投入的不是能发现教材级别的 SQL 注入而是能找出那些静态扫描器经常漏掉的问题。举一个典型的越权例子接口长这样router.get(/order/:id, async (req, res) { const order await db.findOne({ id: req.params.id }); res.json(order); });人的眼睛一眼看过来可能觉得就是普通查询。技能在审计时会把路由定义和权限校验逻辑放在一起看它发现order查询没有验证req.session.user.id是否与订单的 owner 一致于是报了一个高危 IDOR 越权漏洞。这属于业务逻辑层的问题SAST 工具很难靠规则匹配发现但对代理却很合适因为它能同时理解“路由”“会话”“数据库查询”三层逻辑。还有一个场景让我印象很深。一个微服务里用child_process.exec执行外部命令拼接了文件名参数。代理追踪后发现文件名由用户上传决定而且没有做路径过滤最终判定为命令注入。我过去手动审这种问题通常要花不少时间因为要翻好几个文件确认输入是否真的可控。代理把这些跨文件的调用链串起来之后整个证据链变得非常清晰。5.3 依然存在的局限它不是人类审计员把技能吹得再好它也有明显的天花板这个必须说实话。首先它容易败在高度复杂的业务逻辑里。比如涉及多步状态流转、多个参与者协作的支付逻辑代理很难靠静态分析发现“某些步骤可以跳过”这种深层的业务漏洞。其次它对底层框架行为的理解是间接的。如果项目在一个极其冷门或者文档不全的框架上代理常常会做出错误假设产生新的误报。这类情况下技能最好的定位是“辅助人脑”帮安全工程师快速排出可疑范围而不是给出最终权威结论。我在规则里也明确写了遇到复杂业务技能只负责把相关代码路径整理出来标注“此区域存在复杂逻辑需要人工深度审计”而不是硬凑一个结论。这种边界感是我在做这个技能过程中最有价值的设计决策。6. 团队推广和“技能持续进化”的实战建议6.1 从个人技能变成团队共有资产如果只有我一个人在本地用这个技能价值有限。把它变成团队资产首先要做的是统一存放位置。建议单独建一个security-audit-skill仓库里面除了技能文件本身还要有一份README.md说明技能是什么、怎么安装、怎么贡献新的审计规则。团队里的每个人 clone 一次之后只要把技能目录软链接到自己的 Claude Code 或 OpenCode 配置目录就能保持同步更新。6.2 版本管理与规则入库标准技能和普通代码一样需要版本管理。我建议每次更新规则库都走明确的版本记录用CHANGELOG.md记录每次变更的理由、影响范围和验证结果。新增规则尤其要谨慎一条不成熟的规则如果进了技能包代理会在每次审计时反复用不靠谱的判断去“骚扰”开发者团队很快就会怀疑整个技能的价值。我摸索出一套简单的入库标准新规则必须来自一个已经确认的真实问题有完整证据链不接受纯理论模型。必须在测试样本库上跑通既检测出目标问题又不产生额外误报。必须附带修复示例代理不是只报问题还要告诉开发者怎么修。6.3 让技能变成团队的“安全记忆库”运行一段时间之后我发现这个技能最大的价值反而是它演化出的规则库。团队每次发现一个新的真实漏洞就往rules/里加一条对应的证据链和修复方案。半年积累下来这个技能包实际上成了团队的安全记忆库新人入职后不用从头看几十篇安全文档直接让代理带着技能去审计代码就能复现团队积累的安全判断经验。这个过程没有终点技能的价值会随着每次真实攻防、每次漏洞复盘逐渐积累。对我来说这就是把security-audit-skill继续维护下去最大的驱动力。