Cindy 代码审计伙伴 delivery.md 审计台账模板详解:八列字段、问题指纹与可复现审计交付

原创2026-10-26 23:05:251,983 阅读
文章标签:人工智能AI Agent代码智能体大模型AI 技能Agent 记忆工具调用MCP Clients多智能体浏览器控制GUI 自动化本地部署插件系统桌面应用移动开发前端跨平台语音任务调度交互助手

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 说得很直接:

指纹只用于相同问题线索的导航,不是语义等价或修复证明。行号会随版本变动,需同时保存提交与相对路径。

这句话同时解释了两个高频误用:

  1. 指纹相同 ≠ 已修复。指纹是“身份”,不是“状态”。修复状态必须由本轮重新复现的结果决定,模板把它交给「状态」列,而不是让指纹承担。
  2. 行号不能单独作为定位。因为行号会随版本漂移,所以「基线」列必须记录具体提交或内容哈希,而「相对路径与位置」列提供版本内稳定的相对坐标。

基线列:把“当时看到的那份代码”钉死

如果只写模块名和行号,评审者无法判断问题是否已被后续提交改掉。基线列应至少包含一种可回溯标识:提交 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."
}

三个读法要点:

  1. resolution 恒为 NOT_INFERRED:脚本明确不推断修复状态。看到某个指纹出现过,不等于问题已修;只有本轮重新复现才能改变台账「状态」列。
  2. duplicateFingerprints 只给指纹,不合并证据:脚本遇到已存在的指纹时把它塞进 duplicates 数组并跳过,后续同指纹条目不会进入 findings。这与规程「重复线索只合并证据」的要求形成分工——合并证据必须人工完成,脚本只负责识别重复。
  3. 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):

  1. 范围与基线是否可核对:基线列是否给出具体提交;“已知限制”是否覆盖未纳入审查的模块。
  2. 是否区分了旧分支与产品缺陷:规程要求“不把旧分支缺少实现当成产品缺陷”,这类情况应进“已知限制”,而不是台账行。
  3. 每条是否都有触发步骤、预期/实际与受影响用户:缺任一要素,说明复现链条未闭合。
  4. 未运行的宿主/集成测试是否显式标出:写进“未执行”,并确保没有把 mock 通过写成真实通过。
  5. 严重性是否有依据:区分 P0/P1、普通缺陷与合理取舍;没有依据不报安全结论。
  6. 指纹是否只用于导航:重复线索只合并证据,不用指纹吞掉复发问题。
  7. 是否守住默认权限:默认只审阅,不建 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。

登录后查看全文
cindy