security-audit-skill 实战：为 coding agent 注入安全审计能力

1. 从"security-audit-skill"这个名字说起：它到底在解决什么问题

第一次看到security-audit-skill这个命名，我的直觉是：这不是一个普通的脚本或者工具包，而是一个面向coding agent场景的"技能模块"。命名里带skill这个词，基本可以判断它是给 AI 编码助手（coding agent）挂载的能力单元——就像给一个刚入职的工程师发一本《安全审计作业手册》，让他知道在写代码、审代码的时候该盯哪些点。

为什么我这么判断？因为最近一年，coding agent 的生态里出现了一个明显的趋势：大家不再满足于"能写代码"，而是开始要求"写得安全"。一个 agent 如果只会堆功能，却对注入、越权、敏感信息泄露毫无感知，那它在真实项目里就是个定时炸弹。security-audit-skill要解决的，正是这个痛点——把安全审计这件事，从"事后人工排查"变成"agent 在编码过程中就能主动执行的动作"。

它适合谁用？三类人最该关注：一是正在搭建 coding agent 工作流的开发者，你需要给 agent 加装安全能力；二是团队里的安全负责人，你想把审计规则固化下来而不是靠人肉记忆；三是独立开发者，你没有专职安全团队，但希望自己的项目别在基础安全问题上翻车。

这篇文章我不打算写成一份干巴巴的 API 文档，而是按照我实际落地这类 skill 的思路，把"它是什么、为什么这么设计、怎么用、坑在哪"讲透。你读完应该能自己动手把类似的安全审计能力接进自己的 agent 流程里。

2. 拆解 security-audit-skill 的能力边界

2.1 它审计的到底是什么：三个层次的安全问题

很多人一听"安全审计"就想到渗透测试、漏洞扫描，其实在 coding agent 这个语境下，security-audit-skill覆盖的范围要更聚焦、更贴近代码本身。我把它拆成三个层次，这样你在设计或使用的时候心里有数。

第一层是代码级缺陷。这是最基础也最高频的，比如硬编码的密钥、SQL 拼接、命令注入、路径穿越、不安全的反序列化。这类问题的特点是：单看某一行代码就能判断出风险，不需要理解整个业务上下文。agent 做这类审计的准确率相对高，因为规则明确。

第二层是逻辑级缺陷。这就麻烦一些了，比如权限校验缺失、越权访问、竞态条件、业务规则绕过。这类问题往往要跨多个函数甚至多个文件才能看出来，对 agent 的上下文理解能力要求很高。security-audit-skill在这层的价值，更多是"提示可疑点"而不是"直接定罪"。

第三层是配置与依赖级问题。包括依赖库的已知问题版本、不安全的默认配置、过宽的权限声明、暴露的调试接口等。这层其实很适合自动化，因为大部分判断可以靠比对规则库完成。

提示：不要指望一个 skill 能把三层都做到 100% 准确。我的经验是，代码级缺陷可以做到高召回，逻辑级缺陷重点在"不漏报可疑点"，配置级问题则要保证规则库及时更新。

2.2 为什么是"skill"而不是"tool"：设计哲学上的关键区别

这里有个容易被忽略的点：为什么它叫skill而不是scanner或者linter？这个命名差异背后是两种完全不同的工作模式。

传统的安全扫描工具是被动触发的——你写完代码，跑一遍扫描，看报告。而 skill 是主动嵌入的——agent 在生成代码、修改代码、审查代码的每一个环节，都可以调用这个能力。换句话说，tool 是"事后体检"，skill 是"随身医生"。

这个区别带来的实际影响很大。举个例子，当 agent 要生成一段数据库查询代码时，如果它内置了 security-audit-skill，它可能在写的时候就避开了字符串拼接，直接用参数化查询。而如果是事后扫描，你得先让它写错，再扫描出来，再改——多了一轮返工。

我在实际项目里对比过这两种模式，嵌入式的 skill 模式在"首次生成即安全"的比例上明显更高。当然代价是 agent 的推理链路变长了，每次生成都要多走一步安全判断，响应速度会慢一些。这个取舍后面我会细讲。

2.3 和普通代码审查的区别：审计视角 vs 功能视角

还有一个常见误解：觉得代码审查（code review）里已经包含安全审查了，为什么还要单独搞一个 skill？

区别在于视角。普通 code review 的主线是"这段代码能不能正确实现功能"，安全只是顺带看一眼。而 security-audit-skill 的主线是"这段代码在恶意输入、异常调用、越权访问下会怎样"，功能正确性反而退居其次。

举个具体例子。一段用户查询接口，功能审查关注的是"参数传对了没、返回结构对不对"；安全审计关注的是"这个 user_id 是不是从 session 里取的、能不能被前端篡改成别人的 id、查询有没有做租户隔离"。同一个函数，两种视角看出来的问题完全不同。

所以security-audit-skill不是 code review 的替代品，而是补充。它强迫 agent 切换到"攻击者思维"，这是普通审查做不到的。

3. 把 security-audit-skill 接进 coding agent 的完整流程

3.1 环境与前置准备：别急着写规则

在动手之前，有几件事必须先理清楚，否则后面会反复返工。

第一，确定你的 agent 框架支持 skill 挂载机制。不同的 coding agent 框架对"技能"的支持方式不一样，有的通过插件系统，有的通过 prompt 模板注入，有的通过工具调用（tool call）注册。你得先搞清楚你的框架是哪种。如果是 tool call 模式，那 security-audit-skill 本质上就是注册一个可被调用的审计函数；如果是 prompt 注入模式，那它更多是一套规则文本加示例。

第二，准备好你的规则来源。安全审计的核心是规则，规则从哪来？我的建议是三层来源：通用规则（比如 OWASP 那套经典清单）、语言/框架特定规则（比如某个 Web 框架的常见坑）、团队内部规则（你们自己踩过的坑）。前两层可以找现成的，第三层必须自己积累。

第三，明确审计的触发时机。是在 agent 生成代码后自动触发，还是等用户显式要求"帮我审一下"？这个决定了 skill 的调用频率和性能开销。我一般建议：生成阶段做轻量级实时检查（只查高危项），提交前做一次完整审计。

注意：不要一上来就把所有规则全开。规则越多，误报越多，agent 越容易被噪音带偏。先从最高危的十几条开始，跑顺了再逐步加。

3.2 规则的组织方式：结构化比自然语言更靠谱

规则怎么组织，直接决定了审计效果。我试过两种方式，差别很大。

方式一：自然语言描述规则。比如"检查代码中是否存在硬编码的密码"。这种方式写起来快，但 agent 执行时理解不稳定，同一段代码两次审计可能给出不同结论。

方式二：结构化规则。每条规则包含：规则 ID、风险等级、匹配模式（正则或 AST 模式）、正例、反例、修复建议。这种方式前期投入大，但执行稳定、可追溯、可测试。

我现在的做法是混合：用结构化规则处理能明确匹配的（比如硬编码密钥、危险函数调用），用自然语言规则处理需要语义理解的（比如权限校验逻辑）。下面是一个结构化规则的示例：

rule_id: SA-001 name: 硬编码凭证 severity: high pattern: '(password|passwd|secret|token|apikey)\s*=\s*["''][^"'']{6,}["'']' languages: [python, javascript, java, go] example_bad: 'db_password = "admin123456"' example_good: 'db_password = os.environ["DB_PASSWORD"]' fix_hint: 改用环境变量或密钥管理服务读取

这种规则的好处是，你可以直接拿它做单元测试——喂正例应该命中，喂反例不应该命中。规则库有了测试，才敢放心地让 agent 自动执行。

3.3 审计结果的呈现：怎么让 agent 和人都看得懂

审计跑完了，结果怎么给出来，这里也有讲究。我见过两种失败案例：一种是结果太啰嗦，agent 被淹没在几十条低危提示里，反而忽略了真正的高危问题；另一种是结果太简略，只说"有安全问题"却不给位置和修复方案，等于没说。

我的做法是分级 + 定位 + 修复建议三件套。每条审计结果包含：

• 风险等级（critical / high / medium / low）
• 精确位置（文件、行号、涉及的代码片段）
• 问题说明（一句话讲清楚风险是什么）
• 修复建议（给出可直接替换的安全写法）

这样 agent 拿到结果后，能直接决定"这条要不要改、怎么改"，而不是再去猜。对于 critical 和 high 级别的问题，我一般会让 agent 强制中断当前流程，先修复再继续；medium 和 low 则记录到报告里，批量处理。

3.4 一个最小可用的接入示例

说了这么多原理，给一个能跑起来的最小示例。假设你的 agent 框架支持注册工具函数，那 security-audit-skill 的核心就是一个审计函数：

import re RULES = [ { "id": "SA-001", "severity": "high", "pattern": re.compile(r'(password|secret|token)\s*=\s*["\'][^"\']{6,}["\']'), "message": "疑似硬编码凭证", "fix": "改用环境变量或密钥管理服务" }, { "id": "SA-002", "severity": "critical", "pattern": re.compile(r'(execute|query)\s*\(\s*["\'].*%s.*["\']\s*%'), "message": "疑似 SQL 字符串拼接", "fix": "改用参数化查询" }, ] def security_audit(code: str) -> list: findings = [] for rule in RULES: for match in rule["pattern"].finditer(code): line_no = code[:match.start()].count("\n") + 1 findings.append({ "rule_id": rule["id"], "severity": rule["severity"], "line": line_no, "snippet": match.group(0), "message": rule["message"], "fix": rule["fix"] }) return findings

这个示例很粗糙，但骨架是完整的：规则定义、匹配、定位、输出。你可以在此基础上加 AST 解析、加语言判断、加规则库热加载。关键是先跑通链路，再优化规则质量。

4. 实测中踩过的坑和对应的处理办法

4.1 误报把 agent 带偏：一次真实的排查过程

我印象最深的一次，是 agent 在审计时把一段完全正常的代码标成了高危。那段代码大概是这样的：

token = generate_token()

规则匹配到了token =这个模式，判定为"硬编码凭证"。但实际上generate_token()是动态生成的，根本不是硬编码。问题出在哪？出在规则只看了赋值语句的左边，没看右边是不是字面量。

这个坑的排查链路是这样的：先看审计报告，发现误报集中在"变量名含 token/password 但值是函数调用"的场景；然后回看规则，发现正则只匹配了变量名 = 值的结构，没有约束"值必须是字符串字面量"；最后修正规则，把匹配模式改成必须包含引号包裹的字面量。

修正后的规则：

re.compile(r'(password|secret|token)\s*=\s*["\'][^"\']{6,}["\']')

关键就是那个["\']，强制要求右边是引号包裹的字符串。这一改，误报率直接降下来了。

提示：写安全规则时，"变量名"永远不能作为唯一判据。变量名叫 password 不代表它就是密码，得看它的值从哪来。

4.2 上下文丢失：为什么单文件审计会漏掉越权问题

第二个坑更隐蔽。有次 agent 审计一个接口，单看这个文件完全没问题——参数校验、类型检查都做了。但实际这个接口存在越权漏洞，因为权限校验是在另一个中间件里做的，而这个接口的路由配置漏挂了那个中间件。

单文件审计根本发现不了这种问题，因为问题不在代码本身，而在"代码之间的连接关系"。这就是前面说的逻辑级缺陷的典型特征。

我的处理办法是：对于逻辑级审计，不能只喂单个文件，要把相关的路由配置、中间件、权限定义一起喂给 agent。具体做法是，在调用 security-audit-skill 时，除了目标文件，再附带一份"上下文包"——包含路由表、中间件列表、权限模型定义。agent 拿到这些，才能判断"这个接口该有的校验到底有没有"。

这个改动让审计的输入变大了，token 消耗也上去了，但对于涉及权限、认证的代码，这个投入是值得的。我的经验是：代码级审计可以单文件，逻辑级审计必须带上下文。

4.3 规则库更新滞后：依赖问题怎么持续跟进

第三个坑是时间维度的。依赖库的已知问题版本是不断更新的，如果你的规则库是静态的，那它很快就会过时。我一开始就是手动维护一份依赖黑名单，结果两个月后发现有新披露的问题版本没加进去。

后来我改成半自动：规则库里存的是"查询逻辑"而不是"固定名单"，agent 审计依赖时，实时去查权威的漏洞数据库。当然这里要注意，查询要有限流和缓存，不能每次审计都全量拉取。

对于没有条件接实时数据库的场景，我的建议是至少做到"定期更新 + 版本标记"。规则库带上更新日期，审计报告里注明"基于 X 月 X 日的规则库"，这样至少你知道自己的审计结论有多新。

4.4 性能与安全的平衡：审计频率怎么定

最后一个坑是性能。全量审计很慢，尤其是大项目。我试过每次 agent 生成代码都跑全量审计，结果响应时间从几秒涨到几十秒，体验很差。

后来我做了分级触发：

这个分级策略的核心思路是：高频操作只查最致命的，低频操作才做全面检查。这样既保证了"生成即安全"的底线，又不至于拖垮日常体验。

5. 让 security-audit-skill 真正产生价值的几个进阶思路

5.1 从"发现问题"到"教会 agent 避免问题"

skill 的最高价值不是审计出多少问题，而是让 agent 逐渐不需要被审计。怎么做到？我的做法是把审计结果反哺到 agent 的生成阶段。

具体来说，每次审计发现的问题，如果属于"重复犯"的类型，就把它提炼成一条生成时的约束。比如 agent 老是忘记给数据库查询加参数化，那就在生成 SQL 相关代码的 prompt 里，预先注入"必须使用参数化查询"的约束。这样 agent 在写的时候就避开了，而不是写完再被审计出来。

这个思路本质上是把"审计规则"和"生成规则"打通。审计是后验，生成约束是先验，两者共享同一套知识库。我在项目里这么做了之后，同类问题的重复出现率明显下降。

5.2 审计规则的分层维护：通用、框架、团队

规则库怎么维护才能不混乱？我的经验是分三层，各管各的。

通用层放跨语言、跨框架的经典问题，比如硬编码凭证、命令注入、路径穿越。这层相对稳定，更新频率低。

框架层放特定框架的坑，比如某个 Web 框架的模板注入、某个 ORM 的批量赋值问题。这层跟着框架版本走，需要定期更新。

团队层放自己踩过的坑。这层最有价值，因为它是你团队特有的教训。我建议每次线上出了安全问题，复盘后都往这层加一条规则。时间长了，这就是你们团队的安全资产。

三层规则的优先级是：团队层 > 框架层 > 通用层。因为越贴近你实际场景的规则，越应该优先执行。

5.3 审计报告的可追溯性：为什么要留痕

最后说一个容易被忽略但很重要的点：审计报告要留痕。

为什么？因为安全审计不只是"当下发现问题"，还要能回答"这个问题是什么时候引入的、谁引入的、之前审过没有"。如果审计结果不留存，你就没法做趋势分析，也没法在出事后快速定位。

我的做法是每次审计结果都结构化存储，带上时间戳、代码版本、规则库版本。这样你可以随时查"某个文件的历史审计记录"，也能统计"哪类问题反复出现"。这些数据反过来又能指导你优化规则库——反复出现的问题，说明生成阶段的约束没做到位。

留痕还有个好处是应对合规要求。很多场景下，你需要证明"我们对代码做了安全审计"，一份完整的审计记录就是最好的证据。

5.4 一个我常用的规则自检清单

最后分享一份我维护规则库时用的自检清单，每次加新规则都过一遍：

• 这条规则有没有正例和反例？反例能不能通过？
• 规则的匹配范围会不会太宽导致误报？
• 修复建议是不是具体可执行，而不是"请注意安全"这种废话？
• 这条规则属于哪一层（通用/框架/团队）？
• 它和现有规则有没有重叠或冲突？
• 规则库版本号更新了吗？

这份清单看着简单，但能挡掉大部分"加了规则反而添乱"的情况。规则库的质量比数量重要得多，十条精准的规则胜过一百条模糊的规则。

我在实际落地 security-audit-skill 这类能力时最大的体会是：它的价值不在于"能扫出多少漏洞"，而在于"把安全思维固化进了 agent 的工作流"。当 agent 每次写代码都习惯性地想一下"这里会不会有安全问题"，这个 skill 才算真正发挥了作用。规则可以慢慢补，流程先跑起来，剩下的都是迭代的事。