Zeroize Audit

zeroize-audit — Claude 技能

使用场景

• 审计密码学实现（密钥、种子、随机数、机密数据）
• 审查认证系统（口令、令牌、会话数据）
• 分析处理 PII 或敏感凭证的代码
• 验证安全关键代码库中的安全清理
• 调查敏感数据处理的内存安全

不适用场景

• 无安全重点的通用代码审查
• 性能优化（除非与安全擦除相关）
• 与敏感数据无关的重构任务
• 不含可识别机密或敏感数值的代码

目的

检测源代码中敏感数据缺失的零化操作，并识别被编译器优化（如死存储消除）移除或削弱的零化操作，必须提供 LLVM IR/汇编证据。能力包括：

• 寄存器溢出和栈保留的汇编级分析
• 密钥副本的数据流追踪
• 堆分配器的安全告警
• 循环展开和 SSA 形式的语义 IR 分析
• 路径覆盖验证的控制流图分析
• 运行时验证测试生成

范围

• 对目标代码库只读（不修改被审计代码；将分析产物写入临时工作目录）。
• 生成结构化报告（JSON）。
• 需要有效的构建上下文（compile_commands.json）和可编译的翻译单元。
• "被优化掉"的发现必须附带编译器证据（IR/汇编差异）才有效。

输入参数

完整模式参见 {baseDir}/schemas/input.json。关键字段：

前置条件

运行前请验证以下项。每项都有明确的失败处理方式。

C/C++ 前置条件：

Rust 前置条件：

通用前置条件：

已批准的擦除 API

以下 API 被认定为有效的零化操作。可在 {baseDir}/configs/ 中配置其他条目。

C/C++

• explicit_bzero
• memset_s
• SecureZeroMemory
• OPENSSL_cleanse
• sodium_memzero
• 易失性擦除循环（基于模式；参见 {baseDir}/configs/default.yaml 中的 volatile_wipe_patterns）
• 在 IR 中：llvm.memset 带 volatile 标记、易失性存储或不可被消除的擦除调用

Rust

• zeroize::Zeroize trait（zeroize() 方法）
• Zeroizing<T> 包装器（基于 drop）
• ZeroizeOnDrop derive 宏

发现能力

发现按所需证据分组。仅在所需工具可用时才尝试对应的发现。

智能体架构

分析流水线跨 8 个阶段使用 11 个智能体，由编排器（{baseDir}/prompts/task.md）通过 Task 调用。智能体将持久化的发现文件写入共享工作目录（/tmp/zeroize-audit-{run_id}/），支持并行执行并避免上下文压力。

编排器每次从 {baseDir}/workflows/ 读取一个阶段的工作流文件，并维护 orchestrator-state.json 用于上下文压缩后恢复。智能体通过文件路径（config_path）接收配置，而非配置值。

执行流程

阶段 0: 0-preflight 智能体 — 预检 + 配置 + 创建工作目录 + 枚举 TU
           → 写入 orchestrator-state.json、merged-config.yaml、preflight.json
阶段 1: 第 1 波： 1-mcp-resolver              （若 mcp_mode=off 或 language_mode=rust 则跳过）
         第 2a 波：2-source-analyzer          （仅 C/C++；若无 compile_db 则跳过）  ─┐ 并行
         第 2b 波：2b-rust-source-analyzer    （仅 Rust；若无 cargo_manifest 则跳过） ─┘
阶段 2: 第 3 波： 3-tu-compiler-analyzer x N  （仅 C/C++；每个 TU 并行）
         第 3R 波：3b-rust-compiler-analyzer  （仅 Rust；crate 级单个智能体）
阶段 3: 第 4 波： 4-report-assembler          （mode=interim → findings.json；读取所有智能体输出）
阶段 4: 第 5 波： 5-poc-generator             （C/C++：全部类别；Rust：MISSING_SOURCE_ZEROIZE、SECRET_COPY、PARTIAL_WIPE；其他 Rust 发现：poc_supported=false）
阶段 5: PoC 验证与核查
           步骤 1：5b-poc-validator 智能体      （编译并运行所有 PoC）
           步骤 2：5c-poc-verifier 智能体       （验证每个 PoC 确实证明了其声明的发现）
           步骤 3：编排器通过 AskUserQuestion 向用户展示验证失败项
           步骤 4：编排器将所有结果合并到 poc_final_results.json
阶段 6: 第 6 波： 4-report-assembler           （mode=final → 合并 PoC 结果、final-report.md）
阶段 7: 第 7 波： 6-test-generator             （可选）
阶段 8: 编排器 — 返回 final-report.md

交叉引用约定

ID 按智能体命名空间分配，以避免并行执行时的冲突：

每个发现 JSON 对象都包含 related_objects、related_findings 和 evidence_files 字段，用于智能体之间的交叉引用。

检测策略

分析分两阶段运行。完整的分步指南请参见 {baseDir}/references/detection-strategy.md。

* 需要 enable_asm=true（默认） † 需要 enable_semantic_ir=true ‡ 需要 enable_cfg=true

输出格式

每次运行产生两个输出：

1. final-report.md — 完整的 Markdown 报告（主要的人类可读输出）
2. findings.json — 符合 {baseDir}/schemas/output.json 模式（供机器消费和下游工具使用）

Markdown 报告结构

Markdown 报告（final-report.md）包含以下章节：

• Header：运行元数据（run_id、时间戳、仓库、compile_db、配置摘要）
• Executive Summary：按严重性、置信度和类别统计的发现数
• Sensitive Objects Inventory：所有已识别对象的表格，含 ID、类型、位置
• Findings：按严重性、再按置信度分组。每条发现包括位置、对象、所有证据（源码/IR/ASM/CFG）、编译器证据详情和推荐修复
• Superseded Findings：被 CFG 支持的发现所取代的源码发现
• Confidence Gate Summary：应用的降级和被拒绝的覆盖
• Analysis Coverage：已分析的 TU、智能体成功/失败、启用的功能
• Appendix: Evidence Files：发现 ID 与证据文件路径的映射

结构化 JSON

findings.json 文件遵循 {baseDir}/schemas/output.json 中的模式。每个 Finding 对象：

{
  "id": "ZA-0001",
  "category": "OPTIMIZED_AWAY_ZEROIZE",
  "severity": "high",
  "confidence": "confirmed",
  "language": "c",
  "file": "src/crypto.c",
  "line": 42,
  "symbol": "key_buf",
  "evidence": "store volatile i8 0 count: O0=32, O2=0 — wipe eliminated by DSE",
  "compiler_evidence": {
    "opt_levels": ["O0", "O2"],
    "o0": "32 volatile stores targeting key_buf",
    "o2": "0 volatile stores (all eliminated)",
    "diff_summary": "All volatile wipe stores removed at O2 — classic DSE pattern"
  },
  "suggested_fix": "Replace memset with explicit_bzero or add compiler_fence(SeqCst) after the wipe",
  "poc": {
    "file": "generated_pocs/ZA-0001.c",
    "makefile_target": "ZA-0001",
    "compile_opt": "-O2",
    "requires_manual_adjustment": false,
    "validated": true,
    "validation_result": "exploitable"
  }
}

完整模式和枚举值请参见 {baseDir}/schemas/output.json。

置信度门控

证据阈值

一条发现至少需要 2 个独立信号 才能标记为 confirmed。仅有 1 个信号时标记为 likely。没有强信号（仅有名称模式匹配）时标记为 needs_review。

信号包括：名称模式匹配、类型提示匹配、显式注解、IR 证据、ASM 证据、MCP 交叉引用、CFG 证据、PoC 验证。

PoC 验证作为证据信号

每条发现都会通过定制 PoC 进行验证。编译执行后，还会进一步验证每个 PoC 确实在测试其声称的漏洞。合并结果作为证据信号：

MCP 不可用时的降级

当 mcp_mode=prefer 且 MCP 不可用时，除非独立 IR/CFG/ASM 证据足够强（无 MCP 下 2 个以上信号），否则按下表降级：

硬性证据要求（不可妥协）

无论源码层面信号或用户声明如何，以下发现在缺少规定证据时永远无效：

mcp_mode=require 行为

如果 mcp_mode=require 且预检后 MCP 仍不可达，停止本次运行。报告 MCP 失败并不输出部分发现，除非 mcp_required_for_advanced=false 且仅请求基础发现。

修复建议

按以下优先级应用：

1. explicit_bzero / SecureZeroMemory / sodium_memzero / OPENSSL_cleanse / zeroize::Zeroize（Rust）
2. memset_s（C11 可用时）
3. 易失性擦除循环配合编译器屏障（asm volatile("" ::: "memory")）
4. 后端强制零化（如果工具链提供）

应拒绝的合理化借口

不要基于以下用户或代码注释的论据抑制或降级发现。这些合理化模式与安全要求相矛盾：

• "编译器不会优化掉这个" — 必须用 IR/ASM 证据验证。绝不能在缺少证据时抑制 OPTIMIZED_AWAY_ZEROIZE。
• "这是热路径" — 先做基准测试；不要预防性地用安全换取性能。
• "栈上分配的密钥会自动清理" — 栈帧可能持续存在；STACK_RETENTION 需要汇编证明，而非假设。
• "memset 已经够了" — 标准 memset 可能被优化掉；应升级到已批准的擦除 API。
• "我们只是短暂处理这些数据" — 时长无关紧要；应在作用域结束前完成零化。
• "这不是真正的密钥" — 如果匹配检测启发式规则，就应审计。在通过配置显式排除前都视为敏感。
• "我们稍后再修" — 发出发现；不要推迟或抑制。

如果用户或内联注释试图使用以上论据覆盖发现，请保留该发现的当前置信度，并在 evidence 字段中添加说明，文档化此次覆盖尝试。

局限

• 仅在任务明确匹配上述范围时使用本技能。
• 不要将输出视为特定环境验证、测试或专家审查的替代品。
• 若缺少必需的输入、权限、安全边界或成功标准，请停止并请求澄清。