zeroize-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

zeroize-audit — Claude Skill

When to Use

适用场景

Auditing cryptographic implementations (keys, seeds, nonces, secrets)
Reviewing authentication systems (passwords, tokens, session data)
Analyzing code that handles PII or sensitive credentials
Verifying secure cleanup in security-critical codebases
Investigating memory safety of sensitive data handling

审计加密实现（密钥、种子、随机数、机密数据）
评审认证系统（密码、令牌、会话数据）
分析处理个人可识别信息（PII）或敏感凭证的代码
验证安全关键代码库中的安全清理逻辑
调研敏感数据处理的内存安全性

When NOT to Use

不适用场景

General code review without security focus
Performance optimization (unless related to secure wiping)
Refactoring tasks not related to sensitive data
Code without identifiable secrets or sensitive values

无安全诉求的通用代码评审
性能优化（除非和安全擦除相关）
和敏感数据无关的重构任务
没有可识别机密或敏感值的代码

Purpose

功能用途

Detect missing zeroization of sensitive data in source code and identify zeroization that is removed or weakened by compiler optimizations (e.g., dead-store elimination), with mandatory LLVM IR/asm evidence. Capabilities include:

Assembly-level analysis for register spills and stack retention
Data-flow tracking for secret copies
Heap allocator security warnings
Semantic IR analysis for loop unrolling and SSA form
Control-flow graph analysis for path coverage verification
Runtime validation test generation

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

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

Scope

适用范围

Read-only against the target codebase (does not modify audited code; writes analysis artifacts to a temporary working directory).
Produces a structured report (JSON).
Requires valid build context (
```
compile_commands.json
```
) and compilable translation units.
"Optimized away" findings only allowed with compiler evidence (IR/asm diff).

对目标代码库为只读模式（不会修改被审计代码，仅将分析产物写入临时工作目录）
输出结构化报告（JSON格式）
需要有效的构建上下文（
```
compile_commands.json
```
）和可编译的翻译单元
仅当有编译器证据（IR/汇编差异）时才会判定「清零逻辑被优化移除」问题

Inputs

输入参数

See

{baseDir}/schemas/input.json

for the full schema. Key fields:

Field	Required	Default	Description
`path`	yes	—	Repo root
`compile_db`	no	`null`	Path to `compile_commands.json` for C/C++ analysis. Required if `cargo_manifest` is not set.
`cargo_manifest`	no	`null`	Path to `Cargo.toml` for Rust crate analysis. Required if `compile_db` is not set.
`config`	no	—	YAML defining heuristics and approved wipes
`opt_levels`	no	`["O0","O1","O2"]`	Optimization levels for IR comparison. O1 is the diagnostic level: if a wipe disappears at O1 it is simple DSE; O2 catches more aggressive eliminations.
`languages`	no	`["c","cpp","rust"]`	Languages to analyze
`max_tus`	no	—	Limit on translation units processed from compile DB
`mcp_mode`	no	`prefer`	`off` , `prefer` , or `require` — controls Serena MCP usage
`mcp_required_for_advanced`	no	`true`	Downgrade `SECRET_COPY` , `MISSING_ON_ERROR_PATH` , and `NOT_DOMINATING_EXITS` to `needs_review` when MCP is unavailable
`mcp_timeout_ms`	no	—	Timeout budget for MCP semantic queries
`poc_categories`	no	all 11 exploitable	Finding categories for which to generate PoCs. C/C++ findings: all 11 categories supported. Rust findings: only `MISSING_SOURCE_ZEROIZE` , `SECRET_COPY` , and `PARTIAL_WIPE` are supported; other Rust categories are marked `poc_supported=false` .
`poc_output_dir`	no	`generated_pocs/`	Output directory for generated PoCs
`enable_asm`	no	`true`	Enable assembly emission and analysis (Step 8); produces `STACK_RETENTION` , `REGISTER_SPILL` . Auto-disabled if `emit_asm.sh` is missing.
`enable_semantic_ir`	no	`false`	Enable semantic LLVM IR analysis (Step 9); produces `LOOP_UNROLLED_INCOMPLETE`
`enable_cfg`	no	`false`	Enable control-flow graph analysis (Step 10); produces `MISSING_ON_ERROR_PATH` , `NOT_DOMINATING_EXITS`
`enable_runtime_tests`	no	`false`	Enable runtime test harness generation (Step 11)

完整schema请查看

{baseDir}/schemas/input.json

，关键字段如下：

字段	必填	默认值	描述
`path`	是	—	仓库根目录
`compile_db`	否	`null`	C/C++分析使用的 `compile_commands.json` 路径，未设置 `cargo_manifest` 时必填
`cargo_manifest`	否	`null`	Rust crate分析使用的 `Cargo.toml` 路径，未设置 `compile_db` 时必填
`config`	否	—	定义启发式规则和已认可擦除逻辑的YAML配置
`opt_levels`	否	`["O0","O1","O2"]`	用于IR对比的优化级别。O1为诊断级别：如果擦除逻辑在O1级别消失则属于简单死存储消除，O2可捕获更激进的优化消除
`languages`	否	`["c","cpp","rust"]`	待分析的编程语言
`max_tus`	否	—	从编译数据库中处理的翻译单元上限
`mcp_mode`	否	`prefer`	取值为 `off` / `prefer` / `require` ，控制Serena MCP的使用
`mcp_required_for_advanced`	否	`true`	当MCP不可用时，将 `SECRET_COPY` 、 `MISSING_ON_ERROR_PATH` 、 `NOT_DOMINATING_EXITS` 降级为 `needs_review`
`mcp_timeout_ms`	否	—	MCP语义查询的超时时间
`poc_categories`	否	全部11种可利用类型	生成PoC的问题类别。C/C++支持全部11个类别，Rust仅支持 `MISSING_SOURCE_ZEROIZE` 、 `SECRET_COPY` 、 `PARTIAL_WIPE` ，其他Rust类别标记为 `poc_supported=false`
`poc_output_dir`	否	`generated_pocs/`	生成PoC的输出目录
`enable_asm`	否	`true`	启用汇编生成与分析（第8步），会输出 `STACK_RETENTION` 、 `REGISTER_SPILL` 问题。如果 `emit_asm.sh` 缺失会自动禁用
`enable_semantic_ir`	否	`false`	启用语义LLVM IR分析（第9步），会输出 `LOOP_UNROLLED_INCOMPLETE` 问题
`enable_cfg`	否	`false`	启用控制流图分析（第10步），会输出 `MISSING_ON_ERROR_PATH` 、 `NOT_DOMINATING_EXITS` 问题
`enable_runtime_tests`	否	`false`	启用运行时测试框架生成（第11步）

Prerequisites

前置依赖

Before running, verify the following. Each has a defined failure mode.

C/C++ prerequisites:

Prerequisite	Failure mode if missing
`compile_commands.json` at `compile_db` path	Fail fast — do not proceed
`clang` on PATH	Fail fast — IR/ASM analysis impossible
`uvx` on PATH (for Serena)	If `mcp_mode=require` : fail. If `mcp_mode=prefer` : continue without MCP; downgrade affected findings per Confidence Gating rules.
`{baseDir}/tools/extract_compile_flags.py`	Fail fast — cannot extract per-TU flags
`{baseDir}/tools/emit_ir.sh`	Fail fast — IR analysis impossible
`{baseDir}/tools/emit_asm.sh`	Warn and skip assembly findings (STACK_RETENTION, REGISTER_SPILL)
`{baseDir}/tools/mcp/check_mcp.sh`	Warn and treat as MCP unavailable
`{baseDir}/tools/mcp/normalize_mcp_evidence.py`	Warn and use raw MCP output

Rust prerequisites:

Prerequisite	Failure mode if missing
`Cargo.toml` at `cargo_manifest` path	Fail fast — do not proceed
`cargo check` passes	Fail fast — crate must be buildable
`cargo +nightly` on PATH	Fail fast — nightly required for MIR and LLVM IR emission
`uv` on PATH	Fail fast — required to run Python analysis scripts
`{baseDir}/tools/validate_rust_toolchain.sh`	Warn — run preflight manually. Checks all tools, scripts, nightly, and optionally `cargo check` . Use `--json` for machine-readable output, `--manifest` to also validate the crate builds.
`{baseDir}/tools/emit_rust_mir.sh`	Fail fast — MIR analysis impossible ( `--opt` , `--crate` , `--bin/--lib` supported; `--out` can be file or directory)
`{baseDir}/tools/emit_rust_ir.sh`	Fail fast — LLVM IR analysis impossible ( `--opt` required; `--crate` , `--bin/--lib` supported; `--out` must be `.ll` )
`{baseDir}/tools/emit_rust_asm.sh`	Warn and skip assembly findings ( `STACK_RETENTION` , `REGISTER_SPILL` ). Supports `--opt` , `--crate` , `--bin/--lib` , `--target` , `--intel-syntax` ; `--out` can be `.s` file or directory.
`{baseDir}/tools/diff_rust_mir.sh`	Warn and skip MIR-level optimization comparison. Accepts 2+ MIR files, normalizes, diffs pairwise, and reports first opt level where zeroize/drop-glue patterns disappear.
`{baseDir}/tools/scripts/semantic_audit.py`	Warn and skip semantic source analysis
`{baseDir}/tools/scripts/find_dangerous_apis.py`	Warn and skip dangerous API scan
`{baseDir}/tools/scripts/check_mir_patterns.py`	Warn and skip MIR analysis
`{baseDir}/tools/scripts/check_llvm_patterns.py`	Warn and skip LLVM IR analysis
`{baseDir}/tools/scripts/check_rust_asm.py`	Warn and skip Rust assembly analysis ( `STACK_RETENTION` , `REGISTER_SPILL` , drop-glue checks). Dispatches to `check_rust_asm_x86.py` (production) or `check_rust_asm_aarch64.py` (EXPERIMENTAL — AArch64 findings require manual verification).
`{baseDir}/tools/scripts/check_rust_asm_x86.py`	Required by `check_rust_asm.py` for x86-64 analysis; warn and skip if missing
`{baseDir}/tools/scripts/check_rust_asm_aarch64.py`	Required by `check_rust_asm.py` for AArch64 analysis (EXPERIMENTAL); warn and skip if missing

Common prerequisite:

Prerequisite	Failure mode if missing
`{baseDir}/tools/generate_poc.py`	Fail fast — PoC generation is mandatory

运行前请验证以下依赖，每个依赖缺失都有定义好的失败处理逻辑。

C/C++前置依赖：

前置依赖	缺失时的失败处理
`compile_db` 路径下的 `compile_commands.json`	快速失败，不继续执行
环境变量PATH中存在 `clang`	快速失败，无法进行IR/汇编分析
环境变量PATH中存在 `uvx` （Serena依赖）	如果 `mcp_mode=require` 则失败；如果 `mcp_mode=prefer` 则不使用MCP继续执行，按照置信度管控规则降级受影响的问题
`{baseDir}/tools/extract_compile_flags.py`	快速失败，无法提取单翻译单元的编译参数
`{baseDir}/tools/emit_ir.sh`	快速失败，无法进行IR分析
`{baseDir}/tools/emit_asm.sh`	告警并跳过汇编相关问题检测（STACK_RETENTION、REGISTER_SPILL）
`{baseDir}/tools/mcp/check_mcp.sh`	告警并视为MCP不可用
`{baseDir}/tools/mcp/normalize_mcp_evidence.py`	告警并直接使用原始MCP输出

Rust前置依赖：

前置依赖	缺失时的失败处理
`cargo_manifest` 路径下的 `Cargo.toml`	快速失败，不继续执行
`cargo check` 执行通过	快速失败，crate必须可构建
环境变量PATH中存在 `cargo +nightly`	快速失败，输出MIR和LLVM IR需要nightly工具链
环境变量PATH中存在 `uv`	快速失败，运行Python分析脚本需要该依赖
`{baseDir}/tools/validate_rust_toolchain.sh`	告警，需要手动执行预检。该脚本会检查所有工具、脚本、nightly版本，可选执行 `cargo check` 。使用 `--json` 输出机器可读结果， `--manifest` 额外验证crate可构建
`{baseDir}/tools/emit_rust_mir.sh`	快速失败，无法进行MIR分析（支持 `--opt` 、 `--crate` 、 `--bin/--lib` 参数， `--out` 可为文件或目录）
`{baseDir}/tools/emit_rust_ir.sh`	快速失败，无法进行LLVM IR分析（必填 `--opt` 参数，支持 `--crate` 、 `--bin/--lib` 参数， `--out` 必须为 `.ll` 后缀）
`{baseDir}/tools/emit_rust_asm.sh`	告警并跳过汇编相关问题检测（ `STACK_RETENTION` 、 `REGISTER_SPILL` ）。支持 `--opt` 、 `--crate` 、 `--bin/--lib` 、 `--target` 、 `--intel-syntax` 参数， `--out` 可为 `.s` 文件或目录
`{baseDir}/tools/diff_rust_mir.sh`	告警并跳过MIR级别优化对比。接受2个及以上MIR文件，标准化后两两对比，报告清零/drop-glue模式首次消失的优化级别
`{baseDir}/tools/scripts/semantic_audit.py`	告警并跳用语义源码分析
`{baseDir}/tools/scripts/find_dangerous_apis.py`	告警并跳过危险API扫描
`{baseDir}/tools/scripts/check_mir_patterns.py`	告警并跳过MIR分析
`{baseDir}/tools/scripts/check_llvm_patterns.py`	告警并跳过LLVM IR分析
`{baseDir}/tools/scripts/check_rust_asm.py`	告警并跳过Rust汇编分析（ `STACK_RETENTION` 、 `REGISTER_SPILL` 、drop-glue检查）。会调用 `check_rust_asm_x86.py` （生产可用）或 `check_rust_asm_aarch64.py` （实验性——AArch64检测结果需要手动验证）
`{baseDir}/tools/scripts/check_rust_asm_x86.py`	`check_rust_asm.py` 做x86-64分析时的必填依赖，缺失则告警并跳过
`{baseDir}/tools/scripts/check_rust_asm_aarch64.py`	`check_rust_asm.py` 做AArch64分析时的必填依赖（实验性），缺失则告警并跳过

通用前置依赖：

前置依赖	缺失时的失败处理
`{baseDir}/tools/generate_poc.py`	快速失败，PoC生成是必填能力

Approved Wipe APIs

认可的清零API

The following are recognized as valid zeroization. Configure additional entries in

{baseDir}/configs/

C/C++

```
explicit_bzero
```
```
memset_s
```
```
SecureZeroMemory
```
```
OPENSSL_cleanse
```
```
sodium_memzero
```

Volatile wipe loops (pattern-based; see

volatile_wipe_patterns

{baseDir}/configs/default.yaml

)

In IR:
```
llvm.memset
```
with volatile flag, volatile stores, or non-elidable wipe call

Rust

```
zeroize::Zeroize
```
trait (
```
zeroize()
```
method)
```
Zeroizing<T>
```
wrapper (drop-based)
```
ZeroizeOnDrop
```
derive macro

以下API会被识别为有效的清零操作，可在

{baseDir}/configs/

中配置额外的认可条目。

C/C++

```
explicit_bzero
```
```
memset_s
```
```
SecureZeroMemory
```
```
OPENSSL_cleanse
```
```
sodium_memzero
```
易失性擦除循环（基于模式匹配，见
```
{baseDir}/configs/default.yaml
```
中的
```
volatile_wipe_patterns
```
配置）
IR层面：带volatile标记的
```
llvm.memset
```
、易失性存储、不可消除的擦除调用

Rust

```
zeroize::Zeroize
```
trait（
```
zeroize()
```
方法）
```
Zeroizing<T>
```
封装器（基于drop实现）
```
ZeroizeOnDrop
```
派生宏

Finding Capabilities

检测能力

Findings are grouped by required evidence. Only attempt findings for which the required tooling is available.

Finding ID	Description	Requires	PoC Support
`MISSING_SOURCE_ZEROIZE`	No zeroization found in source	Source only	Yes (C/C++ + Rust)
`PARTIAL_WIPE`	Incorrect size or incomplete wipe	Source only	Yes (C/C++ + Rust)
`NOT_ON_ALL_PATHS`	Zeroization missing on some control-flow paths (heuristic)	Source only	Yes (C/C++ only)
`SECRET_COPY`	Sensitive data copied without zeroization tracking	Source + MCP preferred	Yes (C/C++ + Rust)
`INSECURE_HEAP_ALLOC`	Secret uses insecure allocator (malloc vs. secure_malloc)	Source only	Yes (C/C++ only)
`OPTIMIZED_AWAY_ZEROIZE`	Compiler removed zeroization	IR diff required (never source-only)	Yes
`STACK_RETENTION`	Stack frame may retain secrets after return	Assembly required (C/C++); LLVM IR `alloca` + `lifetime.end` evidence (Rust); assembly corroboration upgrades to `confirmed`	Yes (C/C++ only)
`REGISTER_SPILL`	Secrets spilled from registers to stack	Assembly required (C/C++); LLVM IR `load` +call-site evidence (Rust); assembly corroboration upgrades to `confirmed`	Yes (C/C++ only)
`MISSING_ON_ERROR_PATH`	Error-handling paths lack cleanup	CFG or MCP required	Yes
`NOT_DOMINATING_EXITS`	Wipe doesn't dominate all exits	CFG or MCP required	Yes
`LOOP_UNROLLED_INCOMPLETE`	Unrolled loop wipe is incomplete	Semantic IR required	Yes

检测问题按所需证据分组，仅当所需工具可用时才会检测对应问题。

问题ID	描述	所需依赖	PoC支持
`MISSING_SOURCE_ZEROIZE`	源码中未找到清零逻辑	仅需源码	支持（C/C++ + Rust）
`PARTIAL_WIPE`	擦除大小错误或擦除不完整	仅需源码	支持（C/C++ + Rust）
`NOT_ON_ALL_PATHS`	部分控制流路径缺失清零逻辑（启发式）	仅需源码	支持（仅C/C++）
`SECRET_COPY`	敏感数据被复制但未做清零追踪	源码 + 优先使用MCP	支持（C/C++ + Rust）
`INSECURE_HEAP_ALLOC`	机密数据使用了不安全的分配器（比如使用malloc而非secure_malloc）	仅需源码	支持（仅C/C++）
`OPTIMIZED_AWAY_ZEROIZE`	编译器移除了清零逻辑	必须有IR差异（不能仅靠源码判断）	支持
`STACK_RETENTION`	栈帧返回后可能留存机密数据	C/C++需要汇编；Rust需要LLVM IR `alloca` + `lifetime.end` 证据；有汇编佐证可升级为 `confirmed`	支持（仅C/C++）
`REGISTER_SPILL`	机密数据从寄存器溢出到栈	C/C++需要汇编；Rust需要LLVM IR `load` +调用点证据；有汇编佐证可升级为 `confirmed`	支持（仅C/C++）
`MISSING_ON_ERROR_PATH`	错误处理路径缺少清理逻辑	需要CFG或MCP	支持
`NOT_DOMINATING_EXITS`	擦除逻辑未覆盖所有退出路径	需要CFG或MCP	支持
`LOOP_UNROLLED_INCOMPLETE`	展开的循环擦除不完整	需要语义IR	支持

Agent Architecture

Agent架构

The analysis pipeline uses 11 agents across 8 phases, invoked by the orchestrator (

{baseDir}/prompts/task.md

) via

Task

. Agents write persistent finding files to a shared working directory (

/tmp/zeroize-audit-{run_id}/

), enabling parallel execution and protecting against context pressure.

Agent	Phase	Purpose	Output Directory
`0-preflight`	Phase 0	Preflight checks (tools, toolchain, compile DB, crate build), config merge, workdir creation, TU enumeration	`{workdir}/`
`1-mcp-resolver`	Phase 1, Wave 1 (C/C++ only)	Resolve symbols, types, and cross-file references via Serena MCP	`mcp-evidence/`
`2-source-analyzer`	Phase 1, Wave 2a (C/C++ only)	Identify sensitive objects, detect wipes, validate correctness, data-flow/heap	`source-analysis/`
`2b-rust-source-analyzer`	Phase 1, Wave 2b (Rust only, parallel with 2a)	Rustdoc JSON trait-aware analysis + dangerous API grep	`source-analysis/`
`3-tu-compiler-analyzer`	Phase 2, Wave 3 (C/C++ only, N parallel)	Per-TU IR diff, assembly, semantic IR, CFG analysis	`compiler-analysis/{tu_hash}/`
`3b-rust-compiler-analyzer`	Phase 2, Wave 3R (Rust only, single agent)	Crate-level MIR, LLVM IR, and assembly analysis	`rust-compiler-analysis/`
`4-report-assembler`	Phase 3 (interim) + Phase 6 (final)	Collect findings from all agents, apply confidence gates; merge PoC results and produce final report	`report/`
`5-poc-generator`	Phase 4	Craft bespoke proof-of-concept programs (C/C++: all categories; Rust: MISSING_SOURCE_ZEROIZE, SECRET_COPY, PARTIAL_WIPE)	`poc/`
`5b-poc-validator`	Phase 5	Compile and run all PoCs	`poc/`
`5c-poc-verifier`	Phase 5	Verify each PoC proves its claimed finding	`poc/`
`6-test-generator`	Phase 7 (optional)	Generate runtime validation test harnesses	`tests/`

The orchestrator reads one per-phase workflow file from

{baseDir}/workflows/

at a time, and maintains

orchestrator-state.json

for recovery after context compression. Agents receive configuration by file path (

config_path

), not by value.

分析流水线包含8个阶段共11个Agent，由编排器（

{baseDir}/prompts/task.md

）通过

Task

调用。Agent将持久化的问题文件写入共享工作目录（

/tmp/zeroize-audit-{run_id}/

），支持并行执行，避免上下文压力问题。

Agent	阶段	用途	输出目录
`0-preflight`	阶段0	预检（工具、工具链、编译数据库、crate构建）、配置合并、工作目录创建、翻译单元枚举	`{workdir}/`
`1-mcp-resolver`	阶段1，第一波（仅C/C++）	通过Serena MCP解析符号、类型和跨文件引用	`mcp-evidence/`
`2-source-analyzer`	阶段1，第二波2a（仅C/C++）	识别敏感对象、检测擦除逻辑、验证正确性、数据流/堆分析	`source-analysis/`
`2b-rust-source-analyzer`	阶段1，第二波2b（仅Rust，和2a并行）	感知Rustdoc JSON trait的分析 + 危险API grep	`source-analysis/`
`3-tu-compiler-analyzer`	阶段2，第三波（仅C/C++，N个并行）	单翻译单元IR差异、汇编、语义IR、CFG分析	`compiler-analysis/{tu_hash}/`
`3b-rust-compiler-analyzer`	阶段2，第三波R（仅Rust，单Agent）	crate级别MIR、LLVM IR和汇编分析	`rust-compiler-analysis/`
`4-report-assembler`	阶段3（中期） + 阶段6（终期）	收集所有Agent的检测问题，应用置信度管控；合并PoC结果并生成最终报告	`report/`
`5-poc-generator`	阶段4	生成定制化的概念验证程序（C/C++支持所有类别；Rust支持MISSING_SOURCE_ZEROIZE、SECRET_COPY、PARTIAL_WIPE）	`poc/`
`5b-poc-validator`	阶段5	编译并运行所有PoC	`poc/`
`5c-poc-verifier`	阶段5	验证每个PoC确实可以复现声称的问题	`poc/`
`6-test-generator`	阶段7（可选）	生成运行时验证测试框架	`tests/`

编排器每次从

{baseDir}/workflows/

读取一个单阶段工作流文件，维护

orchestrator-state.json

用于上下文压缩后的恢复。Agent通过文件路径（

config_path

）获取配置，而非直接传递配置值。

Execution flow

执行流程

Phase 0: 0-preflight agent — Preflight + config + create workdir + enumerate TUs
           → writes orchestrator-state.json, merged-config.yaml, preflight.json
Phase 1: Wave 1:  1-mcp-resolver              (skip if mcp_mode=off OR language_mode=rust)
         Wave 2a: 2-source-analyzer           (C/C++ only; skip if no compile_db)  ─┐ parallel
         Wave 2b: 2b-rust-source-analyzer     (Rust only; skip if no cargo_manifest) ─┘
Phase 2: Wave 3:  3-tu-compiler-analyzer x N  (C/C++ only; parallel per TU)
         Wave 3R: 3b-rust-compiler-analyzer   (Rust only; single crate-level agent)
Phase 3: Wave 4:  4-report-assembler          (mode=interim → findings.json; reads all agent outputs)
Phase 4: Wave 5:  5-poc-generator             (C/C++: all categories; Rust: MISSING_SOURCE_ZEROIZE, SECRET_COPY, PARTIAL_WIPE; other Rust findings: poc_supported=false)
Phase 5: PoC Validation & Verification
           Step 1: 5b-poc-validator agent      (compile and run all PoCs)
           Step 2: 5c-poc-verifier agent       (verify each PoC proves its claimed finding)
           Step 3: Orchestrator presents verification failures to user via AskUserQuestion
           Step 4: Orchestrator merges all results into poc_final_results.json
Phase 6: Wave 6: 4-report-assembler           (mode=final → merge PoC results, final-report.md)
Phase 7: Wave 7: 6-test-generator             (optional)
Phase 8: Orchestrator — Return final-report.md

阶段0: 0-preflight Agent — 预检 + 配置合并 + 创建工作目录 + 枚举翻译单元
           → 输出orchestrator-state.json、merged-config.yaml、preflight.json
阶段1: 第一波:  1-mcp-resolver              （如果mcp_mode=off或语言为Rust则跳过）
         第二波2a: 2-source-analyzer           （仅C/C++；无compile_db则跳过） ─┐ 并行执行
         第二波2b: 2b-rust-source-analyzer     （仅Rust；无cargo_manifest则跳过） ─┘
阶段2: 第三波:  3-tu-compiler-analyzer x N  （仅C/C++；按翻译单元并行）
         第三波R: 3b-rust-compiler-analyzer   （仅Rust；单crate级别Agent）
阶段3: 第四波:  4-report-assembler          （mode=interim → 输出findings.json；读取所有Agent输出）
阶段4: 第五波:  5-poc-generator             （C/C++支持所有类别；Rust支持MISSING_SOURCE_ZEROIZE、SECRET_COPY、PARTIAL_WIPE；其他Rust问题poc_supported=false）
阶段5: PoC验证与确认
           步骤1: 5b-poc-validator Agent      （编译并运行所有PoC）
           步骤2: 5c-poc-verifier Agent       （验证每个PoC可复现声称的问题）
           步骤3: 编排器通过AskUserQuestion向用户反馈验证失败的情况
           步骤4: 编排器将所有结果合并到poc_final_results.json
阶段6: 第六波: 4-report-assembler           （mode=final → 合并PoC结果，输出final-report.md）
阶段7: 第七波: 6-test-generator             （可选）
阶段8: 编排器 — 返回final-report.md

Cross-Reference Convention

交叉引用规则

IDs are namespaced per agent to prevent collisions during parallel execution:

Entity	Pattern	Assigned By
Sensitive object (C/C++)	`SO-0001` – `SO-4999`	`2-source-analyzer`
Sensitive object (Rust)	`SO-5000` – `SO-9999` (Rust namespace)	`2b-rust-source-analyzer`
Source finding (C/C++)	`F-SRC-NNNN`	`2-source-analyzer`
Source finding (Rust)	`F-RUST-SRC-NNNN`	`2b-rust-source-analyzer`
IR finding (C/C++)	`F-IR-{tu_hash}-NNNN`	`3-tu-compiler-analyzer`
ASM finding (C/C++)	`F-ASM-{tu_hash}-NNNN`	`3-tu-compiler-analyzer`
CFG finding	`F-CFG-{tu_hash}-NNNN`	`3-tu-compiler-analyzer`
Semantic IR finding	`F-SIR-{tu_hash}-NNNN`	`3-tu-compiler-analyzer`
Rust MIR finding	`F-RUST-MIR-NNNN`	`3b-rust-compiler-analyzer`
Rust LLVM IR finding	`F-RUST-IR-NNNN`	`3b-rust-compiler-analyzer`
Rust assembly finding	`F-RUST-ASM-NNNN`	`3b-rust-compiler-analyzer`
Translation unit	`TU-{hash}`	Orchestrator
Final finding	`ZA-NNNN`	`4-report-assembler`

Every finding JSON object includes

related_objects

related_findings

, and

evidence_files

fields for cross-referencing between agents.

ID按Agent划分命名空间，避免并行执行时出现冲突：

实体	命名模式	分配方
敏感对象（C/C++）	`SO-0001` – `SO-4999`	`2-source-analyzer`
敏感对象（Rust）	`SO-5000` – `SO-9999` （Rust命名空间）	`2b-rust-source-analyzer`
源码问题（C/C++）	`F-SRC-NNNN`	`2-source-analyzer`
源码问题（Rust）	`F-RUST-SRC-NNNN`	`2b-rust-source-analyzer`
IR问题（C/C++）	`F-IR-{tu_hash}-NNNN`	`3-tu-compiler-analyzer`
汇编问题（C/C++）	`F-ASM-{tu_hash}-NNNN`	`3-tu-compiler-analyzer`
CFG问题	`F-CFG-{tu_hash}-NNNN`	`3-tu-compiler-analyzer`
语义IR问题	`F-SIR-{tu_hash}-NNNN`	`3-tu-compiler-analyzer`
Rust MIR问题	`F-RUST-MIR-NNNN`	`3b-rust-compiler-analyzer`
Rust LLVM IR问题	`F-RUST-IR-NNNN`	`3b-rust-compiler-analyzer`
Rust汇编问题	`F-RUST-ASM-NNNN`	`3b-rust-compiler-analyzer`
翻译单元	`TU-{hash}`	编排器
最终问题	`ZA-NNNN`	`4-report-assembler`

每个问题JSON对象都包含

related_objects

、

related_findings

和

evidence_files

字段，用于Agent之间的交叉引用。

Detection Strategy

检测策略

Analysis runs in two phases. For complete step-by-step guidance, see

{baseDir}/references/detection-strategy.md

Phase Steps Findings produced Required tooling

Phase 1 (Source)

1–6

Phase	Steps	Findings produced	Required tooling
Phase 1 (Source)	1–6	`MISSING_SOURCE_ZEROIZE` , `PARTIAL_WIPE` , `NOT_ON_ALL_PATHS` , `SECRET_COPY` , `INSECURE_HEAP_ALLOC`	Source + compile DB
Phase 2 (Compiler)	7–12	`OPTIMIZED_AWAY_ZEROIZE` , `STACK_RETENTION` , `REGISTER_SPILL` , `LOOP_UNROLLED_INCOMPLETE` †, `MISSING_ON_ERROR_PATH` ‡, `NOT_DOMINATING_EXITS` ‡	`clang` , IR/ASM tools

MISSING_SOURCE_ZEROIZE

PARTIAL_WIPE

NOT_ON_ALL_PATHS

SECRET_COPY

INSECURE_HEAP_ALLOC

Source + compile DB

Phase 2 (Compiler)

7–12

OPTIMIZED_AWAY_ZEROIZE

STACK_RETENTION

,
REGISTER_SPILL
,

LOOP_UNROLLED_INCOMPLETE

†,

MISSING_ON_ERROR_PATH

‡,

NOT_DOMINATING_EXITS

‡

clang

, IR/ASM tools

* requires

enable_asm=true

(default) † requires

enable_semantic_ir=true

‡ requires

enable_cfg=true

分析分为两个阶段执行，完整的分步指南请查看

{baseDir}/references/detection-strategy.md

。

阶段步骤输出问题所需工具

阶段1（源码）

1–6

阶段	步骤	输出问题	所需工具
阶段1（源码）	1–6	`MISSING_SOURCE_ZEROIZE` 、 `PARTIAL_WIPE` 、 `NOT_ON_ALL_PATHS` 、 `SECRET_COPY` 、 `INSECURE_HEAP_ALLOC`	源码 + 编译数据库
阶段2（编译器）	7–12	`OPTIMIZED_AWAY_ZEROIZE` 、 `STACK_RETENTION` 、 `REGISTER_SPILL` 、 `LOOP_UNROLLED_INCOMPLETE` †、 `MISSING_ON_ERROR_PATH` ‡、 `NOT_DOMINATING_EXITS` ‡	`clang` 、IR/汇编工具

MISSING_SOURCE_ZEROIZE

、

PARTIAL_WIPE

、

NOT_ON_ALL_PATHS

、

SECRET_COPY

、

INSECURE_HEAP_ALLOC

源码 + 编译数据库

阶段2（编译器）

7–12

OPTIMIZED_AWAY_ZEROIZE

、

STACK_RETENTION

、
REGISTER_SPILL
、

LOOP_UNROLLED_INCOMPLETE

†、

MISSING_ON_ERROR_PATH

‡、

NOT_DOMINATING_EXITS

‡

clang

、IR/汇编工具

* 需要

enable_asm=true

（默认开启） † 需要

enable_semantic_ir=true

‡ 需要

enable_cfg=true

Output Format

输出格式

Each run produces two outputs:

final-report.md
— Comprehensive markdown report (primary human-readable output)
findings.json
— Structured JSON matching
```
{baseDir}/schemas/output.json
```
(for machine consumption and downstream tools)

每次运行生成两类输出：

final-report.md
— 完整的markdown报告（主要的人类可读输出）
findings.json
— 符合
```
{baseDir}/schemas/output.json
```
的结构化JSON（用于机器消费和下游工具）

Markdown Report Structure

Markdown报告结构

The markdown report (

final-report.md

) contains these sections:

Header: Run metadata (run_id, timestamp, repo, compile_db, config summary)
Executive Summary: Finding counts by severity, confidence, and category
Sensitive Objects Inventory: Table of all identified objects with IDs, types, locations
Findings: Grouped by severity then confidence. Each finding includes location, object, all evidence (source/IR/ASM/CFG), compiler evidence details, and recommended fix
Superseded Findings: Source findings replaced by CFG-backed findings
Confidence Gate Summary: Downgrades applied and overrides rejected
Analysis Coverage: TUs analyzed, agent success/failure, features enabled
Appendix: Evidence Files: Mapping of finding IDs to evidence file paths

markdown报告（

final-report.md

）包含以下章节：

头部：运行元数据（run_id、时间戳、仓库、compile_db、配置摘要）
执行摘要：按严重级别、置信度、类别统计的问题数量
敏感对象清单：所有识别到的对象表格，包含ID、类型、位置
问题详情：按严重级别、置信度分组。每个问题包含位置、对象、所有证据（源码/IR/汇编/CFG）、编译器证据详情、修复建议
被取代的问题：被CFG支撑的问题替代的源码级问题
置信度管控摘要：应用的降级和被拒绝的覆盖配置
分析覆盖率：已分析的翻译单元、Agent成功/失败状态、启用的功能
附录：证据文件：问题ID到证据文件路径的映射

Structured JSON

结构化JSON

The

findings.json

file follows the schema in

{baseDir}/schemas/output.json

. Each

Finding

object:

json

{
  "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"
  }
}

See

{baseDir}/schemas/output.json

for the full schema and enum values.

findings.json

文件遵循

{baseDir}/schemas/output.json

中的schema，每个

Finding

对象结构如下：

json

{
  "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"
  }
}

完整schema和枚举值请查看

{baseDir}/schemas/output.json

。

Confidence Gating

置信度管控

Evidence thresholds

证据阈值

A finding requires at least 2 independent signals to be marked

confirmed

. With 1 signal, mark

likely

. With 0 strong signals (name-pattern match only), mark

needs_review

Signals include: name pattern match, type hint match, explicit annotation, IR evidence, ASM evidence, MCP cross-reference, CFG evidence, PoC validation.

一个问题至少需要2个独立信号才能标记为

confirmed

；只有1个信号标记为

likely

；没有强信号（仅名称模式匹配）标记为

needs_review

。

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

PoC validation as evidence signal

PoC验证作为证据信号

Every finding is validated against a bespoke PoC. After compilation and execution, each PoC is also verified to ensure it actually tests the claimed vulnerability. The combined result is an evidence signal:

PoC Result	Verified	Impact
Exit 0 (exploitable)	Yes	Strong signal — can upgrade `likely` to `confirmed`
Exit 1 (not exploitable)	Yes	Downgrade severity to `low` (informational); retain in report
Exit 0 or 1	No (user accepted)	Weaker signal — note verification failure in evidence
Exit 0 or 1	No (user rejected)	No confidence change; annotate as `rejected`
Compile failure / no PoC	—	No confidence change; annotate in evidence

每个问题都会通过定制化PoC验证。编译运行后，会进一步验证PoC确实可以测试声称的漏洞，合并结果作为证据信号：

PoC结果	验证通过	影响
退出码0（可利用）	是	强信号，可将 `likely` 升级为 `confirmed`
退出码1（不可利用）	是	将严重级别降级为 `low` （信息类），保留在报告中
退出码0或1	否（用户接受）	弱信号，在证据中记录验证失败
退出码0或1	否（用户拒绝）	置信度不变，标记为 `rejected`
编译失败 / 无PoC	—	置信度不变，在证据中标记

MCP unavailability downgrade

MCP不可用降级规则

When

mcp_mode=prefer

and MCP is unavailable, downgrade the following unless independent IR/CFG/ASM evidence is strong (2+ signals without MCP):

Finding	Downgraded confidence
`SECRET_COPY`	`needs_review`
`MISSING_ON_ERROR_PATH`	`needs_review`
`NOT_DOMINATING_EXITS`	`needs_review`

当

mcp_mode=prefer

且MCP不可用时，降级以下问题，除非有独立的IR/CFG/汇编强证据（无MCP时也有2+信号）：

问题	降级后的置信度
`SECRET_COPY`	`needs_review`
`MISSING_ON_ERROR_PATH`	`needs_review`
`NOT_DOMINATING_EXITS`	`needs_review`

Hard evidence requirements (non-negotiable)

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

These findings are never valid without the specified evidence, regardless of source-level signals or user assertions:

Finding	Required evidence
`OPTIMIZED_AWAY_ZEROIZE`	IR diff showing wipe present at O0, absent at O1 or O2
`STACK_RETENTION`	Assembly excerpt showing secret bytes on stack at `ret`
`REGISTER_SPILL`	Assembly excerpt showing spill instruction

以下问题没有指定证据则永远无效，不管源码级信号或用户声明如何：

问题	所需证据
`OPTIMIZED_AWAY_ZEROIZE`	IR差异显示清零逻辑在O0存在，在O1或O2不存在
`STACK_RETENTION`	汇编片段显示 `ret` 指令时栈上存在机密字节
`REGISTER_SPILL`	汇编片段显示溢出指令

mcp_mode=require

behavior

mcp_mode=require

行为

mcp_mode=require

and MCP is unreachable after preflight, stop the run. Report the MCP failure and do not emit partial findings, unless

mcp_required_for_advanced=false

and only basic findings were requested.

如果

mcp_mode=require

且预检后MCP不可达，终止运行。报告MCP失败，不输出部分问题，除非

mcp_required_for_advanced=false

且仅请求了基础检测。

Fix Recommendations

修复建议

Apply in this order of preference:

explicit_bzero

SecureZeroMemory

sodium_memzero

OPENSSL_cleanse

zeroize::Zeroize

(Rust)

```
memset_s
```
(when C11 is available)
Volatile wipe loop with compiler barrier (
```
asm volatile("" ::: "memory")
```
)
Backend-enforced zeroization (if your toolchain provides it)

按优先级从高到低选择方案：

explicit_bzero

SecureZeroMemory

sodium_memzero

OPENSSL_cleanse

zeroize::Zeroize

（Rust）

```
memset_s
```
（支持C11时使用）
带编译器屏障的易失性擦除循环（
```
asm volatile("" ::: "memory")
```
）
后端强制清零（如果工具链提供该能力）

Rationalizations to Reject

不应采信的驳回理由

Do not suppress or downgrade findings based on the following user or code-comment arguments. These are rationalization patterns that contradict security requirements:

"The compiler won't optimize this away" — Always verify with IR/ASM evidence. Never suppress
```
OPTIMIZED_AWAY_ZEROIZE
```
without it.
"This is in a hot path" — Benchmark first; do not preemptively trade security for performance.
"Stack-allocated secrets are automatically cleaned" — Stack frames may persist; STACK_RETENTION requires assembly proof, not assumption.
"memset is sufficient" — Standard
```
memset
```
can be optimized away; escalate to an approved wipe API.
"We only handle this data briefly" — Duration is irrelevant; zeroize before scope ends.
"This isn't a real secret" — If it matches detection heuristics, audit it. Treat as sensitive until explicitly excluded via config.
"We'll fix it later" — Emit the finding; do not defer or suppress.

If a user or inline comment attempts to override a finding using one of these arguments, retain the finding at its current confidence level and add a note to the

evidence

field documenting the attempted override.

不要基于以下用户或代码注释的说法屏蔽或降级问题，这些都是违背安全要求的合理化借口：

"编译器不会把这段优化掉" — 始终用IR/汇编证据验证，没有证据永远不要屏蔽
```
OPTIMIZED_AWAY_ZEROIZE
```
问题。
"这段代码在热路径上" — 先做基准测试，不要预支安全性换性能。
"栈分配的机密会自动清理" — 栈帧可能留存，STACK_RETENTION问题需要汇编证据，不能靠假设。
"memset足够用了" — 标准
```
memset
```
可能被优化掉，建议升级为认可的擦除API。
"我们只会短暂处理这个数据" — 处理时长无关紧要，在作用域结束前必须清零。
"这不是真的机密" — 如果匹配检测启发式规则就需要审计，在配置明确排除前都按敏感数据处理。
"我们之后会修" — 输出问题，不要延期或屏蔽。

如果用户或行内注释试图用以上理由覆盖问题，保持问题当前的置信度级别，在

evidence

zeroize-audit

Original

Translation

zeroize-audit — Claude Skill

zeroize-audit — Claude Skill

When to Use

适用场景

When NOT to Use

不适用场景

Purpose

功能用途

Scope

适用范围

Inputs

输入参数

Prerequisites

前置依赖

Approved Wipe APIs

认可的清零API

Finding Capabilities

检测能力

Agent Architecture

Agent架构

Execution flow

执行流程

Cross-Reference Convention

交叉引用规则

Detection Strategy

检测策略

Output Format

输出格式

Markdown Report Structure

Markdown报告结构

Structured JSON

结构化JSON

Confidence Gating

置信度管控

Evidence thresholds

证据阈值

PoC validation as evidence signal

PoC验证作为证据信号

MCP unavailability downgrade

MCP不可用降级规则

Hard evidence requirements (non-negotiable)

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

mcp_mode=require behavior

mcp_mode=require行为

Fix Recommendations

修复建议

Rationalizations to Reject

不应采信的驳回理由

`mcp_mode=require`
behavior

`mcp_mode=require`
行为