想给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-skillsecurity-audit-skill 是一个多阶段安全审计技能包coding-agent skill它让编码 Agent 变成一名安全审计员从侦察、猎查到独立验证最终产出机器可读的审计结论。这个项目最值得普通开发者偷师的不是审计流程本身而是它的两个零依赖校验器validate-findings.cjs 校验findings.jsonvalidate-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.cjsfindings.json 的零依赖校验器阶段 4、5 调用skills/security-audit/validate-findings.test.cjsfindings 校验器的完整测试套件skills/security-audit/validate-coverage-ledger.cjscoverage-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 入手。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考