1. 从security-audit-skill这个名字说起它到底在解决什么问题第一次看到security-audit-skill这个命名我的直觉是这大概率是一个面向编码智能体coding-agent的技能包而不是一个独立的扫描器。为什么这么判断因为-skill这个后缀在当下的智能体生态里已经形成了约定俗成的语义——它代表一段可被智能体加载、调用、编排的能力单元通常包含提示词模板、工具调用声明、执行流程定义这几样东西。而security-audit则明确了它的职责边界安全审计。把这两个词拼在一起含义就很清楚了让编码智能体具备执行安全审计的能力。这件事的价值在于传统安全审计工具SAST、SCA、密钥扫描大多是独立进程 报告输出的模式人要去读报告、判断优先级、再回到代码里改。而把审计能力做成智能体的 skill 之后审计这件事就被嵌进了写代码—审代码—改代码的同一个闭环里智能体可以在生成代码后立刻自查也可以在 review 阶段主动扫描甚至能结合上下文解释为什么这行有风险。我之所以对这个方向感兴趣是因为过去几年我见过太多团队的安全工具装了但没人用。SonarQube 挂在 CI 里报告红了一片开发看一眼就关掉Semgrep 规则写了几十条误报率高到大家直接忽略。问题不在于工具不好而在于审计结果和修复动作之间隔了太远。security-audit-skill这类东西试图缩短的正是这段距离。这篇文章适合三类人看一是正在给自家 coding-agent 扩展能力的工程师想知道一个安全审计 skill 该怎么设计二是安全工程师想理解智能体场景下的审计逻辑和传统 SAST 有什么不同三是技术负责人在评估要不要把安全审计接进 AI 编码流程。我会从能力边界、核心机制、实操落地、误报治理、进阶扩展几个角度把它拆开讲尽量给到能直接抄的配置和踩过的坑。需要先说明一点security-audit-skill目前没有公开的、标准化的官方规范不同团队实现差异很大。下面讲的内容一部分来自我对这类 skill 的通用理解一部分来自实际项目里落地类似能力的经验涉及具体实现的地方我会标注哪些是常见做法、哪些是我的取舍。2. 一个安全审计 skill 的能力边界它能做什么绝对不能指望它做什么2.1 它擅长的是模式识别 上下文解释不是形式化验证很多人对 AI 安全审计有个误解觉得它能像定理证明器一样把代码的所有执行路径都推一遍然后给出绝对安全或绝对有漏洞的结论。这是不现实的。智能体做审计本质上是基于模式识别和上下文推理它见过大量漏洞样本能识别出这段代码长得像 SQL 注入再结合变量来源、调用链、框架约定去判断风险是否真实存在。这个定位决定了它的强项和弱项。强项是能理解语义、能跨文件追踪数据流、能用自然语言解释风险、能给出符合项目风格的修复建议。弱项是对复杂的控制流、加密算法正确性、并发竞态这类需要严格推理的问题它的判断可靠性远不如专门的静态分析工具。我一般会把审计任务分成三档对应不同的处理策略风险类型典型例子适合交给 skill 吗原因模式明确型硬编码密钥、eval拼接、innerHTML赋值非常适合特征明显误报可控数据流依赖型SQL 注入、命令注入、路径穿越适合但需上下文要追踪污点传播智能体有优势逻辑与算法型权限绕过、加密误用、竞态条件谨慎使用需要形式化推理易漏报2.2 它和传统 SAST 的分工关系我从来不认为 skill 是要取代 SAST。两者的定位完全不同。SAST 工具比如基于 AST 和污点分析的引擎的优势是确定性、可重复、覆盖全它能把所有代码都过一遍规则命中就是命中不会因为今天模型心情不好而漏掉。缺点是误报多、不理解业务语义、修复建议生硬。skill 的优势是语义理解、上下文感知、解释能力强它能把 SAST 报出来的一堆告警做二次筛选判断哪些是真问题、哪些是误报还能结合项目实际给出可落地的修复。缺点是覆盖不稳定、有幻觉风险、成本比跑规则高。所以我的实践方案是两层过滤第一层用 SAST 或正则规则做全量粗筛把可疑点捞出来第二层用 security-audit-skill 做精筛和解释。这样既保证了覆盖率又压低了误报还省了 token 成本。这个组合我在几个项目里跑下来效果比单用任何一层都好。2.3 明确不该交给它的场景有几类事情我坚决不交给 skill 做这里也提醒一下合规性判定比如这段代码是否符合某标准某条款这需要人来做最终判断skill 只能提供参考。密钥泄露的最终确认skill 可以标记这里疑似有密钥但真伪、是否已泄露、影响范围必须人工核实。生产环境的实时拦截skill 是审计工具不是 WAF不要把它放在请求链路上做实时阻断延迟和稳定性都扛不住。提示把 skill 定位成审计助手而不是审计裁判这个心态摆正了后面很多设计决策都会顺。3. 拆开看核心机制一个审计 skill 内部到底跑了什么3.1 输入层喂给它的不只是代码一个设计良好的 security-audit-skill输入绝对不只是一段代码。我见过做得比较扎实的实现输入通常包含这几块待审代码可以是 diff、单个文件、或整个仓库的相关片段。项目上下文技术栈、框架版本、依赖清单。同样是query()调用在 ORM 框架里和在裸 SQL 拼接里风险等级完全不同。审计规则或关注点这次是查注入、查密钥、还是查权限聚焦范围能显著提升准确率。历史基线之前审过的问题、已知的误报模式用来做去重和抑制。我特别想强调项目上下文这一块。很多团队做 skill 时只把代码丢进去结果模型对框架约定一无所知把框架已经做了转义的场景也报成 XSS误报率直接爆炸。把框架信息、依赖版本一起喂进去是压低误报最有效的手段之一。3.2 分析层从看代码到追数据流分析层的核心动作我总结为三步定位可疑点 → 追踪数据流 → 评估可达性。定位可疑点靠的是模式匹配这一步和传统规则引擎类似但智能体能理解变量命名和注释能识别出这个input变量其实来自用户请求。追踪数据流是智能体的强项它可以从一个 source用户输入出发沿着赋值、传参、拼接一路追到 sink危险函数判断中间有没有经过净化。评估可达性则是判断这段代码在什么条件下会被执行是不是死代码、是不是只有管理员能触发。举个具体例子。假设代码里有这么一段def get_user(request): uid request.GET.get(id) sql SELECT * FROM users WHERE id uid return db.execute(sql)一个合格的审计 skill 应该输出uid来自request.GET不可信 source未经任何校验直接拼进 SQL 字符串无净化传入db.executesink构成 SQL 注入。同时它应该建议用参数化查询改写。而一个不合格的实现可能只会说这里用了字符串拼接可能有注入风险既没确认 source也没确认 sink这种输出对开发毫无价值。3.3 输出层报告要能直接指导修复输出层是最容易被忽视、但最影响落地效果的一环。我见过太多 skill 输出一大段该代码存在安全风险建议修复的废话。好的输出应该包含问题定位文件、行号、涉及的变量。风险类型与等级明确是注入、XSS 还是密钥泄露给出高/中/低。数据流路径从哪来、到哪去、中间经过了什么。修复建议最好直接给出改写后的代码片段。置信度明确告诉使用者这个判断有多确定方便人工复核。其中置信度这一项是我强烈建议加上的。智能体审计必然有误报与其假装自己很准不如诚实地标注高置信/需人工确认让使用者知道哪些可以直接改、哪些要再看一眼。这个设计能极大提升团队对工具的信任度。4. 落地实操把 security-audit-skill 接进编码流程的完整步骤4.1 环境与依赖准备假设你要在一个基于智能体的编码工具里挂载这个 skill准备工作大致分三块。第一块是确定 skill 的载体格式。目前主流做法有两种一种是把 skill 写成一个带元数据的目录含提示词、工具声明、示例另一种是直接作为系统提示的一部分注入。前者更规范、可复用后者更轻量、上手快。我一般推荐前者因为安全审计的提示词往往很长塞进系统提示会污染其他任务。第二块是准备审计所需的工具。skill 本身通常不直接读文件而是通过工具调用获取代码。你需要给它配好文件读取工具、代码搜索工具grep 类、依赖清单读取工具。如果要做数据流分析最好再配一个能查调用关系的工具。第三块是准备规则库和基线。把团队关注的漏洞类型整理成清单把历史误报整理成抑制规则。这两样东西是 skill 准确率的命脉比提示词写得多漂亮都重要。4.2 提示词结构的设计要点提示词是 skill 的灵魂。我踩过的坑是一开始把提示词写得太全面恨不得把所有漏洞类型都塞进去结果模型注意力被稀释每类都审得很浅。后来改成按需聚焦一次审计只关注 2-3 类风险准确率明显提升。一个我常用的提示词骨架是这样的角色你是一名代码安全审计员负责识别 [本次关注的风险类型]。 输入 - 代码片段{code} - 技术栈{stack} - 依赖版本{deps} 审计要求 1. 对每个可疑点必须确认 source不可信输入来源和 sink危险操作。 2. 追踪数据流说明中间是否经过净化处理。 3. 输出格式文件:行号 | 风险类型 | 等级 | 数据流路径 | 修复建议 | 置信度。 4. 无法确认 source 或 sink 的标记为需人工确认不要臆断。 5. 不要报告纯风格问题只报安全风险。 约束 - 如果代码中不存在本次关注的风险明确回复未发现。 - 不要为了凑数而报告低置信度问题。这里有几个细节值得说。必须确认 source 和 sink这条约束能过滤掉大量看到拼接就报注入的误报。无法确认就标记需人工确认这条给了模型一个诚实的出口避免它硬编一个结论。不要为了凑数而报告这条是针对模型总想给点东西的倾向做的抑制。4.3 触发时机什么时候调用这个 skillskill 挂上去之后什么时候触发是个关键设计。我实践下来有三种触发方式各有适用场景提交前自动触发在代码提交或生成后自动跑一遍只审 diff 部分。优点是及时缺点是可能打断流程。按需手动触发开发者主动调用审指定文件或模块。优点是灵活缺点是依赖自觉。定时全量触发每天或每周对全仓库跑一次。优点是覆盖全缺点是成本高、噪音大。我的建议是以提交前自动触发为主按需手动为辅。全量扫描交给传统 SASTskill 专注在增量代码上做深度审计。这样成本可控反馈也及时。4.4 一个完整的调用示例假设你的智能体支持通过命令调用 skill一次典型的审计调用可能长这样# 审计当前分支相对主分支的改动 audit --skill security-audit-skill \ --scope diff \ --base main \ --focus injection,secrets \ --format markdown \ --output audit-report.md跑完之后报告里应该能看到类似这样的条目src/api/user.py:42 | SQL注入 | 高 | request.GET.id - 字符串拼接 - db.execute | 建议改用参数化查询db.execute(SELECT * FROM users WHERE id %s, [uid]) | 置信度高这种颗粒度的输出开发拿到就能直接改不需要再去理解到底哪里有问题。5. 误报治理让团队愿意用下去的关键5.1 误报从哪来三个主要来源误报是安全审计工具的头号杀手。我观察下来skill 的误报主要来自三个地方。第一是上下文缺失。模型不知道框架已经做了转义不知道这个变量其实经过了校验中间件于是把安全的代码报成风险。这类误报占比最高解决靠的是把上下文喂全。第二是模式过度泛化。模型学到字符串拼接 危险于是把所有拼接都报一遍包括拼接常量、拼接已经净化的值。这类误报靠提示词约束和示例来纠正。第三是幻觉。模型凭空想象出一条不存在的数据流或者把不相关的代码关联起来。这类误报最难治只能靠置信度标注和人工复核兜底。5.2 抑制机制让误报不再重复出现治理误报的核心思路是建立抑制基线。具体做法是每次人工确认一个误报后把它记录到抑制规则里下次审计时自动跳过或降级。抑制规则的粒度可以很细比如文件 X 的第 Y 行风险类型 Z标记为误报。我一般会维护一个audit-suppressions.yaml结构大致如下suppressions: - file: src/utils/crypto.py rule: weak-hash reason: 此处使用 MD5 仅用于非安全场景的缓存键计算已人工确认 expires: 2025-12-31 - file: src/api/legacy.py rule: sql-injection line: 88 reason: 该参数已在上游中间件强制校验为整数误报注意我加了expires字段。抑制规则不能永久有效因为代码会变今天安全的写法明天可能就不安全了。定期让抑制规则过期强制重新审视是个好习惯。5.3 用置信度分层而不是一刀切与其纠结这个到底是不是误报不如用置信度把结果分层让使用者自己决定怎么处理。我的分层策略是高置信source、sink、数据流都清晰直接进修复队列。中置信部分环节需要确认进人工复核队列。低置信仅模式匹配无数据流支撑只做记录不打扰。这样团队不会被低置信的噪音淹没高置信的问题又能被及时处理。实测下来这个分层能让有效告警占比从三成提到七成以上。6. 进阶玩法把审计 skill 从能用做到好用6.1 结合依赖清单做供应链审计安全审计不只是审自己写的代码依赖里的漏洞同样是重灾区。把依赖清单比如package-lock.json、requirements.txt作为输入喂给 skill让它结合已知的漏洞模式做判断能覆盖到供应链这一层。不过要注意依赖漏洞的权威信息应该来自漏洞库skill 的角色是解释影响和给出升级建议而不是自己判断某个版本有没有漏洞。6.2 让 skill 学会项目的安全约定每个项目都有自己的安全约定比如所有数据库访问必须走 ORM、所有外部输入必须过校验层。把这些约定写进 skill 的知识库它就能判断代码是否违反了项目自身的规范而不只是通用漏洞。这类项目级审计的价值往往比通用扫描更高因为它贴合实际。6.3 审计结果的趋势追踪单次审计的价值有限把多次审计的结果存下来做趋势分析价值就上来了。比如本周新增高危问题 3 个修复 5 个、某模块连续三周有同类问题这些趋势能帮团队发现系统性的安全短板。我一般会把每次审计结果落库用一个简单的看板做可视化。6.4 和修复环节打通审计的终点是修复。如果 skill 能直接生成修复补丁甚至自动提交 PR闭环就完整了。但这里要非常谨慎自动修复必须经过人工确认才能合并。我见过自动改代码把功能改坏的案例安全修复引入功能 bug 是得不偿失的。稳妥的做法是 skill 生成建议补丁人工 review 后再合并。7. 我在实际落地中踩过的几个坑第一个坑是提示词太长导致注意力涣散。前面提过一开始我追求大而全结果每类风险都审得很浅。后来改成按需聚焦一次只审 2-3 类效果立竿见影。这个教训是skill 的能力不是靠提示词堆出来的而是靠聚焦换来的。第二个坑是忽视 token 成本。全量审计一个中型仓库token 消耗非常可观。我后来改成只审 diff、只审高风险模块成本降了一个数量级效果反而更好因为噪音少了。第三个坑是过度信任模型判断。早期我让 skill 直接输出安全/不安全的结论结果有几次把真问题判成了安全差点出事。后来改成只输出发现的问题 置信度把最终判断权交回给人风险就控住了。第四个坑是抑制规则没有过期机制。有段时间抑制规则越积越多后来发现有些已确认误报的代码早就改了抑制规则却还在导致真问题被误抑制。加上expires字段后这个问题才解决。第五个坑是没有和团队沟通清楚定位。skill 刚上线时有同事以为它能替代所有安全测试结果发现它漏报了一些逻辑漏洞就对整个方案失去信心。后来我明确跟大家说这是辅助工具覆盖的是模式明确和数据流类风险逻辑漏洞还得靠人工和专项测试。定位说清楚了接受度反而高了。8. 关于这个方向我个人的几点判断security-audit-skill这类东西本质上是把安全审计从独立环节变成编码流程的内嵌能力。这个方向我认为是对的因为安全的根本问题是发现太晚、修复太远而把审计嵌进编码闭环正好对症。但它不会是银弹。智能体审计的可靠性受限于模型能力短期内不可能替代专业的安全测试和人工审计。它最合适的定位是第一道过滤网把明显的、模式化的问题挡在前面让人工精力集中在真正复杂的逻辑漏洞上。如果你正准备做类似的东西我的建议是先把能力边界划清楚别贪大求全把上下文喂全这是准确率的命脉把置信度和抑制机制做好这是团队愿不愿意用的关键最后永远保留人工复核这一环别让自动化冲昏头脑。这套东西我前后迭代了大半年从最初的报一堆没人看到现在的报一个改一个中间踩的坑基本都写在上面的章节里了。如果你也在做类似的事希望这些经验能帮你少走点弯路。