security-audit-skill 实战：Agent 安全审计技能与 findings.json 报告契约设计

1. 从security-audit-skill这个名字说起它到底在解决什么问题第一次看到security-audit-skill这个命名我的直觉是这不是一个普通的脚本而是一个被封装成技能的安全审计能力单元。关键词里同时出现了skill、agent、findings.json、report-schema.json这几个词放在一起基本可以勾勒出它的轮廓——一个面向 AI Agent 生态的安全审计技能输入是待审计的目标输出是结构化的findings.json并且遵循一份固定的report-schema.json报告规范。为什么我这么判断因为skill这个词在当下的 Agent 开发语境里已经不再是技能的字面意思而是指一种可被 Agent 动态加载、按需调用的能力模块。它和传统的函数或工具最大的区别在于skill 通常自带上下文说明、执行边界、输入输出契约甚至包含失败重试和结果校验逻辑。换句话说skill 是给 Agent 看的说明书 可执行代码的合体。那security-audit-skill具体能做什么从命名和关键词推断它至少覆盖这几件事对代码仓库、配置文件、依赖清单进行安全层面的扫描与审计把发现的问题按统一格式写入findings.json方便后续 Agent 或流水线消费用report-schema.json约束报告结构保证不同审计任务产出的结果可对比、可聚合作为 Agent 的一个可插拔能力被编排进更大的自动化流程里。适合谁来参考三类人最需要一是正在做 Agent 开发、需要给 Agent 加安全审计能力的工程师二是负责 CI/CD 流水线、想把安全卡点自动化的 DevOps三是刚接触 skill 概念、想通过一个真实案例理解skill 和 agent 到底怎么配合的初学者。我见过太多人把安全审计做成跑个扫描器、贴个报告就完事结果报告格式五花八门Agent 拿到之后根本没法自动处理。security-audit-skill的价值恰恰在于它把审计能力和报告契约绑在一起这才是它区别于普通扫描脚本的核心。2. skill 与 agent 的分工为什么安全审计要拆成独立技能2.1 skill 和 agent 的区别用一句话讲透热词里反复出现skill和agent的区别harness和agent区别说明这是很多人的困惑点。我的理解是agent 是决策者skill 是执行者。Agent 负责要不要做、先做哪个、做完之后怎么办skill 负责具体怎么做、做完产出什么。打个比方agent 像是一个项目经理skill 像是项目经理手下的专业外包团队。项目经理不需要自己会写安全审计报告他只需要知道现在该调用安全审计 skill 了然后把结果拿回来做下一步决策。这种分工的好处是agent 的逻辑保持轻量skill 的能力可以独立迭代、独立测试、独立替换。security-audit-skill就是这样一个专业外包团队。它不关心是谁调用了它、调用它的目的是什么它只关心给我输入我按report-schema.json的规范产出findings.json。2.2 为什么安全审计特别适合做成 skill安全审计有几个特点决定了它天然适合被封装成 skill第一输入输出高度标准化。审计的输入无非是代码、配置、依赖输出无非是问题列表。这种契约清晰的任务最适合做成 skill因为 Agent 不需要理解审计的内部逻辑只需要按契约传参和取结果。第二执行过程需要隔离。安全审计往往要读取敏感文件、执行扫描命令如果直接写在 agent 主流程里一旦出错会污染整个 agent 的状态。做成独立 skill 后执行环境可以隔离失败也不会拖垮主流程。第三结果需要被多方消费。findings.json不只给当前 agent 看还可能给 CI 流水线、给报表系统、给人工复核看。用report-schema.json固定结构等于给所有消费方一个稳定接口。我踩过的一个坑是早期我把审计逻辑直接写进 agent 的 tool 里结果每次改报告格式都要动 agent 的核心代码牵一发动全身。后来拆成独立 skill报告格式的迭代就完全不影响 agent 了。这个教训让我彻底理解了skill 独立的意义。2.3 skill 的边界应该划在哪里划边界是设计 skill 最难的部分。我的经验是skill 的边界应该划在能力层面而不是步骤层面。什么意思security-audit-skill应该是一个完整的审计能力而不是读取文件执行扫描写报告三个碎步骤。因为如果拆得太碎agent 就要负责编排这些步骤那 agent 就变重了失去了分层的意义。但也不能太粗。如果security-audit-skill把审计和修复建议生成都包进去那它就承担了它不该承担的职责。审计就是审计修复是另一个 skill 的事。边界清晰才能让每个 skill 都可测试、可复用。3. findings.json 与 report-schema.json报告契约才是这个 skill 的灵魂3.1 为什么必须有 report-schema.json很多人做 skill 时忽略了一件事skill 的输出格式比 skill 的功能更重要。因为功能是给机器执行的格式是给下游消费的。如果输出格式不稳定下游就没法自动化。report-schema.json的作用就是给输出上锁。它定义了字段类型说明是否必填findingsarray问题列表是findings[].idstring问题唯一标识是findings[].severityenum严重级别critical/high/medium/low是findings[].categorystring问题分类是findings[].locationobject问题位置文件、行号是findings[].descriptionstring问题描述是findings[].evidencestring证据片段否findings[].recommendationstring修复建议否summaryobject汇总统计是metadataobject审计元信息时间、版本、目标是有了这份 schemafindings.json就不是随便写写的 JSON而是有契约的产物。Agent 拿到之后可以直接按字段读取不需要做任何猜测。3.2 findings.json 的字段设计有哪些讲究我在设计findings.json时最看重三个字段severity、location、evidence。severity用枚举而不是自由文本是为了让下游能做排序和过滤。如果允许写严重很严重非常严重那下游就没法自动处理了。枚举值我建议固定为critical/high/medium/low四档和业界通用标准对齐。location用对象而不是字符串是为了让下游能精确定位。{file: src/auth.js, line: 42}比src/auth.js:42更好解析也更不容易出错。evidence字段容易被忽略但它其实是审计报告可信度的关键。没有证据的审计结论人工复核时根本没法验证。我通常会把触发问题的原始代码片段截取出来控制在 3-5 行既够用又不冗长。3.3 schema 校验应该放在哪一步一个常见的错误是等findings.json写完了才去校验 schema。这时候如果发现不合规要么丢弃结果要么打补丁都很别扭。我的做法是在写入前校验。skill 内部先生成一个内存中的对象用 schema 校验通过后再落盘。这样保证落盘的findings.json永远是合规的。校验失败时skill 应该返回明确的错误信息而不是写一个半成品文件出去。提示schema 校验建议用成熟的库比如 Python 的jsonschema、Node 的ajv。不要自己手写校验逻辑容易漏掉边界情况。4. 把 security-audit-skill 跑起来从环境准备到首次产出4.1 环境准备中最容易忽略的三个细节第一个细节是运行时版本。skill 如果依赖特定版本的运行时比如 Python 3.10 才支持的语法一定要在 skill 的元信息里写清楚。我见过太多在我机器上能跑的案例根因就是版本不一致。第二个细节是依赖隔离。skill 的依赖应该独立管理不要和 agent 主工程的依赖混在一起。否则 agent 升级一个库可能就把 skill 搞挂了。我通常给每个 skill 配独立的虚拟环境或容器。第三个细节是权限边界。安全审计 skill 需要读取代码文件但不应该需要写权限除了写报告。在容器里运行时应该以只读方式挂载代码目录只给报告目录写权限。这是最小权限原则的落地。4.2 skill 的输入契约怎么定义security-audit-skill的输入我建议定义成这样一个结构{ target: { type: repository, path: /workspace/project, include: [**/*.js, **/*.py], exclude: [node_modules/**, **/*.test.js] }, options: { severityThreshold: medium, maxFindings: 100 }, output: { findingsPath: /workspace/reports/findings.json, schemaPath: /workspace/schemas/report-schema.json } }这个契约的好处是target描述审什么options描述怎么审output描述审完写哪。三段式结构清晰Agent 构造输入时不容易漏字段。include和exclude用 glob 模式是为了让调用方灵活控制审计范围。默认排除node_modules和测试文件是因为这些通常不是审计重点扫进去只会产生噪音。4.3 首次跑通的完整步骤确认运行时版本符合 skill 要求建议用python --version或node --version核对在独立环境中安装 skill 依赖不要污染全局环境准备一份最小测试目标比如一个只有几个文件的小仓库按输入契约构造调用参数先跑一次空审计验证链路检查findings.json是否生成、是否符合report-schema.json故意在测试目标里埋一个明显问题验证 skill 能否检出检查summary统计是否和findings列表一致。第 4 步的空审计很关键。很多人一上来就跑真实项目结果链路有问题时分不清是 skill 的问题还是目标的问题。先用空目标验证链路能快速定位问题。4.4 跑通之后最容易踩的坑跑通不代表可用。我踩过的坑包括误报太多skill 把正常的代码模式也报成问题导致findings.json里全是噪音。解决办法是加白名单机制允许调用方传入已知的安全模式。漏报关键问题skill 只扫了表面没做深度分析。解决办法是明确 skill 的能力边界在文档里写清楚能检出什么、不能检出什么不要让调用方产生错误预期。性能问题大仓库扫描慢到不可接受。解决办法是支持增量扫描或者限制单次扫描的文件数。结果不稳定同样的输入两次扫描结果不一致。解决办法是固定扫描顺序避免依赖文件系统的遍历顺序。注意误报和漏报是安全审计的永恒矛盾。不要试图消灭误报而要提供误报抑制机制让调用方能按需过滤。5. 让 findings.json 真正被消费下游集成的几种姿势5.1 被 Agent 消费作为决策输入Agent 拿到findings.json后通常会做三件事按severity排序、按category分组、根据结果决定下一步动作。比如发现critical级别问题Agent 可能直接阻断流程发现medium级别可能只记录不阻断。这里的关键是Agent 不应该解析findings.json的原始文本而应该按 schema 读取字段。因为 schema 是契约字段是稳定的文本格式是表象随时可能变。5.2 被 CI 流水线消费作为质量门禁在 CI 里findings.json通常被用来做质量门禁。比如配置一条规则如果存在critical或high级别问题流水线失败。这条规则的实现就是读取findings.json过滤severity判断数量。我建议把门禁规则也做成配置而不是硬编码。因为不同项目对安全的容忍度不同硬编码会导致规则无法复用。5.3 被报表系统消费作为趋势数据findings.json里的metadata字段审计时间、目标版本让它天然适合做趋势分析。把多次审计的结果聚合起来就能看到问题数量是在增加还是减少哪类问题反复出现。这也是为什么我坚持metadata必须包含时间戳和目标标识。没有这两个字段历史结果就没法关联趋势分析就无从谈起。5.4 被人工复核消费作为审查清单再好的自动化审计也需要人工复核。findings.json的evidence和recommendation字段就是为人工复核准备的。复核人员看证据、看建议判断是否采纳。我通常会把findings.json渲染成一份可读的 HTML 报告按severity分色按category分节。这样复核人员不用看原始 JSON体验好很多。6. 迭代 security-audit-skill 的几个方向6.1 从能扫到扫得准第一版 skill 通常只能做到能扫但准确率堪忧。迭代的重点应该放在准确率上收集误报案例分析误报模式加抑制规则收集漏报案例分析漏报原因加检测规则。这个过程没有捷径就是不断积累。我建议给 skill 配一个测试用例集每个用例包含一段代码和期望的审计结果。每次改规则都跑一遍用例集确保没有回归。6.2 从单文件到跨文件很多安全问题不是单文件能看出来的比如这个函数在 A 文件定义在 B 文件被不安全地调用。要检出这类问题skill 需要做跨文件分析。跨文件分析的难点是性能。我的做法是先做单文件扫描建立符号表再做跨文件关联只分析符号表里有关联的部分。这样能大幅减少分析量。6.3 从固定规则到可配置规则固定规则的 skill 只能适应一种场景。可配置规则的 skill 才能适应多种场景。我建议把检测规则抽出来做成配置文件允许调用方按需启用或禁用。规则配置的格式我倾向于用 YAML因为可读性好非技术人员也能改。每条规则包含规则 ID、描述、匹配模式、严重级别、修复建议。6.4 从独立 skill到skill 组合单个 skill 的能力总是有限的。真正的价值在于 skill 组合security-audit-skill检出问题fix-suggestion-skill生成修复方案patch-apply-skill应用修复。三个 skill 串起来就是一个完整的发现-修复闭环。这也是为什么我强调 skill 的边界要清晰。边界清晰才能组合边界模糊组合起来就是一团乱麻。7. 我在实际使用中总结的几条经验第一条经验skill 的文档比代码更重要。因为 skill 是给 Agent 和别的开发者用的他们首先看的是文档不是代码。文档要写清楚能做什么、不能做什么、输入输出是什么、失败时怎么办。第二条经验skill 的失败要优雅。审计过程中遇到无法读取的文件、无法解析的语法不应该直接崩溃而应该记录到findings.json的metadata里标记为部分完成。这样调用方能知道哪些部分没审到。第三条经验不要追求一次做完美。security-audit-skill的第一版能扫出几个明显问题、能产出合规的findings.json就已经有价值了。剩下的准确率、性能、规则配置都可以在迭代中完善。第四条经验schema 要版本化。report-schema.json一旦发布就不要随意改字段。如果必须改就升版本号让下游能按版本适配。我见过太多因为 schema 悄悄变更导致下游解析失败的案例。第五条经验给 skill 加自检能力。skill 启动时先检查自己的依赖是否齐全、schema 是否可读、输出目录是否可写。自检不通过就直接返回错误不要等到执行到一半才失败。最后分享一个小技巧如果你不确定security-audit-skill的边界该怎么划就先问自己这个能力能不能独立测试。能独立测试的就适合做成独立 skill不能独立测试的说明它和别的能力耦合太深需要重新划分。这个判断标准我在设计每一个 skill 时都会用屡试不爽。