上个月给一个业务系统做上线前的安全审计代码量不算大但三轮人工过下来同类配置问题、依赖版本漏洞、硬编码密钥在复查单里反复出现。我一边在修复单里写“同上”一边忍不住琢磨如果这些检查步骤和判断标准能固化下来让AI完全按我的节奏去执行能省下多少时间。这就是我开始折腾security-audit-skill的直接原因。先解释一下这里说的skill是什么。在最近的AI Agent生态里skill技能包是把某一类任务的执行方法、工具调用规则、经验判断封装成可复用单元的东西。它和普通Prompt最大的区别在于Prompt是一次性的对话指令而skill自带文件、规则和流程可以被反复调用、迭代更新。对于安全审计这种流程重、检查项多、输出格式固定的场景skill天然合适。这篇文章我会从结构设计讲到规则落地再讲实战中踩过的坑尽量把整个思路讲透。1. 为什么安全审计是Skill化的最佳试验田1.1 审计流程的“重”恰好是技能包的甜区做过安全审计的人都有体会这项工作表面上是“检查代码”实际操作里严重依赖流程的完整性。一个标准的审计任务大致由几个环节组成先做信息收集搞清楚仓库的语言栈、框架版本、第三方依赖然后做依赖安全分析比对已知漏洞库接着是配置审计检查部署脚本、CI配置、容器镜像里有没有危险项最后才是源码审计定位具体的安全缺陷整理成报告。这套流程的问题是每个环节之间的顺序是强依赖的跳步就会漏检而每个环节内部又是高度重复的项目一多人会疲劳一疲劳就会肉眼漏。我最早试过用普通Prompt让AI做审计效果很不稳定。今天让它查硬编码密钥它给你列出一堆关键词明天换成别的仓库它可能把检测逻辑忘了一半回答风格也变了。后来我意识到问题不在AI的理解能力而在于我给的指令太松散。那些真正可靠的审计经验——检查什么、怎么查、什么条件算命中、什么情况要排除——全部装在我脑子里没有结构化地传递给AI。Skill要解决的就是这件事把方法论变成文件把标准变成规则让每次执行都站在同一条起跑线上。另外还要注意到安全审计的交付物很固定无非是风险评估、问题清单、修复建议。这意味着报告模板可以预先设计AI只需要向模板里填内容而不是自由发挥。自由发挥的审计报告一百个人能写出一百种风格对收报告的安全负责人来说反而是负担。固定模板下的输出才是团队里每个人都能快速消化的东西。1.2 规则可结构化判断可标准化安全审计之所以适合做成skill还有一个更底层的理由这个领域已经有大量现成的结构化标准。OWASP Top 10给出了Web应用最典型的风险类别CWE给缺陷类型做了统一编号CIS Benchmark覆盖了各类系统与中间件的基线配置CVE库则为每个已知漏洞提供了版本范围和修复版本。这些标准本身就是一份“规则清单”天然适合转成机器可读的格式。规则来源覆盖范围转成skill的用法OWASP Top 10 / ASVSWeb应用风险类别定义源码层面的检查项与风险等级CWE缺陷类型统一编号给审计发现打标准化标签CVE / 漏洞库第三方依赖已知漏洞依赖版本比对时的判定依据CIS Benchmark系统与中间件基线配置文件与部署环境的检查基线举个例子一条“硬编码密钥”的审计规则在人工审查时我会看代码里有没有明显的密钥关键字、有没有高熵字符串、有没有私钥文件片段。这些判断标准完全可以落到规则文件里变成字段、正则、排除清单。AI执行skill时不需要“理解”什么是密钥它只需按规则命中、按规则排除然后把结果交给我复核。这一步的差别非常关键——它把AI从一个“可能懂安全”的聊天对象变成了一个“按我的标准执行”的自动化审计助手。我在设计security-audit-skill时定了一条原则一切能固化的判断都固化一切不能固化的判断才交给模型推理。依赖审计、配置检查、密钥检测这些有明确规则的交给规则引擎而业务逻辑漏洞、越权判断这种需要上下文的场景才让模型去分析。这个边界划清楚之后skill的表现一下子稳定了很多。2. 拆解一个security-audit-skill的内部结构2.1 SKILL.md技能包的心脏每个合格的skill都要有一个主文件一般叫SKILL.md。它的作用有两个一是让Agent识别这个技能包的能力边界和触发条件二是向Agent说明执行流程和注意事项。如果说整个skill是一台机器SKILL.md就是使用说明书。我实际使用的SKILL.md结构大概长这样--- name: security-audit description: 对目标代码库执行结构化安全审计覆盖依赖、配置与源码检查输出风险清单及修复建议。 version: 1.0.0 allowed-tools: - read_file - execute_bash - grep_search - http_get triggers: - 安全审计 - security audit - 代码安全检查 - 漏洞扫描 --- # 执行流程 1. 确认目标仓库路径、语言栈、扫描范围全量/增量。 2. 调用 scripts/dependency_check.py 解析依赖锁文件比对漏洞库快照。 3. 调用 scripts/config_scanner.py 检查部署与配置文件。 4. 按 rules/ 目录下的规则分类执行源码模式匹配。 5. 将结果汇总到 templates/report_template.md 并输出。 # 关键原则 - 检出问题必须给出文件路径、行号、风险等级、修复建议。 - 未命中的检查项不写进报告但要在执行记录里留痕。 - 所有结果先过一遍人工复核规则再输出最终结论。这个文件看起来简单但有几个细节值得强调。第一description要写清楚“做什么、不做什么”避免Agent在其他无关场景里误触发第二allowed-tools要明确列出允许使用的工具安全审计涉及读文件、执行命令行、查漏洞库不该有外网请求的时候就不要给外网请求权限第三执行流程要用步骤式写法Agent会把它当成操作手册来解读写得越清晰执行越不容易跑偏。2.2 把检查项变成机器能读的规则文件SKILL.md解决的是“流程怎么走”的问题而rule文件解决的是“每一步查什么”的问题。我习惯把检查项拆成独立的规则文件按类别放在rules目录下面。每个规则文件里是一条条结构化的检查项字段包括检查项ID、风险类别、风险等级、适用语言、命中模式、排除模式、修复建议、参考标准。{ check_id: SEC-HARD-001, category: secret-hardcoding, title: 硬编码API密钥或口令, severity: high, languages: [python, javascript, java, go], patterns: [ (api[_-]?key|secret|pass[_-]?word|token)\\s*[:]\\s*[\][A-Za-z0-9/_-]{16,}[\], sk-[A-Za-z0-9_-]{20,}, -----BEGIN (RSA|EC|OPENSSH) PRIVATE KEY----- ], exclude_patterns: [ example, test-key, dummy, your_token_here ], fix_suggestion: 使用环境变量或密钥管理服务注入并立即撤销已泄露的密钥。, reference: OWASP Secrets Management Cheat Sheet }有人可能会问写成正则不是很容易误报吗确实会所以我在字段里专门留了exclude_patterns。这个排除清单很重要它的价值在实战中会被反复验证。第一次跑这个规则时文档里的示例代码全部中招满屏都是“高危险”把示例代码的特征词加进排除清单之后误报率直线下降。规则不是一次性写好的它是在一次次审计里磨出来的这也是我建议把规则文件独立出来的原因——改起来方便不用动SKILL.md主文件。2.3 输出模板决定审计报告能不能直接用很多AI审计工具跑完给你一堆扫描结果但接收者根本没法直接用。问题出在输出没有结构。安全审计的产出是要流转到工单系统、修复负责人手里的信息字段必须完整且统一。我的报告模板大致包含几个区域审计概览、风险统计、问题明细、修复优先级建议。风险统计用表格呈现按严重程度分为严重、高、中、低四个等级。问题明细里每个条目都必须具备“位置、现象、风险、修复建议”四要素缺了一个修复负责人就得回来找审计人问效率一下就下来了。模板这部分我放在了templates/report_template.md里Agent每次执行到最后一步时直接往这个模板里填充内容。这里有一个技巧模板里不要写太多“口语化描述”的占位符尽量写字段说明。例如“[文件路径:行号]”“[风险类型]”“[一句话现象描述]”这样AI才能准确理解每个位置该填什么。我见过有同事把模板写成了一篇散文AI填出来的报告也变成了散文看起来很热闹实际上没有人能对照字段去处理工单。3. 从零手写一个可运行的安全审计Skill3.1 先用任务分解法设计审计工作流动手写规则之前先把一次人工审计的完整流程画在纸上这一步绝不能省。我习惯按“输入—处理—输出”来拆。输入是仓库路径和扫描范围处理环节拆成依赖审计、配置审计、源码审计三层输出是结构化报告。每一环节都对应一个脚本或者一组规则未来调试时能够单独跑通不用整个流程一起调试。我当时把工作流拆成了五个步骤元信息采集识别语言栈、框架、包管理器、仓库规模。依赖审计解析lockfile或依赖清单比对漏洞库快照输出受影响依赖列表。配置审计检查Dockerfile、CI配置、环境变量示例、云服务配置模板。源码审计按规则分类扫描覆盖密钥泄露、注入风险、不安全反序列化、敏感函数滥用等。报告生成汇总所有发现按模板输出。为什么这么拆因为每个环节的失败模式不一样。依赖审计出问题大概率是lockfile格式没识别出来跟源码扫描的失败原因完全不同。如果不拆开AI跑一半报错你根本不知道是规则格式写错了还是脚本解析失败。拆开之后每一步可以单独验证这个设计在后续迭代里救了我很多次。3.2 规则文件落地从一个检查项到一套清单有了工作流接下来就是把每个环节的检查项落成文件。我建议先不要贪多从一个最典型的检查项开始比如硬编码密钥检测跑通整个链路再逐步扩充规则集。一次性写完几十条规则的结果通常是每条规则的质量都不高误报满天飞。等单个检查项跑通了再按优先级逐步加规则。我整理了一套最小可用的分类清单密钥与敏感信息泄露检查私钥、API密钥、数据库连接串、云服务凭证。注入类风险识别SQL拼接、命令拼接、模板注入特征。不安全配置容器以root运行、特权模式、关闭TLS、弱加密算法。已知漏洞依赖重点排查存在已知CVE且影响范围内的高危依赖。敏感函数滥用eval、exec、反序列化、文件上传未做类型校验。每一类在写规则时都要想清楚“什么才算命中”。以注入类为例单纯看到字符串拼接不算命中还要看拼接的内容是否进入了执行函数以及输入是否经过校验。规则文件里我会同时写入“进入危险函数”的模式和“存在白名单校验”的排除模式这样减少把正常代码误报成漏洞的概率。3.3 报告生成与修复建议联动规则命中只是第一步真正体现skill价值的是修复建议的质量。我在规则文件里给每条检查项都配套了fix_suggestion字段AI生成报告时会把这条建议原样带出。这样设计的好处是修复建议保持稳定不会因为AI每次理解的差异而飘忽不定。依赖漏洞的输出我用的格式大致是这样| 依赖 | 当前版本 | 受影响版本 | 已有漏洞 | 修复版本 | 建议操作 | | --- | --- | --- | --- | --- | --- | | lodash | 4.17.15 | 4.17.20 | CVE-2021-23337 | 4.17.21 | 升级至4.17.21 |每一个漏洞条目背后都带着参考链接让开发同学知道为什么改、改了有什么影响。报告里还会有一个“人工复核建议”区块专门放那些AI拿不准、需要人再判断的发现。这很重要——审计结果不是机器代言人机器负责找出疑点人负责最终拍板。4. 实战运行三个翻车现场与修复方案4.1 误报风暴AI把注释里的关键词当成漏洞第一次拿完整规则集跑真实代码库时结果非常难看。报告里列了四十多个“硬编码密钥”我点开一看三分之一来自文档里的示例三分之一来自代码注释里的示例命令真正需要处理的只有一小部分。那天的第一反应是“这规则废了”后来冷静下来才想明白问题不在于规则方向错了而在于排除逻辑不够完整。排查链路是这样的我先随机抽取了十条例检出结果逐一比对源码位置发现命中文本都是“password123456”这类示例且上下文里普遍存在“example”“demo”“do not use”等字样。然后我把这些特征词统一补进exclude_patterns重新跑了一遍误报数量从四十多降到个位数。这个经历告诉我新规则上线前一定要先样本测试不要直接推给全量仓库。每条规则都要经历“写规则—跑样例—加排除—再验证”的循环等到误报率降到可接受范围再投入使用。如果你不想被报告淹没这个环节绝对不能省。4.2 上下文断片长文件审计时AI突然“失忆”第二个坑出在源码审计环节。当一个文件超过几百行时Agent在分析过程中会出现明显的上下文丢失前半段发现的疑点后半段写报告时就不记得了。表现出来就是报告里漏项同一个文件里的SQL注入没有被列进去。一开始我以为是模型上下文窗口不够加长窗口之后问题依旧。后来我换了个思路不是让AI一次性吞下整个文件而是在外部脚本里先把文件按函数或代码块做切片每片单独执行检查再把结果合并。这个改动解决了两个问题一是每一片的内容量变小分析精度上升二是切片的边界天然对应函数级作用域可以让规则匹配更精准。配合脚本输出结构化中间结果报告漏项的问题基本消失。我自己的体会是任何长文本审计任务都应当让AI处理“代码块”而不是“代码文件”这个粒度控制是稳定性的分水岭。4.3 规则过时新漏洞模式AI根本识别不了第三类翻车最隐蔽。跑一个新仓库时依赖审计环节显示全部通过但我很清楚这个框架最近有多个高危漏洞被曝光为什么一个都没命中查下去发现本地漏洞库快照是两个月前的新漏洞根本没有进入比对范围。Skill里存的规则再完整也追不上漏洞库的更新速度。修复方案是给skill加上“先同步、再审计”的前置步骤。每次执行审计前先检查本地漏洞库快照的更新时间如果超过设定阈值就从可信源拉取最新数据同时把规则维护纳入例行节奏高危漏洞披露后第一时间更新对应规则。对于一个要长期使用的skill规则集应当被当成代码一样管理——版本化、可追溯、定期维护。不要指望一次写完就一劳永逸安全领域的规则天然有时效性。5. 给Skill装上“成长机制”我的几点扩展经验5.1 不同审计场景下深度与速度的取舍security-audit-skill用得越久越发现不能一套参数打天下。上线前的全量审计需要覆盖足够深适合跑完所有规则输出详细报告日常增量代码提交的审计则要快只看本次变更涉及的文件和依赖应急排查场景里重点是快速定位疑似问题规则可以适当放宽优先保证不遗漏。场景扫描范围规则深度输出侧重上线前全量审计全仓库全量规则完整报告、修复工单增量代码审计变更文件精简规则快速意见、阻断高风险应急风险排查指定模块放宽规则疑点列表、待人工确认这三种模式我在SKILL.md里用不同的triggers标识AI会根据用户输入的关键词自行选择对应的执行分支。你可以在设计自己的skill时参考这个思路——不是说每个skill都必须支持多场景但至少要在说明文档里写明适用的范围避免AI在错误的场景下过度执行或执行不到位。5.2 跨Agent迁移同一个Skill在不同平台的体验差异我在Claude、Codex、opencode等不同Agent环境下都跑过同一个security-audit-skill整体的流程逻辑是通用的但平台差异会造成体验差别。最大的变量是工具能力有的环境允许skill直接执行bash脚本有的只支持有限的文件操作有的环境能发起网络请求方便读取漏洞库有的环境没这个权限只能依赖离线快照。因此写skill时尽量避免强依赖某个平台的独有能力。脚本尽量用通用语言Python、Shell等规则文件用JSON或YAML描述文档用标准Markdown。这样迁移时小改allowed-tools和执行命令就能跑起来。如果你打算把skill分享到社区或者团队内部这一点要提前想清楚否则换一个平台就要重写一次维护成本会很高。5.3 让Skill在每次审计后自我更新最后聊聊我认为最有价值的一点把每次审计中发现的新模式反馈到规则里。我在项目的rules目录下放了一个“补充规则”文件夹每次人工复核报告时发现AI漏掉的新问题就手动补一条规则进去。比如有一次AI没有识别出某云厂商特有的凭据格式我在补充规则里加了一条对应的pattern下次再遇到就能命中。这种“审计—反馈—更新”的闭环听起来慢但坚持三个月后规则集的质量会明显高于初期。我把这个思路总结成一条项目原则skill不是一个静态的脚本集合而是一个随着使用持续生长的知识体。它吸收的不仅是公开标准还有你这个团队在实际项目中踩过的坑、见过的问题。这比任何框架设计都更能提升skill的长期价值。如果只让我留一条建议我会说先把一次真实审计的全流程记录下来然后花一个下午把它写成规则文件再找两个历史项目做回归测试。这个流程跑通了你对skill的理解会比看十篇教程都深。
