基于Agent Skill构建代码安全审计自动化：从规则设计到落地实践

最近我在给团队用的AI编程助手调优时发现一个很有意思的现象大家越来越喜欢把零散的安全审计经验塞进 Agent 里让它帮我们自动过代码。于是就有了今天这篇博文的主角——security-audit-skill。这个名字听起来像个安全工具其实更准确地说它是一个专门用来做安全审计的 Agent Skill也就是一套可以被 Claude Code、Codex、OpenCode 这类 AI 助手直接加载的“技能包”。它的作用是让 AI 在项目代码里自动找安全隐患比如 SQL 注入、硬编码密码、危险函数、错误配置、依赖漏洞最后输出一份带风险等级和修复建议的报告。我自己在多个项目里实测下来这东西在代码自审、上线前检查、外包代码验收这几个场景里特别能顶事。这篇内容主要写给三类人一是手里捏着 AI 编程助手但不知道怎么让它干安全活的人二是安全工程师想用新的方式把重复性检查自动化三是对 Agent Skill 好奇想找一个具体落地案例来学习的开发者。下面我会从头拆解这个 skill 的完整设计思路、文件怎么写、规则怎么定再带你把一个真实项目跑一遍最后聊聊我踩过的坑和调优经验。1. 项目整体设计与思路拆解1.1 先搞清楚Agent Skill 到底是个什么东西在聊 security-audit-skill 之前得先把“Skill”这个概念说清楚。最近半年“skill”这个词在 AI Agent 圈子里特别热很多人在搜索“skill 是什么”“agent skill 和 agent 的区别”“skill 插件怎么装”。我自己的理解是Skill 是给 Agent 的一组结构化知识包里面包含详细的操作指令、判断规则、参考示例有时还附带可执行脚本。它就像一个“老师傅的作业手册”AI 看完这本手册就能在某个特定任务上表现得像干了很多年一样。普通 Prompt 和 Skill 的区别在哪里普通 Prompt 是每次临时对话里的提示词说得再详细换一个会话就没了全靠模型自由发挥。Skill 则可以持久化存放按需加载还能分享给团队使用。它把隐性经验变成了显性的、可版本化的文件这就是它最值钱的地方。那 Skill 和 Agent 的区别呢Agent 是一个能自主规划、调用工具、分步执行任务的完整系统Skill 更像 Agent 手里的一张技能卡Agent 决定什么时候出这张卡出卡之后按里面的说明书干活。所以你可以把 security-audit-skill 理解成一个藏了安全审计知识和检查脚本的工具包放到支持 Skill 的 Agent 环境里它就能驱动 Agent 去做审计。1.2 为什么安全审计特别适合做成 Skill安全审计这个场景其实特别适合沉淀成 Skill。原因有三个。第一个原因是知识密集且容易沉淀。安全审计需要记的东西非常多危险函数列表、漏洞触发模式、依赖漏洞清单、配置检查项。这些知识是相对稳定的不会每天变完全可以固化成规则文件。我最早是让 AI 直接“凭记忆”审计代码效果忽好忽坏遇到模型没见过的框架就漏报。后来把规则写进 Skill漏报率明显下降。第二个原因是过程重复。每次审计一摞代码干的都是差不多的事情先看项目结构再找配置文件扫敏感信息查依赖版本最后检查常见漏洞模式。把这个流程固定下来一次跑完比每次对话重新描述“请你先看这个文件再查那个配置”干脆多了。第三个原因是结果需要一致。人工审计最大的问题是不同人看同样的代码会给出不同结论。Skill 把所有检查标准和报告格式写死输出的结果就稳定得多团队成员看同一份报告沟通成本低很多。做个不恰当的比喻这就像你在后厨里放了一本标准菜谱没有菜谱今天这个师傅放两勺盐明天那个师傅放一勺半有了菜谱出品就稳定。1.3 能力边界它能做什么不能做什么我给自己写的 security-audit-skill 定了几个明确的目标和能力边界避免期望过高导致失望。它能做的事包括对指定目录下的后端、前端、脚本代码做静态安全扫描检查高频漏洞SQL 注入、XSS、路径穿越、命令注入、SSRF、不安全反序列化、硬编码密钥检查配置文件CORS 配置、TLS 配置、调试开关、默认口令检查依赖文件识别已知漏洞版本给出升级建议输出结构化报告风险等级、文件位置、问题原因、修复建议。但它做不到的事也必须讲清楚它不能替代真正的动态渗透测试不能证明系统“绝对安全”也不能覆盖所有业务逻辑漏洞。一个 Skill 再强也只是把已知的、模式化的安全问题找出来真正的安全负责人还是要靠人工复核关键模块。我还把适用场景整理过一张表方便直接对照适用场景推荐程度备注上线前代码自审强烈推荐能挡住大部分低级问题Code Review 辅助推荐人工主审AI 提供线索外包代码验收推荐用统一标准批量检查替换商业扫描器不推荐覆盖面和准确率有差距替代渗透测试绝对不行动态测试仍需专业人士2. 核心细节Skill 的文件结构与审计规则编写2.1 一个可用的 Skill 目录长什么样真正动手写 skill 之前我建议你先看一下自己用的 Agent 工具对 skill 目录结构的要求。不同工具的加载方式略有差异但大体逻辑一致一个文件夹里面放一个主说明文件再加规则、脚本、示例等子文件。我常用的结构是这样security-audit-skill/ ├── SKILL.md ├── rules/ │ ├── code-risk-rules.md │ ├── dependency-rules.md │ └── config-rules.md ├── scripts/ │ ├── quick_scan.py │ └── report_formatter.py ├── references/ │ └── owasp_top10_cheat_sheet.md └── examples/ ├── sample_report.md └── demo_vuln_app/这里每个文件都有自己的职责不能随意堆在一起。SKILL.md 是入口负责告诉 Agent“这个技能是干什么的、什么时候用、怎么用”。规则文件是核心承载了具体的检查标准。脚本负责做模型不擅长的事情比如批量解析依赖版本、调用系统命令扫描。参考资料里有 OWASP 等安全知识的精简版方便模型在不确定时查阅。示例目录放一个故意写了很多漏洞的样本项目一方面用来测试另一方面给模型做 few-shot 参考。2.2 SKILL.md 怎么写才不会让 Agent 误解编写 SKILL.md 是我踩坑最多的地方。最开始的版本写得太笼统Agent 经常看了不知道什么时候应该用这个技能。后来我调整成一个固定格式效果好了很多。我的 SKILL.md 大概包含这几块内容# Security Audit Skill ## Description 当用户要求对代码项目进行安全审计、漏洞扫描、代码安全检查、依赖风险排查时使用此技能。 ## Trigger Words - 安全审计 - 漏洞扫描 - 检查代码风险 - security audit - find vulnerabilities ## Usage Steps 1. 确认审计范围读取用户指定的项目路径如果没有指定默认当前工作区。 2. 分析项目结构识别语言、框架、关键配置文件和依赖文件。 3. 调用规则检查依次读取 rules/ 下的规则文件按规则扫描。 4. 执行脚本对依赖版本、敏感信息等使用 scripts/ 下的工具辅助扫描。 5. 生成报告按风险等级输出包含文件、行号、原因和修复建议。 ## Output Format - 先输出风险统计摘要高/中/低数量。 - 再按风险等级列出问题每个问题包含风险等级、文件路径、行号、问题描述、修复建议。 - 如果没有发现问题明确说明“未发现常见高风险问题”。 ## Constraints - 不要对业务可行性做评价只输出安全相关问题。 - 报告必须使用中文术语保留英文缩写。比较关键的是 Trigger Words 和 Usage Steps。前者决定 Agent 会不会主动想起这个技能后者决定它拿到技能后的执行顺序。我建议 trigger words 中英文都写上因为很多人会直接用英文描述。2.3 审计规则编写的三个核心原则规则文件是整个 skill 的灵魂。我写了三个版本才稳定下来核心原则可以概括为具体、去重、可验证。第一个原则是具体。不要写“检查 SQL 注入”而要写清楚“在 Python 代码中发现字符串拼接 SQL 语句且拼接内容来自变量或请求参数时判定为高风险”。同样不要只写“检查敏感信息”要列出哪些是敏感信息私钥、API Key、数据库密码、云服务凭证。模型就像新人你给它的标准越具体它执行得越准确。第二个原则是去重。一开始我把同一个漏洞类型散落到多个文件里导致审计时重复报告。后来我规定每个漏洞类型只能在一个规则文件中出现其他文件引用时只能写“详见 code-risk-rules.md”。这个规则节省了大量去重时间。第三个原则是可验证。每条规则都要配上最少一个危险示例和一个安全示例。这样模型不仅能靠文字判断还能通过对比模式识别。举一个我在 code-risk-rules.md 里写的片段### SQL 注入检测 - 风险等级高危 - 检测模式 - 使用字符串拼接构造 SQL 查询 - 查询语句包含用户可控变量或请求参数 - 危险示例 python cursor.execute(SELECT * FROM users WHERE id user_input)安全示例cursor.execute(SELECT * FROM users WHERE id %s, (user_input,))这样做还有一个额外好处更新规则的时候直接改示例就行不需要改动 SKILL.md 主文件。 ## 3. 实操过程把 security-audit-skill 真正跑起来 ### 3.1 环境准备与安装路径 实操之前先把环境搭好。我用的是 Codex CLI 的 skill 机制但思路可以平移到 Claude Code、OpenCode 等支持 skill 的代理上。 安装方式很简单把上面那个目录复制到 Agent 的 skills 存放路径下。以 Codex 为例一般放在 ~/.codex/skills/security-audit-skill。放好后重新打开会话Agent 就能识别到了。 为了验证是否加载成功我会先问一句 text 你知道 security-audit-skill 吗如果知道请简单说明它的用途。如果 Agent 能准确说出“用于对项目进行安全审计检查注入、敏感信息、依赖漏洞等”说明加载成功。如果它说不知道或者答得不对多半是 SKILL.md 的 description 写得太模糊需要回头改。3.2 典型案例审计一个 Node.js 服务我准备了一个故意写了很多漏洞的 Node.js Express 服务来做演示。项目不大但覆盖了最常见的几类问题。先看入口文件app.jsconst express require(express); const mysql require(mysql); const cors require(cors); const app express(); const connection mysql.createConnection({ host: localhost, user: root, password: 123456, database: demo }); app.use(cors({ origin: * })); app.use(express.json()); app.get(/user/:id, (req, res) { const sql SELECT * FROM users WHERE id req.params.id; connection.query(sql, (err, rows) { if (err) throw err; res.json(rows); }); }); app.listen(3000);这段代码放在真实环境里就是大事故现场但拿来做 skill 测试非常合适。我在会话里输入请使用 security-audit-skill 对当前项目的 ./src 目录做一次安全审计。 重点关注注入、敏感信息、依赖漏洞、配置错误。Agent 按照 skill 定义的流程跑完后输出了一份报告。我截取关键部分给你们看看## 安全审计报告 ### 风险统计 - 高风险: 3 - 中风险: 2 - 低风险: 1 ### 高风险问题 1. SQL 注入 - 文件: src/app.js - 行号: 22 - 问题描述: 使用字符串拼接构造 SQL 查询且拼接内容来自 URL 参数 req.params.id。 - 修复建议: 改用参数化查询例如 connection.query(SELECT * FROM users WHERE id ?, [req.params.id], ...) 2. 硬编码口令 - 文件: src/app.js - 行号: 8 - 问题描述: 数据库密码以明文硬编码在代码中。 - 修复建议: 使用环境变量或密钥管理服务例如 process.env.DB_PASSWORD 3. 宽松 CORS 配置 - 文件: src/app.js - 行号: 15 - 问题描述: cors({ origin: * }) 允许任意源跨域访问接口。 - 修复建议: 配置具体允许的来源域名不要使用通配符。 ### 中风险问题 4. 错误信息泄漏 - 文件: src/app.js - 行号: 23 - 问题描述: 捕获到的错误直接抛出可能导致堆栈信息泄漏给客户端。 - 修复建议: 记录错误日志对客户端返回统一错误信息。 5. 使用了不安全的 HTTP 方法 - 文件: src/app.js - 行号: 30 - 问题描述: 未限制 DELETE、PUT 等方法的访问范围。 - 修复建议: 按角色配置路由访问控制。 ### 低风险问题 6. 缺少请求频率限制 - 文件: src/app.js - 行号: 19 - 问题描述: 登录和查询接口未做 rate limiting存在暴力破解风险。 - 修复建议: 接入 express-rate-limit 中间件。这份报告基本把我想演示的问题都覆盖了。实际测试下来对这类明显漏洞的检出率是非常高的关键命中的行号也都对省去了人工逐行找的时间。3.3 依赖审计与配置审计的玩法代码之外的依赖和配置是安全审计的另外两块大头。我在 skill 里做了专门的设计。依赖审计这部分我没有让模型自己去背 CVE 库因为它根本背不全。我的方案是用脚本调用系统级的漏洞扫描命令然后把输出喂给模型做解释和汇总。比如 Node.js 项目在 skill 脚本里执行npm audit --jsonPython 项目执行pip-auditJava 项目用dependency-check。这样既保证了漏洞数据的更新又避免了模型幻觉编造 CVE。脚本会生成一个 JSON 文件skill 里的规则告诉模型“解析 JSON提取 severity、package、patched version 并输出成报告”。这是一个非常实用的做法模型不擅长精确记忆但擅长解析和解释结构化数据。配置审计则偏重规则匹配。我在 config-rules.md 里专门列了常见的错误配置数据库端口暴露在公网Redis 未设置密码云服务对象存储权限设置为 public生产环境开启 debug modeTLS 版本低于 1.2容器配置中使用了 privileged 模式。这些配置项无法靠模型自己凭空想全全靠规则文件一条条列出匹配模式。所以我经常说规则文件才是 skill 的真正价值所在代码只是搬运工。4. 常见问题、误报处理与调优心得4.1 高频问题速查表我在使用过程中遇到不少问题有些问题在别人的项目里也经常出现。整理成一张速查表遇到情况直接查现象常见原因解决办法Agent 完全不触发 skillSKILL.md 里 description 太泛或触发词没写明确写“安全审计”“漏洞扫描”等触发词中英文都要有skill 被触发了但报告很空审计范围没定清楚在输入里指定目录或在 Usage Steps 里默认先列出项目文件误报特别多规则缺少上下文判断在规则里加“只有当输入来自用户参数时才判定为风险”这类条件漏报明显上下文窗口不够扫描大文件时丢失变量信息对超大文件做切片扫描或让脚本先提取函数级片段依赖漏洞报得不准模型自己记忆的 CVE 过期改用npm audit/pip-audit等工具输出再由模型解析报告太长没法看输出格式没约束在 SKILL.md 里规定先出摘要再出详细清单规则升级后旧报告对不上没有做版本管理整个 skill 目录用 git 管理规则变更走 pr 评审4.2 误报和漏报的调优思路误报是安全审计 skill 的最大敌人。我经历过一次最夸张的情况skill 把一个正常的 ORM 查询判断成 SQL 注入原因是规则里只写了“存在 SQL 相关关键字就告警”完全没有考虑 ORM 的参数绑定。后来我把规则改成“必须是使用原始拼接方式且拼接内容包含非白名单变量”才算命中。这个改法非常有效误报率下降了一半以上。如果你发现误报多第一件事不是删规则而是去给规则补充“豁免条件”。漏报调优则完全相反需要做减法而不是加法。上下文窗口有限规则越多模型越抓不到重点。我在实际使用里把检查项控制在四个优先级别第一优先是高危注入类第二优先是敏感信息泄漏第三优先是配置错误第四优先才是依赖问题。如果 Agent 一次要检查的文件特别多我甚至会故意把某些低优先级规则暂时关掉保证高优先级问题不被淹没。4.3 把 Skill 变成团队安全基线的经验最后一个想分享的经验和团队协作有关。我把这个 skill 放进团队仓库之后做了一次很重要的升级建立了一套审计基线。我们把历次线上安全事故总结出来的高危点全部转成规则文件里的检查项。比如我们出现过一次线上密钥泄露事件从那以后规则文件里就永远留一条“扫描.env、config目录下是否有高权限凭证被误提交”。这种做法的好处是安全经验不再只存在某个老员工的脑子里而是变成团队共享的资产。新人接手项目跑一遍 skill 就能得到和老员工差不多的检查结果上线前跑一遍等于强制过了安全自检。我还给团队定了两个硬性规定一规则文件的改动必须经过安全负责人确认二每次规则更新都要在演示项目上做回归测试防止新规则影响旧项目的检查结果。真正确保这个 skill 长期可用靠的不是一次性的热情而是持续的维护和迭代。我个人最后的体会是千万不要迷信一个 skill 能解决所有安全问题。它更像一个放大镜能把已知问题看得更清楚但系统真正安全与否仍取决于写代码的人有没有安全意识。把重复性的、确定性的检查交给 AI把人解放出来去思考复杂的业务逻辑和攻击路径这才是 security-audit-skill 最有价值的用法。