想给Agent写自己的校验器？向security-audit-skill学测试导出接口设计-平芜编程栈

想给Agent写自己的校验器？向security-audit-skill学测试导出接口设计

【免费下载链接】security-audit-skillA coding-agent skill for multi-phase security audits with independently verified, machine-readable findings项目地址: https://gitcode.com/GitHub_Trending/se/security-audit-skill

security-audit-skill 是一个多阶段安全审计技能包（coding-agent skill），它让编码 Agent 变成一名安全审计员：从侦察、猎查到独立验证，最终产出机器可读的审计结论。这个项目最值得普通开发者偷师的，不是审计流程本身，而是它的两个"零依赖校验器"：validate-findings.cjs 校验findings.json，validate-coverage-ledger.cjs 校验coverage-ledger.json。它们没有任何 npm 依赖，却能被测试直接"拆开"验证——这背后的测试导出接口设计，正是本文要拆解的重点。

为什么校验器是 Agent 技能的核心基建

先理解背景。整个审计流程分六个阶段，前四个阶段会不断生成结构化数据：

阶段 1 产出architecture.md和coverage-ledger.json（覆盖率台账）；
阶段 4 把confirmed、needs_validation、rejected三类结论写入findings.json，并对照 report-schema.json 做校验；
阶段 5 每次替换记录后还要重新校验一遍。

也就是说，校验器被 Agent 高频调用。如果它依赖一堆 npm 包、只能黑盒测试，出了问题你既修不动也测不清。security-audit-skill 给出的答案是：零依赖 + 模块化导出 + 分层测试。

项目结构速览：校验器都在哪

文件	作用
skills/security-audit/validate-findings.cjs	findings.json 的零依赖校验器（阶段 4、5 调用）
skills/security-audit/validate-findings.test.cjs	findings 校验器的完整测试套件
skills/security-audit/validate-coverage-ledger.cjs	coverage-ledger.json 的零依赖校验器
skills/security-audit/report-schema.json	三种判定结论的 JSON Schema 契约
skills/security-audit/SKILL.md	技能总纲：工作流、执行边界、反模式
skills/security-audit/VALIDATION-AND-REPORTING.md	阶段 3–6 的验证与报告规则

要点一：一个文件，双重身份（CLI 与模块）

这是测试导出接口设计的前提。校验器文件末尾有两行关键代码：

module.exports = { LIMITS, collect, validateDocument, /* ... */ }; if (require.main === module) process.exit(run(process.argv[2]));

node validate-findings.cjs findings.json直接运行时，走 CLI 路径，输出PASS/FAIL和退出码；
require("./validate-findings.cjs")引入时，只得到导出的函数和常量，不会触发 CLI。

这个require.main === module判定的价值在于：Agent 用命令行调用它，测试则把它当普通模块调用。同一个文件服务两种消费者，且互不干扰——这是可测试性的第一块基石。

要点二：导出什么，测试才能验证什么

注意module.exports导出的不只是"入口函数"，还包括：

LIMITS：全部资源上限常量（输入 5 MiB、嵌套 64 层、数组 1000 项、错误输出 100 条）；
collect/validateDocument/collectSchemaErrors：核心校验函数；
isSafeRelativeSourcePath、hasVisibleProse等语义判断函数；
VISIBLE_CONTENT等共享正则。

为什么要把内部函数全导出来？因为导出粒度决定了测试粒度。如果只导出一个 CLI 入口，测试就只能写"喂文件→看退出码"，一条测试覆盖不了"为什么失败"。而导出了语义函数后，测试可以直接断言：空标题被拒、严重级别不能高于已证明的影响、trace 必须以 entrypoint 开头……规则与规则之间的对应关系一目了然。

要点三：三层测试覆盖，由快到慢

validate-findings.test.cjs 全部基于 Node 自带的node:test和node:assert，无需任何安装，三层分工非常清晰：

第 1 层：直接函数测试（毫秒级）

大部分测试直接调用validateDocument，构造一个"标准结论对象"，然后做变异：把标题改成纯空格、把行号改成 0、把 fingerprint 复制重复……每个变异都必须报出错误。这种方式测试速度快、断言精确，是测试的主体。

第 2 层：CLI 子进程测试（守护输出契约）

少数测试用spawnSync真实启动 CLI 进程，验证的是对外契约：

超限输入要返回退出码 1 和明确错误信息，而不是抛出未捕获的异常栈；
终端控制字符（ESC、方向控制符等）绝不能原样出现在 stderr 里——诊断信息必须先转义再输出；
符号链接、FIFO 等特殊文件要被优雅拒绝且不阻塞。

这层测试模拟的是"最坏输入"场景：你的校验器本身也可能被恶意 JSON 攻击，CLI 层面的行为必须稳定。

第 3 层：跨校验器一致性回归

最巧妙的一层。项目里有两个校验器，它们共用一批正则（Unicode 安全字符、路径禁止字符）和限流常量。测试里专门有一段，逐一比较两个模块导出的正则source、flags以及共享的LIMITS值是否完全一致，并用同一路径语料分别调用两边的安全路径函数，断言判定结果相同。

这解决了一个真实痛点：两个相似文件里的复制粘贴规则会随时间悄悄漂移。把一致性写进测试，漂移当天就会红灯。

要点四：把校验器自己当攻击面来设计

作为安全审计技能，它的校验器对"投毒输入"的防御值得所有写校验器的人学习，用大白话总结就是四条：

进门前先量尺寸：先按字节上限（5 MiB）读文件，再对 JSON 文本做深度/长度预检，最后才JSON.parse——超大、超深、超大数组在解析前就被拦截，不会拖垮进程；
输出必须有上限：错误信息最多输出 100 条，防止一份"坏文件"生成几 MB 的错误报告；
诊断信息先消毒：任何来自输入的值进入错误信息前，控制字符一律转义成\uXXXX；
读取文件不跟软链接：使用不跟随符号链接、非阻塞的方式打开输入，符号链接和 FIFO 直接拒绝。

可直接抄走的检查清单

给你的 Agent 技能写校验器前，对照这份清单：

✅ 零依赖优先：只用 Node 内置模块，Agent 环境无需npm install；
✅require.main === module实现 CLI/模块双身份；
✅module.exports导出常量表 + 核心函数 + 关键语义函数，让测试能精确断言；
✅ 测试分三层：函数级（快）、CLI 子进程级（契约）、跨模块一致性（防漂移）；
✅ 给输入和输出都设上限，错误信息先转义再打印；
✅ 稳定输出契约：成功打印PASS: ...，失败打印ERROR:逐条原因，退出码 0/1 分明。

总结

security-audit-skill 用两个不到千行的零依赖文件证明：校验器写得好不好，不只看它能校验什么，更看它自己能不能被廉价地测试和验证。双重身份、按测试需求导出、三层测试覆盖、自我防攻击——这四条组合起来，就是你给 Agent 写下一个校验器时的完整设计模板。想深入审计流程本身，可以从 SKILL.md 和 VALIDATION-AND-REPORTING.md 入手。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考