安全审计技能包实战：如何为AI Agent构建可复用的安全审计能力

我手头有个困扰了很久的场景每次项目要上线安全审计都是临时抱佛脚团队对我提交的代码里是不是藏了硬编码密钥、某个依赖是不是已经被爆出高危漏洞这类问题完全没有掌控感。后来我决定把安全审计这套经验做成一个可供AI Agent直接加载的技能包命名为 security-audit-skill。这篇文章就把从设计思路、模块实现到接入配置的过程完整拆一遍也把我在迭代中踩过的坑一并交代清楚。如果你正在用Claude、Codex这类Agent做开发也想把手里的专业经验固化成可复用的技能文件这篇会很有参考价值。1. 安全审计这件事为什么值得做成一个技能包1.1 传统审计方式的最大问题检查靠人反馈靠催我最早接触安全审计是在一个业务系统上线前安全团队给了一份几十页的审计报告。里面有一半问题是很基础的比如某个测试环境的数据库口令被写进了配置文件、某个管理接口没做鉴权、生产环境缺少安全响应头。这类问题并不是发现不了而是太依赖审计人员逐行读代码最后往往是上线前一周集中爆发开发团队通宵修复。这种模式有两个明显的弊端。第一审计动作太靠后问题只能在代码已经完整开发后才暴露返工成本极高。第二大量审计项其实是高度重复的规则检查例如是否出现私钥块依赖锁文件里是否有已知漏洞版本CORS头是否配置为*这些完全可以在代码提交阶段就自动化完成。我当时想要的是一个能嵌入日常开发流程的轻量级安全审计员它不需要完全替代人工审计但必须能稳定地把我关心的基础检查项全部覆盖。问题在于独立的脚本只能做确定性匹配处理不了需要理解业务上下文才能判断的问题普通的对话式提示词又不可控模型会在审计中途被无关内容带偏甚至给出自相矛盾的结论。技能包这个概念正好处在两者中间。1.2 技能包与普通提示词、独立脚本的本质差异很多人容易把技能包理解成高级提示词这个理解太浅了。提示词是一次性的对话设定Agent用完就忘无法约束模型在多轮对话里始终遵循同一套流程。独立脚本则相反它能精确完成规则匹配但无法理解调用链和业务场景。技能包是把两者组合起来用规则文件承载确定性的检查逻辑用步骤文档约束模型的推理路径再用输出模板规范最终结论。顺带说清楚一个经常被混淆的问题技能和Agent是什么关系。Agent是执行体负责调度工具、管理多轮对话、决定下一步动作技能是Agent可以加载的一套行为规范加工具集。同一个Agent加载了审计技能就表现出审计专业能力加载了写作技能就表现出内容创作能力。安全审计这项工作的价值之所以能被固化成一个技能包正是因为它的核心流程相对稳定可以标准化成步骤文档同时又有大量需要专业知识判断的分支恰好适合模型介入。一旦技能包成型接入它的任何Agent都能以几乎相同的标准输出审计报告不再依赖每次对话随机生成的提示词质量。这也是我把这个项目命名为 security-audit-skill 的原因。2. 安全审计技能包的整体设计从审计任务到技能文件的结构映射2.1 技能包目录结构与每个文件的职责我在设计技能包目录时遵循的是常见的Agent Skill规范便于不同平台之间迁移。完整结构如下security-audit-skill/ ├── SKILL.md # 技能主文件Agent入口 ├── audit_steps/ │ ├── 01_define_scope.md # 审计范围界定 │ ├── 02_dependency_scan.md # 依赖漏洞排查 │ ├── 03_secret_scan.md # 密钥与敏感信息扫描 │ ├── 04_config_review.md # 配置审查 │ └── 05_injection_review.md # 注入类风险分析 ├── rules/ │ ├── secret_patterns.json # 密钥正则规则库 │ ├── security_headers.yaml # Web安全头检查规则 │ └── risk_levels.yaml # 风险等级判定参考 ├── scripts/ │ ├── scan_deps.py # 依赖锁文件解析与漏洞比对 │ └── secret_scan_regex.py # 高信噪比密钥正则扫描 ├── templates/ │ └── security_report.md # 审计报告输出模板 └── ignore_security_items.yaml # 白名单列表SKILL.md是整个技能包的门面Agent加载技能时首先读取它。audit_steps目录存储审计步骤文档每个步骤对应一个独立的Markdown文档rules目录存放能被脚本直接读取的结构化规则比如正则表达式和风险等级阈值scripts目录放执行确定性检查的脚本templates目录负责锁定最终报告的结构。这个结构有一个核心设计原则步骤文档与规则文件彻底分离。步骤文档是给模型读的自然语言说清楚这一步要检查什么、怎么判断、什么时候算完成规则文件是给脚本读的结构化数据说清楚匹配到什么模式才算命中。为什么要分离因为我试过把正则直接写进步骤文档里模型会机械地去套字符串忽略上下文误报率立刻飙升。另一个细节是审计步骤按数字前缀排序。模型虽然能并行读取多个文档但给它一个明确的执行顺序输出稳定性会明显提升。无序的步骤文档会让模型随机挑检查点导致报告逻辑跳跃。2.2 审计流程的编排把人工审计经验翻译成步骤安全审计本身就是一套成熟的方法论我的技能包把流程编排成五个阶段范围界定、依赖检查、密钥扫描、配置审查、注入类分析。范围界定是我最强调的一步也是最容易被忽视的一步。没有范围界定的审计模型会尝试审查整个仓库既浪费上下文窗口又让结论变得空泛。我在步骤文档里明确要求模型先读取项目目录结构、锁定当前审计对象涉及的文件集合同时把静态资源、构建产物目录列入排除清单。每个步骤文档都包含三个要素输入、处理动作、输出物。输入说明这一步需要读取哪些文件或脚本结果处理动作说明模型需要执行哪些分析输出物说明这一步最终应产出什么内容。项目里大概4到5个步骤文档每个文档控制在200到300行之间太长了模型容易在后面忘记前面的要求。2.3 双轨制规则设计为什么脚本和模型各干一半设计安全审计技能时我反复纠结过一个问题风险判断到底交给脚本还是模型。单独交给模型自然语言理解能力强但会漏掉一些简单的格式特征单独交给脚本精确但死板无法处理业务逻辑。最终我采用了双轨制确定性规则由脚本执行语义判断由模型完成。以密钥泄漏检测为例。脚本先跑一遍高信噪比正则命中后输出候选风险点。模型拿到候选列表后逐个分析上下文确认变量名、使用位置、是否真的会被提交到外部仓库然后才给出最终风险等级。这个流程同时发挥了脚本的高覆盖率和模型的语境理解能力。规则文件的具体编写质量会直接影响技能效果的上下限。我会在下一节展开说明。3. 核心模块逐一拆解从依赖漏洞检查到敏感信息扫描3.1 依赖与第三方库的漏洞排查依赖漏洞排查是每一次安全审计的第一道硬性检查原因很简单现代应用一半以上的攻击面来自第三方库而这些库的漏洞信息通常是公开的稍微一查就能发现风险。这部分工作非常适合自动化因为锁文件是确定性的包名和版本号白纸黑字写在里面。我的实现方式是让Agent先读取项目里的锁文件。不同生态对应的文件名不一样Node项目看package-lock.jsonPython项目看requirements.txt或poetry.lockGo项目看go.mod和go.sum。读取之后脚本scan_deps.py负责解析出包名和版本然后到漏洞数据里做比对。这里有一个容易踩的坑直接比对版本号字符串是完全不够的。漏洞库里的受影响版本通常是一个区间比如某个CVE影响1.0.0到1.4.2之间的所有版本而不是只影响某一个精确版本。脚本必须把包版本解析成可比较的结构化对象再判断当前版本是否落在受影响的区间里。脚本运行结束后会输出三行结构化信息包名、当前版本、建议修复版本。模型拿到这三行信息后结合项目对库的依赖程度来判断优先级。比如某个库只在开发阶段被使用完全不暴露在公网即使版本匹配到漏洞实际受攻击面也很小模型可以把风险等级从高危降为中危或者提示。3.2 敏感信息与密钥泄漏扫描密钥泄漏扫描是安全审计里最考验规则设计能力的模块。这个模块的难点从来不是能不能匹配到而是匹配到的内容到底是不是真实密钥。初版技能在这里翻过车我用了非常宽泛的匹配规则结果项目里所有Base64编码的配置项都被标记成高危密钥整个审计报告失去参考价值。痛定思痛后我把密钥扫描分成两层。第一层是确定性规则采用信噪比很高的正则模式命中后基本可以确定是真实密钥。我维护了以下几类典型模式贴在规则文件里作为示例{ private_key_block: { pattern: -----BEGIN (RSA|EC|OPENSSH|DSA) PRIVATE KEY-----, confidence: high, description: 私钥块 }, aws_access_key: { pattern: AKIA[0-9A-Z]{16}, confidence: high, description: AWS Access Key ID }, github_token: { pattern: ghp_[A-Za-z0-9]{36}, confidence: high, description: GitHub Personal Access Token }, generic_password_assignment: { pattern: (password|passwd|secret|api_key|apikey)\\s*[:]\\s*[\][^\][\], confidence: requires_review, description: 口令赋值模式需人工复核 } }第一层命中high置信度的模式脚本直接输出告警命中requires_review的模式脚本只把它放进候选列表不直接定性。第二层是疑似密钥高熵字符串、超过16位的随机字符等。这层必须由模型结合上下文判断看变量名、看出现位置、看是否真的被使用。规则文件里会把这类模式标记为requires_review: true模型看到这个标记之后不会直接下结论而是主动去追上下文。3.3 配置审查Web安全头、CORS、权限配置配置审查是checked规则最直接的模块因为它几乎不需要理解语义查字典就能完成。我把常见检查项写进rules/security_headers.yaml里脚本负责提取项目的配置内容并逐条比对模型负责解释风险影响并给出修复建议。检查项风险含义期望值Strict-Transport-Security未启用HTTPS强制传输max-age不低于15552000Content-Security-Policy缺失会导致XSS缓解能力下降存在且未使用unsafe-inlineAccess-Control-Allow-OriginCORS配置过宽可能导致跨域读取不能为*且不随Origin回显管理接口路径鉴权缺少鉴权可能导致越权必须经过鉴权中间件这个模块我给每个检查项都加了一个业务影响说明字段。不要小看这个字段——它决定了模型输出的报告到底是只说一句缺少CSP头还是能进一步解释缺了这个头在什么攻击场景下会被利用。前者是查字典后者才是审计。3.4 注入类风险分析与代码审计要点注入类检查是最难模块化的部分SQL注入、命令注入、路径穿越都需要完整的调用链理解。脚本在这个环节几乎帮不上忙因为注入漏洞的本质是数据流问题用户输入是否经过了危险函数并且没有被有效过滤或参数化。技能在这个阶段要求模型执行一套固定的分析路径。先找出所有网络入口包括Controller、路由处理函数、API Handler然后追踪外部参数流入的方向再对流入终点做判断看是否进入了query、exec、eval、shell、拼接命令这类敏感函数最后检查数据流路径上是否存在参数化查询、白名单校验或转义处理。为了防止模型在分析过程中偷懒我在步骤文档里强调了一个证据链要求凡是判定为风险的项必须给出从入口点到危险函数的完整调用关系。审计报告里如果出现存在SQL注入风险却没有任何代码路径佐证那就是无效结论宁可删除也不能保留。这条规则让技能输出的可信度提升了非常多。4. 接入Agent的实操配置让模型按技能节奏走4.1 技能包在Agent中的加载与触发方式技能包做好之后接进Agent的方式目前我接触到的有两种显式配置和斜杠命令触发。显式配置是在Agent的配置文件里列出技能目录启动时自动加载适合每个项目默认必须审计的场景。斜杠命令触发则是让用户在对话里输入/security-auditAgent才会进入审计模式适合只在需要时调用的场景。我实际用的方案是两者的中间态默认不启用审计技能但在CI流水线的指定阶段自动带上技能目录。这样既能保证每次代码提交后都能自动跑一轮基础审计又不会让Agent在日常开发对话里自作主张地反复扫描代码。4.2 SKILL.md主文件的字段设计与提示词编写SKILL.md是技能包的核心我维护过非常多版本最终结构固定为四块元信息、目标定义、执行步骤、输出要求。元信息部分记录技能ID、适用场景、禁用场景。技能ID决定了Agent在什么场景下会想起加载它禁用场景用来防止误用比如我会注明本技能不适用于基础设施层面的网络架构审计。目标定义部分要求写得非常窄只做减法不做加法。比如我的技能目标定义是负责代码安全风险识别不负责漏洞修复不负责合规报告生成边界划得越清楚后面麻烦越少。否则模型会在审计到一半时顺着话题去教你怎么修漏洞、怎么做合规把审计主线丢掉。执行步骤部分的写法和纯提示词有本质区别。我给每个步骤都配了终止条件——满足什么条件后才可以进入下一步。依赖扫描步骤的终止条件很明确锁文件全部被解析完成或者确认项目没有使用任何第三方依赖。没有终止条件的步骤列表本质上还是提示词。模型会因为找不到什么时候该结束而持续输出冗余分析或者跳过后续步骤草草收尾。输出要求部分直接引用报告模板模型必须按模板输出这是为了减少自由发挥空间。报告结构我在4.3节给出。4.3 审计报告的格式化输出审计报告是给别人和下游工具看的格式必须稳定可解析。我的模板定义为五个部分审计范围、风险总览、风险明细、未发现问题的检查项、附录。# 安全审计报告 ## 审计范围 - 仓库路径 - 分支 - 提交范围 - 审计的文件列表 ## 风险总览 | 严重级别 | 数量 | | --- | --- | | 高危 | 0 | | 中危 | 0 | | 低危 | 0 | | 提示 | 0 | ## 风险明细 ### [高危] 风险标题 - 位置 - 风险类型 - 证据链 - 修复建议 ## 未发现问题的检查项 - [ ] 依赖漏洞检查 - [ ] 密钥泄漏检查 - [ ] 配置审查 - [ ] 注入类分析 ## 附录白名单排除项最后加了一个未发现问题的检查项清单。很多AI审计报告默认只列问题不列检查完但没问题的项导致阅读者无法判断模型是否真的完成了对应检查。强制模型列出已检查项反而能减少漏检因为模型在向读者汇报我做完了的时候会更诚实地面对自己的扫描过程。5. 实测效果与误报治理审计技能最关键的可信度问题5.1 在自己项目上的真实审计效果我用自己一个接入MySQL的Python后端项目做了实测。项目规模不算大40个文件左右。依赖扫描阶段锁文件解析耗时不到2秒命中了一个已知漏洞的旧版本库。密钥扫描命中3个可疑点其中1个经过模型确认是真实的测试环境数据库口令泄漏另外2个是配置文件中以password命名的非敏感字段。配置审查阶段发现CORS头设置过宽Access-Control-Allow-Origin被设成了*对于一个需要处理用户数据的项目来说这属于中危问题。还有一个命令注入误报的案例让我印象很深。代码里有一段把外部输入拼接到subprocess.call的调用表面看上去就是标准的命令注入模式。但模型在证据链要求下继续追发现输入在进入subprocess.call之前经过了一层白名单校验能可靠地限制可执行命令集合于是把风险等级从高危降为了提示。这个案例恰好说明了双轨制的价值脚本负责找出可疑点模型负责判断上下文。5.2 误报的三个主要来源与治理方法误报是安全审计技能落地过程中最影响体验的问题我在迭代中总结了三个主要来源。第一正则规则过于宽泛。这是最基础的问题治理方式是把规则分成确定性规则和需复核规则两层。确定性规则匹配到了可以直接输出结论需复核规则只作为候选由模型二次确认。第二模型对当前项目上下文理解不足。比如项目README里明确写了这些是测试密钥仅用于本地开发模型还是会把这些密钥当成泄漏报警。治理方式是在审计步骤开始时要求模型先读取README和项目维护文档把文档中明列的已知问题加入白名单。第三模型对风险等级的判断不稳定。同一个问题这次报高危下次报中危这对使用者的信任度影响很大。治理方式是在rules/risk_levels.yaml中加入等级判定参考表比如直接可被外部访问且无鉴权的敏感接口高危内部工具接口缺少鉴权中危开发环境配置项过期提示。模型在判定时先查表再结合实际上下文等级稳定度高了很多。5.3 白名单机制与上下文消歧白名单是治理误报最有效的机制我设计了ignore_security_items.yaml文件紧挨着rules目录。文件里记录两类条目项目级白名单和全局白名单。项目级白名单记录当前仓库的特殊情况比如CI脚本中故意使用的测试密钥全局白名单记录通用易混淆模式比如常见代码示例中出现的示例API Key。白名单条目必须包含一个原因字段。我明确在技能说明里写过没有任何原因的白名单是不可接受的因为三个月后没有人能想起来当初为什么排除它。技能加载白名单时会要求模型把每条白名单的排除原因写进审计报告附录让整个审计结果经得起推敲。6. 复盘做技能包时踩过的坑和迭代经验6.1 坑1审计粒度设置不当导致无效结论初版技能我让模型对整个仓库做全面审计结果模型试图覆盖所有文件输出的全是一些正确的废话比如建议使用参数化查询建议增加输入校验完全没法用。后来我把审计范围从全仓库改成本次变更涉及的代码路径以及与它们直接关联的入口点结论质量立刻提升了一个档次。审计不是越全越好而是越聚焦越好。一个功能点一个功能点地审比一次审整个系统要可靠得多。6.2 坑2技能上下文过长导致模型失忆技能包里的文件越来越多SKILL.md加上五六个步骤文档再加上规则文件模型一次性需要读取的内容变得很长。结果是在审计到后半段时模型会忘记前面步骤的要求出现前后矛盾。我用了三个办法解决。第一步骤文档只保留检查要点具体正则全部放进脚本读取的规则文件不占用模型的上下文窗口。第二关键要求在SKILL.md里反复出现比如所有结论必须附证据链这条我不放心只写在某个步骤文档的深层SKILL.md里也要写一遍。第三要求模型在每个审计阶段结束时输出一次中间结论摘要把模型的注意力拉回来。最终报告基于每个阶段的摘要生成而不是在最后一次性总结全流程。这个调整对报告质量的提升非常显著。6.3 坑3让模型自由发挥审计顺序的后果有一版我为了给模型更大的自主性没有严格强调步骤顺序。结果模型在执行过程中跳来跳去一会儿检查依赖一会儿检查CORS导致报告结构混乱阅读者很难跟踪每个结论的推导过程。加入数字前缀和终止条件之后情况稳定了很多。这件事带给我的启发是技能包的核心价值不一定是给模型更多知识而是给模型一套明确的行为边界。安全审计这种强流程任务自由度越高烂尾的风险越大。6.4 后续迭代想法从审计工具走向审计顾问现在这个技能包已经能稳定完成基础审计工作但我还在迭代两个方向。一个是把误报治理的经验持续沉淀进规则库每次人工确认一条误报就把对应的模式加入排除列表。另一个是考虑加入威胁建模步骤让模型在正式审计之前先根据项目的业务场景规划哪里最可能被攻击再从高价值攻击面开始审计。如果这一步跑通这个技能的定位就不再只是一个检查工具而更像一个会先思考再动手的安全审计顾问。我的经验是做技能包和做产品一样都是一个持续迭代的过程。初版跑通永远只是开始规则库的积累、白名单的完善、输出模板的打磨才决定它在真实项目中到底能不能被信任。