AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

zeroize-audit

Detects missing zeroization of sensitive data in source code and identifies zeroization removed by compiler optimizations, with assembly-level analysis, and control-flow verification. Use for auditing C/C++/Rust code handling secrets, keys, passwords, or other sensitive data.

Original source
trailofbits
License
CC-BY-SA-4.0
Pinned revision
2be6433b39e009cd2b6fd3be1895f6b1faa5af9a

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read trailofbits--zeroize-audit at revision 2be6433b39e009cd2b6fd3be1895f6b1faa5af9a, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 18

prompts/system.md

zeroize-audit

Audits C/C++/Rust code for missing zeroization and compiler-removed wipes. Pipeline: source scan -> MCP/LSP semantic context -> IR diff -> assembly checks.

Use the Execution Contract to run the bundled roles through the current agent environment. The orchestrator resolves baseDir to the skill directory before any role reads or executes resources.

Findings

  • MISSING_SOURCE_ZEROIZE, PARTIAL_WIPE, NOT_ON_ALL_PATHS
  • OPTIMIZED_AWAY_ZEROIZE (IR evidence required)
  • REGISTER_SPILL, STACK_RETENTION (assembly evidence for C/C++; LLVM IR evidence for Rust; assembly corroboration available for Rust via check_rust_asm.py)
  • SECRET_COPY, INSECURE_HEAP_ALLOC
  • MISSING_ON_ERROR_PATH, NOT_DOMINATING_EXITS, LOOP_UNROLLED_INCOMPLETE

Working Directory

Each run creates a working directory at /tmp/zeroize-audit-{run_id}/ with the following structure. Agents write persistent finding files here; later agents and the orchestrator reconstruct the full picture from these files without relying on conversation history.

/tmp/zeroize-audit-{run_id}/
  preflight.json                     # Orchestrator: env, config, TU list
  mcp-evidence/
    status.json                      # MCP resolver status (success/partial/fail)
    symbols.json                     # Resolved symbol definitions + types
    references.json                  # Cross-file reference graph
    notes.md                         # MCP observations + cross-refs
  source-analysis/
    sensitive-objects.json           # C/C++ SO-NNNN + Rust SO-NNNN (shared, appended by each source-analyzer)
    source-findings.json             # F-SRC-NNNN (C/C++) + F-RUST-SRC-NNNN (Rust, appended)
    tu-map.json                      # C/C++ TU hashes + Rust crate hash
    rust-semantic-findings.json      # Intermediate: 2b-rust-source-analyzer rustdoc output
    rust-dangerous-api-findings.json # Intermediate: 2b-rust-source-analyzer grep output
    rust-notes.md                    # 2b-rust-source-analyzer notes
    notes.md                         # 2-source-analyzer observations
  rust-compiler-analysis/
    {rust_tu_hash}.mir               # MIR text (emit_rust_mir.sh; supports --opt, --bin/--lib)
    {rust_tu_hash}.O0.ll             # LLVM IR at O0 (emit_rust_ir.sh; supports --bin/--lib)
    {rust_tu_hash}.O2.ll             # LLVM IR at O2 (emit_rust_ir.sh; supports --bin/--lib)
    {rust_tu_hash}.O2.s              # Assembly at O2 (emit_rust_asm.sh; only if enable_asm=true)
    mir-findings.json                # F-RUST-MIR-NNNN IDs
    ir-findings.json                 # F-RUST-IR-NNNN IDs
    asm-findings.json                # F-RUST-ASM-NNNN IDs (empty array if enable_asm=false)
    coverage-gaps.json               # Section D patterns no script audits (empty array if none)
    notes.md
  compiler-analysis/
    {tu_hash}/
      ir-findings.json              # F-IR-{tu_hash}-NNNN IDs
      asm-findings.json             # F-ASM-{tu_hash}-NNNN IDs
      cfg-findings.json             # F-CFG-{tu_hash}-NNNN IDs
      semantic-ir.json              # F-SIR-{tu_hash}-NNNN IDs
      superseded-findings.json      # CFG results that replace heuristic source findings
      notes.md
  report/
    raw-findings.json               # All findings pre-gating
    id-mapping.json                 # Namespaced IDs -> final ZA-NNNN IDs
    findings.json                   # Gated findings (structured JSON for downstream tools)
    final-report.md                 # Comprehensive markdown report (primary output)
    notes.md
  poc/                              # PoC files, manifest, validation/verification results, notes.md
    poc_manifest.json               # Generated by agent 5
    poc_validation_results.json     # Written by agent 5b (compile/run results)
    poc_verification.json           # Written by agent 5c (semantic verification)
    poc_final_results.json          # Written by orchestrator Phase 5 (merged results)
  tests/                            # Test harnesses, Makefile, notes.md

Cross-Reference Convention

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

| Entity | Pattern | Assigned By | |---|---|---| | Sensitive object (C/C++) | SO-NNNN | 2-source-analyzer | | Sensitive object (Rust) | SO-NNNN (offset 5000+) | 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 | 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: ["SO-0003"] — which sensitive objects this applies to
  • related_findings: ["F-SRC-0001"] — related findings in other files
  • evidence_files: ["compiler-analysis/a1b2/ir-diff-O0-O2.txt"] — paths relative to workdir

Dual-Mode Report Assembly

Agent 4-report-assembler is invoked twice during a run:

  1. Interim mode (Phase 3): Collects findings, applies supersessions and confidence gates, produces findings.json only. No final-report.md at this stage.
  2. Final mode (Phase 6): Reads existing findings.json, merges PoC validation and verification results from poc/poc_final_results.json, then produces both an updated findings.json and the final final-report.md.

Agent Error Protocol

  • Always write output files: Every agent must write its status/output JSON files even on failure (use empty arrays [] or error status objects).
  • Prefer partial results over nothing: If one sub-step fails (e.g., ASM analysis), write results from completed steps and continue.
  • Notes.md is mandatory: Every agent writes a notes.md summarizing what it did, any errors, and relative paths to its output files.
  • Temp file cleanup: Agents must clean up /tmp/zeroize-audit/<tu_hash>.* temp files on completion or failure.

Prerequisites

C/C++ analysis:

  • compile_commands.json is mandatory.
  • Codebase must be buildable with commands from the compile DB.
  • Required tools: clang, uvx (for Serena MCP server), python3.

Rust analysis:

  • Cargo.toml path is mandatory.
  • Crate must be buildable (cargo check passes).
  • Required tools: cargo +nightly, uv.

Quick check:

which clang uv uvx python3   # C/C++
cargo +nightly --version  # Rust
uv --version              # Rust Python scripts

Rust Analysis — Few-Shot Examples

Example 1 — Copy derive on sensitive type → SECRET_COPY (critical)

#[derive(Copy, Clone)]
struct HmacKey([u8; 32]);

Finding: SECRET_COPY (critical). #[derive(Copy)] on HmacKey — all assignments are untracked duplicates, no Drop ever runs. Every let k2 = k1 silently copies all 32 key bytes with no automatic cleanup.

Fix: Remove Copy. Add #[derive(ZeroizeOnDrop)] from the zeroize crate.

Example 2 — mem::forget on secret → MISSING_SOURCE_ZEROIZE (critical)

let key = SecretKey::new();
// ... use key ...
std::mem::forget(key);  // BAD: prevents Drop / ZeroizeOnDrop

Finding: MISSING_SOURCE_ZEROIZE (critical). mem::forget() prevents Drop and ZeroizeOnDrop from running — secret bytes remain in memory indefinitely.

Fix: Remove mem::forget. Let the value drop normally, or call key.zeroize() before the forget if explicit timing is required.

Example 3 — Non-volatile memset removed at O2 → OPTIMIZED_AWAY_ZEROIZE (high)

At O0 LLVM IR:

store volatile i8 0, ptr %key_buf    ; 32 volatile stores present

At O2 LLVM IR:

; stores absent — LLVM DSE removed them (key_buf never read after)

Finding: OPTIMIZED_AWAY_ZEROIZE (high). Volatile store count dropped from 32 (O0) to 0 (O2). Dead-store elimination removed the wipe.

Fix: Use zeroize::Zeroize::zeroize(&mut key_buf) which emits a compiler-fence-backed wipe that survives DSE.