zeroize-audit

# 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 ## 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 ## 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). --- ## 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) | --- ## 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 | --- ## Approved Wipe APIs 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` in `{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 --- ## 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 | --- ## Agent Architecture 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. ### 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 ``` ## 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` |