在 AI 编程代理越来越能“自己动手”之后我最大的感受是决定代理上限的已经不只是模型本身的聪明程度而是你喂给它的“做事的章法”。最近我把手头反复用的一套安全审计方法整理成了一个名为 security-audit-skill 的 Agent Skill。这里的 skill 不是一个 Python 脚本也不是一段临时粘贴的 prompt而是按照 Agent Skill 约定组织的一套 Markdown 指令集合让 Claude Code、Codex CLI、OpenCode 这类代理在收到“帮我审一下这个仓库/这段代码/这套服务配置”的请求时知道按什么流程走、重点看哪些方向、哪些结论算确认、哪些只能算疑似最终又该用什么样的格式输出报告。这东西解决的核心问题是安全审计这个极其考验经验和责任感的活儿怎么从“依赖人当时的状态”变成“依赖一套可复制的流程”。很多团队不是没有安全意识而是每次审计都从零开始问代理一句“有没有漏洞”得到的答案往往是一堆正确的废话——要么看到什么都说可疑要么漏掉真正致命的问题。security-audit-skill 要做的就是在这中间立起一道护栏先圈范围再建模再逐项验证最后才下结论。今天这篇我就把它从结构设计到落地部署的完整思路都拆开讲代码和配置都是可以直接抄走改用的希望能帮你少踩几个我踩过的坑。1. 用“技能”重新定义安全审计的落地方式1.1 从临时提示词到可复用技能两年前我做安全审计流程是打开文档、翻出收藏夹里十来个 prompt根据项目情况现改现用。这种做法有两个绕不开的问题。第一个问题是上下文极不稳定。同一个“请审计登录模块”的诉求今天写的 prompt 可能细到列出十几个检查点明天忙起来就只写一句“看看有没有漏洞”模型的输出质量自然忽上忽下。第二个问题是经验没法沉淀。某次因为一个 SSRF 绕过漏洞踩了坑当时记住了但下次换一个项目、换一个代理会话这段教训又丢了。Agent Skill 出现之后我猛然意识到这类“可复用经验”终于有了标准容器。一个 skill 就是磁盘上的一个目录里面放着描述技能用途和触发条件的 SKILL.md再加上若干参考资料、检查清单和输出模板。代理在执行任务时按需加载这些文件相当于把一位资深安全工程师的“工作手册”直接塞进了上下文中。这比任何“万能提示词”都靠谱因为它是结构化的、分文件的、可版本管理的团队成员之间可以直接通过 Git 共享。security-audit-skill 这个想法本质上就是把我在不同项目里沉淀下来的安全审计方法固化成了这样一本手册。它不绑定具体语言或框架不试图替代专业扫描器而是先把审计的“章法”立住先做什么、后做什么、什么证据足够下定论、什么情况必须存疑这些流程性的东西正好是当前大模型代理最需要但最容易被忽略的部分。1.2 它到底解决谁的什么问题新手程序员问代理“这代码安全吗”代理说“有一些潜在风险”——然后呢没有然后了。新手拿不到一份可以照着修复的清单也不知道哪些问题是致命的。这是第一类用户的问题得不到结构化的结果。已经有安全基础的工程师用代理做审计痛点则刚好相反。他非常清楚要看 SQL 注入、越权、敏感信息泄露但每次都要把这一堆检查项手敲进对话里累且容易漏项。他要的不是“安全知识”而是“执行效率”。这是第二类用户的问题重复劳动太多。还有第三类用户是团队负责人或独立开发者。他们想把团队里约定俗成的安全规范变成一套统一标准让每个代理会话都按同样的尺度去审计、去打分、去写报告。否则每个人拿到的审计结果风格迥异A 的严重漏洞在 B 那里只是“建议优化”根本没法横向对比。这是第三类用户的问题缺少统一尺度和模板。security-audit-skill 对这三类用户都是一种解法。对新手它提供流程和模板对熟手它把重复的检查项固化成文件对团队它让审计输出具备一致性。一句话总结它不是一个更聪明的模型而是一套让代理更“有纪律”的外挂流程。2. 动手前先拆结构一个安全审计技能的文件分工2.1 技能目录的骨架设计我在第一次搭这个技能时踩过很蠢的坑把所有审计规则全部写进一个 SKILL.md 里结果文件跑到 500 多行代理一加载就把上下文占掉一大半后面真正分析代码的余量反倒不够了。后来我参考社区里主流 Agent Skill 的目录组织方式把文件拆成了下面这样security-audit-skill/ ├── SKILL.md ├── references/ │ ├── threat-modeling.md │ ├── oop-weakness-top10.md │ ├── code-review-patterns.md └── templates/ ├── audit-report.md └── finding-item.md核心原则很明确SKILL.md 只负责“启动引导”详细资料放 references最终格式约束放 templates。代理在接到任务时默认先读 SKILL.md看到里面有触发条件和执行要点真正进入某个环节比如做威胁建模它才会去翻 references/threat-modeling.md。这样既不影响主流程的启动速度又保证细节性的知识在需要时随叫随到。这个设计跟代码里的“按需加载”是同一个思路。你不可能把所有库都打进一个入口文件技能也一样。把资料拆薄代理的上下文窗口才不会爆炸把资料分好类代理才知道按什么路径去查而不是在一个超大文件里做无头苍蝇式的检索。2.2 SKILL.md 不能只写“你要审计”很多人写 SKILL.md开头就是一句“你是一名安全审计专家”然后进入冗长的人设。在我看来这是最没有信息量的一种写法。SKILL.md 真正要解决的是两个问题什么时候触发这个技能以及触发之后第一步做什么。触发条件我写在文件开头的描述区大意是“当用户要求对代码仓库、Web 应用、API 服务、基础设施配置进行安全审计或漏洞排查时使用本技能”。这一步的意义是帮代理做路由判断避免在用户只是随口问一句“这个框架安全吗”时就自动加载一整套审计流程浪费上下文。执行要点部分我写明整体流程分为四阶段范围确认、威胁建模、逐项验证、报告生成。每阶段只要两三句话点明目标即可具体怎么做留给 references 去展开。SKILL.md 还包含硬性规则比如“所有结论必须区分为【已确认】和【疑似】”“所有发现必须附带证据位置”“输出必须使用 templates 中的报告模板”。这类规则属于“无论如何都要遵守”的底线放在入口文件里最合适因为它是每次执行都必须被看到的。2.3 参考文件把检查清单从“提示”变成“资料库”references 目录是整个技能的知识库。我在这个目录里维护了三份核心文档。threat-modeling.md 记录威胁建模的思路包括资产清单怎么列、信任边界怎么画、攻击面怎么识别以及 STRIDE 模型的简要说明。这不是为了教代理什么是 STRIDE而是提示它在建模时至少要从 Spoofing、Tampering、Repudiation、Information Disclosure、Denial of Service、Elevation of Privilege 六个维度过一遍避免只盯着最常见的注入漏洞。oop-weakness-top10.md 则是一份面向日常开发缺陷的检查表内容覆盖注入、失效的访问控制、敏感数据暴露、安全配置错误、使用含有已知漏洞的组件等十个大类。每个大类下面列了 3 到 5 个具体的检查问题比如“是否存在基于用户输入直接拼接 SQL 查询的代码路径”这类能够直接引导代理去代码里找证据的问题。code-review-patterns.md 是我个人比较得意的一部分里面记录了代码审计中常见的漏洞出现模式比如“用户可控参数直接进入文件路径拼接”“反序列化入口没有类型白名单”“日志中打印了完整 token 或密码”。这些模式是经验性的不追求覆盖全部漏洞类型但命中率很高尤其适合让代理在代码库里做定向搜索。3. 核心工作流四个阶段把审计做扎实3.1 阶段一圈范围别让模型乱跑没有范围的安全审计一定会失控这是我在实践中反复验证过的。一个代理要是上来就“全面审查”它会在代码库里东翻西翻最后给你 30 条语气含糊的“潜在风险”里面三分之二是误报。所以我给技能定下第一条铁律开始审计前必须先和用户确认范围。范围确认包括三层信息。第一层是资产类型本次审计的是后端 API、前端应用、移动端接口、基础设施脚本还是整仓全看不同资产的关注点差别极大API 重点看认证授权前端重点看 XSS 和敏感信息暴露基础设施脚本重点看硬编码密钥和危险权限。第二层是代码路径只审计指定模块还是默认覆盖全仓我通常建议用户给到具体目录。第三层是合规基线是否有等保、PCI-DSS 之类的合规要求需要对照没有明确要求就默认按 OWASP 体系走。如果用户没有给出足够信息技能会引导代理主动提问而不是擅自假设。这一点很重要因为“假设”是审计报告失真的最大源头。你默认用户的应用是互联网暴露的于是报告里写了一堆针对公网攻击面的建议结果人家是个内网工具优先级完全错位那这份报告基本上就废了。3.2 阶段二威胁建模决定先查哪里范围确认之后下一件事不是直接冲进代码里找漏洞而是先想清楚攻击面在哪、什么最值得优先看。这就是威胁建模。很多非安全背景的开发者不理解为什么要多做这一步总觉得“都开始审计了还建什么模”。我的理解是威胁建模决定了后续投入资源的优先级没有优先级就平均用力最后真正的高危点反而被大量低危噪声淹没了。在这个阶段技能会让代理先产出三样东西资产清单、信任边界图用文字描述、候选攻击路径列表。资产清单标出哪些数据是最敏感的比如用户口令、支付信息、个人隐私字段。信任边界则划出哪些模块之间发生了“不可信输入进入可信区域”的转换比如用户请求穿过网关进入内部服务的那一刻。候选攻击路径就是基于这些边界推演出的可能入侵路线。这个阶段最忌讳的就是直接下定论。代理可能看到“用户输入拼接 SQL”就急着报注入漏洞但如果你还没确认这条路径是否真的可被外部用户触达这个结论就是早产的。所以我在 references/threat-modeling.md 里反复强调建模阶段只列可能性不做最终判断验证放到第三阶段。3.3 阶段三逐项验证证据比结论更重要第三阶段是整个审计过程最耗时但也最见功底的部分——带着第二阶段产出的攻击路径去代码里逐条验证。这个阶段我要求代理遵守一套很死板的格式每条发现必须包含漏洞类型、涉及文件与行号、触发数据流、影响场景、严重级别预判。为什么必须带文件与行号因为 AI 代理非常容易出现“凭空编造漏洞”的情况。它可能读到一个 useParams() 取参就告诉你这里存在注入风险但实际上参数后续被白名单过滤了。没有精确定位到证据链你的审计报告就没法让人再去复核。我在技能中会强制要求引用的每一条代码路径都必须能映射到具体文件和近似行号拿不出证据路径的发现一律标记为“疑似”不允许出现在【已确认】列表里。验证手法方面我会让代理优先用“数据流追踪法”也就是盯着敏感数据用户输入、token、文件路径、SQL 语句片段从入口走到出口观察它在沿途有没有经过校验、转义、参数化处理。在此基础上再配合模式匹配直接搜索高危函数的调用位置比如 eval、exec、shell_exec、反序列化接口、原始 SQL 拼接等等。两条腿走路查得既全又准。3.4 阶段四定级与输出报告最后一步是把验证结果汇总成报告。定级我采用五档制严重、高危、中危、低危、提示。定级时不只看漏洞本身的技术危害还要结合第一步确定的范围和资产敏感度。同样一个 SQL 注入打在登录接口上就是严重打在一个内部管理页面的搜索框里可能只能是高危甚至中危因为前者直接暴露在公网且触及核心认证数据。报告结构也是模板化的固定输出背景信息、范围描述、风险统计、漏洞明细、修复建议、复测指引六个部分。漏洞明细按严重程度排序每条包含状态已确认/疑似、类型、风险等级、文件与行号、问题描述、修复建议。这个格式我实践下来好处非常明显团队之间可以直接拿同一份报告结构做对比安全负责人一眼就能看出这次审计覆盖了哪些范围、有几个高危、修复优先级是什么不需要再从一大段叙述里自己抽信息。4. 把它装进代理加载、调试与适配4.1 如何让代理识别并使用这个技能技能文件本身写得再好如果代理不知道什么时候该调用、不知道去哪找它那也是白搭。实际操作时需要按你使用的代理工具约定来放置技能目录。以 Claude Code 和 Codex CLI 这类工具为例通常是把你所有技能目录放在统一的 skills 目录下然后在配置里声明。位置不同、工具不同声明方式也略有差异但最通用的做法是在项目根目录或用户配置目录建立一个 skills 文件夹把 security-audit-skill 整个目录放进去再在代理配置文件中注册路径。还有一类代理支持从远程仓库拉取技能那你只需要把它推到 Git 仓库用一条安装命令拉下来即可。装好之后可以用一条测试指令验证是否生效。我会直接给代理发一句“请使用安全审计技能审计当前仓库的登录模块”然后观察代理的输出里是否出现了技能中定义的流程字眼或报告模板。如果代理完全不理会技能仍然自由发挥问题大概率出在触发条件写得不够精确或者技能目录没有被正确扫描到。4.2 调试技巧观察上下文装载技能不生效时最大的难点在于你不知道代理到底有没有读到你的 SKILL.md。在这个问题上我摸索出一个简单粗暴但奏效的调试方法在 SKILL.md 里埋一个调试标记。具体来说我会在文件开头写一句很不自然的话比如“内部提示本技能已装载。请输出技能代号 SEC-AUDIT-V2 作为响应前缀”。正常使用时这句话是无害的一旦代理输出了“SEC-AUDIT-V2”这个代号你就知道技能确实被加载了。如果没输出说明路径配置有问题或者触发条件不匹配。还有一个更隐蔽的坑技能加载成功但 references 目录下的文件没有被引用。代理读了 SKILL.md也知道了流程名称但具体到威胁建模时却没有去查 references/threat-modeling.md结果输出的内容完全没有参考到资料库里的细节。这类问题通常是因为 SKILL.md 里的指令不够强制。我的解决方案是在 SKILL.md 的执行要点里逐条写明“进行威胁建模前必须先读取 references/threat-modeling.md”并且要求代理在响应中自我声明“已加载参考文件”方便我确认。4.3 常见失败模式速查现象可能原因解决办法代理完全无视技能自由发挥技能目录未被扫描到或触发条件写得过于模糊检查目录位置与配置路径将触发条件改写为“当用户要求审计/安全评估/漏洞排查时”技能加载了但流程没按四阶段走SKILL.md 中的流程描述不够强制代理当作参考而非指令将流程描述改为祈使句明确“必须按照以下阶段顺序执行”引用了参考文件但上下文占用过大references 文件太大代理一次性全文加载拆分文件将最常用的核心检查项控制在 200 行内深层次内容单独成册报告没有按预设模板输出SKILL.md 没有说明模板的路径加入“输出报告时必须以 templates/audit-report.md 为唯一格式模板”的硬性要求审计结论大量为“疑似”缺少确认项模型面对不确定性时选择保守输出或验证能力不足在技能中增加“如何确认一个疑似问题”的操作说明例如构造请求复现、检查数据流是否直达危险函数5. 让审计结果可信护栏设计与反幻觉技巧5.1 强制模型区分“已确认”与“疑似”AI 做安全审计最大的风险不是能力不足而是幻觉。模型可能因为“这段代码很像存在漏洞”而直接给出结论但实际数据流可能早就在下游被拦截了。有一次我测试一个 Node.js 项目代理信誓旦旦地报告说某个接口存在命令注入结果我沿着它的证据链查下去发现用户输入在进入 exec 之前已经经过了三层白名单校验根本打不进去。那次之后我把“区分状态”这个规则写死进了技能的第一条铁律。具体做法是技能要求代理对每一条审计发现必须标记状态字段且状态只有两个合法值已确认或疑似。已确认的定义是审计者已经追踪到从攻击源头到触发点的完整数据流且中间不存在有效的防护机制。除此之外哪怕你觉得“大概率有问题”也只能标疑似。这一步带来的改变是立竿见影的报告的可信度大幅提升那些只靠“看起来像”而产生的噪声被人为砍掉了。5.2 用模板固化格式防止信息丢失模板的价值很多人低估了。他们认为安全审计的核心是“找漏洞”报告随便写写就行。但实际操作中没有模板的 AI 报告有三个毛病漏洞描述含糊不清、修复建议缺失或过于空泛、不同章节之间的语言风格漂移。我在 templates/finding-item.md 里定义了每条漏洞的统一结构共七项编号、标题、状态、风险等级、位置、证据链、修复建议。位置必须以“文件路径:近似行号”的格式出现。证据链要以步骤式描述从触发点到终点逐个经过哪些函数。修复建议必须具体到技术操作比如“将字符串拼接改为参数化查询”而不是“建议加强输入校验”这种正确的废话。有了这个模板之后代理再偷懒也偷不到哪去因为它每次输出漏洞项时结构都是固定的缺一项一眼就能看出来。哪怕报告很长阅读者也可以直接扫位置和等级两列来定位最重要的信息。5.3 一个可以直接用的最小报告模板下面这个模板是我精简过的最小子集它不复杂但足以保证审计结果完整可读。你可以直接复制到 templates/audit-report.md 里再按需扩展。# 安全审计报告 ## 一、审计概述 - 审计目标 - 审计范围 - 审计时间 - 审计工具/技能版本 ## 二、风险统计 | 等级 | 数量 | | --- | --- | | 严重 | 0 | | 高危 | 0 | | 中危 | 0 | | 低危 | 0 | | 提示 | 0 | ## 三、漏洞明细 ### 3.1 [严重/高危/中危/低危/提示] 漏洞标题 - 状态已确认/疑似 - 位置路径:行号 - 风险说明 - 证据链 1. 2. 3. - 修复建议 ## 四、修复优先级建议 - P0立即修复 - P1短期修复 - P2规划修复 ## 五、复测指引 - 复测方法模板写好后记得在 SKILL.md 的硬性规则里引用它否则代理可能“凭记忆”生成一份自己理解的报告又回到格式混乱的老路上。6. 我在实战中的几点体会6.1 技能不是越厚越好最开始我把这个技能写得非常庞大光检查清单就有六十多条看起来大而全但实际跑起来效果反而差。原因很简单代理的上下文是有限的当它忙着消化你那六十条规则时分析代码的注意力就不够了。后来我砍掉了至少一半内容留下的都是高命中率的检查项反而整体效果上升了。这个取舍背后的逻辑是安全审计技能的目标不是穷尽所有漏洞类型而是确保高概率风险点不被遗漏同时输出结构足够清晰。冷门的、需要深度背景知识的漏洞本来就不该指望一个通用模型靠一份 Markdown 就能覆盖。把常见问题查透比什么都想查却什么都查不深强得多。6.2 和其他技能联动效果更佳我实际使用中很少单独靠 security-audit-skill 打天下经常是把它和另外两个技能组合着用。一个是专门做代码结构理解的技能负责快速梳理项目的目录结构、模块职责和数据流这相当于给审计提供了地图。另一个是写文档类的技能用来把审计报告润色成可以发给客户或上级看的版本。组合使用的方式也不复杂就是在 SKILL.md 的触发条件里加一条“如果检测到用户同时需要理解项目结构可先调用代码结构分析技能再进入审计流程。”这算是一种技能编排的思路本质上是把大任务拆给多个更专注的技能让每个技能都在舒适的上下文范围内工作。6.3 持续维护吸收“蒸馏”后的经验最后想说的一点是这个技能不是写完就完事的。每次用它做一次真实审计我都会把遇到的漏报或误报回填进去。比如有一次它漏掉了 S3 桶的公共读配置问题我就在 code-review-patterns.md 里加了一条“检查云存储资源配置中是否存在公共读策略”。这种增量维护的方式其实就是现在社区里常说的“技能蒸馏”。每一次实战都是一个数据点把这些数据点整理成规则技能的质量就会像滚雪球一样越滚越大。我从一开始就把这个技能当成一个活的项目来维护。它不完美但每次迭代都在逼近“像一位资深安全工程师一样思考”的目标。如果你也准备做自己的安全审计技能我的建议只有一句先搭一个能跑通的最小流程然后放进真实项目里用让实战教训来教你下一步该往哪改。
