Cindy 代码审计伙伴 delivery.md 审计台账模板详解:八列字段、问题指纹与可复现审计交付
Cindy 代码审计伙伴 delivery.md 审计台账模板详解:八列字段、问题指纹与可复现审计交付
Cindy 内置的「代码审计伙伴」(nightly-audit-engineer 0.5.1)用一份极简的 Markdown 模板承载整个审计结论——delivery.md。它只有一张 8 列的表格和两行收尾说明,却直接决定了审计结果能否被复现、去重、评审和长期跟踪。本文以这份模板为骨架,逐列拆解字段语义,并结合配套的问题指纹脚本、审计规程与包清单,给出可直接落地的填写规范与命令示例。
模板原文与它在交付链路中的位置
模板文件的完整内容如下(apps/desktop/resources/bot-packages/nightly-audit-engineer/0.5.1/skills/nightly-audit-engineer-ops/templates/delivery.md):
# 代码审计伙伴
| 指纹 | 基线 | 区域/规则 | 相对路径与位置 | 复现与证据 | 影响 | 建议 | 状态 |
|---|---|---|---|---|---|---|---|
已知限制:
未执行:
它由 nightly-audit-engineer-ops 技能在 SKILL.md 中被明确指定为输出载体,原文要求:
使用 templates/delivery.md,事实/推断/未知分开。具体辅助检查见配套 nightly-audit-engineer-evidence,不要把离线PASS当作真实Bot运行。
这意味着模板不是“随便写的表格”,而是三类信息的边界线:可证实的事实(基线、路径、复现)、推断(根因、影响判断)、未知(未执行的验证、无法确认的环境)。模板里的空白行并不代表“没有内容”,而是等待按顺序填入受控范围、可复现证据和最小建议。
模板本身也被纳入包完整性清单:manifest.json 的 integrity.files 记录了该模板的 SHA-256(skills/nightly-audit-engineer-ops/templates/delivery.md),说明它是受校验的交付物,而非示例草稿。同时该包的 skills<a href="https://link.gitcode.com/i/fd0ffe6981da78a4380c9973d4a72d3a" target="_blank">] 条目把模板登记为 resources,knowledge[] 则挂载了方法参考 [knowledge/method.md。
在分发层面,这些 Bot 包随桌面端一起打包:forge.config.ts 的打包清单包含 resources/bot-packages;运行时由 bot-import/host.ts 计算包根目录:
const packageRoot = () => path.join(app.isPackaged ? process.resourcesPath : path.join(app.getAppPath(), 'resources'), 'bot-packages');
这解释了一个实操细节:开发态与安装态下模板路径前缀不同(app.getAppPath()/resources 与 process.resourcesPath),但包内相对路径 skills/nightly-audit-engineer-ops/templates/delivery.md 保持一致。
八列字段逐列拆解
模板表头定义了审计台账的最小信息集。每一列都有明确的“填写义务”,缺失任意一列都会让结论退化为不可评审的推测。
| 列名 | 填写内容 | 证据边界 | 与指纹脚本的关系 |
|---|---|---|---|
| 指纹 | 问题行的稳定标识 | 仅对人工确认的问题生成 | 由 area/rule/path/rootCause 计算 SHA-256 |
| 基线 | 审计所依据的提交、分支或内容哈希 | 必须写明具体版本,行号会随版本漂移 | 不参与指纹计算 |
| 区域/规则 | 模块区域 + 规则短名,如 cache / stale-owner |
区域与规则是人工归类,不是脚本推断 | 直接进入指纹输入 |
| 相对路径与位置 | 仓库相对路径与符号/行位置 | 禁止绝对路径与 .. 上跳 |
path 进入指纹输入 |
| 复现与证据 | 触发步骤、预期/实际、证据位置 | 未执行项必须显式标出 | evidence 必须非空,但不参与哈希 |
| 影响 | 受影响用户与严重性依据 | 严重性来自真实影响,非主观打分 | 不参与指纹 |
| 建议 | 最小可执行修复方向 | 只收可执行修复建议 | 不参与指纹 |
| 状态 | 本轮处置状态(新发现/重复/待修/未验证等) | 重复不等于已修复 | 与 previouslySeen 输出对应 |
这张表的设计意图可以从审计规程的操作顺序读出来(nightly-audit-engineer-ops/SKILL.md):先核对基线与范围,再按真实数据流找输入、授权、持久化、异步失效与恢复问题,用最小定向复现检验候选,最后才谈严重性与建议。表的列序恰好复刻了这条推理链——先有身份(指纹)、再有坐标(基线、区域、路径)、再有证据、最后才是判断(影响、建议、状态)。
指纹列:为什么它是第一列
指纹解决的是“同一条问题线索在不同批次里被重复报告”的问题。方法参考 method.md 说得很直接:
指纹只用于相同问题线索的导航,不是语义等价或修复证明。行号会随版本变动,需同时保存提交与相对路径。
这句话同时解释了两个高频误用:
- 指纹相同 ≠ 已修复。指纹是“身份”,不是“状态”。修复状态必须由本轮重新复现的结果决定,模板把它交给「状态」列,而不是让指纹承担。
- 行号不能单独作为定位。因为行号会随版本漂移,所以「基线」列必须记录具体提交或内容哈希,而「相对路径与位置」列提供版本内稳定的相对坐标。
基线列:把“当时看到的那份代码”钉死
如果只写模块名和行号,评审者无法判断问题是否已被后续提交改掉。基线列应至少包含一种可回溯标识:提交 SHA、分支 + 提交、或文件内容哈希。这与模板中「指纹」列并列出现并非偶然——一个是问题身份,一个是代码身份,二者共同构成可复现的前提。
区域/规则列:让问题可被聚合
area 与 rule 是低基数(low-cardinality)字段:区域通常是模块名(如 cache、auth),规则是短横线命名的规则名(如 stale-owner)。把它们放在同一列,是为了让人一眼看出“这一类问题在这个模块里是否反复出现”,而指纹脚本也恰好把二者一起哈希。
相对路径与位置列:相对路径是硬约束
这一列不只是排版约定。指纹脚本对路径做了显式校验(见 finding_keys.py 的 fingerprint 函数):
require(not values[2].startswith("/") and ".." not in values[2].split("/"), "relative source path required")
也就是说,绝对路径(以 / 开头)和包含 .. 路径段的上跳写法会让整批输入被拒绝(退出码 2)。这与审计台账要求“可跨机器、跨检出位置复现”的目标一致:路径必须相对于仓库根,而不是相对于某台机器的工作目录。
复现与证据列:证据字段参与校验但不参与哈希
这是模板与脚本之间最值得注意的设计。指纹函数只取四个字段进哈希:
values = [text(row[key]) for key in ("area", "rule", "path", "rootCause")]
text(row["evidence"])
return hashlib.sha256(json.dumps(values, ensure_ascii=False).encode()).hexdigest()
evidence 被 text() 校验为“去空白后非空的字符串”,但没有进入哈希输入。由此可以推断出两条实操结论(与源码结构一致):
- 补充或更新证据(新增一条复现日志、换一个证据链接)不会改变指纹,因此历史台账里的指纹仍然可用;
- 但如果根因判断变了(
rootCause变化),指纹就会变——这正是期望行为:根因不同就是另一条线索,应当作为新行记录,而不是悄悄改掉旧行。
影响列:必须落到真实影响
方法参考要求「审计项至少含具体触发、位置、影响、证据和修复方向」,并强调「没有依据不报安全结论」。模板把「影响」单列,是为了强制写清受影响主体:哪些用户、哪条数据流、是否涉及授权边界、是否只要特定配置才触发。写不出具体受影响主体的条目,通常说明复现链条还没走通。
建议列:只收可执行修复
审计规程第 4 条要求:「只收可执行修复建议;区分 P0/P1、普通缺陷与合理取舍。」这与模板的「建议」列配合使用:建议应当是能在代码里落地的最小改动方向,而不是“建议重构”“建议加强测试”这类无法验收的表述。规程第 6 条进一步限定了默认边界——默认只审阅,不创建 Issue、PR 或改代码;获得修复授权时,「每个区域只做一项最小清理,便于逐项评审」。这条约束直接影响台账写法:如果本轮没有修复授权,「建议」列只写方向,「状态」列保持未处置。
状态列:把“未知”留在明面上
状态列承接的是整个模板最核心的诚实性要求。方法参考写明:「空台账只表示本次范围未发现已证实问题。未执行的集成验证不应被降格为“通过”。」因此状态取值应能区分至少四种情形:已复现待修、复现条件不足、属于合理取舍、本轮未执行相关验证。把“未执行”写成“通过”,是这套模板最需要防范的失真。
表格下方的两行:已知限制与未执行
模板末尾两行是固定收尾区,不是可选装饰:
已知限制:
未执行:
- 已知限制:记录本轮审计的覆盖边界,例如只读了某个模块、未接入真实宿主环境、缺少某些集成测试的运行条件、基线是旧分支等。
- 未执行:明确列出“本来该跑但没跑”的验证项,例如宿主集成测试、端到端链路、需要凭据的真实连接。
审计规程第 3 条对此有直接对应:「用最小定向复现或代码事务顺序检验候选。标出未运行的宿主/集成测试,不能用mock通过替代真实边界。」这条规则正是模板第二行的来源——它不是让你写“暂无”,而是要求把 mock 与真实边界的差距显式写出来。配套证据技能的 SKILL.md 也补了一句同样的边界声明:「输出不是凭证、授权、测试或真实连接证明。」
用 finding_keys.py 做批内去重与历史对照
模板的「指纹」列一旦开始积累,就需要工具化处理。finding_keys.py 是随包的离线辅助脚本,位于 skills/nightly-audit-engineer-evidence/scripts/。
运行前提与调用方式
技能说明给出了标准调用方式(见 nightly-audit-engineer-evidence/SKILL.md):
python3 scripts/finding_keys.py < selected-input.json
关键约束(均来自该 SKILL.md 与脚本实现):
- 仅使用 Python 3.10+ 标准库,不访问网络、不读 Home、不写文件、不执行子进程;
- 只从 stdin 读、向 stdout 写,安装与打包过程不会执行它;
- 输入上限 1 MiB(脚本读取
1048577字节后校验<= 1048576); - 单批最多 10000 条(
items()中的len(value) <= 10000); - 成功退出码 0;输入结构或引用错误时向 stderr 打印
INVALID_INPUT: ...并以 2 退出。
输入结构
输入契约见 contract.md,字段形状示例见 input.json:
{
"findings": [
{
"area": "cache",
"rule": "stale-owner",
"path": "src/cache.py",
"rootCause": "owner changes before commit",
"evidence": "synthetic://race-steps"
}
],
"previouslySeen": []
}
字段映射回模板列:
| 模板列 | JSON 字段 | 校验要求 |
|---|---|---|
| 区域/规则 | area、rule |
非空字符串 |
| 相对路径与位置 | path |
非空、不得以 / 开头、不得含 .. 路径段 |
| 复现与证据 | evidence |
非空字符串,不参与哈希 |
| (隐含的根因列) | rootCause |
非空字符串,参与哈希 |
| 指纹 | previouslySeen[] |
64 位小写十六进制 |
| 状态(重复/已见) | 输出中的 previouslySeen 布尔 |
由脚本计算 |
注意 findings 中的对象字段集合被严格校验:record(row, "area rule path rootCause evidence") 要求字段完全一致,多一个少一个都会报 unexpected or missing fields。因此不要把「基线」「影响」「建议」「状态」塞进指纹输入——这些是台账的展示字段,不是身份字段。特别地,「基线」不参与指纹,这也从侧面印证了前述判断:指纹标识的是“问题模式”,而不是“某次提交里的一段代码”。
输出结构与两个必读字段
输出为按键名排序的 JSON,包含四个字段:
{
"findings": [
{ "fingerprint": "<64位十六进制>", "finding": { "...": "..." }, "previouslySeen": false }
],
"duplicateFingerprints": ["<64位十六进制>"],
"resolution": "NOT_INFERRED",
"note": "Exact identity only; root cause and severity require review."
}
三个读法要点:
resolution恒为NOT_INFERRED:脚本明确不推断修复状态。看到某个指纹出现过,不等于问题已修;只有本轮重新复现才能改变台账「状态」列。duplicateFingerprints只给指纹,不合并证据:脚本遇到已存在的指纹时把它塞进duplicates数组并跳过,后续同指纹条目不会进入findings。这与规程「重复线索只合并证据」的要求形成分工——合并证据必须人工完成,脚本只负责识别重复。previouslySeen是布尔标记,不是判定:规程第 5 条明确「已见指纹不能自动判已修复或压掉复发」。历史已见只说明“这条线索以前出现过”,本轮是否仍存在必须靠复现证据说话。
会被拒绝的输入
脚本的防御性校验相当严格,下列情况都会以退出码 2 结束(错误信息以 INVALID_INPUT: 开头):
- JSON 中出现重复键(
object_pairs_hook=unique_object抛duplicate JSON key); findings内id重复(渲染阶段用indexed()校验重复 id);- 出现
NaN/Infinity(parse_constant直接抛nonfinite JSON); previouslySeen中的指纹不是 64 位小写十六进制;- 日期字段非 ISO 格式(
date.fromisoformat,契约要求“按 ISO 日历日,不读取机器当前时间”); - 输入超过 1 MiB 或数组超过 10000 条。
这套校验的价值在于:它把“台账格式错误”提前到输入阶段暴露,而不是让一条格式错乱的记录污染指纹库。
一份符合模板的最小台账示例
下面用 input.json 中的合成数据演示填写方式。注意这是示例数据(synthetic://race-steps),不是真实缺陷结论:
| 指纹 | 基线 | 区域/规则 | 相对路径与位置 | 复现与证据 | 影响 | 建议 | 状态 |
|---|---|---|---|---|---|---|---|
| (由脚本生成 64 位十六进制) | main@<commit>(示例占位) |
cache / stale-owner |
src/cache.py,owner 写入与提交之间 |
触发步骤:并发提交期间切换 owner;预期旧 owner 不可写,实际出现短暂可写窗口;证据:synthetic://race-steps |
仅在该路径下受影响;需复核调用方 | 在提交路径上复核 owner 校验顺序 | 已复现,待修 |
已知限制:本次只读审计该模块,未接入真实存储后端;基线为示例占位,实际填写时必须替换为真实提交。 未执行:宿主集成测试未运行,不能用单元测试通过替代真实边界。
填写时的两个实用规则:
- 「基线」列写清具体提交或文件内容哈希,因为行号会随版本变化;
- 「状态」列不要因为脚本输出
previouslySeen: true就写“已修复”,修复状态只能由本轮复现决定。
从模板到流程:审核一次审计交付的检查清单
把模板八列与审计规程的六步操作对齐,可以得到一份可直接执行的验收清单(依据 nightly-audit-engineer-ops/SKILL.md):
- 范围与基线是否可核对:基线列是否给出具体提交;“已知限制”是否覆盖未纳入审查的模块。
- 是否区分了旧分支与产品缺陷:规程要求“不把旧分支缺少实现当成产品缺陷”,这类情况应进“已知限制”,而不是台账行。
- 每条是否都有触发步骤、预期/实际与受影响用户:缺任一要素,说明复现链条未闭合。
- 未运行的宿主/集成测试是否显式标出:写进“未执行”,并确保没有把 mock 通过写成真实通过。
- 严重性是否有依据:区分 P0/P1、普通缺陷与合理取舍;没有依据不报安全结论。
- 指纹是否只用于导航:重复线索只合并证据,不用指纹吞掉复发问题。
- 是否守住默认权限:默认只审阅,不建 Issue、不建 PR、不改代码;修复授权另行记录,且每个区域只做一项最小清理。
与夜间例行任务的关系:模板不授权执行
包清单里定义了名为「夜间代码审计」的例行任务(routines[].id = nightly-review),触发器为 cron 表达式 0 4 * * *,时区 Etc/UTC,且 enabledByDefault: false。它同时给出了三条必须写进运维认知的约束:
- 该 cron 定义的 UTC 时间「仅离线示例,必须取得用户实际时区、时间、来源及启用选择」,本包不授权执行;
- 例行任务的提示词要求:仅审计用户已选择的仓库范围;无来源或基线不可用则不宣称完成;有新可复现问题再报告;不自动修复、不发 PR、不改权限;
- 包的
updatePolicy.loaderStatus为NOT_IMPLEMENTED,overwriteUserEdits为false,说明用户对SOUL.md、memories、USER.md等路径的编辑不会被覆盖。
换句话说,delivery.md 是“交付格式”,不是“执行许可”。判定一份夜间审计是否可信,看的是台账里「基线」「复现与证据」「未执行」三列是否诚实,而不是看它有没有被定时触发。
常见误用与修正
| 误用写法 | 问题 | 修正 |
|---|---|---|
| 指纹列手写随机字符串 | 无法与历史线索对上,跨批次去重失效 | 用 finding_keys.py 生成,或严格按 area/rule/path/rootCause 的 JSON 数组做 SHA-256 |
路径写成 ../src/cache.py 或绝对路径 |
脚本直接拒绝(relative source path required) |
改为仓库根相对路径 |
| 把行号当唯一定位 | 行号随版本漂移,无法回溯 | 同时写基线与相对路径 |
| 用“pass”填「未执行」 | 与规程“未执行的集成验证不应被降格为通过”冲突 | 明确写未执行的验证项与原因 |
| 指纹已见即标记已修复 | 指纹是身份不是状态 | 本轮重新复现后再更新「状态」 |
| 把离线脚本输出当真实运行证明 | 技能明确“输出不是凭证、授权、测试或真实连接证明” | 在「已知限制」中标明这是离线检查 |
| 一条记录塞多个根因 | 指纹被混合,后续无法定位 | 一个根因一行,各自独立指纹 |
小结
delivery.md 的八列不是排版偏好,而是一套约束:指纹锁定问题身份、基线锁定代码身份、区域与路径提供可聚合坐标、复现与证据承担可验证性、影响与建议承担可评审性、状态承担诚实性。配套的 finding_keys.py 只做一件事——用 area + rule + path + rootCause 的精确哈希做去重与历史对照,并明确返回 resolution: NOT_INFERRED。真正决定审计价值的仍然是模板最后那两行:把已知限制和未执行项写清楚,比多报几条推测性问题更有用。
继续深入可查阅:审计规程 SKILL.md、方法参考 knowledge/method.md、指纹输入契约 contract.md 与脚本 finding_keys.py。