去年有段时间我在帮团队维护一套内部项目的安全自查流程。每次发版前都要人工核对一堆代码坏味道、敏感信息泄露和越权风险效率低就算了最关键的是每个人审查的标准还不一样。后来我开始尝试把安全审计流程交给大模型来做但直接用“帮我检查一下这个项目有没有安全问题”这种对话式Prompt去驱动AI效果很不稳定——它有时候能发现几个明显问题有时候又答得特别空泛像是在“乱猜”。试了几次之后我意识到问题不在于大模型本身而在于我根本没有给它一套可重复的、结构化的审计方法论。于是就有了“security-audit-skill”这个项目。它本质上不是一段Prompt而是一个可以装进Agent框架里直接调用的“技能包”。如果你接触过Claude Code、Codex、OpenCode或者最近很火的agent-skill体系你会发现这类skill的本质是把某个专业领域的完整流程、判断规则、输出格式和边界约束打包成一个可复用的工具。而“安全审计”这个场景恰好非常适合用这种形态来做。这篇文章我就把这个项目的设计思路、规则库怎么写、踩过的坑、以及实际运行效果一次说清楚。适合正在做AI编码助手二次开发、或者想把自己团队的审计流程“固化”成可复用技能的同学参考。1. 内容整体设计与思路拆解1.1 为什么是“skill”而不是普通Prompt很多人第一次看到“security-audit-skill”这个名字时会想这不就是一个提示词吗把一堆审计规则塞给AI让它去执行不就可以了么理论上确实可以但实际效果会打折扣。普通Prompt是一次性的、松散的输入它没有“边界意识”也没有“输出契约”。你给它一段代码让它审计它可能今天给你返回一份表格明天给你一段对话式的总结后天直接写一篇散文。这种不确定性在真实工程场景里是非常致命的问题——下游没法接结果没法比对审计质量也无法追踪。而Skill的形态解决的是“稳定复用”的问题。它拥有固定的元数据名称、触发条件、版本号、固定的工作流程Step 1做什么、Step 2做什么、固定的输出结构审计报告格式、以及明确的“禁区声明”哪些内容不做、什么时候必须拒绝回答。当我把“安全审计能力”封装成skill时AI就不再是“用一个Prompt临时客串审计师”而是“进入一种专业的审计工作状态”。这个区别很微妙但使用体验差异巨大。1.2 审计场景的三个关键特性我之所以选择安全审计作为第一个动手做的技能包是因为这个场景有三个天然适合被“技能化”的特征。第一是高一致性要求。安全审计最怕的就是两个人审出两套结论同一段代码A说高风险B说没问题。用skill固化标准之后只要规则库稳定AI每次输出的标准偏差就会很小。第二是高透明性要求。安全审计不光要给出结论还必须给出“为什么”。审计报告里每一处风险点都要能追溯到具体的代码行、具体的规则依据以及危害等级的判定逻辑。这类推理过程可以通过skill里的输出模板强行约束。第三是高规范性要求。安全领域有大量公认的标准和红线比如OWASP Top 10、SANS 25这类清单。把这些标准内置到skill里可以借力权威知识沉淀而不是让AI凭空判断什么重要什么不重要。基于这三个特性我在设计skill时把重心放在了“流程结构化”和“规则明确化”上而不是一味追求让AI“更聪明”。1.3 整体目录结构设计实际落地时我把整个skill拆成了几个相对独立的模块目录结构是这样的security-audit-skill/ ├── SKILL.md # 主文件定义skill的元信息、工作流程、输出契约 ├── audit_rules/ │ ├── injection.md # 注入类风险检测规则 │ ├── sensitive_data.md # 敏感信息与密钥泄露检测规则 │ ├── authz.md # 权限与越权检测规则 │ ├── unsafe_api.md # 危险函数与不安全API调用检测规则 │ └── output_safety.md # LLM输出内容安全自检规则 ├── references/ │ ├── owasp_top10.md # 内置参考知识 │ └── severity_guide.md # 危害等级判定标准 ├── templates/ │ ├── audit_report.md # 最终审计报告模板 │ └── checklist.md # 审计前快速检查清单 └── examples/ ├── demo_flask_app/ # 故意包含漏洞的示例项目 └── sample_report.md # 样例审计报告这样分层的设计是刻意的。主文件只负责流程调度不负责具体知识规则库按领域拆分方便单独维护和扩展references提供知识底座templates约束输出。如果你在某些Agent框架里使用会发现这种结构可以直接被识别为“可调用的技能”不需要额外写解析器。2. 核心细节解析与实操要点2.1 SKILL.md主文件怎么写SKILL.md是整个skill的灵魂它负责告诉大模型“你是谁、你要做什么、你按什么流程做、你绝对不能做什么”。很多人在写skill文件的时候会犯一个错误把大量审计知识塞进主文件里结果导致模型上下文被撑爆反而影响核心任务的执行准确率。我的做法是在SKILL.md里只保留以下四块关键内容元数据区定义skill的名字、描述、触发条件。描述要写得尽量“可被模型识别”比如“当用户要求对代码进行安全审计、安全复核、风险扫描时使用本技能”。描述写得越贴近真实使用场景Agent框架判断何时调用这个skill就越准确。流程区明确审计步骤的先后顺序。比如我的流程是收集上下文 → 建立基线 → 分域扫描 → 交叉验证 → 生成报告。每一步都要说明输入和输出让模型知道“现在进行到哪一步了”。输出合约区固定报告格式告诉模型必须按模板输出。这一点极其重要——审计报告是要给人和机器读的格式不规范后面所有下游工作都做不了。禁区声明区明确写清楚这个skill“不会执行什么”比如“本技能未获得授权时不执行任何代码修改操作只报告不修复”。这些边界能让模型在安全领域更谨慎避免过度操作。2.2 规则文件中的“论证思维”在写audit_rules目录下的规则文件时我特别强调了一个原则所有规则必须要求模型提供证据链。举个例子。在注入风险检测规则里我简单列了几个危险函数比如Python的eval()、exec()、os.system()Java的Runtime.getRuntime().exec()以及JavaScript的child_process.exec()。但真正的审计不光是匹配函数名还要分析数据流。所以我在规则里专门加了一段“深入分析提示”如果检测到可疑函数请按以下路径做分析这个函数的参数来源是否涉及用户输入用户输入在到达该函数前经过了哪些处理是否存在绕过过滤的方式基于以上分析判定风险等级并说明判定依据。为什么要这么写因为直接让AI“列出所有调用了eval()的位置”是入门水平而安全审计应该做的是“判断这条调用链是否真的构成可利用风险”。把这种论证思维写进规则模型就不会盲目报一堆函数名而是会像真正的审计员一样去跟踪数据流和攻击路径。2.3 危害等级判定标准我在references/severity_guide.md中定义了四级风险等级严重、高、中、低。判定标准刻意做得表格化方便模型查阅。等级定义典型场景严重可被未授权用户直接利用且造成全面影响未授权SQL注入可拖库、硬编码云厂商AK/SK可接管账号高需要特定条件但利用难度较低影响范围可控越权访问他人数据、命令注入点位于低权限容器内中风险需要叠加其他条件才能利用或只影响边缘功能反射型XSS需要配合社工敏感信息记录在日志中低不符合安全规范但不构成直接入侵路径注释中的内部路径泄露、代码风格安全优化建议这个等级表不是拍脑袋定的。它借鉴了很多安全团队的评估方法核心思路是同时看“可利用性”和“影响面”。在给模型的指令里我要求它对每个问题都先套用这个表再给出判断。2.4 输出模板审计报告必须能“落库”最后再讲一下templates/audit_report.md的设计。审计报告的模板我做得非常死板甚至可以说有点“机械化”因为它的目的是让结果可以结构化存储。报告包含六大部分概况摘要、风险统计、问题清单、证据链、修复建议、免责声明。其中“修复建议”是我特别强调的——审计不能只发现问题就不管缺少建议的审计报告价值会打对折。同时我要求所有代码路径用绝对行号标注所有风险描述里必须包含“为什么这是一个风险”的解释坚决禁止只输出“这里存在安全问题”这种没有信息量的废话。3. 实操过程与核心环节实现这一节我会把从零到一搭建security-audit-skill的核心过程拆开每一步都给可直接参考的写法和配置方式。我默认你使用的Agent框架支持常见的skill格式定义。如果你用的是Claude Code或Codex这类支持技能仓库的工具这套写法基本可以直接套用。3.1 第一步定义核心工作流程最开始我写SKILL.md时工作流程写得特别散四个步骤之间没有明确的前置条件结果模型经常在“分析风险”和“输出报告”两个阶段之间来回横跳输出质量很不稳定。后来我把流程改成严格的六步每一步都设定了产出物。上下文确认确认审计对象、审计范围、代码语言栈、框架版本。此步输出“审计基准说明”。基线检查根据references里的清单做快速初筛。此步输出“初步风险扫描记录”。分域审计按安全域拆分任务包括应用代码、配置项、依赖清单、部署脚本。此步输出“分域风险清单”。数据流分析针对初筛中命中高风险的问题进行调用链和数据来源追溯。此步输出“深度证据链记录”。交叉验证把不同安全域中排查到的信息进行关联排查组合风险。此步输出“关联风险分析记录”。报告生成按模板汇总所有结论输出最终审计报告。第5步交叉验证是很多人忽略的环节。真实攻击往往不是靠单点漏洞而是多个看起来不起眼的小问题串联成一条完整的攻击链。举个例子Nginx配置里泄露了一个内部服务地址中风险同时FastCGI调用未做缓存键隔离中风险单独看都不至于被定为高风险。但攻击者如果注意到这个地址再结合FastCGI的参数污染就可能打出一套远程利用的组合拳。只有做了交叉验证报告的价值才会从“逐个列问题”升级为“还原攻击视角”。我建议你在写SDILL.md的时候把每一步的“输入-操作-产出”写在一个小节里不要写得太意识流。模型是靠这些操作指令来知道当前应该干什么的你把步骤写得越清晰它的行为就越可控。3.2 第二步编写注入类审计规则规则文件是整个skill的知识核心。以injection.md为例我把审计目标拆成了系统命令注入、SQL注入、代码注入和LLM提示注入四大类针对每类设了独立的分析指令。以系统命令注入为例我的规则文本大体长这样## 系统命令注入审计 **检测目标** - socket / 子进程 / 环境变量 / 文件路径等外部可控数据源 - 涉及调用exec、system、popen、subprocess、child_process.exec等 **审计步骤** 1. 定位所有命令执行函数调用点 2. 分析参数来源如果参数来自用户输入、请求头、文件名等标记为“可疑外部输入” 3. 检查是否存在清理逻辑白名单校验、转义、路径归一化 4. 若无可信校验记录为“命令注入疑似点”并给出利用假设。 **证据要求** - 必须标注数据流的完整路径输入从哪里来经过哪些函数最后进入哪个执行点。这一段之所以可以作为“可直接抄作业”的范例是因为它根本不是让模型去“发现漏洞”而是让模型去“描述调用链”。当模型能把一条数据流完整画出来的时候它自然就具备了判断漏洞的能力而不是靠猜。3.3 第三步编写权限与敏感信息审计规则权限审计是安全审计里比较难做的一块因为它不完全是代码层面的问题。我在这份skill里把“越权”拆成了三个层次来写。第一层是未授权访问接口或页面缺少身份校验中间件直接允许匿名请求落地到业务逻辑。第二层是越权访问水平用户A能操作用户B的数据典型特征是ID直接从请求参数中取用且无所有权校验。第三层是越权操作垂直普通用户可以调用管理员的接口典型特征是缺少角色校验注解。针对这三个层次我在权限规则文件里分别给了一组“审计问题”让模型按问题列表去代码中找答案。比如针对水平越权问题列表是这样的数据查询是否使用了当前登录用户ID而不是客户端传入的参数对象级权限是否有统一校验入口是否存在直接通过拼接ID访问文件、订单、消息等资源的逻辑写完权限规则之后我强烈建议你再补一份敏感信息检测规则。这块查阅频率很高而且有非常典型的命中模式AWS AK/SK、支付宝/微信密钥以及自定义算法的加解密密钥。我在规则里写的是正则匹配加模式分析双模式正则负责初筛模式分析负责减少误报——比如发现一段疑似密钥的字符串后会检查它是否被真实用在访问外部服务的代码路径上如果只是测试代码里的随机样例就会降级提示。3.4 第四步接入工具并实测规则编写好之后不能直接在某个Agent对话框里测试一遍就算完。我把skill挂到常用的Agent框架里专门准备了一个故意内置了漏洞的Flask项目作为测试样本分别跑了五轮检查输出稳定性和命中率。接入过程其实就是将整个skill目录放到Agent框架指定加载的skills路径下然后在会话里输入“对当前项目执行安全审计”框架会自动识别到security-audit-skill并触发。如果你使用OpenCode或类似支持指令式驱动的工具也可以直接通过/skill执行审计技能。第一次实测跑下来效果惊喜但是问题也不少。惊喜的是AI能自己组合多个文件里的信息还原出完整攻击链比如在SQL注入检测中它能追踪到参数从HTML表单进来、经过一个未使用参数化查询的DAO层、最终拼进原生SQL的完整链路。问题则主要集中在误报率偏高下一节详细说。4. 常见问题与排查技巧实录4.1 常见问题速查表现象根因解决办法报告格式不稳定时而是表格时而是段落没有把输出模板写进规则库在SKILL.md里加入“强制按模板输出”指令并把模板全文嵌入references审计结果偏向“表面文章”只罗列函数名规则文件中缺少数据流分析引导补充审计步骤要求跟踪输入来源和调用链禁止只报函数名不解释流向误报率过高把正常代码判定为漏洞规则没有区分“危险函数”和“可利用漏洞”在规则中增加“前置条件”判断只有数据源不可信时才标记为疑似漏洞上下文超限导致审计结果截断或丢失细节规则库过大一次性加载内容过多将规则按审计域拆分主文件只保留索引让Agent按需加载对应rules文件模型在“审计”和“修复”之间摇摆甚至自动改代码边界声明不明确在SKILL.md里明确写“由于存在风险本技能默认不执行任何代码修改操作只输出审计报告与修复建议”遇到非代码目标时答非所问触发条件太宽泛在元数据的description里写明适用范围例如“仅用于代码仓库、配置文件、部署脚本的审计不用于代码生成”同一份代码跑两次结论差异很大流程中缺少交叉验证步骤检查SKILL.md中的流程是否完整确定第5步交叉验证没有被省略4.2 误报率调优的经验之谈第一次测试时这个skill的报告出来我自己看着都尴尬——把正常的参数化查询误判成SQL注入把测试代码里的假密钥报成高风险把完全没有外部输入的命令执行也标成“疑似注入点”。问题出在哪里出在规则文件里没有“污染源判定”这一环。所谓污染源判定就是让模型在报洞之前先确认“这条输入到底是不是用户可控的”。我后来在规则里加了一个强制动作每个疑似风险点都先回答三个问题——这个输入变量能被外部用户修改吗修改之后能到达危险函数吗中间有校验或净化吗如果三个问题的答案都是否那就不是漏洞最多算一个风格建议。加完这个强制动作之后误报率下降了非常明显。所以如果你是第一次做类似的skill我的建议是宁可让规则文件多写一点“判定前提”也不要让AI靠关键词命中直接报风险。审计不是静态扫描器解的应该是“真实的攻击可能”而不是“代码里有这个词”的可能。4.3 让AI“论证”而非“断言”另一个值得单独拿出来说的经验是关于语言表达层面的引导。AI在不确定安全问题时很爱用“可能存在安全风险”、“建议进一步确认”这类含糊表达。初看没什么但审计报告里到处都“可能”负责人根本无从下手。我在SKILL.md的规则里专门加了一段“论证要求”所有风险描述必须是“结论证据影响”的结构禁止输出无依据的推测。举一个正确的示例结构某个接口存在水平越权原因是订单查询接口ID直接取自URL参数且后端未校验订单归属攻击者可遍历订单ID查看他人订单数据。这种输出形式比十个“建议确认”都有用。4.4 上下文管理不要一次性塞太多当前主流Agent的上下文窗口虽然很大但实际审计项目动辄几百个文件全部塞进去是不可能的。这个skill的应对策略是分轮扫描先扫入口文件路由、控制器再扫核心逻辑服务层、工具类接着扫配置与部署文件最后汇总关联。每一轮只分析一部分文件把中间结论写入临时记录最后统一生成报告。这也意味着你在给审计场景定义skill时最好在流程里明确“分批扫描”策略而不是硬让模型一口气处理整个仓库。我在SKILL.md的流程区里加了一条提示“如果目标项目文件数量超过100个请分批扫描建议顺序为入口层→业务逻辑层→数据访问层→配置与部署层。”5. 扩展方向让安全审计Skill具备真正的“职业素养”5.1 对接依赖漏洞库与代码扫描工具skill本身跑的是模型对代码的理解但它不排斥外部工具。我在后续迭代时给它加了一个“外部工具钩子”当需要识别第三方依赖漏洞时skill会建议运行pip-audit或npm audit并把命令返回的结果纳入审计报告作为“依赖安全”章节的数据支撑。为什么要这么设计因为大模型的训练数据有截止时间对于新曝出的漏洞它可能并不知道。而扫描工具用的是实时漏洞库两边正好互补。把工具结果引入报告既不牺牲模型的分析能力又能补上时效性的短板。配置方法是通过SKILL.md中的“工具调用说明”来定义让模型在审计依赖文件时按需推荐用户执行对应扫描命令再把输出喂给报告。5.2 建立团队专属审计规则库通用安全规则库永远无法完全匹配团队自己的技术栈和业务特点。比如你可能用了一套内部RPC框架它的鉴权方式和Spring Security完全不同你可能在代码里约定了一个特殊的前缀表示“内部接口”这些规则没法从通用库直接获得。我的解决方案是skill支持在references目录下增加“团队补充规则”文件。这个文件里可以写团队内部的编码规范、框架特定风险点、以及历史安全事故复盘总结。模型在审计时会把通用规则和补充规则同时作为参考。这样做的好处是审计标准从“行业通用”变成“团队通用”更贴合实际工作流。5.3 Skill与Agent的边界很多人搞不清楚skill和agent的区别。我觉得可以用一个不太严谨但好理解的说法Agent是一个“有自主行动能力的员工”而Skill是一本“岗位操作手册”。员工能做什么、能调动哪些资源由Agent层面的决策逻辑来定而具体每一步该怎么做、有什么纪律、按什么格式交付则由Skill来约束。所以当有人问我“security-audit-skill能代替安全工程师吗”我的回答是不能。它是一个很称职的“审计助理”能按照你定好的标准流程把活干得又快又规范但它不具备安全专家那种根据业务上下文灵活调整判断维度的能力。最好的使用姿态是让skill出初稿让人做终审。模型负责“全面、快速、不遗漏”人负责“定性、决策、拍板”。6. 实操心得与复盘跑通security-audit-skill之后我陆陆续续又写了几个别的场景的skill慢慢摸出了一些相对通用的方法论。这里写几条个人体会供想入坑的人参考。第一写skill最耗时间的不是写规则而是“定边界”。让AI输出一份权威感十足的偽报告很容易难的是让它清楚“什么不归自己管”。我在SKILL.md里写“不执行修复、不保证绝对安全、不替代人工专家复核”这些否定式描述花的精力比写审计流程本身还多。但效果也确实立竿见影——AI开始懂得收敛自己了。第二skill一定是一个需要持续迭代的动态文件。别指望一次写完就一劳永逸。第一次实测跑了五轮每次都手动记录失败案例再根据失败案例向规则库里补充新的分析指令这样迭代了三个版本之后整体的误报率才降到可以接受的水平。每次在上线新框架、新语言时持续往references里补一些规范化的底料skill才会越用越顺手。第三如果你准备在生产环境中用这个skill我建议你设置一个人工复核环节把重点放在高危漏洞的人工确认工序上。任何时候文档里都应当写清楚由大模型产出的审计报告只能作为辅助参考最终结论必须以安全工程师的复核为准。这既是对业务负责也是对skill能力的合理定位。最后分享一个我个人的小习惯每改一次规则我都会用同一份故意埋雷的测试项目重新跑一遍然后对比前后两次结果的差异。这个方法帮我发现了很多“改一处、崩一片”的连带问题。如果你也在做类似的东西强烈建议保留一份属于你自己的“雷区样板项目”它就是你调试skill时最趁手的工具。