1. 从零拆解 security-audit-skill一个安全审计 Agent 的完整设计思路第一次看到security-audit-skill这个标题我脑子里蹦出来的不是“又一个安全扫描脚本”而是一个更具体的问题怎么把一个安全审计员的判断流程封装成一个 Agent 能反复调用、能产出结构化结论的 skill这两件事差别很大。扫描脚本只负责跑规则、吐告警而 skill 要负责的是“知道自己在查什么、查到什么程度算完、结论怎么落地”。我最近在几个内部项目里反复折腾这类东西从最初的“写个脚本扫一遍”到后来演变成一套带findings.json和coverage-ledger.json双产物的审计 skill中间踩的坑足够写一篇长文。这篇就围绕security-audit-skill这个标题把它的核心领域、潜在需求、技术点和落地方式完整拆一遍。适合谁看如果你正在做 agent 开发、想给自己的 agent 加一个安全审计能力或者你本身就是做安全、想把经验沉淀成可复用的 skill那这篇基本能直接抄作业。先说清楚这个 skill 到底解决什么问题。传统安全审计有三个老大难第一覆盖度不可见——你扫了哪些文件、哪些接口、哪些依赖没人说得清最后只能靠一句“我扫过了”交差第二结论不可复现**——同一个项目换个人审结论可能完全不一样第三产出不可消费——审计报告是给人看的散文agent 拿到之后没法继续处理。security-audit-skill的核心价值就是用findings.json解决“结论结构化”用coverage-ledger.json解决“覆盖度可追溯”让安全审计从一次性人工动作变成一个 agent 可以稳定调用的能力单元。这里要先厘清一个高频混淆点skill 和 agent 到底什么关系。热词里“skill和agent的区别”被反复搜说明很多人卡在这一步。我的理解很直接agent 是“会做决策的执行者”skill 是“被调用的能力包”。agent 负责决定“现在要不要做安全审计、审哪个模块、审完要不要修”skill 负责“给定输入按固定流程产出固定格式的结果”。security-audit-skill就是一个典型的 skill——它不自己做决策它只保证“你让我审我就审得全、审得准、审得可追溯”。这个边界划清楚后面所有设计都顺了。2. 核心需求解析为什么安全审计必须做成 skill 而不是脚本2.1 从“扫描脚本”到“审计 skill”的认知升级大部分人做安全审计的第一反应是写脚本遍历目录、匹配正则、输出一堆疑似问题。我早期也这么干结果很快撞墙。脚本的问题是它只有“执行”没有“判断”。比如你扫到一个eval()调用脚本只会报“发现危险函数”但真实审计里你要判断的是这个eval的输入是不是用户可控有没有前置的白名单校验它所在的代码路径是不是死代码这些判断脚本做不了只有具备推理能力的 agent 才能做。所以security-audit-skill的定位不是替代脚本而是给 agent 一套标准化的审计作业流程。脚本负责“找线索”skill 负责“定流程”agent 负责“下判断”。三者分工明确。这也是为什么热词里“agent skill”“skill插件”“codex skill”这些词会火——大家逐渐意识到光有 agent 不够还得有高质量的 skill 喂给它agent 才能干出专业活。2.2 findings.json 与 coverage-ledger.json 的双产物设计这个 skill 最核心的设计决策就是产出两个文件而不是一个。很多人会问为什么不能把覆盖度信息塞进 findings 里我试过结果是文件结构混乱消费方要写一堆判断逻辑才能区分“这是一条漏洞”还是“这是一条覆盖记录”。拆成两个文件之后职责立刻清晰findings.json审计结论。每一条都是一个具体的、可定位、可复现的问题包含位置、类型、严重级别、证据、修复建议。coverage-ledger.json审计台账。记录这次审计到底覆盖了哪些范围、每个范围的状态已审/跳过/待定、跳过原因、审计深度。这个设计的精妙之处在于它把“我审出了什么”和“我审了哪些”彻底解耦。findings.json回答“有没有问题”coverage-ledger.json回答“这次审计可不可信”。一个没有 coverage ledger 的审计结论本质上是不敢信的——因为你不知道它是“真的没问题”还是“根本没审到”。2.3 覆盖度台账为什么是审计可信度的命门我举个真实场景。有次团队做上线前审计findings 里干干净净大家准备放行。结果我翻了一下 coverage ledger发现payment/目录状态是skipped原因是“文件过大超时”。也就是说整个支付模块压根没审。如果没有这个台账这个漏审就会被“零 findings”掩盖过去后果不堪设想。这就是coverage-ledger.json的价值它让“没审到”这件事变得可见。审计的可信度不取决于你审出了多少问题而取决于你能不能说清楚哪些地方没审、为什么没审。一个诚实的“这里我没覆盖”远比一个虚假的“全部通过”有价值。所以我在设计这个 skill 时强制要求任何skipped状态必须带reason字段任何partial状态必须带covered_scope和uncovered_scope。没有理由的跳过直接判定为审计失败。3. 核心技术点拆解一个审计 skill 的骨架长什么样3.1 skill 的输入契约设计skill 能不能被稳定调用关键看输入契约定得够不够死。security-audit-skill的输入我一般设计成这几个字段{ target: /path/to/project, scope: [src/, api/, config/], exclude: [node_modules/, dist/, *.test.js], depth: standard, ruleset: owasp-top10secrets, context: { language: javascript, framework: express, entry_points: [src/app.js] } }这里每个字段都有讲究。scope和exclude必须显式声明不能靠 skill 自己猜——因为“审哪些”是审计员的责任不是工具的责任。depth控制审计粒度quick只做模式匹配standard加数据流分析deep加跨文件追踪。context是给 agent 的推理提示告诉它这是个 express 项目、入口在哪agent 才能判断哪些输入是用户可控的。注意输入契约里千万不要留“自动推断”的口子。我见过太多 skill 因为“智能推断 scope”导致漏审最后 coverage ledger 里全是unknown状态整个审计作废。3.2 审计执行引擎的分层结构skill 内部我习惯分三层采集层、分析层、裁决层。采集层负责把代码、配置、依赖清单拉进来做初步的规则匹配分析层负责对采集层标记的线索做数据流和上下文分析裁决层负责把分析结果转成标准 findings并同步更新 coverage ledger。这个分层的好处是每一层都可以独立替换。比如你想把规则引擎从正则换成 AST 解析只动采集层就行想加一个 LLM 辅助判断只动分析层。热词里“agent架构”“agent框架与编排”讨论得很多但落到 skill 内部架构清晰比框架花哨重要得多。一个 skill 如果三层混在一起维护成本会指数级上升。3.3 规则集与启发式判断的配比纯规则会漏纯启发式会误报这是安全审计的铁律。我的经验配比是规则集负责“广撒网”启发式负责“精筛选”。规则集覆盖 OWASP Top 10、常见密钥泄露模式、危险函数调用这些确定性高的场景启发式则交给 agent让它结合上下文判断“这个疑似点到底是不是真问题”。举个具体例子。规则集扫到db.query(SELECT * FROM users WHERE id userId)标记为“疑似 SQL 注入”。但 agent 在分析层会去看userId的来源如果它来自req.params.id且没有类型校验那就是真漏洞如果它来自内部枚举且经过parseInt那风险等级就要下调。这种判断规则集做不了必须靠 agent 的推理。所以 skill 的设计不是“让 agent 从零判断”而是“规则集给候选agent 做裁决”效率和准确率都能兼顾。4. 实操过程手把手实现一个可运行的审计 skill4.1 环境准备与依赖选型先说环境。我一般用 Python 做 skill 主体因为生态成熟、agent 集成方便。核心依赖就几个tree-sitter做 AST 解析比正则靠谱太多、pydantic做输入输出校验、pathspec做 gitignore 风格的路径过滤。如果你用 Node 生态babel/parser加zod是等价组合。pip install tree-sitter tree-sitter-languages pydantic pathspec选tree-sitter而不是纯正则是因为安全审计里大量判断依赖语法结构。比如你要找“用户输入直接进 SQL”正则很难准确匹配跨行的字符串拼接而 AST 可以精确追踪变量引用链。这个选型我踩过坑早期用正则误报率高到 agent 都懒得看后来换 AST误报直接降了一个数量级。4.2 采集层实现把审计范围变成可追踪的台账采集层的核心任务是把scope展开成一份完整的文件清单并初始化 coverage ledger。这一步的关键是每个文件都要有明确状态不能有“未记录”的文件。from pathlib import Path import pathspec def build_coverage_ledger(target, scope, exclude): spec pathspec.PathSpec.from_lines(gitwildmatch, exclude) ledger {entries: [], summary: {}} for s in scope: for f in Path(target, s).rglob(*): if f.is_file() and not spec.match_file(str(f)): ledger[entries].append({ path: str(f.relative_to(target)), status: pending, depth: None, reason: None }) ledger[summary][total] len(ledger[entries]) return ledger这段代码看起来简单但有个细节很重要初始状态必须是pending而不是clean。我见过有人图省事初始化就标clean结果审计中途崩了台账里一堆clean其实是没审的直接误导结论。状态机必须是pending → in_progress → clean/finding/skipped/partial每一步都要落盘。4.3 分析层实现从线索到结论的推理链分析层是 skill 的大脑。我的做法是先把采集层标记的候选点聚合成“审计单元”每个单元包含代码片段、上下文、调用链然后交给 agent 逐单元裁决。def analyze_unit(unit, context): result { unit_id: unit[id], location: unit[location], candidate_type: unit[type], verdict: None, severity: None, evidence: [], reasoning: } # 交给 agent 裁决这里只做结构封装 agent_verdict call_agent_for_verdict(unit, context) result.update(agent_verdict) return result这里有个实操心得审计单元不要切得太碎。我一开始按单个函数切结果 agent 看不到跨函数的调用关系判断经常出错。后来改成按“数据流路径”切把从入口到 sink 的整条链打包成一个单元agent 的判断准确率明显提升。这个粒度调整花了我不少时间但非常值。4.4 裁决层实现findings.json 的标准化产出裁决层负责把分析结果转成标准 findings并回写 coverage ledger。findings 的 schema 我固定成这几个字段方便下游消费{ id: FIND-001, type: sql_injection, severity: high, location: {file: src/api/user.js, line: 42}, evidence: userId 来自 req.params 且直接拼接进 SQL, reasoning: 无类型校验无参数化查询, remediation: 改用参数化查询, confidence: 0.92 }confidence字段是我强烈建议加的。安全审计里没有 100% 确定的事把置信度显式暴露出来下游 agent 才能决定“这条要不要人工复核”。我一般把confidence 0.7的 finding 标记为“需人工确认”避免 agent 拿着低置信结论去自动修复反而引入新问题。4.5 coverage-ledger.json 的实时更新策略台账更新必须是实时的不能等审计结束再统一写。因为审计可能中途失败如果台账没落盘下次就不知道审到哪了。我的做法是每处理完一个文件就更新一次对应 entry 的状态用原子写避免文件损坏。import json, os, tempfile def update_ledger(ledger, path, status, reasonNone): for entry in ledger[entries]: if entry[path] path: entry[status] status entry[reason] reason break fd, tmp tempfile.mkstemp() with os.fdopen(fd, w) as f: json.dump(ledger, f, indent2) os.replace(tmp, ledger_path)os.replace保证原子性避免审计中途崩溃导致台账文件半截。这个细节看着小但在长时间审计任务里能救命。5. 常见问题与排查技巧实录5.1 审计超时导致覆盖度不完整怎么办这是最高频的问题。大项目审计动辄几十分钟超时后 coverage ledger 里一堆pending。我的处理策略是分级超时 断点续审。给每个文件设独立超时比如 30 秒超时的文件标skipped并记录原因然后继续下一个。审计结束后针对skipped的文件单独跑一轮轻量级模式匹配至少保证“有覆盖”。提示千万不要因为超时就把整个审计判失败。审计的价值在于“尽可能多地覆盖并诚实记录”而不是“要么全审要么不审”。5.2 误报太多导致 findings 不可用误报是安全审计的顽疾。我的经验是三层过滤规则层过滤掉明显不可能的比如测试文件里的危险函数分析层让 agent 判断上下文裁决层用 confidence 阈值卡一道。三层下来误报率能从 60% 降到 15% 左右。剩下的低置信 finding 不删但标记为needs_review交给人工。5.3 coverage ledger 与 findings 对不上怎么排查有时候 findings 里报了一个文件有问题但 ledger 里这个文件状态是clean这就矛盾了。排查思路是先看 ledger 的更新时机是不是 findings 写入后忘了回写 ledger再看状态机是不是clean被错误地当成终态。我一般会在裁决层加一个断言任何产生 finding 的文件ledger 状态必须是finding不一致直接抛错强制暴露问题。问题现象可能原因排查动作findings 有记录但 ledger 是 clean回写遗漏检查裁决层是否同步更新 ledgerledger 大量 pending审计中断检查是否有断点续审机制同一文件重复 finding去重缺失按 locationtype 做去重confidence 普遍偏低上下文不足检查审计单元粒度是否过碎5.4 agent 裁决不稳定怎么破同一个审计单元agent 两次裁决结果不一样这在早期很常见。根因通常是 prompt 里上下文给得不够agent 只能靠猜。解决办法是把判断依据显式喂给 agent数据流路径、变量来源、是否有校验函数、是否在测试代码里。信息给足之后裁决稳定性会大幅提升。我实测下来把上下文从“代码片段”升级到“代码片段调用链来源标注”后同一单元的裁决一致率从 70% 提到了 95% 以上。6. 影响范围与扩展方向这个 skill 能用到哪些场景6.1 在 CI/CD 流水线里的接入方式security-audit-skill最自然的落点就是 CI。我一般把它挂在 PR 阶段每次提交触发一次quick深度审计只审变更文件几分钟出结果。findings 里severity high的直接阻断合并medium的留评论提醒。coverage ledger 作为构建产物存档方便追溯“这次 PR 到底审了哪些”。这里有个实操细节CI 里跑审计一定要设 scope 为变更文件全量审计太慢会拖垮流水线。变更文件的识别用git diff --name-only就行简单可靠。6.2 与 agent 记忆系统的结合热词里“agent记忆”讨论很多security-audit-skill其实很适合和记忆系统结合。比如把历史 findings 存进记忆下次审计时 agent 可以先查“这个文件以前报过什么问题”避免重复报同一个已知问题也能发现“上次修了这次又出现”的回归。coverage ledger 也可以进记忆让 agent 知道“这个模块上次审到什么深度”这次可以针对性加深。6.3 从单项目审计到多项目审计平台单个 skill 跑通之后往上扩展就是多项目审计平台。核心是把 findings 和 coverage ledger 按项目维度聚合做趋势分析哪个项目的漏洞密度在上升、哪类问题反复出现、哪些模块长期没被覆盖。这些数据反过来能指导审计策略——比如长期skipped的模块要么是工具能力不够要么是优先级该调整了。6.4 扩展到其他审计领域这套“findings coverage ledger”的双产物模式其实不限于安全审计。代码质量审计、合规审计、依赖许可证审计都可以套这个骨架。核心思想是一样的结论要结构化覆盖要可追溯。我甚至见过有人把它用到文档审计上检查哪些文档过期、哪些没审到逻辑完全通用。所以security-audit-skill与其说是一个安全工具不如说是一套“可追溯审计”的方法论模板。我在实际项目里最大的体会是审计 skill 的价值不在于它多聪明而在于它多诚实。一个能清楚告诉你“我审了哪些、没审哪些、为什么没审”的 skill比一个号称“全都能审”的 skill 可靠得多。coverage ledger 这个设计本质上就是把审计员的职业操守——不隐瞒、不夸大——编码进了工具里。后续如果你要扩展这个 skill我建议优先加的是“审计单元粒度的自适应调整”和“跨项目 findings 去重”这两个方向对实际使用的提升最明显。