interface:
  display_name: "Zeroize Audit"
  short_description: "Find missing or compiler-removed secret zeroization"
  icon_small: "assets/trail-of-bits-mark.svg"
  icon_large: "assets/trail-of-bits-mark.svg"
  brand_color: "#D83A34"

version: 0.1.0

sensitive_name_regex:
  - "(?i)\\b(secret|key|seed|priv|private|sk|nonce|token|pwd|pass(word)?)\\b"

explicit_sensitive_markers:
  - "annotate\\(\"sensitive\"\\)"
  - "\\bSENSITIVE\\b"

approved_wipe_funcs:
  - "explicit_bzero"
  - "memset_s"
  - "SecureZeroMemory"
  - "OPENSSL_cleanse"
  - "sodium_memzero"

ir_wipe_patterns:
  - "call void @llvm\\.memset\\."
  - "store volatile i8 0"
  - "call .*@explicit_bzero"
  - "call .*@memset_s"

version: 0.1.0

languages:
  - c
  - cpp
  - rust

# Pattern-specific configs (register_spill_patterns, callee_saved_registers,
# asm_wipe_patterns, ir_wipe_patterns, secret_copy_patterns, cfg_patterns,
# ir_semantic_patterns) are defined directly in their analysis scripts.

# Heuristic sensitivity signals
sensitive_name_regex:
  - "(?i)\\b(secret|key|seed|priv|private|sk|shared[_-]?secret|nonce|token|pwd|pass(word)?)\\b"
  - "(?i)\\b(master[_-]?key|session[_-]?key|api[_-]?key)\\b"

# Optional annotation/macros that should flip needs_review=false
explicit_sensitive_markers:
  - "annotate(\"sensitive\")"
  - "SENSITIVE"
  - "#\\[secret\\]"
  - "Secret<"
  - "secrecy::Secret"

# Approved wipe function names (source-level)
approved_wipe_funcs:
  - "explicit_bzero"
  - "memset_s"
  - "SecureZeroMemory"
  - "OPENSSL_cleanse"
  - "sodium_memzero"
  - "zeroize"          # rust crate fn (name-only heuristic)
  - "Zeroize::zeroize" # rust trait call heuristic
  - "zeroize::Zeroize::zeroize"

# Patterns to recognize volatile wipe loops / barriers (source-level heuristics)
volatile_wipe_regex:
  - "(?s)volatile\\s+.*\\*.*=\\s*0"
  - "(?s)asm\\s+volatile\\s*\\(\\s*\"\"\\s*:\\s*:\\s*:\\s*\"memory\"\\s*\\)"
  - "(?s)__asm__\\s+__volatile__\\s*\\(\\s*\"\"\\s*:\\s*:\\s*:\\s*\"memory\"\\s*\\)"

# "Wrong size" heuristics (common bug: sizeof(ptr))
wrong_size_regex:
  - "memset\\s*\\(\\s*\\w+\\s*,\\s*0\\s*,\\s*sizeof\\s*\\(\\s*\\w+\\s*\\*\\s*\\)\\s*\\)"
  - "explicit_bzero\\s*\\(\\s*\\w+\\s*,\\s*sizeof\\s*\\(\\s*\\w+\\s*\\*\\s*\\)\\s*\\)"

# Insecure heap allocators (should use secure variants)
insecure_heap_alloc_patterns:
  - pattern: "malloc\\s*\\([^)]*\\)"
    secure_alternative: "OPENSSL_secure_malloc / sodium_malloc"
  - pattern: "calloc\\s*\\([^)]*\\)"
    secure_alternative: "OPENSSL_secure_zalloc / sodium_allocarray"
  - pattern: "realloc\\s*\\([^)]*\\)"
    secure_alternative: "OPENSSL_secure_realloc"
  - pattern: "new\\s+\\w*(?:key|secret|token|pwd)\\w*"
    secure_alternative: "custom allocator with mlock"

# Secure heap allocators (approved)
secure_heap_alloc_funcs:
  - "OPENSSL_secure_malloc"
  - "OPENSSL_secure_zalloc"
  - "OPENSSL_secure_realloc"
  - "sodium_malloc"
  - "sodium_allocarray"
  - "SecureAlloc"  # Custom implementations

# Memory protection functions
memory_protection_funcs:
  lock:
    - "mlock"
    - "mlock2"
    - "mlockall"
  advise:
    - "madvise.*MADV_DONTDUMP"
    - "madvise.*MADV_DONTFORK"
    - "madvise.*MADV_WIPEONFORK"

# === Medium Priority Features (v0.3.0) ===

# Semantic IR analysis configuration
semantic_ir_analysis:
  enabled: true
  detect_loop_unrolling: true
  detect_phi_nodes: true
  min_unrolled_stores: 4  # Minimum consecutive stores to flag as unrolled loop
  track_ssa_form: true

# Control-flow analysis configuration
cfg_analysis:
  enabled: true
  verify_all_paths: true
  compute_dominators: true
  detect_early_returns: true
  max_paths_to_analyze: 1000  # Limit for performance

# Runtime validation configuration
runtime_validation:
  generate_tests: true
  test_types:
    - basic          # Basic memory check tests
    - msan           # MemorySanitizer tests
    - valgrind       # Valgrind tests
    - stack_canary   # Stack retention tests
  sanitizers:
    - memory         # -fsanitize=memory
    - address        # -fsanitize=address

# PoC generation configuration
# NOTE: PoC generation is always mandatory in the pipeline. This section
# controls PoC parameters (categories, thresholds, etc.), not whether PoCs run.
poc_generation:
  enabled: true
  categories:
    - MISSING_SOURCE_ZEROIZE
    - OPTIMIZED_AWAY_ZEROIZE
    - STACK_RETENTION
    - REGISTER_SPILL
    - SECRET_COPY
    - MISSING_ON_ERROR_PATH
    - PARTIAL_WIPE
    - NOT_ON_ALL_PATHS
    - INSECURE_HEAP_ALLOC
    - LOOP_UNROLLED_INCOMPLETE
    - NOT_DOMINATING_EXITS
  source_inclusion_threshold: 5000
  output_dir: generated_pocs
  stack_probe_max_size: 4096
  secret_fill_byte: 0xAA

version: 0.1.0

# Rust-specific signals
sensitive_name_regex:
  - "(?i)\\b(secret|key|seed|priv|sk|shared[_-]?secret|nonce|token)\\b"

explicit_sensitive_markers:
  - "#\\[secret\\]"
  - "Secret<"
  - "secrecy::Secret"

approved_wipe_funcs:
  - "zeroize"
  - "Zeroize::zeroize"
  - "zeroize::Zeroize::zeroize"
  - "explicit_bzero"   # if using FFI

# Async suspension: secret-named local live across .await
async_suspension_pattern:
  category: NOT_ON_ALL_PATHS
  severity: high
  detail: "secret local live across .await suspension point — stored in heap-allocated Future state machine; ZeroizeOnDrop covers stack only"

# LLVM IR confidence gates for Rust (check_llvm_patterns.py)
# These findings require the named evidence; without it, downgrade to needs_review.
rust_ir_confidence_gates:
  OPTIMIZED_AWAY_ZEROIZE:
    requires: ir_diff_evidence
    note: "volatile store count drop O0→O2 or non-volatile memset required"
  STACK_RETENTION:
    requires: alloca_lifetime_evidence
    note: "alloca with @llvm.lifetime.end but no store volatile required"

# Semantic source patterns for semantic_audit.py
rust_semantic_patterns:
  copy_derive_on_sensitive:
    category: SECRET_COPY
    severity: critical
    detail: "Copy derive on sensitive type — all assignments are untracked duplicates, no Drop ever runs"
  no_zeroize_no_drop:
    category: MISSING_SOURCE_ZEROIZE
    severity: high
    detail: "Sensitive type has no Zeroize, ZeroizeOnDrop, or Drop implementation"
  zeroize_without_trigger:
    category: MISSING_SOURCE_ZEROIZE
    severity: high
    detail: "Zeroize trait impl exists but no ZeroizeOnDrop or Drop to trigger it automatically"
  partial_drop:
    category: PARTIAL_WIPE
    severity: high
    detail: "Drop impl zeroes some secret fields but not all"
  zeroize_on_drop_heap_fields:
    category: PARTIAL_WIPE
    severity: medium
    detail: "ZeroizeOnDrop on type with Vec/Box heap fields — capacity bytes beyond len may not be zeroed"
  clone_on_zeroizing_type:
    category: SECRET_COPY
    severity: medium
    detail: "Clone on zeroizing type — each clone is an independent allocation that must be independently zeroed"
  from_into_non_zeroizing:
    category: SECRET_COPY
    severity: medium
    detail: "From/Into returning non-zeroizing type — bytes escape into caller's ownership in a non-zeroizing container"
  ptr_write_bytes_no_fence:
    category: OPTIMIZED_AWAY_ZEROIZE
    severity: medium
    detail: "ptr::write_bytes without following compiler_fence/volatile — DSE-eligible; confirm at IR layer"
  cfg_feature_wrapping_drop:
    category: NOT_ON_ALL_PATHS
    severity: medium
    detail: "#[cfg(feature=...)] wrapping Drop/Zeroize — zeroing absent when feature flag is off"
  debug_derive_on_sensitive:
    category: SECRET_COPY
    severity: low
    detail: "#[derive(Debug)] on sensitive type — secrets may appear in log output"
  serialize_derive_on_sensitive:
    category: SECRET_COPY
    severity: low
    detail: "#[derive(Serialize)] on sensitive type — serialization creates an uncontrolled copy of secret bytes"
  no_zeroize_crate:
    category: MISSING_SOURCE_ZEROIZE
    severity: low
    detail: "No zeroize crate in Cargo.toml — all manual zeroing lacks approved-API guarantee"

# Zeroize Audit Report

**Run ID:** `<run_id>`
**Timestamp:** `<ISO-8601>`
**Repository:** `<path>`
**Compile DB:** `<compile_db>`

**Configuration:**
| Setting | Value |
|---|---|
| Optimization levels | O0, O1, O2 |
| MCP mode | prefer |
| MCP available | yes / no |
| Assembly analysis | enabled / disabled |
| Semantic IR analysis | enabled / disabled |
| CFG analysis | enabled / disabled |
| Runtime tests | enabled / disabled |
| PoC validation | mandatory |

---

## Executive Summary

| Metric | Count |
|---|---|
| Files scanned | 0 |
| Translation units analyzed | 0 |
| **Total findings** | **0** |

### By Severity

| Severity | Count |
|---|---|
| High | 0 |
| Medium | 0 |

### By Confidence

| Confidence | Count |
|---|---|
| Confirmed | 0 |
| Likely | 0 |
| Needs review | 0 |

### PoC Validation

| Metric | Count |
|---|---|
| PoCs generated | 0 |
| PoCs validated | 0 |
| Exploitable (confirmed) | 0 |
| Not exploitable | 0 |
| Compile failures | 0 |
| No PoC generated | 0 |

### By Category

| Category | Count |
|---|---|
| MISSING_SOURCE_ZEROIZE | 0 |
| PARTIAL_WIPE | 0 |
| NOT_ON_ALL_PATHS | 0 |
| OPTIMIZED_AWAY_ZEROIZE | 0 |
| SECRET_COPY | 0 |
| INSECURE_HEAP_ALLOC | 0 |
| STACK_RETENTION | 0 |
| REGISTER_SPILL | 0 |
| MISSING_ON_ERROR_PATH | 0 |
| NOT_DOMINATING_EXITS | 0 |
| LOOP_UNROLLED_INCOMPLETE | 0 |

---

## Sensitive Objects Inventory

| ID | Name | Type | Location | Confidence | Heuristic | Has Wipe |
|---|---|---|---|---|---|---|
| SO-0001 | key | uint8_t[32] | path/to/file.c:45 | low | name pattern | no |
| SO-0002 | session_key | uint8_t[16] | path/to/file.c:89 | medium | type hint | yes |

---

## Findings

### High Severity

#### ZA-0002: STACK_RETENTION — high (confirmed)

**Location:** `path/to/file.c:89`
**Object:** `secret_function` (`stack_frame`, 192 bytes)

**Evidence:**
- [asm] Stack frame (192 bytes) allocated at function entry; no red-zone clearing before ret at line 112.
- [asm] `sub $0xc0, %rsp` at entry; no corresponding zeroing sequence before ret.

**Compiler Evidence:**
- Opt levels analyzed: O0, O2
- O2: Stack allocated 192 bytes; ret reached without clearing red-zone below %rsp.
- **Summary:** Stack frame persists with uncleared secret bytes after function return.

**Recommended Fix:**
Add `explicit_bzero()` across the full stack frame, or use a compiler barrier and volatile wipe loop covering the red-zone.

---

#### ZA-0003: REGISTER_SPILL — high (confirmed)

**Location:** `path/to/file.c:156`
**Object:** `encrypt` (`stack_slot`, 8 bytes)

**Evidence:**
- [asm] `movq %r12, -48(%rsp)` at line 156 spills key fragment to stack; no corresponding zero-store before ret.

**Compiler Evidence:**
- Opt levels analyzed: O0, O2
- O2: `movq %r12, -48(%rsp)` without corresponding cleanup of spill slot.
- **Summary:** Register spill at -48(%rsp) contains key fragment; slot not cleared before return.

**Recommended Fix:**
Use inline assembly with register constraints to prevent spilling, or add explicit zero-store covering the spill slot before return.

---

#### ZA-0005: INSECURE_HEAP_ALLOC — high (confirmed)

**Location:** `path/to/file.c:67`
**Object:** `private_key` (`uint8_t *`)

**Evidence:**
- [source] `malloc()` at line 67 allocates buffer for `private_key`. No `mlock()` or `madvise(MADV_DONTDUMP)` found for this allocation.

**Recommended Fix:**
Replace `malloc()` with `OPENSSL_secure_malloc()` or `sodium_malloc()`. Add `mlock()` and `madvise(MADV_DONTDUMP)` if using standard allocator.

---

### Medium Severity

#### ZA-0001: MISSING_SOURCE_ZEROIZE — medium (likely)

**Location:** `path/to/file.c:123`
**Object:** `key` (`uint8_t[32]`, 32 bytes)

**Evidence:**
- [source] Sensitive buffer `key` matches name pattern; no approved wipe call found before return at line 130.

**Recommended Fix:**
Use `explicit_bzero(key, sizeof(key))` on all exit paths.

---

#### ZA-0006: OPTIMIZED_AWAY_ZEROIZE — medium (confirmed)

**Location:** `path/to/file.c:88`
**Object:** `nonce` (`uint8_t[12]`, 12 bytes)

**Evidence:**
- [ir] O0 IR contains `llvm.memset` call zeroing `nonce` at line 88; absent in O1 IR — dead-store elimination.

**Compiler Evidence:**
- Opt levels analyzed: O0, O1, O2
- O0: `llvm.memset(nonce, 0, 12)` present at line 88.
- O1: `llvm.memset` call removed — dead store eliminated.
- O2: `llvm.memset` call absent.
- **Summary:** Wipe disappears at O1; cause: dead-store elimination of memset with no subsequent read.

**Recommended Fix:**
Replace `memset()` with `explicit_bzero()` or add a volatile compiler barrier after the wipe to prevent elimination.

---

### Needs Review

#### ZA-0004: SECRET_COPY — high (needs_review)

**Location:** `path/to/file.c:203`
**Object:** `session_key` (`uint8_t[16]`, 16 bytes)

**Evidence:**
- [source] `memcpy()` at line 203 copies `session_key` to `tmp_key` (line 199). No approved wipe tracked for destination `tmp_key` before it goes out of scope at line 218.

**Recommended Fix:**
Ensure both `session_key` and `tmp_key` are zeroized on all exit paths using `explicit_bzero()`.

---

## PoC Validation Results

| Finding | Category | PoC File | Exit Code | Result | Impact |
|---|---|---|---|---|---|
| ZA-0001 | MISSING_SOURCE_ZEROIZE | poc_za_0001_missing_source_zeroize.c | 0 | exploitable | Confirmed |
| ZA-0002 | STACK_RETENTION | poc_za_0002_stack_retention.c | 1 | not_exploitable | Downgraded to low (informational) |
| ZA-0003 | REGISTER_SPILL | poc_za_0003_register_spill.c | — | compile_failure | No change |

---

## Superseded Findings

_No findings were superseded in this run._

<!-- Example:
| Superseded | Superseded By | Reason |
|---|---|---|
| F-SRC-0005 (NOT_ON_ALL_PATHS) | ZA-0007 / F-CFG-a1b2-0003 (NOT_DOMINATING_EXITS) | CFG dominance analysis provides definitive result |
-->

---

## Confidence Gate Summary

| Finding | Action | Reason |
|---|---|---|
| ZA-0004 (SECRET_COPY) | Downgraded to needs_review | MCP unavailable; only 1 non-MCP signal (source pattern match) |

---

## Analysis Coverage

| Metric | Value |
|---|---|
| TUs in compile DB | 0 |
| TUs analyzed | 0 |
| TUs with sensitive objects | 0 |
| Agent 1 (MCP resolver) | success / skipped / failed |
| Agent 2 (source analyzer) | success / failed |
| Agent 3 (compiler analyzer) | N/N TUs succeeded |
| Agent 4 (report assembler) | success |
| Agent 5 (PoC generator) | success / failed |
| Agent 6 (test generator) | success / skipped / failed |

### Unaudited Patterns

Patterns from `coverage-gaps.json` that no script detects. A clean report above does not
rule these out. State "none reported" when the file is empty, and never drop this section.

| Pattern | Where | Why it is unaudited |
|---|---|---|
| D3 | `src/keys.rs:44` | `static LazyLock<MasterKey>` never dropped, so no zeroize path exists to check |

---

## Appendix: Evidence Files

| Finding | Evidence File | Description |
|---|---|---|
| ZA-0002 | `compiler-analysis/a1b2/asm-findings.json` | Assembly analysis output |
| ZA-0006 | `compiler-analysis/c3d4/ir-findings.json` | IR diff analysis output |

# zeroize-audit (Claude Skill)

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

## 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:
```bash
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)

```rust
#[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)

```rust
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:
```llvm
store volatile i8 0, ptr %key_buf    ; 32 volatile stores present
```

At O2 LLVM IR:
```llvm
; 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.

Task: Run zeroize-audit.

Inputs:
- path: {{path}}
- compile_db: {{compile_db}}
- cargo_manifest: {{cargo_manifest}}
- config: {{config}}
- opt_levels: {{opt_levels}}
- languages: {{languages}}
- max_tus: {{max_tus}}
- mcp_mode: {{mcp_mode}}
- mcp_required_for_advanced: {{mcp_required_for_advanced}}
- mcp_timeout_ms: {{mcp_timeout_ms}}
- enable_semantic_ir: {{enable_semantic_ir}}
- enable_cfg: {{enable_cfg}}
- enable_runtime_tests: {{enable_runtime_tests}}
- enable_asm: {{enable_asm}}
- poc_categories: {{poc_categories}}
- poc_output_dir: {{poc_output_dir}}

---

## Execution Protocol

### Recovery

If a `workdir` is known from prior context, read `{workdir}/orchestrator-state.json` to recover state after context compression:

- `current_phase`: resume from this phase
- `workdir`, `run_id`: working directory and run identifier
- `inputs`: original input values
- `routing`: key booleans (`mcp_available`, `tu_count`, `finding_count`)
- `phases`: completion status and output file paths for each phase
- `key_file_paths`: paths to all inter-phase artifacts

If no state exists, start at Phase 0.

### Phase Loop

Execute phases sequentially. Before each phase, read its workflow file from `{baseDir}/workflows/phase-{N}-{name}.md`. Follow the workflow's Preconditions, Instructions, State Update, and Error Handling sections.

| Phase | Workflow File | Skip Condition |
|---|---|---|
| 0 | `phase-0-preflight.md` | Never |
| 1 | `phase-1-source-analysis.md` | Never |
| 2 | `phase-2-compiler-analysis.md` | No sensitive objects (`tu-map.json` empty) |
| 3 | `phase-3-interim-report.md` | No sensitive objects |
| 4 | `phase-4-poc-generation.md` | Zero findings in interim report |
| 5 | `phase-5-poc-validation.md` | Zero findings or no PoCs generated |
| 6 | `phase-6-final-report.md` | Never (always produce a report) |
| 7 | `phase-7-test-generation.md` | `enable_runtime_tests=false` or zero findings |

### Early Termination

Skip directly to Phase 6 (produce empty/partial report) when:

- Phase 1 source analyzer finds zero sensitive objects
- Phase 3 interim report contains zero findings

### Phase 8 — Return Results (inline)

Read `{workdir}/report/final-report.md` and return its contents as the skill output.

The markdown report is the primary human-readable output. It contains:
- Executive summary with finding counts by severity, confidence, and category
- PoC validation summary with exploitable/not-exploitable counts
- Sensitive objects inventory
- Detailed findings grouped by severity and confidence, each with evidence, PoC validation result, and recommended fix
- Superseded findings and confidence gate summary
- Analysis coverage and evidence file appendix

The structured `{workdir}/report/findings.json` (matching `{baseDir}/schemas/output.json`) is also available for machine consumption.

---

## Error Handling Summary

| Failure | Behavior |
|---|---|
| Preflight fails (Phase 0) | Stop immediately, report failure |
| Config load fails (Phase 0) | Stop immediately |
| PoC generator agent fails (Phase 4) | Surface error to user — PoC generation is mandatory |
| MCP resolver fails + `mcp_mode=require` | Stop immediately (C/C++ only) |
| MCP resolver fails + `mcp_mode=prefer` | Continue with `mcp_available=false` (C/C++ only) |
| Source analyzer (C/C++) fails | Stop C/C++ analysis — no sensitive object list for C/C++ TUs |
| Rust source analyzer fails | Stop Rust analysis — log failure, continue if C/C++ analysis is also running |
| No sensitive objects found | Skip Phases 2–5, jump to Phase 6 for empty report |
| One TU compiler-analyzer fails | Continue with remaining TUs |
| All TU compiler-analyzers fail | Report assembler produces source-only report |
| Rust compiler analyzer (Wave 3R) fails | Log failure, continue — report assembler handles missing rust-compiler-analysis/ |
| `cargo +nightly` not available (Rust preflight) | Stop the run — nightly is required for MIR/IR emission |
| Python script missing (Rust preflight) | Warn and skip that sub-step — do not fail the run |
| Report assembler fails (interim) | Surface error to user |
| PoC generator fails | Pipeline stalls — cannot proceed to validation. Surface error to user |
| PoC compilation failure | Record in validation results, continue with other PoCs |
| Report assembler fails (final) | Surface error to user |
| Test generator fails | Report is still available without tests |

# Working with compile_commands.json

This reference covers how to generate and use `compile_commands.json` for the zeroize-audit IR/ASM analysis pipeline. Read this before running Step 7 (IR comparison) or Step 8 (assembly analysis) in `task.md`.

---

## Structure

`compile_commands.json` is a JSON array where each entry describes the exact compiler invocation for one translation unit (TU):

```json
[
  {
    "directory": "/path/to/project/build",
    "arguments": [
      "clang", "-std=c11", "-I../include", "-DNDEBUG", "-Wall",
      "-c", "../src/crypto.c", "-o", "crypto.c.o"
    ],
    "file": "../src/crypto.c"
  },
  {
    "directory": "/path/to/project/build",
    "command": "clang++ -std=c++17 -I../include -DNDEBUG -c ../src/aead.cpp -o aead.cpp.o",
    "file": "../src/aead.cpp"
  }
]
```

**`arguments` vs `command`**: Some tools produce an `arguments` array (preferred); others produce a `command` string. `extract_compile_flags.py` handles both forms transparently.

**`directory`**: The working directory for the invocation. All relative paths in `arguments`/`command` and `file` are resolved against this field — **not** against the current working directory when running analysis. `extract_compile_flags.py` handles this automatically; manual invocations must account for it.

---

## Generating compile_commands.json

### CMake (C/C++)

```bash
cmake -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
# Output: build/compile_commands.json
```

**Constraints**: Works only with Makefile and Ninja generators. Does not work with Xcode or MSVC generators. Run from the project root and point `--compile-db` at `build/compile_commands.json`.

### Bear (any Make-based build system)

Bear intercepts compiler invocations at the OS level. Works with any `make`-based or custom build system:

```bash
# Install: apt install bear  OR  brew install bear
bear -- make clean all    # clean build recommended for accuracy
# Output: compile_commands.json in the current directory
```

Use `make clean all` rather than `make` alone to ensure all TUs are recompiled and captured. Incremental builds will only record the files that were actually recompiled.

### intercept-build (LLVM scan-build companion)

```bash
intercept-build make
# Output: compile_commands.json in the current directory
```

### Rust / Cargo

Cargo does not natively emit `compile_commands.json`. Two options:

```bash
# Option 1: Bear with cargo check (faster — avoids linking)
bear -- cargo check
bear -- cargo build   # if cargo check is insufficient

# Option 2: compiledb
uv tool install compiledb
# ensure uv's tool bin dir (~/.local/bin) is on PATH
compiledb cargo build
```

**Critical limitation for Rust**: Bear captures `rustc` invocations, not `clang` invocations. `emit_ir.sh` (which calls `clang`) **will not work** directly on Rust TUs. Use `cargo rustc` instead to emit IR and assembly directly:

```bash
# Preferred: use the emit scripts which handle CARGO_TARGET_DIR isolation:
{baseDir}/tools/emit_rust_ir.sh --manifest Cargo.toml --opt O0 --out /tmp/crate.O0.ll
{baseDir}/tools/emit_rust_ir.sh --manifest Cargo.toml --opt O2 --out /tmp/crate.O2.ll

# Manual alternative (output goes to an isolated temp dir, not target/debug/deps):
CARGO_TARGET_DIR=/tmp/zir cargo rustc -- --emit=llvm-ir -C opt-level=0
CARGO_TARGET_DIR=/tmp/zir cargo rustc -- --emit=llvm-ir -C opt-level=2

# Assembly for Rust (use instead of emit_asm.sh):
cargo rustc -- --emit=asm -C opt-level=2
# Output: target/release/deps/*.s
```

Pass the resulting `.ll` and `.s` files directly to `diff_ir.sh` and `analyze_asm.sh`.

---

## End-to-End Pipeline

The canonical pipeline for C/C++ analysis. Always use a hash of the source path as `<tu_hash>` (not the raw filename) to avoid collisions during parallel TU processing. Clean up temp files on completion or failure.

```bash
mkdir -p /tmp/zeroize-audit/

# Step 1: Extract build-relevant flags for the TU (as a bash array)
FLAGS=()
while IFS= read -r flag; do FLAGS+=("$flag"); done < <(
  uv run --no-project {baseDir}/tools/extract_compile_flags.py \
    --compile-db /path/to/build/compile_commands.json \
    --src /path/to/src/crypto.c --format lines)

# Step 2: Emit IR at each level in opt_levels (always include O0 as baseline)
{baseDir}/tools/emit_ir.sh \
  --src /path/to/src/crypto.c \
  --out /tmp/zeroize-audit/<tu_hash>.O0.ll --opt O0 -- "${FLAGS[@]}"

{baseDir}/tools/emit_ir.sh \
  --src /path/to/src/crypto.c \
  --out /tmp/zeroize-audit/<tu_hash>.O1.ll --opt O1 -- "${FLAGS[@]}"

{baseDir}/tools/emit_ir.sh \
  --src /path/to/src/crypto.c \
  --out /tmp/zeroize-audit/<tu_hash>.O2.ll --opt O2 -- "${FLAGS[@]}"

# Step 3: Diff across all levels — O1 is the diagnostic level for simple DSE;
#         O2 catches more aggressive eliminations
{baseDir}/tools/diff_ir.sh \
  /tmp/zeroize-audit/<tu_hash>.O0.ll \
  /tmp/zeroize-audit/<tu_hash>.O1.ll \
  /tmp/zeroize-audit/<tu_hash>.O2.ll

# Step 4: Emit assembly at O2 for register-spill and stack-retention analysis
{baseDir}/tools/emit_asm.sh \
  --src /path/to/src/crypto.c \
  --out /tmp/zeroize-audit/<tu_hash>.O2.s --opt O2 -- "${FLAGS[@]}"

# Step 5: Analyze assembly output
{baseDir}/tools/analyze_asm.sh /tmp/zeroize-audit/<tu_hash>.O2.s

# Cleanup
rm -rf /tmp/zeroize-audit/<tu_hash>.*
```

Refer to the IR analysis reference (loaded separately from SKILL.md) for how to interpret IR diffs and identify wipe elimination patterns.

---

## Flags Stripped by extract_compile_flags.py

These flags are removed because they are irrelevant to or break single-file IR/ASM emission:

| Flag(s) | Reason stripped |
|---|---|
| `-o <file>` | Emission tools supply their own `-o` |
| `-c` | IR/ASM emission uses `-S -emit-llvm` / `-S` instead |
| `-MF`, `-MT`, `-MQ` (+ argument) | Dependency file generation — irrelevant for analysis |
| `-MD`, `-MMD`, `-MP`, `-MG` | Dependency generation side-effects |
| `-pipe` | OS pipe between compiler stages; not meaningful for direct calls |
| `-save-temps` | Saves intermediate files; produces clutter |
| `-gsplit-dwarf` | Splits debug info to `.dwo`; incompatible with single-file emission |
| `-fcrash-diagnostics-dir=...` | Crash report output; irrelevant |
| `-fmodule-file=...`, `-fmodules-cache-path=...` | Clang module paths; may confuse single-TU invocation |
| `--serialize-diagnostics` | Clang diagnostic binary output; not needed |
| `-fdebug-prefix-map=...` | Debug info path remapping; harmless to strip |
| `-fprofile-generate`, `-fprofile-use=...` | PGO instrumentation; distorts IR for analysis |
| `-fcoverage-mapping` | Coverage instrumentation; alters IR structure |

Flags that are **kept** (build-relevant):

| Pattern | Reason kept |
|---|---|
| `-I`, `-isystem`, `-iquote` | Include paths required to parse the TU |
| `-D`, `-U` | Preprocessor defines/undefines that affect code paths |
| `-std=<val>` | Language standard — affects syntax and semantics |
| `-f*` security/codegen flags | e.g., `-fstack-protector`, `-fPIC`, `-fno-omit-frame-pointer` |
| `-m<arch>` | Target architecture flags (e.g., `-m64`, `-march=x86-64`, `-mthumb`) |
| `-W*` | Warning flags — harmless to pass through |
| `-pthread` | Threading model; affects macro definitions |
| `--sysroot=`, `-isysroot` | System root for cross-compilation |
| `-target <triple>` | Cross-compilation target triple; must be preserved |

---

## Common Pitfalls

### 1. Relative paths and the `"directory"` field

`"file": "../src/crypto.c"` is relative to `"directory"`, not to the CWD when running analysis. Always resolve file paths using `"directory"`. `extract_compile_flags.py` does this automatically; be explicit if invoking `clang` manually.

### 2. Multiple entries for the same file

Some build systems emit duplicate entries (e.g., with and without a precompiled header). `extract_compile_flags.py` returns the **first** match. If that entry includes `-fpch-preprocess`, the PCH must exist in the build directory for compilation to succeed. Either regenerate the PCH or strip PCH-related flags manually.

### 3. Stale or incomplete compile DB (most common failure)

If `bear` or CMake was run on an incremental build, only recompiled TUs are recorded. TUs compiled in a previous run may be missing or have outdated flags. **Always generate the compile DB from a clean build** (`make clean all`, `cargo clean && cargo build`) to ensure all TUs are captured with current flags.

`extract_compile_flags.py` exits with code 2 if a source file is not found in the DB. Common causes:
- Header-only files (no TU entry — expected)
- Files added after the last `bear`/CMake run
- Symlinked paths that resolve differently than recorded

Regenerate the compile DB if entries are missing.

### 4. Generated source files

Entries may point to generated files in the build directory (e.g., `build/generated/config.c`) that don't exist in a clean checkout. Run the build system to generate them before running analysis. Preflight (Step 1 in `task.md`) will catch this if trial compilation is attempted.

### 5. Cross-compilation targets

If the compile DB was generated for a cross-compilation target (e.g., `-target aarch64-linux-gnu` or `-target thumbv7m-none-eabi`), emitted IR and assembly will be for that target, not x86-64. This affects analysis in two ways:

- **IR diffs**: Only compare IR files emitted for the same target. Do not mix targets across opt levels.
- **Assembly analysis**: `analyze_asm.sh` adapts register patterns by target:
  - x86-64: callee-saved registers are `rbx`, `r12`–`r15`; spills use `movq`/`movdqa` to `[rsp+N]`
  - AArch64: callee-saved registers are `x19`–`x28`; spills use `str`/`stp` to `[sp, #N]`
  - Thumb/ARM: callee-saved registers are `r4`–`r11`; spills use `str`/`stm` to `[sp, #N]`

Ensure `--target` is preserved in the stripped flags (it is, per the kept-flags table above).

### 6. `extract_compile_flags.py` exit codes

| Exit code | Meaning |
|---|---|
| 0 | Flags extracted successfully; output on stdout |
| 1 | Compile DB not found or not readable |
| 2 | Source file not found in compile DB |
| 3 | Compile DB is malformed JSON |

Check the exit code before passing flags to emission tools. An empty `FLAGS` array will silently produce incorrect IR.

# Detection Strategy

Read this during execution to guide per-step analysis. Steps 1–6 are Phase 1 (source-level); Steps 7–12 are Phase 2 (compiler-level).

---

## Phase 1 — Source-Level Analysis

### Step 1 — Preflight Build Context (mandatory)
- Verify `compile_db` exists and is readable.
- Verify compile database entries point to existing files/working directories.
- Verify the codebase is compilable with the captured commands (or equivalent build invocation).
- Fail fast if preflight fails; do not continue with partial/source-only analysis.

### Step 2 — Identify Sensitive Objects

Scan all TUs for objects matching these heuristics. Each heuristic has a confidence level that propagates to findings.

**Name patterns (low confidence)** — match substrings case-insensitively:
`key`, `secret`, `seed`, `priv`, `sk`, `shared_secret`, `nonce`, `token`, `pwd`, `pass`

**Type hints (medium confidence)** — byte buffers, fixed-size arrays, or structs whose names or fields match name patterns above.

**Explicit annotations (high confidence)**:
- Rust: `#[secret]`, `Secret<T>` patterns (configurable)
- C/C++: `__attribute__((annotate("sensitive")))`, `SENSITIVE` macro (configurable via `explicit_sensitive_markers` in `{baseDir}/configs/default.yaml`)

Record each sensitive object with: name, type, location (file:line), confidence level, and the heuristic that matched.

### Step 3 — Detect Zeroization Attempts

For each sensitive object identified in Step 2, check whether a call to an approved wipe API (see Approved Wipe APIs in SKILL.md) exists within the same scope or a cleanup function reachable from that scope.

Record: wipe API used, location, and whether the wipe was found at all.

### Step 4 — MCP Semantic Pass (when available)

Run this step **before** correctness validation so that resolved types, aliases, and cross-file references are available to Steps 5 and 6. Skip and continue if MCP is unavailable in `prefer` mode (see Confidence Gating in SKILL.md).

- Run `{baseDir}/tools/mcp/check_mcp.sh` to confirm MCP is live. If it fails and `mcp_mode=require`, stop the run.
- Activate the project with `activate_project` (pass the repository root path). This must succeed before any other Serena tool can be used. If activation fails, treat MCP as unavailable.
- For each sensitive object and wipe call, resolve symbol definitions using `find_symbol` (by name, with `include_body: true` for type details) and collect cross-file references using `find_referencing_symbols`.
- Trace callers and cleanup paths using `find_referencing_symbols` on wipe wrapper functions. For outgoing calls, read the function body from `find_symbol` output and resolve called symbols.
- Use `get_symbols_overview` to get a high-level view of symbols in a file when exploring unfamiliar TUs.
- Normalize all MCP output: `uv run --no-project {baseDir}/tools/mcp/normalize_mcp_evidence.py`.

Prioritize `find_symbol` queries by sensitive-object name first, then wipe wrapper names. Score confidence: name match alone → `needs_review`; name + type resolved → `likely`; name + type + call chain confirmed → `confirmed`.

### Step 5 — Validate Correctness

For each sensitive object with a detected wipe, use type and alias data from Step 4 (if available) to validate:
- **Size correct**: wipe length matches `sizeof(object)`, not `sizeof(pointer)`. MCP-resolved typedefs and array sizes take precedence over source-level estimates.
- **All exits covered** (heuristic): wipe is present on normal exit, early return, and error paths visible in source. Flag `NOT_ON_ALL_PATHS` if any path appears uncovered.
- **Ordering correct**: wipe occurs before `free()` or scope end, not after.

Emit `PARTIAL_WIPE` for incorrect size. Emit `NOT_ON_ALL_PATHS` for missing paths (heuristic; CFG analysis in Step 10 provides definitive results).

### Step 6 — Data-Flow and Heap Checks

Use cross-file reference data from Step 4 (if available) to extend tracking beyond the current TU.

**Data-flow (produces `SECRET_COPY`):**
- Detect `memcpy()`/`memmove()` copying sensitive buffers.
- Track struct assignments and array copies of sensitive objects.
- Flag function arguments passed by value (copies on stack).
- Flag secrets returned by value.
- Emit `SECRET_COPY` when any of the above copies exist and no approved wipe is tracked for the copy destination.

**Heap (produces `INSECURE_HEAP_ALLOC`):**
- Detect `malloc`/`calloc`/`realloc` used to allocate sensitive objects.
- Check for `mlock()`/`madvise(MADV_DONTDUMP)` — note absence as a warning.
- Recommend secure allocators: `OPENSSL_secure_malloc`, `sodium_malloc`.

---

## Phase 2 — Compiler-Level Analysis

All steps in Phase 2 require a valid compile DB and a working `clang` installation. Skip Phase 2 findings if Phase 1 preflight failed.

### Step 7 — IR Comparison (produces `OPTIMIZED_AWAY_ZEROIZE`)

For each TU containing sensitive objects:

```bash
FLAGS=()
while IFS= read -r flag; do FLAGS+=("$flag"); done < <(
  uv run --no-project {baseDir}/tools/extract_compile_flags.py \
    --compile-db <compile_db> --src <file> --format lines)

{baseDir}/tools/emit_ir.sh --src <file> \
  --out /tmp/zeroize-audit/<tu_hash>.O0.ll --opt O0 -- "${FLAGS[@]}"

{baseDir}/tools/emit_ir.sh --src <file> \
  --out /tmp/zeroize-audit/<tu_hash>.O1.ll --opt O1 -- "${FLAGS[@]}"

{baseDir}/tools/emit_ir.sh --src <file> \
  --out /tmp/zeroize-audit/<tu_hash>.O2.ll --opt O2 -- "${FLAGS[@]}"

{baseDir}/tools/diff_ir.sh \
  /tmp/zeroize-audit/<tu_hash>.O0.ll \
  /tmp/zeroize-audit/<tu_hash>.O1.ll \
  /tmp/zeroize-audit/<tu_hash>.O2.ll
```

Use `<tu_hash>` (a hash of the source path) to avoid collisions when processing multiple TUs.
`diff_ir.sh` outputs a unified diff to stdout; a non-zero exit code means divergence was detected.
Clean up `/tmp/zeroize-audit/` on completion or failure.

**Interpretation:**
- Wipe present at O0, absent at O1 → simple dead-store elimination. Flag `OPTIMIZED_AWAY_ZEROIZE`.
- Wipe present at O1, absent at O2 → aggressive optimization. Flag `OPTIMIZED_AWAY_ZEROIZE`.
- Include the IR diff as mandatory evidence in the finding.

Key IR patterns: `store volatile i8 0` is the primary wipe signal; its absence at O2 when present at O0 is DSE. `@llvm.memset` without the volatile flag is elidable. `alloca` with `@llvm.lifetime.end` and no `store volatile` in the same function indicates stack retention.

### Step 8 — Assembly Analysis (produces `STACK_RETENTION`, `REGISTER_SPILL`)

Skip if `enable_asm=false`.

```bash
{baseDir}/tools/emit_asm.sh --src <file> \
  --out /tmp/zeroize-audit/<tu_hash>.O2.s --opt O2 -- "${FLAGS[@]}"

{baseDir}/tools/analyze_asm.sh \
  --asm /tmp/zeroize-audit/<tu_hash>.O2.s \
  --out /tmp/zeroize-audit/<tu_hash>.asm-analysis.json
```

`analyze_asm.sh` outputs annotated findings to stdout.

Check for:
- **Register spills**: `movq`/`movdqa` of secret values to stack offsets → flag `REGISTER_SPILL`.
- **Callee-saved registers**: `rbx`, `r12`–`r15` (x86-64) pushed to stack containing secret values → flag `REGISTER_SPILL`.
- **Stack retention**: stack frame size and whether secret bytes are cleared before `ret` → flag `STACK_RETENTION`.

Include the relevant assembly excerpt as mandatory evidence.

### Step 9 — Semantic IR Analysis (produces `LOOP_UNROLLED_INCOMPLETE`)

Skip if `enable_semantic_ir=false`.

Parse LLVM IR structurally (do not use regex on raw IR text):
- Build function and basic block representations.
- Track memory operations in SSA form after the `mem2reg` pass.
- Detect loop-unrolled zeroization: 4 or more consecutive zero stores.
- Verify unrolled stores target the correct addresses and cover the full object size.
- Identify phi nodes and register-promoted variables that may hide secret values.

Flag `LOOP_UNROLLED_INCOMPLETE` when unrolling is detected but does not cover the full object.

### Step 10 — Control-Flow Graph Analysis (produces `MISSING_ON_ERROR_PATH`, `NOT_DOMINATING_EXITS`)

Skip if `enable_cfg=false`.

Build a CFG from source or LLVM IR:
- Enumerate all execution paths from function entry to exits.
- Compute dominator sets for all nodes.
- Verify that a wipe node dominates all exit nodes. If not, flag `NOT_DOMINATING_EXITS`.
- Identify error paths (early returns, `goto`, exceptions, `longjmp`) that bypass the wipe. Flag `MISSING_ON_ERROR_PATH` for each such path.

This step produces definitive results replacing the heuristic `NOT_ON_ALL_PATHS` finding from Step 5. If both are emitted for the same object, keep only the CFG-backed finding.

### Step 11 — Runtime Validation Test Generation

Skip if `enable_runtime_tests=false`.

For each confirmed finding, generate:
- A C test harness that allocates the sensitive object and verifies all bytes are zero after the expected wipe point.
- A MemorySanitizer test (`-fsanitize=memory`) to detect reads of uninitialized or un-zeroed memory.
- A Valgrind invocation target for leak and memory error detection.
- A stack canary test to detect stack retention after function return.

Output a `Makefile` in `{baseDir}/generated_tests/` that builds and runs all tests with appropriate sanitizer flags.

### Step 12 — PoC Generation (mandatory)

Generate proof-of-concept C programs for all findings regardless of confidence. Each PoC exits 0 (exploitable) or 1 (not exploitable):

```bash
uv run --no-project {baseDir}/tools/generate_poc.py \
  --findings <findings_json> \
  --compile-db <compile_db> \
  --out <poc_output_dir> \
  --categories <poc_categories> \
  --config <config> \
  --no-confidence-filter
```

After generation, review PoCs for `// TODO` comments and fill them in using source context. Compilation and validation are handled by the orchestrator in Phase 5 (interactive).

Key PoC strategies: `OPTIMIZED_AWAY_ZEROIZE` — compile with and without `-O2`, compare memory dumps; `STACK_RETENTION` — call the target function, read stack memory after return; `MISSING_SOURCE_ZEROIZE` — verify bytes are non-zero at function exit. C/C++ findings support all categories. Rust findings support `MISSING_SOURCE_ZEROIZE`, `SECRET_COPY`, and `PARTIAL_WIPE` via `cargo test`; all other Rust categories are marked `poc_supported: false`.

# LLVM IR Analysis for Zeroization Auditing

This reference covers multi-level IR analysis for detecting compiler-optimized zeroization (dead-store elimination of wipes) and interpreting results. Read this during Step 7 (IR comparison) and Step 9 (semantic IR analysis) in `task.md`. For flag extraction and pipeline setup, refer to the compile-commands reference (loaded separately from SKILL.md).

---

## Optimization Level Semantics

| Level | What changes | Relevance to zeroization |
|---|---|---|
| **O0** | No optimization. All stores kept. | Baseline — wipe always present if written in source |
| **O1** | Basic optimizations. Simple dead-store elimination begins. | Diagnostic level: if wipe vanishes here, it's simple DSE. Fix is straightforward. |
| **O2** | Full DSE, inlining, SROA, alias analysis. | Most production builds. Most non-volatile wipes removed here. |
| **O3** | Aggressive vectorization, loop transforms, more inlining. | Rarely removes more wipes than O2, but can for loop-based wipes. |
| **Os/Oz** | Size-optimized. May collapse wipe loops into `memset`. | Verify wipe survives after size optimization; collapsed `memset` may become DSE-vulnerable. |

**Always include O0 as the unoptimized baseline**, regardless of the `opt_levels` input. O1 is the diagnostic level — if the wipe disappears there, the cause is simple DSE and the fix is straightforward. If the wipe only disappears at O2 or O3, proceed to the multi-level root cause analysis below.

---

## Emitting IR at Multiple Levels

Extract flags once, then emit IR for each level in `opt_levels`. Use `<tu_hash>` (a hash of the source path) to avoid collisions during parallel TU processing. Always clean up temp files on completion or failure.

```bash
mkdir -p /tmp/zeroize-audit/

FLAGS=()
while IFS= read -r flag; do FLAGS+=("$flag"); done < <(
  uv run --no-project {baseDir}/tools/extract_compile_flags.py \
    --compile-db build/compile_commands.json \
    --src src/crypto.c --format lines)

# Emit IR for each level in opt_levels (O0 always included as baseline)
for OPT in O0 O1 O2; do
  {baseDir}/tools/emit_ir.sh \
    --src src/crypto.c \
    --out /tmp/zeroize-audit/<tu_hash>.${OPT}.ll \
    --opt ${OPT} -- "${FLAGS[@]}"
done

# Diff all levels — prints pairwise diffs and a WIPE PATTERN SUMMARY
{baseDir}/tools/diff_ir.sh \
  /tmp/zeroize-audit/<tu_hash>.O0.ll \
  /tmp/zeroize-audit/<tu_hash>.O1.ll \
  /tmp/zeroize-audit/<tu_hash>.O2.ll

# Cleanup
rm -f /tmp/zeroize-audit/<tu_hash>.*.ll
```

For Rust TUs, `emit_ir.sh` does not apply. Use `cargo rustc -- --emit=llvm-ir -C opt-level=N` instead and pass the resulting `.ll` files directly to `diff_ir.sh`. Use `bear -- cargo build` to generate `compile_commands.json` for Rust projects.

---

## LLVM IR Zeroization Patterns

### DSE-safe patterns (survive optimization)

These indicate a secure wipe the compiler cannot remove.

**Volatile memset intrinsic** — the `i1 true` (volatile) flag prevents DSE:
```llvm
call void @llvm.memset.p0i8.i64(i8* volatile %ptr, i8 0, i64 32, i1 true)
```

**Volatile zero stores** — volatile side effects must be preserved:
```llvm
store volatile i8 0, i8* %ptr, align 1
store volatile i64 0, i64* %ptr, align 8
```

**Opaque wipe function calls** — DSE cannot remove calls to external functions with unknown side effects:
```llvm
call void @explicit_bzero(i8* %key, i64 32)
call void @sodium_memzero(i8* %key, i64 32)
call void @OPENSSL_cleanse(i8* %key, i64 32)
call void @SecureZeroMemory(i8* %key, i64 32)
```

**`memset_s`** — defined by C11 to be non-optimizable:
```llvm
call i32 @memset_s(i8* %key, i64 32, i32 0, i64 32)
```

**Rust `zeroize` crate** — emits volatile stores via the `Zeroize` trait; look for:
```llvm
store volatile i8 0, i8* %ptr, align 1   ; repeated per byte, or as unrolled loop
```

---

### DSE-vulnerable patterns (may be removed at O1 or O2)

**Non-volatile memset intrinsic** — `i1 false` is the most common `OPTIMIZED_AWAY_ZEROIZE` pattern:
```llvm
call void @llvm.memset.p0i8.i64(i8* %ptr, i8 0, i64 32, i1 false)
```

**Non-volatile zero stores** — any non-volatile store to a dead location is DSE-eligible:
```llvm
store i8 0, i8* %ptr, align 1
store i64 0, i64* %ptr, align 8
store i32 0, i32* %ptr, align 4
```

**Standard `memset` inlined to non-volatile intrinsic** — `memset(key, 0, 32)` in source is lowered by Clang to `@llvm.memset ... i1 false`. The source used `memset` but the IR form is DSE-vulnerable. This is the most frequent source of confusion.

---

## Reading an IR Diff: Concrete Before/After Example

**Source (C):**
```c
void handle_request(uint8_t session_key[32]) {
    // ... use session_key ...
    memset(session_key, 0, 32);  // intended cleanup
}
```

**O0 IR — wipe present:**
```llvm
define void @handle_request(i8* %session_key) {
entry:
  ; ... computation uses session_key ...
  call void @llvm.memset.p0i8.i64(i8* %session_key, i8 0, i64 32, i1 false)
  ret void
}
```

**O2 IR — wipe removed by DSE:**
```llvm
define void @handle_request(i8* %session_key) {
entry:
  ; ... computation ...
  ; llvm.memset REMOVED — no read from session_key after the store;
  ; optimizer treats it as a dead store and eliminates it.
  ret void
}
```

**`diff_ir.sh` output:**
```
=== DIFF: O0.ll vs O2.ll ===
-  call void @llvm.memset.p0i8.i64(i8* %session_key, i8 0, i64 32, i1 false)

=== WIPE PATTERN SUMMARY ===
O0.ll: WIPE PRESENT
O1.ll: WIPE PRESENT
O2.ll: WIPE ABSENT  <-- first disappearance
```

Lines starting with `-` are present in the lower-opt file but absent in the higher-opt file. A `-` line containing any of the following tokens is direct evidence of `OPTIMIZED_AWAY_ZEROIZE`:

`llvm.memset`, `store i8 0`, `store i64 0`, `store i32 0`, `@explicit_bzero`, `@sodium_memzero`, `@OPENSSL_cleanse`, `@SecureZeroMemory`

---

## Multi-Level Root Cause Analysis

The level at which the wipe first disappears narrows the root cause and determines the appropriate fix:

```
O0 → WIPE PRESENT   (baseline — wipe was written in source)
O1 → WIPE ABSENT    → Simple dead-store elimination (basic DSE pass)
                       Fix: replace memset with explicit_bzero or volatile wipe loop
O2 → WIPE ABSENT    → One or more of:
(first disappearance)    • DSE + inlining: wipe is in a helper inlined into caller,
                           becomes dead store in caller's context
                         • SROA: struct/array promoted to scalars; individual
                           zero stores become DSE-eligible
                         • Alias analysis: proves no live uses after the wipe
                       Fix: use explicit_bzero; ensure wipe is not inside
                       an inlined callee (see Inlining section below)
O3 → WIPE ABSENT    → Aggressive loop transforms or vectorization eliminated
(only here)            a loop-based wipe
                       Fix: replace wipe loop with explicit_bzero or volatile loop
```

If the wipe disappears at O1, a simple `explicit_bzero` or `volatile` qualifier is sufficient. If it only disappears at O2 due to inlining, also ensure the wipe is not inside a callee that gets inlined at the call site.

---

## Advanced IR Analysis Scenarios

### Inlining and cross-function DSE

When a cleanup wrapper (e.g., `zeroize_key()`) is inlined into a caller, the wipe may become a dead store in the caller's context even if it survives in the callee's IR. Always emit IR for the **calling** TU — this is where inlining occurs:

```bash
# zeroize_key() defined in utils.c, called from crypto.c
# Emit IR for the caller — inlining happens here:
FLAGS=()
while IFS= read -r flag; do FLAGS+=("$flag"); done < <(
  uv run --no-project {baseDir}/tools/extract_compile_flags.py \
    --compile-db build/compile_commands.json --src src/crypto.c --format lines)

{baseDir}/tools/emit_ir.sh \
  --src src/crypto.c \
  --out /tmp/zeroize-audit/<tu_hash>.O2.ll --opt O2 -- "${FLAGS[@]}"
```

If the wipe is present in `utils.c` IR but absent in `crypto.c` IR at O2, the cause is cross-function DSE after inlining. Mark the `OPTIMIZED_AWAY_ZEROIZE` finding on the call site in `crypto.c`, not on `utils.c`.

### SROA (Scalar Replacement of Aggregates)

At O1+, SROA promotes small structs and arrays to individual scalar SSA values (registers). A `memset` of a struct may become a series of individual `store i32 0` / `store i8 0` instructions per field — each then eligible for DSE independently. In the diff, look for:
- O0: single `llvm.memset` covering the struct
- O1/O2: the `memset` is replaced by per-field zero stores, then those stores are removed

This means the wipe may partially survive SROA (some fields zeroed, others eliminated). Check that **all** fields of a sensitive struct are covered, not just the first.

### Loop unrolling of wipe loops

A manual wipe loop:
```c
for (int i = 0; i < 32; i++) key[i] = 0;
```
may be unrolled at O2 into 32 consecutive `store i8 0` instructions. If unrolling is incomplete (e.g., only 16 of 32 iterations unrolled and the remainder is a DSE-eligible tail), flag `LOOP_UNROLLED_INCOMPLETE`. Use `{baseDir}/tools/analyze_ir_semantic.py` for automated detection — do not use regex on raw IR text. The semantic tool builds a proper basic block representation and counts consecutive zero stores with address verification.

### Phi nodes and register-promoted secrets

After `mem2reg`, secret values that were stack-allocated may be promoted to SSA values tracked through phi nodes. A wipe of the original stack slot may not reach all SSA uses. Look for:
```llvm
%key.0 = phi i64 [ %loaded_key, %entry ], [ 0, %cleanup ]
```
If `%key.0` is used after the phi but the `0` arm is only reached on one path, the secret may persist in the non-zero arm. Flag as `NOT_DOMINATING_EXITS` if CFG analysis confirms it.

---

## Populating `compiler_evidence` in the Report

For each `OPTIMIZED_AWAY_ZEROIZE` finding, populate the output schema fields as follows. `OPTIMIZED_AWAY_ZEROIZE` is **never valid without IR diff evidence** — do not emit this finding from source-level analysis alone.

```json
{
  "category": "OPTIMIZED_AWAY_ZEROIZE",
  "compiler_evidence": {
    "opt_levels": ["O0", "O1", "O2"],
    "o0": "call void @llvm.memset.p0i8.i64(i8* %session_key, i8 0, i64 32, i1 false) present at line 88.",
    "o1": "WIPE PRESENT at O1.",
    "o2": "llvm.memset call absent at O2 — dead store eliminated after SROA promotes session_key to registers.",
    "diff_summary": "Wipe first disappears at O2. Non-volatile memset(session_key, 0, 32) eliminated by DSE after SROA. Fix: replace memset with explicit_bzero."
  }
}
```

Field usage notes:
- `opt_levels`: list every level that was emitted, not just the levels where the wipe changed.
- `o0` through `o2` (and `o1`, `o3` if analyzed): state explicitly whether the wipe is PRESENT or ABSENT at each level, with a short IR excerpt if present.
- If the wipe only disappears at O3 but is present at O2: set `o2` to `"WIPE PRESENT at O2"` and document the O3 removal in `diff_summary`.
- `diff_summary`: always identify the first disappearance level and the most likely optimization pass responsible (DSE, inlining, SROA, alias analysis, loop transform).

# MCP-Assisted Semantic Analysis

This reference covers how to configure, query, and interpret Serena MCP evidence during the zeroize-audit semantic pass. For compile DB generation and flag extraction, refer to the compile-commands reference (loaded separately from SKILL.md).

---

## Preconditions

Before running any MCP queries, the following must hold. These are verified during Step 1 (Preflight) in `task.md` — do not re-run preflight here, just confirm the relevant outputs:

| Precondition | Failure behavior |
|---|---|
| `compile_commands.json` valid and readable | Do not run MCP queries; fail the run if `mcp_mode=require` |
| Codebase buildable from compile DB commands | Same as above |
| `check_mcp.sh` exits 0 | If `mcp_mode=require`: stop run. If `mcp_mode=prefer`: set `mcp_available=false`, continue without MCP, apply confidence downgrades |
| Serena can resolve at least one symbol in the TU | Log a warning; proceed but mark findings from that TU as `needs_review` |

**Rust note**: Cargo does not natively produce `compile_commands.json`. Use `bear -- cargo build` or `bear -- cargo check` to generate it. `rust-project.json` is not a substitute in this workflow.

---

## Configuring Serena

The `plugin.json` registers Serena as the `serena` MCP server, launched via `uvx`. Serena wraps language servers (clangd for C/C++) and exposes semantic analysis as high-level MCP tools. It auto-discovers `compile_commands.json` from the project working directory.

**Prerequisites:**
- `uvx` must be on PATH (installed with `uv` — see https://docs.astral.sh/uv/)
- Serena is fetched and run automatically via `uvx --from git+https://github.com/oraios/serena`
- No separate `clangd` installation is required — Serena manages language server dependencies internally

**Verify before querying:**

```bash
{baseDir}/tools/mcp/check_mcp.sh \
  --compile-db /path/to/compile_commands.json
```

A non-zero exit means MCP is unreachable. Apply the preflight failure behavior above.

---

## MCP Tool Reference

Serena abstracts LSP methods into higher-level, symbol-name-based tools. Unlike raw LSP, you query by symbol name rather than file position.

| MCP tool name | Purpose in zeroize-audit | Key parameters |
|---|---|---|
| `activate_project` | **Must be called first.** Activates the project so Serena indexes it | `project` (path to repo root) |
| `find_symbol` | Resolve where a sensitive symbol is defined; get type info, body, and struct layout | `symbol_name`, `file_path` (optional), `include_body`, `depth` |
| `find_referencing_symbols` | Find all use sites and callers across files | `symbol_name`, `file_path` (optional) |
| `get_symbols_overview` | List all symbols in a file — useful for exploring unfamiliar TUs | `file_path` |

**Mapping from previous LSP-based queries:**

| Analysis need | Serena tool | Notes |
|---|---|---|
| Resolve definition | `find_symbol` | Search by name; returns file, line, kind, and optionally body |
| Find all references | `find_referencing_symbols` | Returns referencing symbols with file and line |
| Find callers (incoming calls) | `find_referencing_symbols` | Search for references to a function name |
| Find callees (outgoing calls) | `find_symbol` + source read | Get function body via `include_body: true`, then resolve called symbols |
| Resolve type / hover | `find_symbol` with `include_body: true` | Type information is included in the symbol result |
| Follow typedef chain | `find_symbol` | Look up the type name directly |

---

## Query Order

Run queries in this order so each step's output informs the next. All queries for a given TU should complete before moving to the next TU.

### Step 0 — Activate the project (`activate_project`)

This **must** be called once before any other Serena tool. Pass the repository root path. If activation fails, treat MCP as unavailable.

```
Tool: activate_project
Arguments:
  project: "/path/to/repo"
```

Expected: confirmation that the project is active. Serena will start indexing the codebase (including launching clangd if needed). Wait for activation to succeed before proceeding.

### Step 1 — Resolve symbol definition (`find_symbol`)

Establishes the canonical declaration location and type information used in all subsequent queries.

```
Tool: find_symbol
Arguments:
  symbol_name: "secret_key"
  include_body: true
```

Expected: result with `file`, `line`, `kind`, `symbol` name, and body content. The body provides type information (array sizes, struct layout) needed for wipe-size validation in Step 3. Store this as the canonical location for Steps 2–4.

If the symbol name is ambiguous, narrow with `file_path`:

```
Tool: find_symbol
Arguments:
  symbol_name: "secret_key"
  file_path: "src/crypto.c"
  include_body: true
```

### Step 2 — Collect all use sites (`find_referencing_symbols`)

Finds every location where the sensitive symbol is referenced. Use these to locate adjacent wipe calls and detect copies to other scopes.

```
Tool: find_referencing_symbols
Arguments:
  symbol_name: "secret_key"
```

Expected: list of referencing symbols with `file`, `line`, `symbol`, and `kind`. For each reference in a file other than the source TU, check that file for cleanup. References in generated files (build directory) can be filtered by source directory prefix.

### Step 3 — Resolve type and size

Type information is returned as part of `find_symbol` results (Step 1). If you need to resolve a typedef or follow a type alias chain, look up the type name directly:

```
Tool: find_symbol
Arguments:
  symbol_name: "secret_key_t"
  include_body: true
```

Use this to validate wipe sizes — a `sizeof(ptr)` bug will be apparent when the symbol body reveals `uint8_t [32]` but the wipe uses `sizeof(uint8_t *)`.

### Step 4 — Trace callers and cleanup paths

Use `find_referencing_symbols` on the function containing the sensitive object to find callers that may hold their own copy of the secret. Use it on wipe wrapper functions to find cleanup paths.

```
Tool: find_referencing_symbols
Arguments:
  symbol_name: "process_key"
```

For outgoing calls (what does this function call?), read the function body from `find_symbol` output and resolve each called function:

```
Tool: find_symbol
Arguments:
  symbol_name: "process_key"
  include_body: true
```

Then for each function called within the body:

```
Tool: find_symbol
Arguments:
  symbol_name: "cleanup_secret"
```

### Step 5 — Normalize output

Before using any MCP results in confidence scoring or finding emission, normalize:

```bash
uv run --no-project {baseDir}/tools/mcp/normalize_mcp_evidence.py \
  --input /tmp/raw_mcp_results.json \
  --output /tmp/normalized_mcp_results.json
```

The normalizer produces a consistent schema consumed by the MCP semantic pass and subsequent confidence gating steps.

---

## Interpreting Responses

| Response | Meaning | Action |
|---|---|---|
| Empty results | Serena could not resolve the symbol | Check compile DB path; verify symbol name spelling; retry with `file_path` to narrow scope |
| Timeout (> `mcp_timeout_ms`) | Query too slow | Mark finding as `needs_review`; do not wait indefinitely |
| Multiple results for same name | Symbol is defined in multiple TUs or headers | Use `file_path` to disambiguate; note in evidence |
| References in generated files | Hits in build-generated sources | Filter by source directory prefix |
| No referencing symbols found | Symbol is unused or not indexed | Acceptable for leaf functions; note in evidence |

---

## Confidence Scoring

MCP evidence contributes one signal toward the 2-signal threshold for `confirmed` findings (see SKILL.md Confidence Gating). Tag each piece of evidence with its source:

| Evidence source tag | Meaning |
|---|---|
| `mcp` | Resolved via Serena MCP query |
| `source` | Source-level pattern match |
| `ir` | LLVM IR analysis |
| `asm` | Assembly analysis |
| `cfg` | Control-flow graph analysis |

MCP evidence alone (1 signal) produces `likely`. MCP + one additional signal (source, IR, CFG, or ASM) produces `confirmed`.

**Mandatory downgrades** — applied by `apply_confidence_gates.py` after all evidence is collected:

| Condition | Findings downgraded to `needs_review` |
|---|---|
| `mcp_available=false` AND `mcp_required_for_advanced=true` | `SECRET_COPY`, `MISSING_ON_ERROR_PATH`, `NOT_DOMINATING_EXITS` (unless 2+ non-MCP signals exist) |
| Assembly evidence missing | `STACK_RETENTION`, `REGISTER_SPILL` |
| IR diff evidence missing | `OPTIMIZED_AWAY_ZEROIZE` |

Apply downgrades after all evidence is collected, not during querying. Do not suppress findings preemptively — emit at `needs_review` rather than dropping them.

---

## Post-Processing

After collecting all MCP evidence and running IR/ASM/CFG analysis, apply confidence gates mechanically:

```bash
uv run --no-project {baseDir}/tools/mcp/apply_confidence_gates.py \
  --input /tmp/raw-report.json \
  --out /tmp/final-report.json \
  --mcp-available \
  --mcp-required-for-advanced
```

Omit `--mcp-available` if MCP was unreachable. Omit `--mcp-required-for-advanced` if `mcp_required_for_advanced=false` in the run config. The script applies all downgrade rules from SKILL.md and outputs gated findings ready for the report assembly phase.

# PoC Crafting Reference

## Overview

Each zeroize-audit finding is demonstrated with a bespoke proof-of-concept program
crafted from the finding details and the actual source code. PoCs are individually
written, not generated from templates — they use the real function signatures,
variable names, types, and sizes from the audited codebase. Each PoC exits 0 if the
secret persists (exploitable) or 1 if the data was properly wiped (not exploitable).

## Exit Code Convention

| Exit code | Meaning |
|-----------|---------|
| 0 | Secret persists after the operation — finding is exploitable |
| 1 | Secret was wiped — finding is not exploitable in this configuration |

The `POC_PASS()` and `POC_FAIL()` macros in `poc_common.h` enforce this convention.

## Common Techniques

### Volatile Reads

The core verification technique is reading through a `volatile` pointer after the
function under test returns. This prevents the compiler from optimizing away the
read, ensuring we observe the actual memory state:

```c
static int volatile_read_nonzero(const void *ptr, size_t len) {
    const volatile unsigned char *p = (const volatile unsigned char *)ptr;
    int found = 0;
    for (size_t i = 0; i < len; i++) {
        if (p[i] != 0) found = 1;
    }
    return found;
}
```

### Stack Probing

For `STACK_RETENTION` and `REGISTER_SPILL` findings, the PoC calls the target
function then immediately calls `stack_probe()` — a `noinline`/`noclone` function
that reads uninitialized local variables to detect whether the prior call frame left
secret data on the stack:

```c
__attribute__((noinline, noclone))
static int stack_probe(size_t frame_size) {
    volatile unsigned char probe[STACK_PROBE_MAX];
    /* Read uninitialized stack — check for secret fill pattern */
    int count = 0;
    for (size_t i = 0; i < frame_size; i++) {
        if (probe[i] == SECRET_FILL_BYTE) count++;
    }
    return count >= (int)(frame_size / 4);
}
```

### Source Inclusion

For static functions and small files (<=5000 lines by default), PoCs include the
source file directly via `#include "../../src/crypto.c"`. This handles both static
and extern functions without requiring separate compilation. For large files with
non-static functions, the Makefile uses object-file linking instead.

### Secret Fill Pattern

Buffers are initialized with `0xAA` (configurable via `secret_fill_byte` in config)
before calling the target function. After the call, the PoC checks whether the fill
pattern persists — indicating the secret was not wiped.

## Per-Category Strategies

### MISSING_SOURCE_ZEROIZE

**Opt level:** `-O0`
**Technique:** Call the function that handles the secret, then volatile-read the
buffer after it returns. At `-O0` there are no optimization passes that could
accidentally wipe the buffer, so if the secret persists, it confirms the source
code lacks a wipe call.

**Crafting guidance:**
- Read the function signature and determine minimal valid arguments
- Identify the exact sensitive variable from the finding — use its real name and type
- If the function takes the sensitive buffer as a parameter, allocate it in `main()`,
  fill with `SECRET_FILL_BYTE`, pass it to the function, then check after return
- If the sensitive variable is a local, include the source file and examine the buffer
  via a global pointer or by modifying the function to expose it

**Pitfalls:**
- The buffer must be the actual sensitive variable, not a local copy
- Stack-allocated secrets may be overwritten by subsequent function calls even
  without explicit zeroization — run immediately after the function returns

### OPTIMIZED_AWAY_ZEROIZE

**Opt level:** The level where the wipe disappears (from `compiler_evidence.diff_summary`)
**Technique:** Same as `MISSING_SOURCE_ZEROIZE`, but compiled at the optimization
level where the compiler removes the wipe. The finding's `compiler_evidence` field
indicates which level this is (typically `-O1` for simple DSE, `-O2` for aggressive
optimization).

**Crafting guidance:**
- Read the `compiler_evidence.diff_summary` to determine the exact optimization level
- The wipe IS present at `-O0` — compiling the PoC at `-O0` will show "not exploitable"
  which would be misleading. Always use the opt level from the evidence.
- Include the source file to ensure the compiler can apply the same optimizations

**Pitfalls:**
- The opt level must match what `diff_ir.sh` reported — compiling at a different
  level may give false negatives
- LTO can change behavior; PoCs use single-TU compilation by default

### STACK_RETENTION

**Opt level:** `-O2`
**Technique:** Call the function, then immediately call `stack_probe()` with a
frame size matching the target function's stack allocation. The probe reads
uninitialized locals that overlap the prior call frame.

**Crafting guidance:**
- Extract the stack frame size from the ASM evidence in the finding
- The probe function MUST be called immediately after the target function returns,
  with no intervening function calls that could overwrite the stack
- Use `noinline` and `noclone` on the probe to prevent frame reuse

**Pitfalls:**
- Stack layout varies between compiler versions and optimization levels
- The probe function must be `noinline` to prevent the compiler from reusing
  the same frame
- Frame size is estimated from ASM evidence; verify against the actual assembly
- Address Space Layout Randomization (ASLR) does not affect stack frame reuse
  within a single thread

### REGISTER_SPILL

**Opt level:** `-O2`
**Technique:** Similar to stack retention, but targets the specific stack offset
where the register spill occurs (extracted from the ASM evidence showing
`movq %reg, -N(%rsp)`).

**Crafting guidance:**
- Extract the exact spill offset from the finding's ASM evidence
- Target the probe at that specific region of the stack
- The same `noinline` probe approach applies

**Pitfalls:**
- Spill offsets are compiler-specific and may change with minor code changes
- Different register allocation strategies produce different spill patterns
- The probe must target the exact offset region to be reliable

### SECRET_COPY

**Opt level:** `-O0`
**Technique:** Call the function that copies the secret, verify the original may
be wiped, then volatile-read the copy destination to confirm the copy persists
without zeroization.

**Crafting guidance:**
- Identify the copy destination from the source code: `memcpy` target, struct
  assignment LHS, return value receiver, or pass-by-value parameter
- The PoC must check the COPY, not the original — the original may be wiped
- If the copy is to a struct field, allocate the struct and check that specific field

**Pitfalls:**
- The copy destination must be identified from the source code
- Multiple copies may exist; each needs separate verification

### MISSING_ON_ERROR_PATH

**Opt level:** `-O0`
**Technique:** Force the error path by providing controlled inputs that trigger
the error return, then volatile-read the secret buffer to confirm it was not
wiped before the error exit.

**Crafting guidance:**
- Read the source code to understand what conditions trigger the error return
- Common error triggers: NULL pointer arguments, invalid key sizes, allocation
  failure (can use `malloc` interposition), invalid magic numbers
- After the function returns with an error code, check both the return value
  (to confirm the error path was taken) AND the secret buffer (to confirm it persists)
- Comment the choice of error-triggering input with a reference to the source line

**Pitfalls:**
- Triggering the error path may require domain knowledge (invalid keys, NULL
  pointers, allocation failures)
- Some error paths involve signals or `longjmp` that are hard to trigger from
  a simple test harness
- Error codes must be checked to confirm the error path was actually taken

### PARTIAL_WIPE

**Opt level:** `-O0`
**Technique:** Fill the full buffer with the secret fill pattern, call the function,
then volatile-read the *tail* beyond the incorrectly-sized wipe region. If the
function wipes only N bytes of an M-byte object (N < M), the tail
`buf[N..M]` still contains the secret.

**Crafting guidance:**
- Extract the wiped size and full object size from the finding evidence
- The PoC must check `buf[wiped_size .. full_size]`, not the entire buffer
- If both sizes are uncertain, read the source to verify `sizeof()` calls

**Pitfalls:**
- The wiped vs. full sizes must be verified against source
- At `-O0` the compiler won't add extra zeroing, so this is a pure source-level bug
- Struct padding may cause false positives if the wipe intentionally skips padding

### NOT_ON_ALL_PATHS

**Opt level:** `-O0`
**Technique:** Force execution down the control-flow path that lacks the wipe,
then volatile-read the secret buffer. This is structurally identical to
`MISSING_ON_ERROR_PATH` but covers *any* uncovered path, not just error paths.

**Crafting guidance:**
- Read the function's control flow to identify which branch lacks the wipe
- Determine what input values force execution through that branch
- Comment the input choice and reference the specific branch condition

**Pitfalls:**
- Requires understanding the function's branching logic
- The heuristic finding from source analysis may be superseded by CFG-backed
  `NOT_DOMINATING_EXITS` — check for duplicates
- Multiple uncovered paths may exist; the PoC demonstrates only one

### INSECURE_HEAP_ALLOC

**Opt level:** `-O0`
**Technique:** Demonstrate heap residue using the `heap_residue_check()` helper:
allocate with `malloc()`, fill with secret, free, re-allocate the same size,
then check if the secret persists in the new allocation. This proves that
standard allocators do not scrub freed memory.

**Crafting guidance:**
- Use the exact allocation size from the finding
- For a function-specific proof, call the target function (which does the
  malloc/use/free), then immediately malloc the same size and check
- Add a comment explaining that this demonstrates the general vulnerability

**Pitfalls:**
- Do **not** compile with AddressSanitizer (`-fsanitize=address`) — ASan poisons
  freed memory, hiding the vulnerability
- Heap allocator behavior varies: glibc `malloc` reuses freed chunks predictably,
  but jemalloc or tcmalloc may not — the PoC may give false negatives on
  non-standard allocators
- The PoC demonstrates the general vulnerability; for function-level proof,
  call the actual target function

### LOOP_UNROLLED_INCOMPLETE

**Opt level:** `-O2`
**Technique:** Like `PARTIAL_WIPE` but compiled at `-O2` where incomplete loop
unrolling occurs. The compiler unrolls the wipe loop for N bytes but the object
is M bytes (N < M). Fill the buffer, call the function, check the tail beyond
the unrolled region.

**Crafting guidance:**
- Extract the covered bytes and object size from the IR semantic analysis evidence
- Compile at `-O2` — at `-O0` the loop executes correctly
- Check `buf[covered_bytes .. object_size]`

**Pitfalls:**
- Must compile at `-O2` (or the level where unrolling occurs) — at `-O0` the
  loop executes correctly
- Covered bytes and object size are extracted from IR semantic analysis evidence;
  if the IR evidence is unavailable, values may be inaccurate
- Different compilers (GCC vs. Clang) and versions unroll differently; the PoC
  is compiler-specific

### NOT_DOMINATING_EXITS

**Opt level:** `-O0`
**Technique:** Force execution through an exit path that bypasses the wipe, as
identified by CFG dominator analysis. The wipe node does not dominate all exit
nodes, meaning some return paths leave the secret in memory.

**Crafting guidance:**
- Read the finding evidence to identify which exit path bypasses the wipe
- Determine what inputs reach the non-dominated exit
- Comment the input choice and reference the CFG evidence (exit line or path count)

**Pitfalls:**
- Requires understanding of the function's CFG; the finding evidence identifies
  the exit line or path count
- Similar to `NOT_ON_ALL_PATHS` but backed by CFG evidence rather than
  source-level heuristics

## Pipeline Integration

PoC crafting and validation is mandatory for every finding, regardless of
confidence level. The pipeline flow is:

1. **Phase 3 — Interim Finding Collection**: Agent 4 produces `findings.json`
   with all gated findings. No final report yet.

2. **Phase 4 — PoC Crafting**: Agent 5 reads each finding and the corresponding
   source code, then writes bespoke PoC programs. Each PoC is individually
   tailored — using real function names, variable names, types, and sizes.

3. **Phase 5 — PoC Validation & Verification**:
   - Agent 5b compiles and runs all PoCs, recording exit codes.
   - Agent 5c verifies each PoC proves its claimed finding by checking:
     target variable match, target function match, technique appropriateness,
     optimization level, exit code interpretation, and result plausibility.
   - Orchestrator presents verification failures to user via `AskUserQuestion`.
   - Orchestrator merges all results into `poc_final_results.json`.

4. **Phase 6 — Report Finalization**: Agent 4 is re-invoked in final mode.
   It merges PoC validation and verification results into findings:
   - Exit 0 + verified → `exploitable` — strong evidence, can upgrade confidence.
   - Exit 1 + verified → `not_exploitable` — downgrade severity to `low`.
   - Verified=false + user rejected → `rejected` — no confidence change.
   - Verified=false + user accepted → use result but note as weaker signal.
   - Compile failure → annotate, no confidence change.
   - Produces the final `final-report.md` with PoC validation and verification summary.

### Validation Result Mapping

| Exit Code | Compile | Verified | Result | Finding Impact |
|-----------|---------|----------|--------|---------------|
| 0 | success | yes | `exploitable` | Confirm finding; can upgrade `likely` → `confirmed` |
| 1 | success | yes | `not_exploitable` | Downgrade severity to `low` (informational) |
| 0/1 | success | no (user accepted) | original | Weaker confidence signal; note verification failure |
| 0/1 | success | no (user rejected) | `rejected` | No confidence change |
| — | failure | — | `compile_failure` | Annotate; no confidence change |
| — | — | — | `no_poc` | No PoC generated; annotate; no confidence change |

## Rust PoC Generation

Rust PoCs are enabled for three categories where a simple volatile-read after drop is sufficient to prove the vulnerability. All other categories remain excluded.

**Exit code convention (cargo test):**
- `assert!` passes → cargo exits 0 → `"exploitable"` (secret persists)
- `assert!` panics → cargo exits non-zero → `"not_exploitable"` (secret wiped)

**Verification primitive:** Use `std::ptr::read_volatile` inside `unsafe { }`. Never use the C `volatile` keyword in Rust PoCs.

**Pointer validity:** `read_volatile` after `drop()` is only safe for heap-backed data. If the sensitive type is stack-only, force heap allocation: `let boxed = Box::new(obj); let raw = boxed.as_ref().as_ptr(); drop(boxed);`. For types with `Vec`/`Box` fields, the raw pointer to the field's backing allocation remains valid after drop (the heap page is not scrubbed by the allocator).

---

### MISSING_SOURCE_ZEROIZE (Rust)

**Opt level:** debug (no `--release`)
**Technique:** Construct the sensitive type with `[0xAAu8; N]` fill. Capture a raw pointer to the backing buffer **before** drop. Drop the type (or let scope end). Volatile-read the buffer to check persistence.

```rust
#[test]
fn poc_za_NNNN_missing_source_zeroize() {
    let key = SensitiveKey::new([0xAAu8; 32]);
    let raw: *const u8 = key.as_slice().as_ptr();
    drop(key);
    let secret_persists = (0..32usize).any(|i| unsafe {
        std::ptr::read_volatile(raw.add(i)) == 0xAA
    });
    assert!(secret_persists, "Secret was wiped — not exploitable");
}
```

**Pitfalls:**
- The raw pointer must point to heap-backed storage — stack pointers become dangling after drop.
- If the type does not expose `as_slice()` or similar, use a field accessor (`key.key_bytes.as_ptr()`).
- At debug build, the compiler does not add extra zeroing — a positive result confirms the source lacks a wipe call.

---

### SECRET_COPY (Rust)

**Opt level:** debug (no `--release`)
**Technique:** Perform the identified copy operation (`.clone()`, `Copy` assignment, `From::from()`, `Debug` formatting). Drop the **original**. Volatile-read the **copy** — not the original.

```rust
#[test]
fn poc_za_NNNN_secret_copy() {
    let original = SensitiveKey::new([0xAAu8; 32]);
    let copy = original.clone();                        // or Copy assignment / From::from()
    let raw: *const u8 = copy.as_slice().as_ptr();
    drop(original);                                      // original may be wiped; copy is not
    let secret_persists = (0..32usize).any(|i| unsafe {
        std::ptr::read_volatile(raw.add(i)) == 0xAA
    });
    drop(copy);
    assert!(secret_persists, "Copy was wiped — not exploitable");
}
```

**Pitfalls:**
- Read the copy, not the original. The original may be properly wiped; the copy is the vulnerability.
- For `#[derive(Debug)]` findings: format via `format!("{:?}", &original)` and check the resulting `String` for the fill pattern bytes (hex or decimal representations of `0xAA`).
- For `From`/`Into` findings: call the conversion and check the target type's buffer.

---

### PARTIAL_WIPE (Rust)

**Opt level:** debug (no `--release`)
**Technique:** Construct the type with `[0xAAu8; full_size]` fill. Trigger drop. Volatile-read **only the tail** (`wiped_size..full_size`). The head (`0..wiped_size`) may be correctly zeroed; only the tail proves the partial wipe.

```rust
#[test]
fn poc_za_NNNN_partial_wipe() {
    // full_size = 64, wiped_size = 32 (from finding evidence)
    let obj = SensitiveStruct { key: [0xAAu8; 64], ..Default::default() };
    let raw: *const u8 = obj.key.as_ptr();
    drop(obj);
    // Only check the tail bytes beyond the wipe region
    let tail_persists = (32usize..64).any(|i| unsafe {
        std::ptr::read_volatile(raw.add(i)) == 0xAA
    });
    assert!(tail_persists, "Tail was wiped — not exploitable");
}
```

**Pitfalls:**
- Must check `buf[wiped_size..full_size]`, not the entire buffer — checking from 0 may hit correctly-wiped bytes and produce a false negative.
- Extract `wiped_size` and `full_size` from the finding evidence. Verify against `sizeof()` calls in the Drop impl.
- Struct padding may occupy bytes beyond the last field — be aware of layout differences with `#[repr(C)]` vs. default `#[repr(Rust)]`.

---

## Excluded Rust Categories

The following Rust finding categories remain `poc_supported=false`. Each requires techniques not yet implemented for Rust.

| Category | Reason |
|---|---|
| `OPTIMIZED_AWAY_ZEROIZE` | Requires compiling at `--release` and confirming the wipe existed at debug level; no PoC harness for opt-level switching |
| `STACK_RETENTION` | Stack probe requires unsafe inline assembly intrinsics; frame layout is not stable across Rust versions |
| `REGISTER_SPILL` | Register allocation in Rust depends on monomorphization; spill offsets from ASM analysis don't map reliably to test code |
| `NOT_ON_ALL_PATHS` | Requires driving async Future state machine through suspension; no implemented harness for Rust async |
| `MISSING_ON_ERROR_PATH` | Requires forcing `Result::Err` or `panic!` paths with domain knowledge of the error conditions |
| `NOT_DOMINATING_EXITS` | CFG dominator analysis results require source-level forcing of specific control-flow paths |
| `INSECURE_HEAP_ALLOC` | Rust's allocator trait system does not support the `malloc`-interposition approach used for C |
| `LOOP_UNROLLED_INCOMPLETE` | Requires `--release` compilation and extracting the covered-byte count from IR evidence |

## Limitations

1. **Stack probe is probabilistic:** Frame layout varies between compiler versions,
   optimization levels, and even minor source changes. A negative result does not
   prove the stack is clean — only that the probe did not find the fill pattern at
   the expected offset.

2. **Register spill offsets are compiler-specific:** The offset extracted from
   ASM evidence (e.g., `-48(%rsp)`) may differ when compiled on a different system
   or with a different compiler version.

3. **Error path triggers may need domain knowledge:** Determining what inputs cause
   a function to take its error path may require understanding the application's
   protocol or data format.

4. **Source inclusion may cause conflicts:** Including a `.c` file that defines
   `main()` or has conflicting global symbols will cause compilation errors. In
   these cases, use object-file linking instead.

5. **Single-TU compilation:** PoCs compile a single translation unit. Cross-TU
   optimizations (LTO) may produce different behavior in production builds.

6. **No dynamic analysis:** PoCs are static programs. They do not use sanitizers,
   Valgrind, or other runtime instrumentation (those are covered by Step 11's
   runtime test generation).

7. **Heap residue is allocator-dependent:** The `heap_residue_check()` helper
   relies on the allocator reusing a recently-freed chunk. This works reliably
   with glibc `malloc` but may produce false negatives with jemalloc, tcmalloc,
   or custom allocators. Do not compile with ASan (it poisons freed memory).

8. **Verification is heuristic:** The PoC verifier checks alignment between the
   PoC and the finding, but cannot prove that a PoC is correct in all cases.
   Suspicious results are flagged for user review.

# Rust Zeroization Patterns Reference

This reference documents vulnerability pattern detected by the zeroize-audit tooling for Rust code.
Each entry includes: what the flaw is, which tool detects it, severity, category, a minimal Rust snippet showing the bug, and a recommended fix.

---

## Section A — Semantic Patterns (`semantic_audit.py`, rustdoc JSON-based)

These patterns are detectable from rustdoc JSON without executing the compiler. `semantic_audit.py` processes trait impls, derives, and field types from the rustdoc index.

---

### A1 — `#[derive(Copy)]` on Sensitive Type

**Category**: `SECRET_COPY` | **Severity**: critical

**Why it's dangerous**: `Copy` types are bitwise-duplicated on every assignment, function call, and return. No `Drop` ever runs — the type cannot implement `Drop`. Every copy is a silent, untracked duplicate that will never be zeroed.

```rust
// BAD: every assignment silently duplicates the secret
#[derive(Copy, Clone)]
pub struct CopySecret {
    data: [u8; 32],
}

fn use_key(key: CopySecret) {  // <-- full copy here
    // original still on stack, unzeroed
}
```

**Fix**: Remove `Copy`. Use `Clone` explicitly where needed and ensure all clones are tracked and zeroed.

---

### A2 — No `Zeroize`, `ZeroizeOnDrop`, or `Drop`

**Category**: `MISSING_SOURCE_ZEROIZE` | **Severity**: high

**Why it's dangerous**: When the type goes out of scope, Rust calls `drop_in_place` which simply frees the memory without zeroing it. The secret bytes remain in the freed heap or on the stack until overwritten by future allocations.

```rust
// BAD: no cleanup whatsoever
pub struct UnprotectedKey {
    bytes: Vec<u8>,
}

fn example() {
    let key = UnprotectedKey { bytes: vec![0x42; 32] };
    // key drops here — heap bytes never zeroed
}
```

**Fix**: Add `#[derive(ZeroizeOnDrop)]` (with `zeroize` crate) or implement `Drop` calling `.zeroize()` on all fields.

---

### A3 — `Zeroize` Impl Without Auto-Trigger

**Category**: `MISSING_SOURCE_ZEROIZE` | **Severity**: high

**Why it's dangerous**: The `Zeroize` trait provides a `.zeroize()` method, but it requires explicit invocation. If no `Drop` or `ZeroizeOnDrop` calls it, the zeroing never happens automatically when the value goes out of scope.

```rust
use zeroize::Zeroize;

// BAD: Zeroize is implemented but never called on drop
pub struct ManualZeroizeToken {
    bytes: Vec<u8>,
}

impl Zeroize for ManualZeroizeToken {
    fn zeroize(&mut self) {
        self.bytes.zeroize();
    }
}

fn example() {
    let token = ManualZeroizeToken { bytes: vec![0x42; 32] };
    // token drops here — zeroize() is NEVER called
}
```

**Fix**: Add `#[derive(ZeroizeOnDrop)]` alongside `Zeroize`, or add an explicit `Drop` impl that calls `self.zeroize()`.

---

### A4 — `Drop` Impl Missing Secret Fields

**Category**: `PARTIAL_WIPE` | **Severity**: high

**Why it's dangerous**: The struct has multiple sensitive fields, but the `Drop` impl only zeroes some of them. The unzeroed fields remain in memory after the struct is freed.

```rust
// BAD: Drop impl zeroes `secret` but forgets `token`
pub struct ApiSecret {
    secret: Vec<u8>,
    token: Vec<u8>,  // <-- never zeroed
}

impl Drop for ApiSecret {
    fn drop(&mut self) {
        self.secret.zeroize();
        // self.token is NOT zeroed
    }
}
```

**Fix**: Ensure `Drop` calls `.zeroize()` on every sensitive field, or use `#[derive(ZeroizeOnDrop)]` to zero all fields automatically.

---

### A5 — `ZeroizeOnDrop` on Struct with Heap Fields

**Category**: `PARTIAL_WIPE` | **Severity**: medium

**Why it's dangerous**: `ZeroizeOnDrop` zeros all fields via the `Zeroize` implementation, but `Vec<T>` zeroes only `len` bytes, not the full allocated `capacity`. Excess capacity bytes remain readable until the allocator reclaims them.

```rust
use zeroize::ZeroizeOnDrop;

// BAD: ZeroizeOnDrop zeros len bytes but capacity tail is untouched
#[derive(ZeroizeOnDrop)]
pub struct SessionKey {
    data: Vec<u8>,
}

fn example() {
    let mut key = SessionKey { data: Vec::with_capacity(64) };
    key.data.extend_from_slice(&[0x42; 32]);
    // capacity[32..64] bytes never zeroed
}
```

**Fix**: Use `Zeroizing<Vec<u8>>` which uses `zeroize_and_drop` for the full buffer, or manually `self.data.zeroize(); self.data.shrink_to_fit()` in `Drop`.

---

### A6 — `ManuallyDrop<T>` Struct Field

**Category**: `MISSING_SOURCE_ZEROIZE` | **Severity**: critical

**Why it's dangerous**: `ManuallyDrop<T>` inhibits automatic drop for the wrapped value. Rust will never call `Drop` on a `ManuallyDrop<T>` field unless `ManuallyDrop::drop()` is called explicitly. If the containing struct's `Drop` impl does not explicitly drop and zero the field, the secret bytes are never wiped.

```rust
use std::mem::ManuallyDrop;

// BAD: Drop is never called on `key` field automatically
pub struct SecretHolder {
    key: ManuallyDrop<Vec<u8>>,
}

// When SecretHolder drops, `key` is NOT zeroed — bytes stay in heap
```

**Fix**: Implement `Drop` for `SecretHolder` that explicitly calls `self.key.zeroize()` (if `Vec<u8>` implements `Zeroize`) and then `unsafe { ManuallyDrop::drop(&mut self.key) }`.

---

### A7 — `#[derive(Clone)]` on Zeroizing Type

**Category**: `SECRET_COPY` | **Severity**: medium

**Why it's dangerous**: Each `clone()` call creates an independent heap allocation containing the same secret bytes. The clone must be independently zeroed. If callers pass clones to functions that don't zero them on return, the secret escapes the zeroing lifecycle.

```rust
// BAD: clone() creates an untracked duplicate that may not be zeroed
#[derive(Clone)]
pub struct CloneableKey {
    bytes: Vec<u8>,
}

impl Drop for CloneableKey {
    fn drop(&mut self) { self.bytes.zeroize(); }
}

fn bad_caller(key: &CloneableKey) {
    let copy = key.clone(); // a new heap allocation
    do_something_with(copy); // copy may not be zeroed on return from do_something_with
}
```

**Fix**: Remove `Clone` if not needed. If cloning is required, document that all clones must implement the same zeroization lifecycle.

---

### A8 — `From<T>` / `Into<T>` to Non-Zeroizing Type

**Category**: `SECRET_COPY` | **Severity**: medium

**Why it's dangerous**: A `From`/`Into` conversion transfers the secret bytes into a type that does not implement `ZeroizeOnDrop` or `Drop`. The original may be zeroed but the converted value escapes without zeroization guarantees.

```rust
type RawBytes = Vec<u8>;  // type alias — does NOT implement ZeroizeOnDrop

pub struct ApiSecret {
    secret: Vec<u8>,
    token: RawBytes,
}

// BAD: From<RawBytes> converts secret into a plain Vec with no zeroing
impl From<RawBytes> for ApiSecret {
    fn from(token: RawBytes) -> Self {
        ApiSecret { secret: vec![], token }
    }
}
// The returned ApiSecret has no Drop/Zeroize impl
```

**Fix**: Ensure the target type of `From`/`Into` also implements `ZeroizeOnDrop`, or wrap in `Zeroizing<T>`.

---

### A9 — `ptr::write_bytes` Without `compiler_fence`

**Category**: `OPTIMIZED_AWAY_ZEROIZE` | **Severity**: medium

**Why it's dangerous**: `ptr::write_bytes` is a non-volatile memory write. If the compiler determines the memory is never read afterwards (classic dead-store elimination), it may remove the write entirely. Unlike `volatile_set_memory`, there is no compiler barrier to prevent this.

```rust
use std::ptr;

pub struct WriteBytesSecret {
    data: [u8; 32],
}

fn wipe_insecure(s: &mut WriteBytesSecret) {
    // BAD: compiler may eliminate this as a dead store
    unsafe {
        ptr::write_bytes(s as *mut WriteBytesSecret, 0, 1);
    }
}
// No compiler_fence — wipe is DSE-vulnerable
```

**Fix**: Add `std::sync::atomic::compiler_fence(std::sync::atomic::Ordering::SeqCst)` after the write, or use `zeroize::Zeroize` which is DSE-resistant by design.

---

### A10 — `#[cfg(feature)]` Wrapping `Drop` or `Zeroize` Impl

**Category**: `NOT_ON_ALL_PATHS` | **Severity**: medium

**Why it's dangerous**: When the controlling feature flag is disabled, the cleanup impl is compiled out entirely. Code built without the feature silently loses all zeroization, with no compile error or warning.

```rust
pub struct CfgGuardedKey {
    secret: Vec<u8>,
}

// BAD: when feature "zeroize" is off, this impl does not exist
#[cfg(feature = "zeroize")]
impl Drop for CfgGuardedKey {
    fn drop(&mut self) {
        self.secret.zeroize();
    }
}
```

**Fix**: Make zeroization unconditional. If the `zeroize` crate is optional, gate the crate import but always zero memory manually in `Drop` using a volatile write loop as the fallback.

---

### A11 — `#[derive(Debug)]` on Sensitive Type

**Category**: `SECRET_COPY` | **Severity**: low

**Why it's dangerous**: The `Debug` trait formats all fields into a string. Any logging framework, panic handler, or `dbg!()` call will print the secret bytes in plaintext. This is a common source of credential leaks in logs.

```rust
// BAD: {key:?} or panic prints the raw bytes
#[derive(Debug)]
pub struct DebugSecret {
    secret: Vec<u8>,
}
```

**Fix**: Remove `#[derive(Debug)]`. Implement `Debug` manually to show a redacted placeholder: `write!(f, "DebugSecret([REDACTED])")`.

---

### A12 — `#[derive(Serialize)]` on Sensitive Type

**Category**: `SECRET_COPY` | **Severity**: low

**Why it's dangerous**: Serialization creates a representation of the secret in the serialization output (JSON, msgpack, etc.). If the output buffer is not itself zeroed after use, the secret bytes leak into the serialized payload.

```rust
use serde::Serialize;

// BAD: serde may write secret bytes to an uncontrolled buffer
#[derive(Serialize)]
pub struct SerializableSecret {
    secret: Vec<u8>,
}
```

**Fix**: Remove `Serialize`. If serialization is required, implement it manually to skip or encrypt sensitive fields, and ensure the output buffer is zeroed after use.

---

## Section B — Dangerous API Patterns (`find_dangerous_apis.py`, source grep-based)

These patterns are detected by scanning Rust source files for calls to APIs that prevent or bypass zeroization. Detection confidence is `"likely"` when the call appears within ±15 lines of a sensitive name, `"needs_review"` otherwise.

---

### B1 — `mem::forget(secret)`

**Category**: `MISSING_SOURCE_ZEROIZE` | **Severity**: critical

**Why it's dangerous**: `mem::forget` leaks the value without running its destructor. If the type has a `Drop` impl that calls `zeroize`, `mem::forget` bypasses it entirely. The heap allocation is leaked and never zeroed.

```rust
use std::mem;

struct SecretKey(Vec<u8>);
impl Drop for SecretKey { fn drop(&mut self) { self.0.zeroize(); } }

fn bad(key: SecretKey) {
    // BAD: Drop is never called — bytes leak forever
    mem::forget(key);
}
```

**Fix**: Never call `mem::forget` on values containing secrets. Use explicit zeroing before consuming the value if early release is needed.

---

### B2 — `ManuallyDrop::new(secret)` Call

**Category**: `MISSING_SOURCE_ZEROIZE` | **Severity**: critical

**Why it's dangerous**: Wrapping a value in `ManuallyDrop` suppresses its destructor. The secret bytes will not be zeroed when the `ManuallyDrop` wrapper is dropped unless `ManuallyDrop::drop()` is called explicitly.

```rust
use std::mem::ManuallyDrop;

struct SecretKey(Vec<u8>);
impl Drop for SecretKey { fn drop(&mut self) { self.0.zeroize(); } }

fn bad(key: SecretKey) {
    // BAD: Drop never runs for the inner SecretKey
    let _md = ManuallyDrop::new(key);
}
```

**Fix**: If `ManuallyDrop` is required for FFI or unsafe code, explicitly call `key.zeroize()` before passing into `ManuallyDrop::new`, or ensure the surrounding code calls `ManuallyDrop::drop()`.

---

### B3 — `Box::leak(secret)`

**Category**: `MISSING_SOURCE_ZEROIZE` | **Severity**: critical

**Why it's dangerous**: `Box::leak` produces a `'static` reference by preventing the `Box` from ever being dropped. The secret allocation persists for the entire program lifetime and is never zeroed.

```rust
struct SecretKey(Vec<u8>);

fn bad(key: SecretKey) -> &'static SecretKey {
    // BAD: key is never dropped or zeroed
    Box::leak(Box::new(key))
}
```

**Fix**: Avoid `Box::leak` for secrets. Use `Arc<SecretKey>` with proper `Drop` if shared ownership is needed, ensuring the last reference is dropped before program exit.

---

### B4 — `mem::uninitialized()`

**Category**: `MISSING_SOURCE_ZEROIZE` | **Severity**: critical

**Why it's dangerous**: `mem::uninitialized` returns memory with undefined contents — which in practice means prior stack or heap bytes are exposed as the return value. It is unsound (deprecated since Rust 1.39) and may expose sensitive data from prior use of that memory region.

```rust
use std::mem;

struct SecretKey([u8; 32]);

unsafe fn bad() -> SecretKey {
    // BAD: may return bytes from prior sensitive allocations
    mem::uninitialized()
}
```

**Fix**: Use `MaybeUninit<T>::zeroed().assume_init()` for zero-initialized memory, or `MaybeUninit::uninit()` only when you will fully initialize before reading.

---

### B5 — `Box::into_raw(secret)`

**Category**: `MISSING_SOURCE_ZEROIZE` | **Severity**: high

**Why it's dangerous**: `Box::into_raw` consumes the `Box` and returns a raw pointer, preventing the destructor from running. The caller is responsible for zeroing and deallocating, but this is often forgotten.

```rust
struct SecretKey(Vec<u8>);
impl Drop for SecretKey { fn drop(&mut self) { self.0.zeroize(); } }

fn bad(key: SecretKey) -> *mut SecretKey {
    // BAD: Drop is suppressed; raw pointer escapes
    Box::into_raw(Box::new(key))
}
```

**Fix**: If raw pointer access is required for FFI, zero the value before converting: call `key.zeroize()` (if applicable), then use `Box::into_raw`. Document the requirement for the caller to `Box::from_raw` and drop the value.

---

### B6 — `ptr::write_bytes` Without Volatile

**Category**: `OPTIMIZED_AWAY_ZEROIZE` | **Severity**: high

**Why it's dangerous**: `ptr::write_bytes` is a non-volatile write. The compiler's dead-store elimination pass can and will remove it if the memory is not read afterwards. Use of this function as a zeroization primitive is unreliable at optimization levels O1 and above.

```rust
use std::ptr;

struct SecretKey([u8; 32]);

fn wipe(key: &mut SecretKey) {
    // BAD: may be eliminated by DSE at -O1/-O2
    unsafe { ptr::write_bytes(key as *mut SecretKey, 0, 1); }
}
```

**Fix**: Use `zeroize::Zeroize` (which uses volatile writes internally) or add `std::sync::atomic::compiler_fence(Ordering::SeqCst)` after the write.

---

### B7 — `mem::transmute::<SensitiveType, _>`

**Category**: `SECRET_COPY` | **Severity**: high

**Why it's dangerous**: `mem::transmute` performs a bitwise copy of the value into the target type. If the target type does not implement `ZeroizeOnDrop`, the transmuted copy is a secret that will never be zeroed.

```rust
use std::mem;

struct SecretKey([u8; 32]);
impl Drop for SecretKey { fn drop(&mut self) { /* zeroize */ } }

fn bad(key: SecretKey) -> [u8; 32] {
    // BAD: bytes escape into a plain array with no zeroing
    unsafe { mem::transmute::<SecretKey, [u8; 32]>(key) }
}
```

**Fix**: Avoid transmuting sensitive types. If raw byte access is needed, use `as_ref()` or slice operations that keep the secret in a `Zeroizing<>` wrapper.

---

### B8 — `mem::take(&mut sensitive)`

**Category**: `MISSING_SOURCE_ZEROIZE` | **Severity**: medium

**Why it's dangerous**: `mem::take` replaces the target with `Default::default()`, which for `Vec<u8>` is an empty `Vec` — not a zeroed one. The taken value is returned to the caller, which may not zero it. The original location now contains the default value without evidence of the prior secret.

```rust
use std::mem;

struct SecretKey(Vec<u8>);

fn bad(key: &mut SecretKey) -> Vec<u8> {
    // BAD: original bytes copied out; neither location is zeroed
    mem::take(&mut key.0)
}
```

**Fix**: Call `self.key.zeroize()` before using `mem::take`, or use a wrapper that zeroes on `Default`. Ensure the returned value is also properly zeroed after use.

---

### B9 — `slice::from_raw_parts` Over Secret Buffer

**Category**: `SECRET_COPY` | **Severity**: medium

**Why it's dangerous**: Creating a slice alias over a secret buffer using raw pointers bypasses Rust's ownership and lifetime tracking. The resulting slice can be passed to functions that copy the bytes or retain a reference beyond the owning struct's lifetime.

```rust
struct SecretKey([u8; 32]);

fn bad(key: &SecretKey) -> &[u8] {
    // BAD: aliased reference — bytes may escape or be copied by caller
    unsafe { std::slice::from_raw_parts(key.0.as_ptr(), 32) }
}
```

**Fix**: Use safe slice references (`key.0.as_ref()` or `&key.0[..]`) which are subject to normal lifetime rules. Avoid unsafe aliasing of secret memory.

---

### B10 — `async fn` with Secret Local Across `.await`

**Category**: `NOT_ON_ALL_PATHS` | **Severity**: high

**Why it's dangerous**: Rust async functions compile to state machines. Any local variable live across an `.await` point is stored in the generated `Future` struct, which resides in heap memory. If the `Future` is cancelled (dropped mid-poll), the state machine drops without running the normal destructor sequence, leaving the secret in heap memory.

```rust
async fn bad() {
    let secret_key = SecretKey([0u8; 32]);  // stored in Future state machine
    some_async_op().await;  // secret_key is live here
    drop(secret_key);       // may never reach here if Future is cancelled
}
```

**Fix**: Zero the secret before every `.await` point: call `secret_key.zeroize()` before `.await`, or use `Zeroizing<>` wrapper (which zeroes on drop). Alternatively, place the secret in a separate non-async function scope.

---

## Section C — Compiler-Level Patterns

These patterns are **invisible to source and rustdoc analysis** but are detected by `check_mir_patterns.py`, `check_llvm_patterns.py`, and `check_rust_asm.py`. Each entry explains why source inspection is blind to it and what compiler artifact reveals the flaw.

---

### C-MIR1 — Closure Captures Sensitive Local by Value

**Tool**: `check_mir_patterns.py` | **Category**: `SECRET_COPY` | **Severity**: high

**Why source is blind**: At the source level, `let f = || use(secret)` looks identical whether `secret` is captured by reference or by move. Only MIR makes the distinction explicit: the closure struct gets a field `_captured = move _secret`.

```rust
fn bad(secret: Vec<u8>) {
    // Source looks fine — is it a move or borrow?
    let f = move || process(&secret);
    // MIR shows: closure struct receives `_captured_secret = move _secret`
    // The copy is now in the closure's heap allocation, not the original binding
    f();
    // `secret` is gone — but closure may outlive intended scope
}
```

**Detection**: MIR shows `closure_body: _captured_field = move _local` where the local matches a sensitive name pattern.

---

### C-MIR2 — Secret Live Across Generator Yield on Error Path

**Tool**: `check_mir_patterns.py` | **Category**: `NOT_ON_ALL_PATHS` | **Severity**: high

**Why source is blind**: Source analysis can find `.await` points but cannot determine which locals are live at each yield, or whether an error exit path skips a `StorageDead` for the secret. MIR encodes exact liveness: each suspend point lists live locals, and each `Err`/early-return basic block shows whether `StorageDead(_secret)` precedes the yield.

```rust
async fn bad() -> Result<(), Error> {
    let secret_key = SecretKey::new();
    let result = risky_op().await?;  // Err path: secret_key may be live at yield
    // If risky_op() returns Err, the ? operator returns early.
    // In MIR: basic block for Err path may lack StorageDead(_secret_key)
    drop(secret_key);
    Ok(result)
}
```

**Detection**: MIR Err-path basic block has no `StorageDead` for the sensitive local before the `yield`/`GeneratorDrop` terminator.

---

### C-MIR3 — `drop_in_place` for Sensitive Type Has No Zeroize Call

**Tool**: `check_mir_patterns.py` | **Category**: `MISSING_SOURCE_ZEROIZE` | **Severity**: medium

**Why source is blind**: When `Drop` is implemented in a separate crate or via blanket impl, source analysis cannot read the drop body. MIR drop-glue functions are generated per-type and show every call inside the drop sequence.

```rust
// The Drop impl may be in an external crate:
impl Drop for ThirdPartySecret {
    fn drop(&mut self) {
        // Does this call zeroize? Source analysis cannot verify.
        self.inner.clear(); // <-- NOT zeroize — MIR reveals no zeroize call
    }
}
```

**Detection**: MIR function `drop_in_place::<SensitiveType>` contains no call to `zeroize`, `volatile_set_memory`, or `memset`.

---

### C-IR1 — DSE Eliminates Correct `zeroize()` Call

**Tool**: `check_llvm_patterns.py` | **Category**: `OPTIMIZED_AWAY_ZEROIZE` | **Severity**: high

**Why source is blind**: The source correctly calls `.zeroize()`. The bug exists only in the optimized IR: LLVM's dead-store elimination pass removes the volatile stores as "dead" before the function returns. Source shows a correct call; IR at O2 shows zero volatile stores.

```rust
fn wipe(key: &mut SecretKey) {
    self.key.zeroize();  // Source looks correct!
    // At O0: 32 volatile stores in IR
    // At O2: 0 volatile stores — DSE eliminated them as "dead before return"
}
```

**Detection**: `volatile store` count drops from N (O0) to 0 (O2) targeting the same buffer.

---

### C-IR2 — Non-Volatile `llvm.memset` on Secret-Sized Range

**Tool**: `check_llvm_patterns.py` | **Category**: `OPTIMIZED_AWAY_ZEROIZE` | **Severity**: high

**Why source is blind**: A `memset` call looks correct in source. IR reveals whether the `llvm.memset` intrinsic has the `volatile` flag set. Without it, LLVM is free to remove the call as a dead store.

```c
// Source: memset(secret, 0, 32); — looks fine
// IR at O0: call void @llvm.memset.p0.i64(ptr %secret, i8 0, i64 32, i1 false)
//                                                                        ^^^^^
//                                                                 volatile=false — removable!
```

**Detection**: `llvm.memset` intrinsic on a buffer matching a sensitive size (16/32/64 bytes) with `volatile=false` flag.

---

### C-IR3 — Secret `alloca` Has `lifetime.end` Without Prior Volatile Store

**Tool**: `check_llvm_patterns.py` | **Category**: `STACK_RETENTION` | **Severity**: high

**Why source is blind**: The local simply goes out of scope in source. IR shows the stack slot's lifetime: if `@llvm.lifetime.end` is reached without any preceding `store volatile`, the slot is released with secret bytes intact.

```rust
fn bad() {
    let mut key = [0u8; 32];
    fill_key(&mut key);
    // key goes out of scope — source shows nothing
    // IR: llvm.lifetime.end(32, %key) with no volatile store before it
    // Stack bytes remain until overwritten
}
```

**Detection**: `@llvm.lifetime.end` on a sensitive `alloca` with no `store volatile` in the dominating path.

---

### C-IR4 — Secret `alloca` Promoted to Registers by SROA/mem2reg

**Tool**: `check_llvm_patterns.py` | **Category**: `OPTIMIZED_AWAY_ZEROIZE` | **Severity**: high

**Why source is blind**: The `alloca` disappears entirely at O2 — LLVM's SROA and mem2reg passes promote it to SSA registers. Any volatile stores targeting that `alloca` are also removed since the `alloca` no longer exists.

```rust
fn bad() {
    let mut key = SecretKey::new();
    // O0 IR: %key = alloca [32 x i8] + volatile stores on drop
    // O2 IR: %key promoted to SSA registers — no alloca, no volatile stores
    use_key(&key);
    // Drop: no volatile stores remain
}
```

**Detection**: `alloca` present at O0 with volatile stores disappears entirely at O2.

---

### C-IR5 — Secret Value in Argument Registers at Call Site

**Tool**: `check_llvm_patterns.py` | **Category**: `REGISTER_SPILL` | **Severity**: medium

**Why source is blind**: Source shows a function call with a sensitive argument. IR shows the calling convention: the value is loaded from memory into argument registers (`%rdi`, `%rsi`, …) before the `call` instruction. The callee may spill those registers to its own stack frame without zeroing them.

```rust
fn bad(key: &SecretKey) {
    callee(key.data);  // Source: pass by value
    // IR: %key_val = load i256, ptr %key; call @callee(i256 %key_val)
    // Callee may spill %rdi/%rsi to its stack frame
}
```

**Detection**: IR shows sensitive `alloca` loaded into argument registers immediately before a `call` instruction.

---

### C-ASM1 — Stack Frame Allocated, No Zero-Stores Before `ret`

**Tool**: `check_rust_asm.py` | **Category**: `STACK_RETENTION` | **Severity**: high

**Why source is blind**: Source shows the function body with no evidence of stack frame contents. Assembly reveals the frame size and whether any zero-store instructions (`movq $0, [rsp+N]` / `str xzr, [sp, #N]`) appear before the `retq`/`ret` instruction.

```asm
; x86-64 example — no zero stores before retq
SecretKey_process:
    subq $64, %rsp      ; allocates 64-byte frame (possibly holds secret)
    ; ... use frame ...
    retq                ; returns without zeroing frame
```

**Detection**: Function with sensitive name allocates stack frame and returns without any zero-store instructions targeting the frame slots.

---

### C-ASM2 — Callee-Saved Register Spilled in Sensitive Function

**Tool**: `check_rust_asm.py` | **Category**: `REGISTER_SPILL` | **Severity**: high

**Why source is blind**: Register allocation decisions are invisible in source or IR. Assembly shows the spill instructions: `movq %r12, [rsp+N]` (x86-64) or `str x19, [sp, #N]` (AArch64). Callee-saved registers (`%r12`–`%r15`/`rbx` on x86-64; `x19`–`x28` on AArch64) are preserved across calls — if they held secret values, the spill creates an unzeroed copy.

```asm
; AArch64 example — x19 (callee-saved) spilled
SecretKey_wipe:
    str x19, [sp, #-16]!   ; spill x19 — may hold secret bytes
    ; ... wipe logic ...
    ldr x19, [sp], #16     ; restore — but spill slot not zeroed
    ret
```

**Detection**: Callee-saved register spill instruction inside a function matching a sensitive name pattern.

---

### C-ASM3 — Caller-Saved Register Spilled in Sensitive Function

**Tool**: `check_rust_asm.py` | **Category**: `REGISTER_SPILL` | **Severity**: medium

**Why source is blind**: Same as C-ASM2 but for caller-saved registers (`%rax`, `%rcx`, etc. / `x0`–`x17` on AArch64). These are not preserved by callees, so the current function is responsible for any secret bytes spilled to the stack.

**Detection**: Caller-saved register spill instruction inside a sensitive function body.

---

### C-ASM4 — `drop_in_place` in Assembly Has No Zeroize/Memset Call

**Tool**: `check_rust_asm.py` | **Category**: `MISSING_SOURCE_ZEROIZE` | **Severity**: medium

**Why source is blind**: Corroborates the MIR-level finding (C-MIR3) with concrete machine code. The emitted assembly for `drop_in_place::<SensitiveType>` contains no `call` to a zeroing function — confirming that the missing zeroize is not merely a MIR-level artifact but reaches the final binary.

**Detection**: `drop_in_place::<SensitiveName>` assembly function contains no `call @zeroize`, `call @volatile_set_memory`, or `call @memset`.

---

## Section D — Undetectable Patterns (TODO)

These patterns are **not detected by any current tool** (`semantic_audit.py`, `find_dangerous_apis.py`, `check_mir_patterns.py`, `check_llvm_patterns.py`, `check_rust_asm.py`). Each entry explains why all current approaches are insufficient and what new capability would be required.

---

### D1 — `Arc<SensitiveType>` / `Rc<SensitiveType>` Deferred Drop

**Category**: `NOT_ON_ALL_PATHS` | **Gap type**: inter-procedural alias/ownership analysis

**Why it's dangerous**: `Drop`/`ZeroizeOnDrop` only runs when the *last* reference is dropped. Any clone of an `Arc<SecretKey>` holds the bytes alive and unzeroed until the reference count reaches zero. If an Arc clone escapes a security boundary (e.g., is passed to a background task), the secret persists until that task completes.

```rust
use std::sync::Arc;

let key = Arc::new(SecretKey::new());  // ZeroizeOnDrop
let clone = Arc::clone(&key);         // reference count = 2
pass_to_background_task(clone);       // may live arbitrarily long
drop(key);                            // count = 1, NOT dropped here
// secret stays in heap until background task finishes
```

**Why undetectable**: `semantic_audit.py` only inspects struct definitions, not call sites. `find_dangerous_apis.py` has no `Arc::clone` pattern — adding one would produce massive false positives without knowing the wrapped type. MIR/IR/ASM tools can detect the drop-glue but cannot statically verify that all Arc clones are dropped before a given boundary.

**Requires**: Inter-procedural ownership/alias tracking (e.g., Polonius dataflow or a custom MIR analysis that tracks Arc reference count propagation across function boundaries).

---

### D2 — `#[repr(C)]` Struct Padding Bytes Not Zeroed

**Category**: `PARTIAL_WIPE` | **Gap type**: struct layout analysis

**Why it's dangerous**: `zeroize()` on a `#[repr(C)]` struct zeros all *declared* fields, but the Rust compiler may insert alignment padding between or after fields. `Zeroize` does not touch padding bytes. An attacker with heap inspection capabilities may recover the secret from pad regions.

```rust
#[repr(C)]
struct MixedSecret {
    flag: u8,      // 1 byte
    // 7 bytes padding here (for alignment of `key`)
    key: [u8; 32],
}
// zeroize() zeros flag and key but NOT the 7 padding bytes
```

**Why undetectable**: `check_rust_asm.py` fires `STACK_RETENTION` only if NO zeroing occurs — it does not detect partial zeroing that skips padding. `check_llvm_patterns.py` counts volatile stores but does not compare bytes-zeroed vs. total struct size.

**Requires**: Struct layout analysis via `rustc -Z print-type-sizes` combined with IR analysis comparing zeroed byte ranges against total struct size.

---

### D3 — `static` / `LazyLock<SensitiveType>` Secret Never Dropped

**Category**: `MISSING_SOURCE_ZEROIZE` | **Gap type**: static item analysis

**Why it's dangerous**: Rust does not call `Drop` on `static` variables at program exit. A `static KEY: LazyLock<ApiKey>` or `static mut SEED: [u8; 32]` is never zeroed, regardless of any `ZeroizeOnDrop` impl.

```rust
use std::sync::LazyLock;

static GLOBAL_KEY: LazyLock<ApiKey> = LazyLock::new(|| ApiKey::generate());
// Drop is never called at program exit — bytes remain in memory until OS reclaim
```

**Why undetectable**: `semantic_audit.py` only processes `kind = "struct"` and `"enum"` items — `kind = "static"` items are silently skipped. `find_dangerous_apis.py` has no `static` binding pattern. Compiler-level tools do not produce zeroing evidence for globals in `.data`/`.bss` sections.

**Requires**: Extend `semantic_audit.py` to process `"static"` kind items from rustdoc JSON, or add a grep in `find_dangerous_apis.py` for `static .* SensitiveName`.

---

### D4 — `async fn` Future Cancellation: State-Machine `Drop` Lacks `ZeroizeOnDrop`

**Category**: `NOT_ON_ALL_PATHS` | **Gap type**: coroutine MIR analysis

**Why it's dangerous**: `find_dangerous_apis.py` and `check_mir_patterns.py` detect secret locals live across `.await` / yield points. The remaining gap is *cancellation safety*: when a `Future` is dropped mid-poll (e.g., by `tokio::select!` dropping the losing branch), any secrets stored in the compiler-generated state-machine struct are freed without zeroing. The generated struct type is anonymous — not written in source.

```rust
async fn process_secret() {
    let key = SecretKey::new();     // stored in coroutine state machine
    phase_one().await;              // suspension point
    phase_two().await;              // another suspension point
    drop(key);
}

// If the Future is cancelled at phase_one().await:
//   - The coroutine struct is dropped
//   - The compiler-generated Drop for the coroutine does NOT zero `key`
//   - Unless the coroutine struct's Drop impl explicitly zeroes captured fields
```

**Why undetectable**: The compiler-generated coroutine struct type is not in the rustdoc index. Its `Drop` impl is generated drop-glue, not user code. `check_mir_patterns.py` detects secrets live at yield points but does not verify that the *coroutine struct's generated Drop glue* calls `zeroize` on each captured field.

**Requires**: `check_mir_patterns.py` extension to identify coroutine/generator MIR bodies, enumerate their captured locals matching sensitive name patterns, and verify presence of `zeroize` calls in the generated Drop glue for the coroutine state machine type.

---

### D5 — `Cow<'_, [u8]>` or `Cow<'_, str>` Silently Cloning a Secret

**Category**: `SECRET_COPY` | **Gap type**: type-taint tracking

**Why it's dangerous**: `Cow::to_owned()`, `Cow::into_owned()`, and `Cow::Owned(...)` allocate an owned copy of the bytes with no tracking. The clone does not inherit any `ZeroizeOnDrop` guarantee. Since `Cow` can hold a reference or an owned value, and conversion between the two is implicit, secrets can be silently promoted to owned allocations.

```rust
use std::borrow::Cow;

fn process(data: Cow<'_, [u8]>) {
    let owned: Vec<u8> = data.into_owned(); // secret bytes in plain Vec
    // owned has no ZeroizeOnDrop — never zeroed
}
```

**Why undetectable**: A source grep on `Cow` alone has unacceptably high false-positive rate without knowing whether the held type is sensitive. `find_dangerous_apis.py` cannot distinguish `Cow<'_, [u8]>` holding secrets from `Cow<'_, str>` holding log messages. MIR/IR would show the allocation but correlation back to "this Cow holds sensitive data" requires type-level taint tracking that current regex-based tools do not perform.

**Requires**: Inter-procedural type taint analysis to track whether the `Cow` inner type originates from a sensitive allocation.

---

### D6 — `mem::swap` Moving Secret Bytes to Non-Zeroizing Location

**Category**: `SECRET_COPY` | **Gap type**: type-aware MIR operand analysis

**Why it's dangerous**: `mem::swap(&mut secret_key, &mut output_buf)` moves the secret bytes bitwise into `output_buf`, which likely does not implement `ZeroizeOnDrop`. The original location is overwritten with `output_buf`'s prior content. The secret now lives in `output_buf` with no zeroing guarantee, while the original location no longer contains the secret (so its Drop impl zeroes the wrong data).

```rust
fn bad(key: &mut SecretKey, output: &mut Vec<u8>) {
    // BAD: key bytes moved into output (plain Vec, no ZeroizeOnDrop)
    unsafe {
        let key_bytes: &mut Vec<u8> = std::mem::transmute(key);
        std::mem::swap(key_bytes, output);
    }
    // key is now "empty" — key.drop() zeroes nothing meaningful
    // output holds the secret bytes with no zeroing guarantee
}
```

**Why undetectable**: `find_dangerous_apis.py` has no `mem::swap` pattern; adding one without type awareness would flag every `swap` call in the codebase. In MIR, `mem::swap` is represented as a pair of assignments — detectable if the checker verifies the types of both operands, but this is not currently implemented.

**Requires**: Type-aware MIR analysis of swap operands to detect when a sensitive type is swapped into a non-zeroizing container.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "zeroize-audit input",
  "type": "object",
  "properties": {
    "path": { "type": "string", "description": "Repository root path" },
    "compile_db": { "type": ["string", "null"], "default": null, "description": "Path to compile_commands.json for C/C++ analysis. Required if cargo_manifest is not set." },
    "cargo_manifest": { "type": ["string", "null"], "default": null, "description": "Path to Cargo.toml for Rust crate analysis. Required if compile_db is not set." },
    "config": { "type": ["string", "null"], "description": "Path to config YAML" },
    "opt_levels": {
      "type": "array",
      "items": { "type": "string", "enum": ["O0", "O1", "O2", "O3", "Os", "Oz"] },
      "default": ["O0", "O1", "O2"]
    },
    "languages": {
      "type": "array",
      "items": { "type": "string", "enum": ["c", "cpp", "rust"] },
      "default": ["c", "cpp", "rust"]
    },
    "max_tus": { "type": "integer", "minimum": 1, "default": 50 },
    "enable_semantic_ir": { "type": "boolean", "default": false, "description": "Enable semantic LLVM IR analysis" },
    "enable_cfg": { "type": "boolean", "default": false, "description": "Enable control-flow graph analysis" },
    "enable_runtime_tests": { "type": "boolean", "default": false, "description": "Enable runtime PoC test generation and execution" },
    "enable_asm": { "type": "boolean", "default": true, "description": "Enable assembly emission and analysis" },
    "mcp_mode": {
      "type": "string",
      "enum": ["off", "prefer", "require"],
      "default": "prefer",
      "description": "Control MCP semantic analysis usage"
    },
    "mcp_required_for_advanced": {
      "type": "boolean",
      "default": true,
      "description": "Downgrade advanced findings when MCP semantic evidence is unavailable"
    },
    "mcp_timeout_ms": {
      "type": "integer",
      "minimum": 100,
      "default": 10000,
      "description": "Timeout budget for MCP semantic queries"
    },
    "poc_categories": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "MISSING_SOURCE_ZEROIZE",
          "PARTIAL_WIPE",
          "NOT_ON_ALL_PATHS",
          "OPTIMIZED_AWAY_ZEROIZE",
          "STACK_RETENTION",
          "REGISTER_SPILL",
          "SECRET_COPY",
          "INSECURE_HEAP_ALLOC",
          "MISSING_ON_ERROR_PATH",
          "NOT_DOMINATING_EXITS",
          "LOOP_UNROLLED_INCOMPLETE"
        ]
      },
      "default": [
        "MISSING_SOURCE_ZEROIZE",
        "PARTIAL_WIPE",
        "NOT_ON_ALL_PATHS",
        "OPTIMIZED_AWAY_ZEROIZE",
        "STACK_RETENTION",
        "REGISTER_SPILL",
        "SECRET_COPY",
        "INSECURE_HEAP_ALLOC",
        "MISSING_ON_ERROR_PATH",
        "NOT_DOMINATING_EXITS",
        "LOOP_UNROLLED_INCOMPLETE"
      ],
      "description": "Finding categories for which to generate PoCs"
    },
    "poc_output_dir": {
      "type": ["string", "null"],
      "default": null,
      "description": "Output directory for generated PoCs (default: generated_pocs/)"
    }
  },
  "required": ["path"],
  "additionalProperties": false
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "zeroize-audit output",
  "type": "object",
  "properties": {
    "tool": { "type": "string", "const": "zeroize-audit" },
    "version": { "type": "string" },
    "summary": {
      "type": "object",
      "properties": {
        "path": { "type": "string" },
        "files_scanned": { "type": "integer", "minimum": 0 },
        "translation_units_analyzed": { "type": "integer", "minimum": 0 },
        "issues_found": { "type": "integer", "minimum": 0 },
        "by_category": {
          "type": "object",
          "properties": {
            "MISSING_SOURCE_ZEROIZE": { "type": "integer", "minimum": 0 },
            "OPTIMIZED_AWAY_ZEROIZE": { "type": "integer", "minimum": 0 },
            "PARTIAL_WIPE": { "type": "integer", "minimum": 0 },
            "NOT_ON_ALL_PATHS": { "type": "integer", "minimum": 0 },
            "STACK_RETENTION": { "type": "integer", "minimum": 0 },
            "REGISTER_SPILL": { "type": "integer", "minimum": 0 },
            "SECRET_COPY": { "type": "integer", "minimum": 0 },
            "INSECURE_HEAP_ALLOC": { "type": "integer", "minimum": 0 },
            "MISSING_ON_ERROR_PATH": { "type": "integer", "minimum": 0 },
            "LOOP_UNROLLED_INCOMPLETE": { "type": "integer", "minimum": 0 },
            "NOT_DOMINATING_EXITS": { "type": "integer", "minimum": 0 }
          },
          "required": [
            "MISSING_SOURCE_ZEROIZE",
            "OPTIMIZED_AWAY_ZEROIZE",
            "PARTIAL_WIPE",
            "NOT_ON_ALL_PATHS",
            "STACK_RETENTION",
            "REGISTER_SPILL",
            "SECRET_COPY",
            "INSECURE_HEAP_ALLOC",
            "MISSING_ON_ERROR_PATH",
            "LOOP_UNROLLED_INCOMPLETE",
            "NOT_DOMINATING_EXITS"
          ],
          "additionalProperties": false
        },
        "poc_generation": {
          "type": "object",
          "properties": {
            "pocs_generated": { "type": "integer", "minimum": 0 },
            "pocs_requiring_adjustment": { "type": "integer", "minimum": 0 },
            "output_dir": { "type": "string" },
            "categories_covered": { "type": "array", "items": { "type": "string" } }
          }
        },
        "poc_validation_summary": {
          "type": "object",
          "properties": {
            "total_findings": { "type": "integer", "minimum": 0 },
            "pocs_generated": { "type": "integer", "minimum": 0 },
            "pocs_validated": { "type": "integer", "minimum": 0 },
            "exploitable_confirmed": { "type": "integer", "minimum": 0 },
            "not_exploitable": { "type": "integer", "minimum": 0 },
            "compile_failures": { "type": "integer", "minimum": 0 },
            "no_poc_generated": { "type": "integer", "minimum": 0 }
          },
          "required": ["total_findings", "pocs_generated", "pocs_validated", "exploitable_confirmed", "not_exploitable", "compile_failures", "no_poc_generated"],
          "additionalProperties": false
        }
      },
      "required": ["path", "files_scanned", "translation_units_analyzed", "issues_found", "by_category", "poc_validation_summary"],
      "additionalProperties": false
    },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "category": {
            "type": "string",
            "enum": [
              "MISSING_SOURCE_ZEROIZE",
              "OPTIMIZED_AWAY_ZEROIZE",
              "PARTIAL_WIPE",
              "NOT_ON_ALL_PATHS",
              "STACK_RETENTION",
              "REGISTER_SPILL",
              "SECRET_COPY",
              "INSECURE_HEAP_ALLOC",
              "MISSING_ON_ERROR_PATH",
              "LOOP_UNROLLED_INCOMPLETE",
              "NOT_DOMINATING_EXITS"
            ]
          },
          "severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
          "confidence": { "type": "string", "enum": ["confirmed", "likely", "needs_review"] },
          "language": { "type": "string", "enum": ["c", "cpp", "rust", "unknown"] },
          "file": { "type": "string" },
          "line": { "type": "integer", "minimum": 1 },
          "symbol": { "type": ["string", "null"] },
          "evidence": { "type": "string" },
          "compiler_evidence": {
            "type": ["object", "null"],
            "properties": {
              "opt_levels": { "type": "array", "items": { "type": "string" } },
              "o0": { "type": ["string", "null"] },
              "o1": { "type": ["string", "null"] },
              "o2": { "type": ["string", "null"] },
              "o3": { "type": ["string", "null"] },
              "diff_summary": { "type": ["string", "null"] }
            },
            "required": ["opt_levels"],
            "additionalProperties": false
          },
          "suggested_fix": { "type": "string" },
          "poc": {
            "type": "object",
            "properties": {
              "file": { "type": "string" },
              "makefile_target": { "type": "string" },
              "compile_opt": { "type": "string" },
              "requires_manual_adjustment": { "type": "boolean" },
              "adjustment_notes": { "type": ["string", "null"] },
              "exit_code": { "type": ["integer", "null"] },
              "validated": { "type": "boolean" },
              "validation_result": {
                "type": "string",
                "enum": ["exploitable", "not_exploitable", "compile_failure", "no_poc", "pending"]
              }
            },
            "required": ["file", "makefile_target", "compile_opt", "requires_manual_adjustment", "validated", "validation_result"]
          }
        },
        "required": ["id", "category", "severity", "confidence", "language", "file", "line", "evidence", "suggested_fix", "poc"],
        "additionalProperties": false
      }
    }
  },
  "required": ["tool", "version", "summary", "findings"],
  "additionalProperties": false
}

#!/usr/bin/env bash
set -euo pipefail

# Analyze assembly for secret exposure patterns.
#
# Usage:
#   analyze_asm.sh --asm path/to/file.s --symbol secret_func --out /tmp/analysis.json
#
# Detects:
# - Register spills to stack (movq/movdqa %reg, -offset(%rbp/%rsp))
# - Stack allocations that may retain secrets
# - Missing red-zone clearing
# - Secrets in callee-saved registers pushed to stack

usage() {
  echo "Usage: $0 --asm <file.s> --out <analysis.json> [--symbol <func_name>]" >&2
}

json_escape() {
  local s="$1"
  s="${s//\\/\\\\}"
  s="${s//\"/\\\"}"
  s="${s//$'\n'/\\n}"
  s="${s//$'\t'/\\t}"
  printf '%s' "$s"
}

ASM=""
SYMBOL=""
OUT=""

while [[ $# -gt 0 ]]; do
  case "$1" in
    --asm)
      ASM="$2"
      shift 2
      ;;
    --symbol)
      SYMBOL="$2"
      shift 2
      ;;
    --out)
      OUT="$2"
      shift 2
      ;;
    *)
      echo "Unknown arg: $1" >&2
      usage
      exit 2
      ;;
  esac
done

if [[ -z "$ASM" || -z "$OUT" ]]; then
  usage
  exit 2
fi

if [[ ! -f "$ASM" ]]; then
  echo "Assembly file not found: $ASM" >&2
  exit 2
fi

# Extract function boundaries if symbol specified
START_LINE=1
END_LINE=$(wc -l <"$ASM")

if [[ -n "$SYMBOL" ]]; then
  # Find function start/end
  START_LINE=$(grep -n "^${SYMBOL}:" "$ASM" | head -1 | cut -d: -f1 || echo "")
  if [[ -z "$START_LINE" ]]; then
    echo "WARNING: symbol '${SYMBOL}' not found in $ASM; analyzing full file" >&2
    START_LINE=1
  fi
  # Find next function or end of file
  END_LINE=$(tail -n +"$((START_LINE + 1))" "$ASM" | grep -n "^[a-zA-Z_][a-zA-Z0-9_]*:" | head -1 | cut -d: -f1 || echo "$(($(wc -l <"$ASM") - START_LINE + 1))")
  END_LINE=$((START_LINE + END_LINE - 1))
fi

# Extract function body
FUNC_ASM=$(sed -n "${START_LINE},${END_LINE}p" "$ASM")

# Detect patterns
REGISTER_SPILLS=()
STACK_STORES=()
CALLEE_SAVED_PUSHES=()
STACK_SIZE=0
RED_ZONE_CLEARED=false

# Parse assembly
while IFS= read -r line; do
  # Skip comments and empty lines
  [[ "$line" =~ ^[[:space:]]*# ]] && continue
  [[ -z "${line// /}" ]] && continue

  # Detect stack allocation (subq $size, %rsp)
  if [[ "$line" =~ subq[[:space:]]+\$([0-9]+),[[:space:]]*%rsp ]]; then
    STACK_SIZE="${BASH_REMATCH[1]}"
  fi

  # Detect register spills to stack (movq/movdqa/movaps %reg, -offset(%rsp/%rbp))
  if [[ "$line" =~ (movq|movdqa|movaps|movups|vmovdqa|vmovaps)[[:space:]]+%([a-z0-9]+),[[:space:]]*-([0-9]+)\(%(rsp|rbp)\) ]]; then
    REG="${BASH_REMATCH[2]}"
    OFFSET="${BASH_REMATCH[3]}"
    BASE="${BASH_REMATCH[4]}"
    REGISTER_SPILLS+=("{\"register\": \"$REG\", \"offset\": -$OFFSET, \"base\": \"$BASE\", \"line\": \"$(json_escape "$line")\"}")
  fi

  # Detect stores to stack (mov* reg/imm, -offset(%rsp/%rbp))
  if [[ "$line" =~ mov[a-z]*[[:space:]]+[^,]+,[[:space:]]*-([0-9]+)\(%(rsp|rbp)\) ]]; then
    OFFSET="${BASH_REMATCH[1]}"
    BASE="${BASH_REMATCH[2]}"
    STACK_STORES+=("{\"offset\": -$OFFSET, \"base\": \"$BASE\", \"line\": \"$(json_escape "$line")\"}")
  fi

  # Detect callee-saved register pushes (pushq %rbx/%r12/%r13/%r14/%r15/%rbp)
  if [[ "$line" =~ pushq[[:space:]]+%(rbx|r12|r13|r14|r15|rbp) ]]; then
    REG="${BASH_REMATCH[1]}"
    CALLEE_SAVED_PUSHES+=("{\"register\": \"$REG\", \"line\": \"$(json_escape "$line")\"}")
  fi

  # Detect red-zone clearing (movq $0, -offset(%rsp) for offset <= 128)
  if [[ "$line" =~ movq[[:space:]]+\$0,[[:space:]]*-([0-9]+)\(%rsp\) ]]; then
    OFFSET="${BASH_REMATCH[1]}"
    if [[ "$OFFSET" -le 128 ]]; then
      RED_ZONE_CLEARED=true
    fi
  fi

done <<<"$FUNC_ASM"

# Generate JSON report
mkdir -p "$(dirname "$OUT")"

cat >"$OUT" <<EOF
{
  "asm_file": "$ASM",
  "symbol": "$SYMBOL",
  "analysis": {
    "stack_size": $STACK_SIZE,
    "red_zone_cleared": $RED_ZONE_CLEARED,
    "register_spills": [
      $(
  IFS=,
  echo "${REGISTER_SPILLS[*]}"
)
    ],
    "stack_stores": [
      $(
  IFS=,
  echo "${STACK_STORES[*]}"
)
    ],
    "callee_saved_pushes": [
      $(
  IFS=,
  echo "${CALLEE_SAVED_PUSHES[*]}"
)
    ]
  },
  "warnings": []
}
EOF

# Validate JSON output
if command -v jq &>/dev/null; then
  if ! jq empty "$OUT" 2>/dev/null; then
    echo "ERROR: generated JSON is malformed: $OUT" >&2
    exit 1
  fi
fi

# Add warnings based on findings
WARNINGS=()

if [[ ${#REGISTER_SPILLS[@]} -gt 0 ]]; then
  WARNINGS+=("{\"type\": \"REGISTER_SPILL\", \"message\": \"Found ${#REGISTER_SPILLS[@]} register spill(s) to stack. Spilled values may contain secrets.\"}")
fi

if [[ $STACK_SIZE -gt 0 ]] && [[ "$RED_ZONE_CLEARED" == "false" ]]; then
  WARNINGS+=("{\"type\": \"STACK_RETENTION\", \"message\": \"Stack frame (${STACK_SIZE} bytes) may retain secrets after function return. Consider clearing red-zone.\"}")
fi

if [[ ${#CALLEE_SAVED_PUSHES[@]} -gt 0 ]]; then
  WARNINGS+=("{\"type\": \"CALLEE_SAVED_SPILL\", \"message\": \"Callee-saved registers pushed to stack. If they contain secrets, stack will retain them.\"}")
fi

# Update JSON with warnings
if [[ ${#WARNINGS[@]} -gt 0 ]]; then
  WARNINGS_JSON=$(
    IFS=,
    echo "${WARNINGS[*]}"
  )
  if command -v jq &>/dev/null; then
    TMP=$(mktemp)
    jq ".warnings = [$WARNINGS_JSON]" "$OUT" >"$TMP" && mv "$TMP" "$OUT"
  else
    echo "WARNING: jq not found; warnings could not be added to output" >&2
  fi
fi

echo "OK: assembly analysis written to $OUT"

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
Control-Flow Graph analyzer for zeroization path coverage.

This tool builds CFGs from source code or LLVM IR to verify that:
- Zeroization occurs on ALL execution paths
- Early returns don't skip cleanup
- Error paths include proper cleanup
- Wipes dominate all function exits
"""

import argparse
import json
import re
import sys
from dataclasses import dataclass, field
from pathlib import Path


@dataclass
class CFGNode:
    """Node in control flow graph."""

    id: str
    type: str  # 'entry', 'exit', 'statement', 'branch', 'return'
    line_num: int | None = None
    statement: str | None = None
    successors: list[str] = field(default_factory=list)
    predecessors: list[str] = field(default_factory=list)
    has_wipe: bool = False
    has_sensitive_var: bool = False


class CFGBuilder:
    """Build control flow graph from source or IR."""

    def __init__(self, source_file: Path, sensitive_patterns: list[str], wipe_patterns: list[str]):
        self.source_file = source_file
        self.sensitive_patterns = sensitive_patterns
        self.wipe_patterns = wipe_patterns
        self.nodes: dict[str, CFGNode] = {}
        self.entry_node: str | None = None
        self.exit_nodes: set[str] = set()
        self.node_counter = 0

    def create_node(
        self, node_type: str, line_num: int | None = None, statement: str | None = None
    ) -> str:
        """Create a new CFG node."""
        node_id = f"node_{self.node_counter}"
        self.node_counter += 1

        node = CFGNode(id=node_id, type=node_type, line_num=line_num, statement=statement)

        # Check if this node has sensitive variable
        if statement:
            for pattern in self.sensitive_patterns:
                if re.search(pattern, statement, re.IGNORECASE):
                    node.has_sensitive_var = True
                    break

            # Check if this node has wipe
            for pattern in self.wipe_patterns:
                if re.search(pattern, statement):
                    node.has_wipe = True
                    break

        self.nodes[node_id] = node
        return node_id

    def add_edge(self, from_id: str, to_id: str) -> None:
        """Add directed edge in CFG."""
        if from_id in self.nodes and to_id in self.nodes:
            self.nodes[from_id].successors.append(to_id)
            self.nodes[to_id].predecessors.append(from_id)

    def build_from_source(self) -> None:
        """Build CFG from source code (simplified C/C++ parser)."""
        with open(self.source_file) as f:
            lines = f.readlines()

        self.entry_node = self.create_node("entry")
        current_node = self.entry_node

        in_function = False
        brace_depth = 0
        branch_stack = []  # Stack of (condition_node, merge_node) pairs

        for line_num, line in enumerate(lines, 1):
            stripped = line.strip()

            # Skip comments and empty lines
            if not stripped or stripped.startswith("//") or stripped.startswith("/*"):
                continue

            # Function start
            if "{" in line and not in_function:
                in_function = True
                brace_depth = line.count("{")
                continue

            if not in_function:
                continue

            # Track brace depth
            brace_depth += line.count("{") - line.count("}")

            # Function end
            if brace_depth == 0:
                in_function = False
                # Connect to exit
                exit_node = self.create_node("exit", line_num)
                self.add_edge(current_node, exit_node)
                self.exit_nodes.add(exit_node)
                continue

            # Return statement
            if re.match(r"\s*return\b", stripped):
                return_node = self.create_node("return", line_num, stripped)
                self.add_edge(current_node, return_node)
                exit_node = self.create_node("exit", line_num)
                self.add_edge(return_node, exit_node)
                self.exit_nodes.add(exit_node)
                # Reset current for next statement (in case there's dead code)
                current_node = return_node
                continue

            # If statement
            if re.match(r"\s*if\s*\(", stripped):
                branch_node = self.create_node("branch", line_num, stripped)
                self.add_edge(current_node, branch_node)

                # Create merge point for later
                merge_node = self.create_node("statement", line_num, "// merge point")
                branch_stack.append((branch_node, merge_node))

                # True branch starts after condition
                true_node = self.create_node("statement", line_num, "// true branch")
                self.add_edge(branch_node, true_node)
                current_node = true_node
                continue

            # Else statement
            if re.match(r"\s*else\b", stripped):
                if branch_stack:
                    branch_node, merge_node = branch_stack[-1]
                    # False branch
                    false_node = self.create_node("statement", line_num, "// false branch")
                    self.add_edge(branch_node, false_node)
                    # Connect previous path to merge
                    self.add_edge(current_node, merge_node)
                    current_node = false_node
                continue

            # End of branch (closing brace)
            if stripped == "}" and branch_stack:
                branch_node, merge_node = branch_stack.pop()
                self.add_edge(current_node, merge_node)
                current_node = merge_node
                continue

            # Regular statement
            stmt_node = self.create_node("statement", line_num, stripped)
            self.add_edge(current_node, stmt_node)
            current_node = stmt_node

        # Ensure we have at least one exit node
        if not self.exit_nodes:
            exit_node = self.create_node("exit")
            self.add_edge(current_node, exit_node)
            self.exit_nodes.add(exit_node)

    def find_all_paths_to_exit(self) -> list[list[str]]:
        """Find all paths from entry to any exit node."""
        if not self.entry_node:
            return []

        all_paths = []

        def dfs(node_id: str, path: list[str], visited: set[str]) -> None:
            if node_id in visited:
                return  # Avoid cycles

            visited.add(node_id)
            path.append(node_id)

            node = self.nodes[node_id]

            # If this is an exit node, save the path
            if node_id in self.exit_nodes:
                all_paths.append(path.copy())
            else:
                # Continue to successors
                for succ_id in node.successors:
                    dfs(succ_id, path, visited.copy())

            path.pop()

        dfs(self.entry_node, [], set())
        return all_paths

    def check_path_has_wipe(self, path: list[str]) -> tuple[bool, str | None]:
        """Check if a path contains a wipe operation."""
        for node_id in path:
            if self.nodes[node_id].has_wipe:
                return True, node_id
        return False, None

    def check_path_has_sensitive_var(self, path: list[str]) -> bool:
        """Check if a path uses sensitive variables."""
        return any(self.nodes[node_id].has_sensitive_var for node_id in path)

    def compute_dominators(self) -> dict[str, set[str]]:
        """Compute dominator sets for all nodes."""
        if not self.entry_node:
            return {}

        # Initialize
        dominators = {}
        all_nodes = set(self.nodes.keys())

        dominators[self.entry_node] = {self.entry_node}

        for node_id in all_nodes:
            if node_id != self.entry_node:
                dominators[node_id] = all_nodes.copy()

        # Iterate until fixpoint
        changed = True
        while changed:
            changed = False
            for node_id in all_nodes:
                if node_id == self.entry_node:
                    continue

                # Dom(n) = {n} ∪ (∩ Dom(p) for all predecessors p)
                new_dom = {node_id}
                if self.nodes[node_id].predecessors:
                    pred_doms = [dominators[pred] for pred in self.nodes[node_id].predecessors]
                    if pred_doms:
                        new_dom = new_dom.union(set.intersection(*pred_doms))

                if new_dom != dominators[node_id]:
                    dominators[node_id] = new_dom
                    changed = True

        return dominators

    def verify_wipe_dominates_exits(self) -> dict:
        """Verify that wipe operations dominate all exit nodes."""
        dominators = self.compute_dominators()

        # Find all wipe nodes
        wipe_nodes = [node_id for node_id, node in self.nodes.items() if node.has_wipe]

        results = {
            "wipe_dominates_all_exits": True,
            "wipe_nodes": wipe_nodes,
            "problematic_exits": [],
        }

        for exit_id in self.exit_nodes:
            exit_doms = dominators.get(exit_id, set())

            # Check if any wipe node dominates this exit
            has_dominating_wipe = any(wipe_id in exit_doms for wipe_id in wipe_nodes)

            if not has_dominating_wipe:
                results["wipe_dominates_all_exits"] = False
                results["problematic_exits"].append(
                    {
                        "exit_node": exit_id,
                        "line": self.nodes[exit_id].line_num,
                        "dominators": list(exit_doms),
                    }
                )

        return results

    def analyze(self) -> dict:
        """Perform comprehensive CFG analysis."""
        # Find all paths
        all_paths = self.find_all_paths_to_exit()

        # Check each path
        paths_with_wipe = 0
        paths_without_wipe = []
        paths_with_sensitive_vars = 0

        for i, path in enumerate(all_paths):
            has_wipe, wipe_node = self.check_path_has_wipe(path)
            has_sensitive = self.check_path_has_sensitive_var(path)

            if has_wipe:
                paths_with_wipe += 1
            elif has_sensitive:
                # Sensitive path without wipe
                paths_without_wipe.append(
                    {
                        "path_id": i,
                        "length": len(path),
                        "nodes": [
                            {
                                "id": node_id,
                                "line": self.nodes[node_id].line_num,
                                "statement": self.nodes[node_id].statement,
                            }
                            for node_id in path
                        ],
                    }
                )

            if has_sensitive:
                paths_with_sensitive_vars += 1

        # Dominator analysis
        dominator_results = self.verify_wipe_dominates_exits()

        return {
            "cfg_stats": {
                "total_nodes": len(self.nodes),
                "total_paths": len(all_paths),
                "exit_nodes": len(self.exit_nodes),
            },
            "wipe_coverage": {
                "paths_with_wipe": paths_with_wipe,
                "paths_without_wipe": len(paths_without_wipe),
                "paths_with_sensitive_vars": paths_with_sensitive_vars,
                "coverage_percentage": (paths_with_wipe / len(all_paths) * 100) if all_paths else 0,
            },
            "problematic_paths": paths_without_wipe,
            "dominator_analysis": dominator_results,
        }


def main():
    parser = argparse.ArgumentParser(description="Control-flow graph analyzer")
    parser.add_argument("--src", required=True, help="Source file to analyze")
    parser.add_argument("--out", required=True, help="Output JSON file")

    args = parser.parse_args()

    # Default patterns
    sensitive_patterns = [
        r"\b(secret|key|seed|priv|private|sk|shared_secret|nonce|token|pwd|pass)\b"
    ]
    wipe_patterns = [
        r"\bexplicit_bzero\s*\(",
        r"\bmemset_s\s*\(",
        r"\bOPENSSL_cleanse\s*\(",
        r"\bsodium_memzero\s*\(",
        r"\bzeroize\s*\(",
    ]

    # Build CFG
    builder = CFGBuilder(Path(args.src), sensitive_patterns, wipe_patterns)
    try:
        builder.build_from_source()
    except OSError as e:
        print(f"Error: cannot read source file {args.src}: {e}", file=sys.stderr)
        sys.exit(1)

    # Analyze
    results = {"source_file": args.src, "analysis": builder.analyze()}

    # Write output
    output_path = Path(args.out)
    output_path.parent.mkdir(parents=True, exist_ok=True)

    with open(output_path, "w") as f:
        json.dump(results, f, indent=2)

    print(f"OK: CFG analysis written to {args.out}")


if __name__ == "__main__":
    main()

#!/usr/bin/env bash
set -euo pipefail

# Analyze heap allocations for security issues with sensitive data.
#
# Usage:
#   analyze_heap.sh --src path/to/file.c --config config.yaml --out /tmp/heap_analysis.json
#
# Detects:
# - malloc/calloc/realloc for sensitive variables (should use secure allocators)
# - Missing mlock/madvise for sensitive heaps
# - Secure allocator usage (approved patterns)

usage() {
  echo "Usage: $0 --src <file> --out <analysis.json> [--config <config.yaml>]" >&2
}

json_escape() {
  local s="$1"
  s="${s//\\/\\\\}"
  s="${s//\"/\\\"}"
  s="${s//$'\n'/\\n}"
  s="${s//$'\t'/\\t}"
  printf '%s' "$s"
}

SRC=""
CONFIG=""
OUT=""

while [[ $# -gt 0 ]]; do
  case "$1" in
    --src)
      SRC="$2"
      shift 2
      ;;
    --config)
      CONFIG="$2"
      shift 2
      ;;
    --out)
      OUT="$2"
      shift 2
      ;;
    *)
      echo "Unknown arg: $1" >&2
      usage
      exit 2
      ;;
  esac
done

if [[ -z "$SRC" || -z "$OUT" ]]; then
  usage
  exit 2
fi

if [[ ! -f "$SRC" ]]; then
  echo "Source file not found: $SRC" >&2
  exit 2
fi

# Load patterns from config
SENSITIVE_PATTERN="(secret|key|seed|priv|private|sk|shared_secret|nonce|token|pwd|pass)"
SECURE_ALLOC_FUNCS="(OPENSSL_secure_malloc|OPENSSL_secure_zalloc|sodium_malloc|sodium_allocarray|SecureAlloc)"

if [[ -n "$CONFIG" ]] && [[ -f "$CONFIG" ]]; then
  # Extract patterns from YAML (POSIX-compatible, no grep -P)
  SENS_PAT=$(grep -A 20 "^sensitive_name_regex:" "$CONFIG" | sed -n 's/.*"\([^"]*\)".*/\1/p' | head -1 || echo "")
  if [[ -n "$SENS_PAT" ]]; then
    SENSITIVE_PATTERN="$SENS_PAT"
  fi

  SEC_FUNCS=$(grep -A 20 "^secure_heap_alloc_funcs:" "$CONFIG" | sed -n 's/.*- "\([^"]*\)".*/\1/p' | tr '\n' '|' | sed 's/|$//')
  if [[ -n "$SEC_FUNCS" ]]; then
    SECURE_ALLOC_FUNCS="($SEC_FUNCS)"
  elif [[ -z "$SENS_PAT" ]]; then
    echo "WARNING: config file provided but no patterns extracted from $CONFIG" >&2
  fi
fi

# Arrays to collect findings
INSECURE_ALLOCS=()
SECURE_ALLOCS=()
MISSING_MLOCK=()
MISSING_MADVISE=()
MADVISE_RE='madvise[[:space:]]*\(([a-zA-Z_][a-zA-Z0-9_]*)[^)]*MADV_(DONTDUMP|DONTFORK|WIPEONFORK)'

# Track allocated pointers to check for mlock/madvise
declare -A ALLOCATED_PTRS

LINE_NUM=0

while IFS= read -r line; do
  ((LINE_NUM++))

  # Skip comments
  [[ "$line" =~ ^[[:space:]]*// ]] && continue
  [[ "$line" =~ ^[[:space:]]*\* ]] && continue

  # Detect insecure allocations
  if [[ "$line" =~ ([a-zA-Z_][a-zA-Z0-9_]*)[[:space:]]*=[[:space:]]*(malloc|calloc|realloc)[[:space:]]*\( ]]; then
    PTR="${BASH_REMATCH[1]}"
    ALLOC_FUNC="${BASH_REMATCH[2]}"

    if [[ "$PTR" =~ $SENSITIVE_PATTERN ]]; then
      INSECURE_ALLOCS+=("{\"line\": $LINE_NUM, \"pointer\": \"$PTR\", \"allocator\": \"$ALLOC_FUNC\", \"severity\": \"high\", \"context\": \"$(json_escape "$line")\"}")
      ALLOCATED_PTRS["$PTR"]="insecure:$LINE_NUM"
    fi
  fi

  # Detect secure allocations
  if [[ "$line" =~ ([a-zA-Z_][a-zA-Z0-9_]*)[[:space:]]*=[[:space:]]*($SECURE_ALLOC_FUNCS)[[:space:]]*\( ]]; then
    PTR="${BASH_REMATCH[1]}"
    ALLOC_FUNC="${BASH_REMATCH[2]}"

    SECURE_ALLOCS+=("{\"line\": $LINE_NUM, \"pointer\": \"$PTR\", \"allocator\": \"$ALLOC_FUNC\", \"context\": \"$(json_escape "$line")\"}")
    ALLOCATED_PTRS["$PTR"]="secure:$LINE_NUM"
  fi

  # Detect mlock usage
  if [[ "$line" =~ mlock[2]?[[:space:]]*\(([a-zA-Z_][a-zA-Z0-9_]*) ]]; then
    PTR="${BASH_REMATCH[1]}"
    if [[ -n "${ALLOCATED_PTRS[$PTR]:-}" ]]; then
      ALLOCATED_PTRS["$PTR"]="${ALLOCATED_PTRS[$PTR]}:mlocked"
    fi
  fi

  # Detect madvise usage
  if [[ "$line" =~ $MADVISE_RE ]]; then
    PTR="${BASH_REMATCH[1]}"
    if [[ -n "${ALLOCATED_PTRS[$PTR]:-}" ]]; then
      ALLOCATED_PTRS["$PTR"]="${ALLOCATED_PTRS[$PTR]}:madvised"
    fi
  fi

done <"$SRC"

# Check for missing protections
for PTR in "${!ALLOCATED_PTRS[@]}"; do
  INFO="${ALLOCATED_PTRS[$PTR]}"

  if [[ "$INFO" =~ ^insecure: ]]; then
    LINE="${INFO#insecure:}"
    LINE="${LINE%%:*}"

    if [[ ! "$INFO" =~ mlocked ]]; then
      MISSING_MLOCK+=("{\"line\": $LINE, \"pointer\": \"$PTR\", \"recommendation\": \"Add mlock() to prevent swapping to disk\"}")
    fi

    if [[ ! "$INFO" =~ madvised ]]; then
      MISSING_MADVISE+=("{\"line\": $LINE, \"pointer\": \"$PTR\", \"recommendation\": \"Add madvise(MADV_DONTDUMP) to exclude from core dumps\"}")
    fi
  fi
done

# Generate JSON report
mkdir -p "$(dirname "$OUT")"

cat >"$OUT" <<EOF
{
  "source_file": "$SRC",
  "findings": {
    "insecure_allocations": [
      $(
  IFS=,
  echo "${INSECURE_ALLOCS[*]}"
)
    ],
    "secure_allocations": [
      $(
  IFS=,
  echo "${SECURE_ALLOCS[*]}"
)
    ],
    "missing_mlock": [
      $(
  IFS=,
  echo "${MISSING_MLOCK[*]}"
)
    ],
    "missing_madvise": [
      $(
  IFS=,
  echo "${MISSING_MADVISE[*]}"
)
    ]
  },
  "summary": {
    "insecure_alloc_count": ${#INSECURE_ALLOCS[@]},
    "secure_alloc_count": ${#SECURE_ALLOCS[@]},
    "missing_protection_count": $((${#MISSING_MLOCK[@]} + ${#MISSING_MADVISE[@]}))
  },
  "recommendations": [
    "Replace malloc/calloc/realloc with OPENSSL_secure_malloc/sodium_malloc for sensitive data",
    "Use mlock() to prevent sensitive memory from being swapped to disk",
    "Use madvise(MADV_DONTDUMP) to exclude sensitive memory from core dumps",
    "Use madvise(MADV_WIPEONFORK) to zero memory in child processes after fork"
  ]
}
EOF

# Validate JSON output
if command -v jq &>/dev/null; then
  if ! jq empty "$OUT" 2>/dev/null; then
    echo "ERROR: generated JSON is malformed: $OUT" >&2
    exit 1
  fi
fi

echo "OK: heap analysis written to $OUT"

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
Semantic LLVM IR analyzer for zeroization detection.

This tool parses LLVM IR structurally (not just regex) to detect:
- Memory operations in SSA form (mem2reg output)
- Loop-unrolled zeroization patterns
- Complex optimization transformations
- Store/load chains that affect zeroization
"""

import argparse
import json
import re
import sys
from dataclasses import dataclass, field
from pathlib import Path


@dataclass
class IRInstruction:
    """Represents an LLVM IR instruction."""

    line_num: int
    opcode: str
    operands: list[str]
    result: str | None
    raw_line: str
    metadata: dict[str, str] = field(default_factory=dict)


@dataclass
class BasicBlock:
    """Represents a basic block in LLVM IR."""

    label: str
    instructions: list[IRInstruction]
    successors: list[str] = field(default_factory=list)
    predecessors: list[str] = field(default_factory=list)


@dataclass
class Function:
    """Represents a function in LLVM IR."""

    name: str
    basic_blocks: dict[str, BasicBlock]
    entry_block: str | None = None
    arguments: list[str] = field(default_factory=list)


class SemanticIRAnalyzer:
    """Semantic analyzer for LLVM IR."""

    def __init__(self, ir_file: Path, config: dict):
        self.ir_file = ir_file
        self.config = config
        self.functions: dict[str, Function] = {}
        self.current_function: Function | None = None
        self.current_block: BasicBlock | None = None

    def parse_ir(self) -> None:
        """Parse LLVM IR file into structured representation."""
        with open(self.ir_file) as f:
            lines = f.readlines()

        line_num = 0
        for line in lines:
            line_num += 1
            line = line.strip()

            # Skip comments and empty lines
            if not line or line.startswith(";"):
                continue

            # Function definition
            if line.startswith("define "):
                self._parse_function_def(line)
                continue

            # Function end
            if line == "}" and self.current_function:
                self.functions[self.current_function.name] = self.current_function
                self.current_function = None
                self.current_block = None
                continue

            # Basic block label
            if self.current_function and ":" in line and not line.startswith("%"):
                label = line.split(":")[0].strip()
                self.current_block = BasicBlock(label=label, instructions=[])
                self.current_function.basic_blocks[label] = self.current_block
                if not self.current_function.entry_block:
                    self.current_function.entry_block = label
                continue

            # Instruction
            if self.current_function and self.current_block:
                inst = self._parse_instruction(line, line_num)
                if inst:
                    self.current_block.instructions.append(inst)

                    # Track control flow
                    if inst.opcode in ["br", "switch", "ret"]:
                        self._update_control_flow(inst)

    def _parse_function_def(self, line: str) -> None:
        """Parse function definition."""
        # Extract function name: define ... @func_name(...)
        match = re.search(r"@([a-zA-Z0-9_\.]+)\s*\(", line)
        if match:
            func_name = match.group(1)
            self.current_function = Function(name=func_name, basic_blocks={})

            # Extract arguments
            args_match = re.search(r"\((.*?)\)", line)
            if args_match:
                args_str = args_match.group(1)
                # Simple argument parsing (just count for now)
                self.current_function.arguments = [
                    arg.strip() for arg in args_str.split(",") if arg.strip()
                ]

    def _parse_instruction(self, line: str, line_num: int) -> IRInstruction | None:
        """Parse single instruction."""
        # Pattern: %result = opcode operands
        # or: opcode operands (for void instructions)

        result = None
        rest = line

        if "=" in line:
            parts = line.split("=", 1)
            result = parts[0].strip()
            rest = parts[1].strip()

        # Extract opcode
        tokens = rest.split(None, 1)
        if not tokens:
            return None

        opcode = tokens[0]
        operands_str = tokens[1] if len(tokens) > 1 else ""

        # Parse operands (simplified)
        operands = self._parse_operands(operands_str)

        return IRInstruction(
            line_num=line_num, opcode=opcode, operands=operands, result=result, raw_line=line
        )

    def _parse_operands(self, operands_str: str) -> list[str]:
        """Parse instruction operands."""
        # Simple tokenization (can be improved)
        operands = []
        current = ""
        depth = 0

        for char in operands_str:
            if char in "([{":
                depth += 1
            elif char in ")]}":
                depth -= 1
            elif char == "," and depth == 0:
                if current.strip():
                    operands.append(current.strip())
                current = ""
                continue
            current += char

        if current.strip():
            operands.append(current.strip())

        return operands

    def _update_control_flow(self, inst: IRInstruction) -> None:
        """Update CFG based on control flow instruction."""
        if not self.current_block:
            return

        if inst.opcode == "br":
            # Conditional: br i1 %cond, label %true, label %false
            # Unconditional: br label %target
            labels = [
                op.replace("label", "").replace("%", "").strip()
                for op in inst.operands
                if "label" in op
            ]
            self.current_block.successors.extend(labels)

            # Update predecessors
            for label in labels:
                if label in self.current_function.basic_blocks:
                    self.current_function.basic_blocks[label].predecessors.append(
                        self.current_block.label
                    )

        elif inst.opcode == "switch":
            # switch i32 %val, label %default [ ... cases ... ]
            labels = [
                op.replace("label", "").replace("%", "").strip()
                for op in inst.operands
                if "label" in op
            ]
            self.current_block.successors.extend(labels)

    def find_memory_operations(self, func: Function) -> dict[str, list[IRInstruction]]:
        """Find all memory operations (load, store, memset, memcpy, etc.)."""
        mem_ops = {"store": [], "load": [], "memset": [], "memcpy": [], "call": []}

        for bb in func.basic_blocks.values():
            for inst in bb.instructions:
                if inst.opcode == "store":
                    mem_ops["store"].append(inst)
                elif inst.opcode == "load":
                    mem_ops["load"].append(inst)
                elif inst.opcode == "call":
                    # Check for memset/memcpy/zeroize calls
                    call_target = self._extract_call_target(inst)
                    if "memset" in call_target or "llvm.memset" in call_target:
                        mem_ops["memset"].append(inst)
                    elif "memcpy" in call_target or "llvm.memcpy" in call_target:
                        mem_ops["memcpy"].append(inst)
                    elif any(
                        fn in call_target
                        for fn in ["explicit_bzero", "OPENSSL_cleanse", "sodium_memzero", "zeroize"]
                    ):
                        mem_ops["call"].append(inst)

        return mem_ops

    def _extract_call_target(self, inst: IRInstruction) -> str:
        """Extract function name from call instruction."""
        for op in inst.operands:
            if "@" in op:
                match = re.search(r"@([a-zA-Z0-9_\.]+)", op)
                if match:
                    return match.group(1)
        return ""

    def detect_loop_unrolled_wipes(self, func: Function) -> list[dict]:
        """Detect zeroization patterns from loop unrolling."""
        findings = []

        for bb_label, bb in func.basic_blocks.items():
            # Look for patterns like:
            # store i8 0, i8* %ptr.0
            # store i8 0, i8* %ptr.1
            # store i8 0, i8* %ptr.2
            # ... (repeated pattern indicating unrolled loop)

            zero_stores = []
            for inst in bb.instructions:
                # Check if storing 0
                if (
                    inst.opcode == "store"
                    and inst.operands
                    and ("i8 0" in inst.operands[0] or "i32 0" in inst.operands[0])
                ):
                    zero_stores.append(inst)

            # If we have 4+ consecutive zero stores, likely an unrolled wipe loop
            if len(zero_stores) >= 4:
                # Check if addresses are sequential
                addresses = [self._extract_store_address(inst) for inst in zero_stores]
                if self._are_sequential_addresses(addresses):
                    findings.append(
                        {
                            "type": "LOOP_UNROLLED_WIPE",
                            "block": bb_label,
                            "count": len(zero_stores),
                            "first_line": zero_stores[0].line_num,
                            "evidence": (
                                f"Found {len(zero_stores)} consecutive zero stores"
                                " (likely unrolled loop)"
                            ),
                        }
                    )

        return findings

    def _extract_store_address(self, inst: IRInstruction) -> str:
        """Extract address operand from store instruction."""
        # store type value, type* pointer
        if len(inst.operands) >= 2:
            return inst.operands[1]
        return ""

    def _are_sequential_addresses(self, addresses: list[str]) -> bool:
        """Check if addresses look sequential (e.g., %ptr.0, %ptr.1, %ptr.2)."""
        if len(addresses) < 2:
            return False

        # Simple heuristic: check for pattern like %name.0, %name.1, etc.
        base_pattern = re.sub(r"\d+", "", addresses[0])
        return all(re.sub(r"\d+", "", addr) == base_pattern for addr in addresses[1:])

    def detect_volatile_stores(self, func: Function) -> list[IRInstruction]:
        """Find volatile store instructions (cannot be optimized away)."""
        volatile_stores = []

        for bb in func.basic_blocks.values():
            for inst in bb.instructions:
                if inst.opcode == "store" and "volatile" in inst.raw_line:
                    volatile_stores.append(inst)

        return volatile_stores

    def analyze_mem2reg_output(self, func: Function) -> dict:
        """Analyze memory operations in SSA form (after mem2reg pass)."""
        # After mem2reg, local variables are promoted to registers
        # Look for phi nodes and register operations

        phi_nodes = []
        register_ops = []

        for bb in func.basic_blocks.values():
            for inst in bb.instructions:
                if inst.opcode == "phi":
                    phi_nodes.append(inst)
                elif inst.result and inst.result.startswith("%"):
                    register_ops.append(inst)

        return {
            "phi_count": len(phi_nodes),
            "register_ops": len(register_ops),
            "has_mem2reg": len(phi_nodes) > 0,
        }

    def analyze_function(self, func_name: str) -> dict:
        """Perform comprehensive analysis on a function."""
        if func_name not in self.functions:
            return {"error": f"Function {func_name} not found"}

        func = self.functions[func_name]

        # Find memory operations
        mem_ops = self.find_memory_operations(func)

        # Detect patterns
        loop_unrolled = self.detect_loop_unrolled_wipes(func)
        volatile_stores = self.detect_volatile_stores(func)
        mem2reg_info = self.analyze_mem2reg_output(func)

        # Check for wipe presence
        has_wipe = (
            len(mem_ops["memset"]) > 0 or len(mem_ops["call"]) > 0 or len(volatile_stores) > 0
        )

        return {
            "function": func_name,
            "basic_blocks": len(func.basic_blocks),
            "memory_operations": {
                "stores": len(mem_ops["store"]),
                "loads": len(mem_ops["load"]),
                "memset_calls": len(mem_ops["memset"]),
                "secure_wipe_calls": len(mem_ops["call"]),
                "volatile_stores": len(volatile_stores),
            },
            "patterns": {
                "loop_unrolled_wipes": loop_unrolled,
                "has_volatile_stores": len(volatile_stores) > 0,
            },
            "ssa_analysis": mem2reg_info,
            "has_zeroization": has_wipe,
            "wipe_instructions": [
                {"line": inst.line_num, "type": "memset", "raw": inst.raw_line}
                for inst in mem_ops["memset"]
            ]
            + [
                {"line": inst.line_num, "type": "secure_call", "raw": inst.raw_line}
                for inst in mem_ops["call"]
            ]
            + [
                {"line": inst.line_num, "type": "volatile_store", "raw": inst.raw_line}
                for inst in volatile_stores
            ],
        }


def main():
    parser = argparse.ArgumentParser(description="Semantic LLVM IR analyzer")
    parser.add_argument("--ir", required=True, help="LLVM IR file (.ll)")
    parser.add_argument("--function", help="Specific function to analyze (default: all)")
    parser.add_argument("--config", help="Configuration YAML file")
    parser.add_argument("--out", required=True, help="Output JSON file")

    args = parser.parse_args()

    # Load config (simplified)
    config = {}

    # Parse IR
    analyzer = SemanticIRAnalyzer(Path(args.ir), config)
    try:
        analyzer.parse_ir()
    except OSError as e:
        print(f"Error: cannot read IR file {args.ir}: {e}", file=sys.stderr)
        sys.exit(1)

    # Analyze functions
    results = {"ir_file": args.ir, "functions_found": len(analyzer.functions), "analyses": []}

    if args.function:
        # Analyze specific function
        analysis = analyzer.analyze_function(args.function)
        results["analyses"].append(analysis)
    else:
        # Analyze all functions
        for func_name in analyzer.functions:
            analysis = analyzer.analyze_function(func_name)
            results["analyses"].append(analysis)

    # Write output
    output_path = Path(args.out)
    output_path.parent.mkdir(parents=True, exist_ok=True)

    with open(output_path, "w") as f:
        json.dump(results, f, indent=2)

    print(f"OK: semantic IR analysis written to {args.out}")


if __name__ == "__main__":
    main()

#!/usr/bin/env bash
set -euo pipefail

# Normalize and diff LLVM IR across one or more optimization levels.
#
# Usage (two-file, backward-compatible):
#   diff_ir.sh <O0.ll> <O2.ll>
#
# Usage (multi-level — recommended):
#   diff_ir.sh <O0.ll> <O1.ll> <O2.ll> [<O3.ll> ...]
#
# Output:
# - Prints a unified diff for each pair of adjacent files.
# - For 3+ files, also prints a WIPE PATTERN SUMMARY identifying the first
#   optimization level at which zeroization patterns disappear.
# - Returns exit code 0 if all files are identical, 1 if any diffs found.
#
# Wipe patterns detected in the summary:
#   llvm.memset, volatile, explicit_bzero, sodium_memzero, OPENSSL_cleanse,
#   SecureZeroMemory, memset_s, store i8 0, store i64 0, store i32 0

usage() {
  echo "Usage: $0 <baseline.ll> <file2.ll> [<file3.ll> ...]" >&2
}

if [[ $# -lt 2 ]]; then
  usage
  exit 2
fi

for f in "$@"; do
  if [[ ! -f "$f" ]]; then
    echo "Missing file: $f" >&2
    exit 2
  fi
done

norm() {
  # Remove comments and metadata noise that changes frequently.
  # Keep it simple and safe: do NOT rewrite semantics, only strip obviously noisy lines.
  sed -E \
    -e 's/;.*$//' \
    -e '/^\s*$/d' \
    -e '/^source_filename = /d' \
    -e '/^target datalayout = /d' \
    -e '/^target triple = /d' \
    -e '/^!llvm\./d' \
    -e '/^!DIGlobalVariable/d' \
    -e '/^!DICompileUnit/d' \
    -e '/^!DIFile/d' \
    -e '/^!DISubprogram/d' \
    -e '/^!DILocation/d' \
    -e '/^!DI.*$/d'
}

has_wipe_pattern() {
  # Return 0 (true) if the file contains any zeroization pattern.
  grep -qE \
    'llvm\.memset|volatile|explicit_bzero|sodium_memzero|OPENSSL_cleanse|SecureZeroMemory|memset_s|store i8 0|store i64 0|store i32 0' \
    "$1"
}

# ---------------------------------------------------------------------------
# Normalize all input files into temp files.
# ---------------------------------------------------------------------------
FILES=("$@")
NUM_FILES=${#FILES[@]}

TMPDIR_BASE="$(mktemp -d -t za-ir-XXXXXX)"
trap 'rm -rf "$TMPDIR_BASE"' EXIT

NORMFILES=()
for i in "${!FILES[@]}"; do
  tmp="$TMPDIR_BASE/norm_${i}.ll"
  norm <"${FILES[$i]}" >"$tmp"
  NORMFILES+=("$tmp")
done

# ---------------------------------------------------------------------------
# Two-file mode: backward-compatible, single diff, no summary.
# ---------------------------------------------------------------------------
if [[ $NUM_FILES -eq 2 ]]; then
  diff_rc=0
  diff -u "${NORMFILES[0]}" "${NORMFILES[1]}" || diff_rc=$?
  if [[ $diff_rc -eq 2 ]]; then
    echo "diff_ir.sh: diff failed (internal error)" >&2
    exit 1
  fi
  exit $diff_rc
fi

# ---------------------------------------------------------------------------
# Multi-file mode: pairwise diffs between adjacent files + wipe summary.
# ---------------------------------------------------------------------------
any_diff=0

for ((i = 0; i < NUM_FILES - 1; i++)); do
  j=$((i + 1))
  A_LABEL="$(basename "${FILES[$i]}")"
  B_LABEL="$(basename "${FILES[$j]}")"
  echo "=== DIFF File $((i + 1)) ($A_LABEL) vs File $((j + 1)) ($B_LABEL) ==="
  if ! diff -u "${NORMFILES[$i]}" "${NORMFILES[$j]}"; then
    any_diff=1
  fi
  echo ""
done

# ---------------------------------------------------------------------------
# Wipe pattern summary: identify first file where wipe disappears.
# ---------------------------------------------------------------------------
echo "=== WIPE PATTERN SUMMARY ==="
first_absent=-1
for i in "${!NORMFILES[@]}"; do
  LABEL="$(basename "${FILES[$i]}")"
  if has_wipe_pattern "${NORMFILES[$i]}"; then
    echo "  File $((i + 1)) ($LABEL): WIPE PRESENT"
  else
    echo "  File $((i + 1)) ($LABEL): WIPE ABSENT"
    if [[ $first_absent -eq -1 ]]; then
      first_absent=$i
    fi
  fi
done

if [[ $first_absent -ne -1 ]]; then
  LABEL="$(basename "${FILES[$first_absent]}")"
  echo ""
  echo "  First disappearance at File $((first_absent + 1)) ($LABEL)."
  echo "  Evidence: OPTIMIZED_AWAY_ZEROIZE — wipe present at lower opt level(s) but absent here."
else
  echo ""
  echo "  Wipe patterns present at all opt levels analyzed."
fi

exit $any_diff

#!/usr/bin/env bash
# diff_rust_mir.sh — Normalize and diff Rust MIR across optimization levels.
#
# Compares MIR output from different optimization levels to detect zeroize-
# related transformations: drop glue removal, StorageDead elimination, and
# zeroize call elimination.
#
# Exit codes:
#   0  all files are identical after normalization
#   1  at least one diff found (or wipe patterns disappeared)
#   2  argument error
#
# Usage (two-file, backward-compatible):
#   diff_rust_mir.sh <O0.mir> <O2.mir>
#
# Usage (multi-level — recommended):
#   diff_rust_mir.sh <O0.mir> <O1.mir> <O2.mir> [<O3.mir> ...]
#
# Output:
# - Unified diff for each pair of adjacent files.
# - For 3+ files, a ZEROIZE PATTERN SUMMARY identifying the first opt level
#   at which patterns disappear.
#
# Wipe patterns detected:
#   zeroize::, Zeroize::zeroize, volatile_set_memory, drop_in_place,
#   StorageDead for sensitive locals, ptr::write_bytes

set -euo pipefail

usage() {
  cat <<'EOF'
Usage:
  diff_rust_mir.sh <baseline.mir> <file2.mir> [<file3.mir> ...]

Compares Rust MIR files across optimization levels. Normalizes away noisy
metadata (source locations, scope info, storage annotations) and diffs
the semantic content. Detects disappearance of zeroize-related patterns.

Examples:
  diff_rust_mir.sh crate.O0.mir crate.O2.mir
  diff_rust_mir.sh crate.O0.mir crate.O1.mir crate.O2.mir crate.O3.mir
EOF
}

if [[ $# -lt 2 ]]; then
  usage
  exit 2
fi

for f in "$@"; do
  if [[ ! -f "$f" ]]; then
    echo "diff_rust_mir.sh: missing file: $f" >&2
    exit 2
  fi
done

# ---------------------------------------------------------------------------
# Normalization: strip noisy metadata that changes between opt levels
# but is semantically irrelevant for zeroize analysis.
# ---------------------------------------------------------------------------
norm() {
  sed -E \
    -e '/^\/\/ WARNING:/d' \
    -e '/^\/\/ MIR for/d' \
    -e 's/scope [0-9]+ at [^ ]+:[0-9]+:[0-9]+/scope N at <loc>/g' \
    -e 's/at [^ ]+\.rs:[0-9]+:[0-9]+/at <loc>/g' \
    -e 's/\/\/ .*$//g' \
    -e '/^\s*$/d'
}

# ---------------------------------------------------------------------------
# Pattern detection: Rust MIR zeroize-related constructs
# ---------------------------------------------------------------------------
has_zeroize_pattern() {
  grep -qE \
    'zeroize::|Zeroize::zeroize|volatile_set_memory|ptr::write_bytes|drop_in_place.*[Kk]ey|drop_in_place.*[Ss]ecret|drop_in_place.*[Pp]assword|drop_in_place.*[Tt]oken|drop_in_place.*[Nn]once|drop_in_place.*[Ss]eed|drop_in_place.*[Pp]riv|Zeroizing|ZeroizeOnDrop' \
    "$1"
}

has_drop_glue() {
  grep -qE 'drop_in_place|drop\(_[0-9]+\)' "$1"
}

# shellcheck disable=SC2329,SC2317 # invoked indirectly by agent prompts
has_storage_dead_sensitive() {
  grep -qE 'StorageDead\(_[0-9]+\)' "$1" &&
    grep -qE '(key|secret|password|token|nonce|seed|priv|master|credential)' "$1"
}

# ---------------------------------------------------------------------------
# Setup
# ---------------------------------------------------------------------------
FILES=("$@")
NUM_FILES=${#FILES[@]}

TMPDIR_BASE="$(mktemp -d -t za-mir-XXXXXX)"
trap 'rm -rf "$TMPDIR_BASE"' EXIT

NORMFILES=()
for i in "${!FILES[@]}"; do
  tmp="$TMPDIR_BASE/norm_${i}.mir"
  norm <"${FILES[$i]}" >"$tmp"
  NORMFILES+=("$tmp")
done

# ---------------------------------------------------------------------------
# Two-file mode: backward-compatible, single diff, no summary.
# ---------------------------------------------------------------------------
if [[ $NUM_FILES -eq 2 ]]; then
  diff_rc=0
  diff -u "${NORMFILES[0]}" "${NORMFILES[1]}" || diff_rc=$?
  if [[ $diff_rc -eq 2 ]]; then
    echo "diff_rust_mir.sh: diff failed (internal error)" >&2
    exit 1
  fi
  exit $diff_rc
fi

# ---------------------------------------------------------------------------
# Multi-file mode: pairwise diffs + zeroize pattern summary.
# ---------------------------------------------------------------------------
any_diff=0

for ((i = 0; i < NUM_FILES - 1; i++)); do
  j=$((i + 1))
  A_LABEL="$(basename "${FILES[$i]}")"
  B_LABEL="$(basename "${FILES[$j]}")"
  echo "=== DIFF File $((i + 1)) ($A_LABEL) vs File $((j + 1)) ($B_LABEL) ==="
  if ! diff -u --label "$A_LABEL" --label "$B_LABEL" \
    "${NORMFILES[$i]}" "${NORMFILES[$j]}"; then
    any_diff=1
  fi
  echo ""
done

# ---------------------------------------------------------------------------
# Zeroize pattern summary
# ---------------------------------------------------------------------------
echo "=== ZEROIZE PATTERN SUMMARY ==="
first_absent=-1
for i in "${!NORMFILES[@]}"; do
  LABEL="$(basename "${FILES[$i]}")"
  if has_zeroize_pattern "${NORMFILES[$i]}"; then
    echo "  File $((i + 1)) ($LABEL): ZEROIZE CALLS PRESENT"
  else
    echo "  File $((i + 1)) ($LABEL): ZEROIZE CALLS ABSENT"
    if [[ $first_absent -eq -1 ]]; then
      first_absent=$i
    fi
  fi
done
echo ""

# ---------------------------------------------------------------------------
# Drop glue summary
# ---------------------------------------------------------------------------
echo "=== DROP GLUE SUMMARY ==="
first_drop_absent=-1
for i in "${!NORMFILES[@]}"; do
  LABEL="$(basename "${FILES[$i]}")"
  if has_drop_glue "${NORMFILES[$i]}"; then
    echo "  File $((i + 1)) ($LABEL): DROP GLUE PRESENT"
  else
    echo "  File $((i + 1)) ($LABEL): DROP GLUE ABSENT"
    if [[ $first_drop_absent -eq -1 ]]; then
      first_drop_absent=$i
    fi
  fi
done
echo ""

# ---------------------------------------------------------------------------
# Verdict
# ---------------------------------------------------------------------------
if [[ $first_absent -ne -1 ]]; then
  LABEL="$(basename "${FILES[$first_absent]}")"
  echo "WARNING: Zeroize patterns first disappear at File $((first_absent + 1)) ($LABEL)."
  echo "  Evidence: OPTIMIZED_AWAY_ZEROIZE — zeroize calls present at lower opt level(s) but absent here."
  any_diff=1
elif [[ $first_drop_absent -ne -1 ]]; then
  LABEL="$(basename "${FILES[$first_drop_absent]}")"
  echo "WARNING: Drop glue first disappears at File $((first_drop_absent + 1)) ($LABEL)."
  echo "  Evidence: Drop glue present at lower opt level(s) but absent here — sensitive type drop may be inlined or elided."
  any_diff=1
else
  echo "OK: Zeroize patterns and drop glue present at all opt levels analyzed."
fi

exit $any_diff

#!/usr/bin/env bash
set -euo pipefail

# Emit assembly for a given translation unit.
#
# Usage:
#   emit_asm.sh --cc clang --src path/to/file.c --out /tmp/file.s --opt O2 -- <extra compile args>

usage() {
  echo "Usage: $0 --src <file> --out <out.s> [--cc clang] [--opt O0|O1|O2|O3|Os|Oz] -- <extra args>" >&2
}

CC="clang"
SRC=""
OUT=""
OPT="O0"

while [[ $# -gt 0 ]]; do
  case "$1" in
    --cc)
      CC="$2"
      shift 2
      ;;
    --src)
      SRC="$2"
      shift 2
      ;;
    --out)
      OUT="$2"
      shift 2
      ;;
    --opt)
      OPT="$2"
      shift 2
      ;;
    --)
      shift
      break
      ;;
    *)
      echo "Unknown arg: $1" >&2
      usage
      exit 2
      ;;
  esac
done

if [[ -z "$SRC" || -z "$OUT" ]]; then
  usage
  exit 2
fi

case "$OPT" in
  O0 | O1 | O2 | O3 | Os | Oz) ;;
  *)
    echo "Invalid --opt: $OPT" >&2
    usage
    exit 2
    ;;
esac

EXTRA=("$@")
mkdir -p "$(dirname "$OUT")"

"$CC" "-$OPT" -S "$SRC" -o "$OUT" ${EXTRA[@]+"${EXTRA[@]}"}

echo "OK: wrote asm to $OUT"

#!/usr/bin/env bash
set -euo pipefail

# Emit LLVM IR for a given translation unit.
#
# Usage:
#   emit_ir.sh --cc clang --src path/to/file.c --out /tmp/file.ll --opt O2 -- <extra compile args>
#
# Notes:
# - Use `--` to pass through extra include/define flags.
# - We intentionally do not attempt to parse compile_commands.json here.
#   Your runner should extract the TU command and pass flags after `--`.

usage() {
  echo "Usage: $0 --src <file> --out <out.ll> [--cc clang] [--opt O0|O1|O2|O3|Os|Oz] -- <extra args>" >&2
}

CC="clang"
SRC=""
OUT=""
OPT="O0"

while [[ $# -gt 0 ]]; do
  case "$1" in
    --cc)
      CC="$2"
      shift 2
      ;;
    --src)
      SRC="$2"
      shift 2
      ;;
    --out)
      OUT="$2"
      shift 2
      ;;
    --opt)
      OPT="$2"
      shift 2
      ;;
    --)
      shift
      break
      ;;
    *)
      echo "Unknown arg: $1" >&2
      usage
      exit 2
      ;;
  esac
done

if [[ -z "$SRC" || -z "$OUT" ]]; then
  usage
  exit 2
fi

# Normalize OPT -> clang flag
case "$OPT" in
  O0 | O1 | O2 | O3 | Os | Oz) ;;
  *)
    echo "Invalid --opt: $OPT" >&2
    usage
    exit 2
    ;;
esac

# Extra args after --
EXTRA=("$@")

# Ensure output dir exists
mkdir -p "$(dirname "$OUT")"

# Emit IR
"$CC" "-$OPT" -S -emit-llvm "$SRC" -o "$OUT" ${EXTRA[@]+"${EXTRA[@]}"}

echo "OK: wrote IR to $OUT"

#!/usr/bin/env bash
# emit_rust_asm.sh — Emit Rust assembly for zeroize analysis.
#
# Exit codes:
#   0  success
#   1  build/output failure
#   2  argument error

set -euo pipefail

usage() {
  cat <<'EOF'
Usage:
  emit_rust_asm.sh --manifest <Cargo.toml> --out <path> [options] [-- <extra cargo rustc args>]

Options:
  --manifest <file>        Cargo manifest path (required)
  --out <path>             Output .s file or directory (required)
  --opt <O0|O1|O2|O3>      Opt level (default: O2)
  --crate <pkg>            Workspace package (-p)
  --bin <target>           Build only a specific bin target
  --lib                    Build only the lib target
  --target <triple>        Cross-compile target (e.g. x86_64-unknown-linux-gnu)
  --intel-syntax           Emit Intel syntax instead of AT&T (default: AT&T)
  --help                   Show this help text

Examples:
  emit_rust_asm.sh --manifest Cargo.toml --opt O2 --out /tmp/crate.O2.s
  emit_rust_asm.sh --manifest Cargo.toml --opt O0 --out /tmp/asm/ --lib
  emit_rust_asm.sh --manifest Cargo.toml --out /tmp/crate.O2.s --crate mycrate --target x86_64-unknown-linux-gnu
EOF
}

die_arg() {
  echo "emit_rust_asm.sh: $*" >&2
  exit 2
}

die_run() {
  echo "emit_rust_asm.sh: $*" >&2
  exit 1
}

require_value() {
  local opt="$1"
  local val="${2-}"
  [[ -n "$val" ]] || die_arg "missing value for ${opt}"
}

MANIFEST=""
OUT=""
OPT="O2"
CRATE=""
BIN_TARGET=""
LIB_TARGET=false
TARGET_TRIPLE=""
INTEL_SYNTAX=false
EXTRA_ARGS=()

while [[ $# -gt 0 ]]; do
  case "$1" in
    --manifest)
      require_value "$1" "${2-}"
      MANIFEST="$2"
      shift 2
      ;;
    --out)
      require_value "$1" "${2-}"
      OUT="$2"
      shift 2
      ;;
    --opt)
      require_value "$1" "${2-}"
      OPT="$2"
      shift 2
      ;;
    --crate)
      require_value "$1" "${2-}"
      CRATE="$2"
      shift 2
      ;;
    --bin)
      require_value "$1" "${2-}"
      BIN_TARGET="$2"
      shift 2
      ;;
    --lib)
      LIB_TARGET=true
      shift
      ;;
    --target)
      require_value "$1" "${2-}"
      TARGET_TRIPLE="$2"
      shift 2
      ;;
    --intel-syntax)
      INTEL_SYNTAX=true
      shift
      ;;
    --help | -h)
      usage
      exit 0
      ;;
    --)
      shift
      EXTRA_ARGS=("$@")
      break
      ;;
    *)
      die_arg "unknown argument: $1"
      ;;
  esac
done

[[ -n "$MANIFEST" ]] || die_arg "--manifest is required"
[[ -n "$OUT" ]] || die_arg "--out is required"
[[ -f "$MANIFEST" ]] || die_run "manifest not found: $MANIFEST"
[[ -n "$BIN_TARGET" && "$LIB_TARGET" == true ]] && die_arg "--bin and --lib are mutually exclusive"

case "$OPT" in
  O0) LEVEL="0" ;;
  O1) LEVEL="1" ;;
  O2) LEVEL="2" ;;
  O3) LEVEL="3" ;;
  *) die_arg "unsupported opt level: $OPT (use O0, O1, O2, O3)" ;;
esac

OUT_IS_FILE=false
if [[ "$OUT" == *.s || "$OUT" == *.asm ]]; then
  OUT_IS_FILE=true
  mkdir -p "$(dirname "$OUT")"
else
  mkdir -p "$OUT"
fi

CARGO_ARGS=(+nightly rustc --manifest-path "$MANIFEST")
[[ -n "$CRATE" ]] && CARGO_ARGS+=("-p" "$CRATE")
[[ -n "$BIN_TARGET" ]] && CARGO_ARGS+=("--bin" "$BIN_TARGET")
[[ "$LIB_TARGET" == true ]] && CARGO_ARGS+=("--lib")
[[ -n "$TARGET_TRIPLE" ]] && CARGO_ARGS+=("--target" "$TARGET_TRIPLE")

RUSTC_FLAGS=(--emit=asm -C "opt-level=$LEVEL")
[[ "$INTEL_SYNTAX" == true ]] && RUSTC_FLAGS+=(-C "llvm-args=-x86-asm-syntax=intel")

TARGET_DIR="${TMPDIR:-/tmp}/zeroize_rust_asm_${LEVEL}_$$"
rm -rf "$TARGET_DIR"
mkdir -p "$TARGET_DIR"

echo "=== emit_rust_asm.sh ==="
echo "manifest: $MANIFEST"
echo "opt:      $OPT"
echo "target:   $TARGET_DIR"
echo "output:   $OUT"
[[ -n "$TARGET_TRIPLE" ]] && echo "triple:   $TARGET_TRIPLE"
[[ "$INTEL_SYNTAX" == true ]] && echo "syntax:   intel"

if ! CARGO_TARGET_DIR="$TARGET_DIR" cargo "${CARGO_ARGS[@]}" \
  "${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}" \
  -- "${RUSTC_FLAGS[@]}"; then
  die_run "cargo rustc failed for opt=${OPT}"
fi

declare -a ASM_FILES=()
while IFS= read -r file; do
  ASM_FILES+=("$file")
done < <(find "$TARGET_DIR" -type f -name "*.s" | LC_ALL=C sort)

[[ "${#ASM_FILES[@]}" -gt 0 ]] || die_run "no .s files found under $TARGET_DIR"

if [[ "$OUT_IS_FILE" == true ]]; then
  : >"$OUT"
  for file in "${ASM_FILES[@]}"; do
    cat "$file" >>"$OUT"
  done
  [[ -s "$OUT" ]] || die_run "emitted assembly is empty: $OUT"
else
  cp "${ASM_FILES[@]}" "$OUT/"
fi

#!/usr/bin/env bash
# emit_rust_ir.sh — Emit Rust LLVM IR for zeroize analysis.
#
# Exit codes:
#   0  success
#   1  build/output failure
#   2  argument error

set -euo pipefail

usage() {
  cat <<'EOF'
Usage:
  emit_rust_ir.sh --manifest <Cargo.toml> --out <path> [options] [-- <extra cargo rustc args>]

Options:
  --manifest <file>        Cargo manifest path (required)
  --out <path>             Output .ll file (required)
  --opt <O0|O1|O2|O3>      Opt level (default: O2)
  --crate <pkg>            Workspace package (-p)
  --bin <target>           Build only a specific bin target
  --lib                    Build only the lib target
  --help                   Show this help text

Examples:
  emit_rust_ir.sh --manifest Cargo.toml --opt O0 --out /tmp/crate.O0.ll
  emit_rust_ir.sh --manifest Cargo.toml --opt O2 --bin cli --out /tmp/cli.O2.ll
EOF
}

die_arg() {
  echo "emit_rust_ir.sh: $*" >&2
  exit 2
}

die_run() {
  echo "emit_rust_ir.sh: $*" >&2
  exit 1
}

require_value() {
  local opt="$1"
  local val="${2-}"
  [[ -n "$val" ]] || die_arg "missing value for ${opt}"
}

MANIFEST=""
OUT=""
OPT="O2"
CRATE=""
BIN_TARGET=""
LIB_TARGET=false
EXTRA_ARGS=()

while [[ $# -gt 0 ]]; do
  case "$1" in
    --manifest)
      require_value "$1" "${2-}"
      MANIFEST="$2"
      shift 2
      ;;
    --out)
      require_value "$1" "${2-}"
      OUT="$2"
      shift 2
      ;;
    --opt)
      require_value "$1" "${2-}"
      OPT="$2"
      shift 2
      ;;
    --crate)
      require_value "$1" "${2-}"
      CRATE="$2"
      shift 2
      ;;
    --bin)
      require_value "$1" "${2-}"
      BIN_TARGET="$2"
      shift 2
      ;;
    --lib)
      LIB_TARGET=true
      shift
      ;;
    --help | -h)
      usage
      exit 0
      ;;
    --)
      shift
      EXTRA_ARGS=("$@")
      break
      ;;
    *)
      die_arg "unknown argument: $1"
      ;;
  esac
done

[[ -n "$MANIFEST" ]] || die_arg "--manifest is required"
[[ -n "$OUT" ]] || die_arg "--out is required"
[[ -f "$MANIFEST" ]] || die_run "manifest not found: $MANIFEST"
[[ -n "$BIN_TARGET" && "$LIB_TARGET" == true ]] && die_arg "--bin and --lib are mutually exclusive"
[[ "$OUT" == *.ll ]] || die_arg "--out must be a .ll file path"

case "$OPT" in
  O0) LEVEL="0" ;;
  O1) LEVEL="1" ;;
  O2) LEVEL="2" ;;
  O3) LEVEL="3" ;;
  *) die_arg "unsupported opt level: $OPT (use O0, O1, O2, O3)" ;;
esac

mkdir -p "$(dirname "$OUT")"

CARGO_ARGS=(+nightly rustc --manifest-path "$MANIFEST")
[[ -n "$CRATE" ]] && CARGO_ARGS+=("-p" "$CRATE")
[[ -n "$BIN_TARGET" ]] && CARGO_ARGS+=("--bin" "$BIN_TARGET")
[[ "$LIB_TARGET" == true ]] && CARGO_ARGS+=("--lib")

TARGET_DIR="${TMPDIR:-/tmp}/zeroize_rust_ir_${LEVEL}_$$"
rm -rf "$TARGET_DIR"
mkdir -p "$TARGET_DIR"

echo "=== emit_rust_ir.sh ==="
echo "manifest: $MANIFEST"
echo "opt:      $OPT"
echo "target:   $TARGET_DIR"
echo "output:   $OUT"

if ! CARGO_TARGET_DIR="$TARGET_DIR" cargo "${CARGO_ARGS[@]}" \
  ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"} \
  -- --emit=llvm-ir -C opt-level="$LEVEL"; then
  die_run "cargo rustc failed for opt=${OPT}"
fi

declare -a LL_FILES=()
while IFS= read -r file; do
  LL_FILES+=("$file")
done < <(find "$TARGET_DIR" -type f -name "*.ll" | LC_ALL=C sort)

[[ "${#LL_FILES[@]}" -gt 0 ]] || die_run "no .ll files found under $TARGET_DIR"

: >"$OUT"
for file in "${LL_FILES[@]}"; do
  cat "$file" >>"$OUT"
done

[[ -s "$OUT" ]] || die_run "emitted IR is empty: $OUT"

#!/usr/bin/env bash
# emit_rust_mir.sh — Emit Rust MIR for zeroize analysis.
#
# Exit codes:
#   0  success
#   1  build/output failure
#   2  argument error

set -euo pipefail

usage() {
  cat <<'EOF'
Usage:
  emit_rust_mir.sh --manifest <Cargo.toml> --out <path> [options] [-- <extra cargo rustc args>]

Options:
  --manifest <file>        Cargo manifest path (required)
  --out <path>             Output .mir file or directory (required)
  --opt <O0|O1|O2|O3>      Opt level (default: O0)
  --crate <pkg>            Workspace package (-p)
  --bin <target>           Build only a specific bin target
  --lib                    Build only the lib target
  --help                   Show this help text

Examples:
  emit_rust_mir.sh --manifest Cargo.toml --opt O0 --out /tmp/crate.O0.mir
  emit_rust_mir.sh --manifest Cargo.toml --out /tmp/zeroize_mir
EOF
}

die_arg() {
  echo "emit_rust_mir.sh: $*" >&2
  exit 2
}

die_run() {
  echo "emit_rust_mir.sh: $*" >&2
  exit 1
}

require_value() {
  local opt="$1"
  local val="${2-}"
  [[ -n "$val" ]] || die_arg "missing value for ${opt}"
}

MANIFEST=""
OUT=""
OPT="O0"
CRATE=""
BIN_TARGET=""
LIB_TARGET=false
EXTRA_ARGS=()

while [[ $# -gt 0 ]]; do
  case "$1" in
    --manifest)
      require_value "$1" "${2-}"
      MANIFEST="$2"
      shift 2
      ;;
    --out)
      require_value "$1" "${2-}"
      OUT="$2"
      shift 2
      ;;
    --opt)
      require_value "$1" "${2-}"
      OPT="$2"
      shift 2
      ;;
    --crate)
      require_value "$1" "${2-}"
      CRATE="$2"
      shift 2
      ;;
    --bin)
      require_value "$1" "${2-}"
      BIN_TARGET="$2"
      shift 2
      ;;
    --lib)
      LIB_TARGET=true
      shift
      ;;
    --help | -h)
      usage
      exit 0
      ;;
    --)
      shift
      EXTRA_ARGS=("$@")
      break
      ;;
    *)
      die_arg "unknown argument: $1"
      ;;
  esac
done

[[ -n "$MANIFEST" ]] || die_arg "--manifest is required"
[[ -n "$OUT" ]] || die_arg "--out is required"
[[ -f "$MANIFEST" ]] || die_run "manifest not found: $MANIFEST"
[[ -n "$BIN_TARGET" && "$LIB_TARGET" == true ]] && die_arg "--bin and --lib are mutually exclusive"

case "$OPT" in
  O0) LEVEL="0" ;;
  O1) LEVEL="1" ;;
  O2) LEVEL="2" ;;
  O3) LEVEL="3" ;;
  *) die_arg "unsupported opt level: $OPT (use O0, O1, O2, O3)" ;;
esac

OUT_IS_FILE=false
if [[ "$OUT" == *.mir ]]; then
  OUT_IS_FILE=true
  mkdir -p "$(dirname "$OUT")"
else
  mkdir -p "$OUT"
fi

CARGO_ARGS=(+nightly rustc --manifest-path "$MANIFEST")
[[ -n "$CRATE" ]] && CARGO_ARGS+=("-p" "$CRATE")
[[ -n "$BIN_TARGET" ]] && CARGO_ARGS+=("--bin" "$BIN_TARGET")
[[ "$LIB_TARGET" == true ]] && CARGO_ARGS+=("--lib")

TARGET_DIR="${TMPDIR:-/tmp}/zeroize_rust_mir_${LEVEL}_$$"
rm -rf "$TARGET_DIR"
mkdir -p "$TARGET_DIR"

echo "=== emit_rust_mir.sh ==="
echo "manifest: $MANIFEST"
echo "opt:      $OPT"
echo "target:   $TARGET_DIR"
echo "output:   $OUT"

if ! CARGO_TARGET_DIR="$TARGET_DIR" cargo "${CARGO_ARGS[@]}" \
  "${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"}" \
  -- --emit=mir -C opt-level="$LEVEL"; then
  die_run "cargo rustc failed for opt=${OPT}"
fi

declare -a MIR_FILES=()
while IFS= read -r file; do
  MIR_FILES+=("$file")
done < <(find "$TARGET_DIR" -type f -name "*.mir" | LC_ALL=C sort)

[[ "${#MIR_FILES[@]}" -gt 0 ]] || die_run "no .mir files found under $TARGET_DIR"

if [[ "$OUT_IS_FILE" == true ]]; then
  : >"$OUT"
  for file in "${MIR_FILES[@]}"; do
    cat "$file" >>"$OUT"
  done
  [[ -s "$OUT" ]] || die_run "emitted MIR is empty: $OUT"
else
  cp "${MIR_FILES[@]}" "$OUT/"
fi

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.11"
# dependencies = []
# ///
"""
Extract per-TU compilation flags from compile_commands.json.

Reads the compile database for a given source file and emits the compilation
flags suitable for single-file LLVM IR or assembly emission via clang. Output
and dependency-generation flags are stripped.

Usage:
  uv run --no-project extract_compile_flags.py \\
    --compile-db compile_commands.json \\
    --src path/to/file.c \\
    [--format shell|json|lines] \\
    [--working-dir /override/cwd]

  # Recommended: capture as a bash array (works in both bash and zsh):
  FLAGS=()
  while IFS= read -r flag; do FLAGS+=("$flag"); done < <(
    uv run --no-project {baseDir}/tools/extract_compile_flags.py \\
      --compile-db build/compile_commands.json \\
      --src src/crypto.c --format lines)
  {baseDir}/tools/emit_ir.sh --src src/crypto.c --out /tmp/out.ll --opt O2 -- "${FLAGS[@]}"

  # Get as JSON list:
  uv run --no-project {baseDir}/tools/extract_compile_flags.py \\
    --compile-db build/compile_commands.json \\
    --src src/crypto.c \\
    --format json

Exit codes:
  0  flags written to stdout
  1  compile_commands.json not found or contains invalid JSON
  2  source file not found in the compile database
"""

import argparse
import contextlib
import json
import re
import shlex
import sys
from pathlib import Path

# ---------------------------------------------------------------------------
# Flags to strip: irrelevant or harmful for single-file IR/ASM emission.
# Ordering matters for the "takes an argument" set — we must skip the next
# token too.
# ---------------------------------------------------------------------------

# Flags that consume the next token as their argument and should be stripped.
_STRIP_WITH_ARG = frozenset(["-o", "-MF", "-MT", "-MQ"])

# Single-token flags to strip (no argument consumed).
_STRIP_STANDALONE = frozenset(
    [
        "-c",
        "-MD",
        "-MMD",
        "-MP",
        "-MG",
        "-pipe",
        "-save-temps",
        "-gsplit-dwarf",
    ]
)

# Prefix patterns: strip any flag whose string starts with one of these.
_STRIP_PREFIXES = (
    "-fcrash-diagnostics-dir",
    "-fmodule-file=",
    "-fmodules-cache-path=",
    "-fpch-preprocess",
    "--serialize-diagnostics",
    "-fdebug-prefix-map=",
    "--debug-prefix-map=",
    "-iprefix",
    "-iwithprefix",
    "-iwithprefixbefore",
    "-fprofile-generate",
    "-fprofile-use=",
    "-fprofile-instr-generate",
    "-fprofile-instr-use=",
    "-fcoverage-mapping",
)

# Regex for "attached" forms of strip-with-arg flags, e.g. "-MFdepfile" or "-MF=depfile".
# These are single tokens that begin with one of the strip-with-arg prefixes.
_STRIP_ATTACHED_RE = re.compile(r"^(?:-o|-MF|-MT|-MQ)(?:=?.+)$")


def _should_strip(flag: str) -> bool:
    """Return True if this flag token should be removed from the output."""
    if flag in _STRIP_STANDALONE:
        return True
    if _STRIP_ATTACHED_RE.match(flag):
        return True
    return any(flag.startswith(prefix) for prefix in _STRIP_PREFIXES)


def _extract_flags(raw_flags: list[str]) -> list[str]:
    """
    Filter a list of raw flag tokens (excluding the compiler executable at index 0
    and the source file argument) down to the build-relevant subset.
    """
    result: list[str] = []
    skip_next = False

    for token in raw_flags:
        if skip_next:
            skip_next = False
            continue

        # Strip-with-arg: consume this token and the next.
        if token in _STRIP_WITH_ARG:
            skip_next = True
            continue

        # Other strip conditions (standalone and prefixed).
        if _should_strip(token):
            continue

        result.append(token)

    return result


def _parse_command_string(command: str) -> list[str]:
    """Split a shell command string into tokens using POSIX shlex rules."""
    try:
        return shlex.split(command)
    except ValueError as exc:
        # Malformed quoting — best-effort split on whitespace.
        sys.stderr.write(f"Warning: shlex.split failed ({exc}), falling back to whitespace split\n")
        return command.split()


def _normalize_path(path_str: str, directory: str) -> Path:
    """Resolve a (possibly relative) path against a directory to an absolute Path."""
    p = Path(path_str)
    if not p.is_absolute():
        p = Path(directory) / p
    return p.resolve()


def find_entry(db: list, src: str, working_dir: str | None = None) -> dict | None:
    """
    Find the compile_commands.json entry for the given source file.

    Matching is done by resolving both the entry's 'file' field and the
    requested 'src' to absolute paths and comparing them.  The first match
    is returned (some projects emit duplicates for different configurations).
    """
    src_path = Path(src)
    if working_dir and not src_path.is_absolute():
        src_path = Path(working_dir) / src_path
    with contextlib.suppress(OSError):
        src_path = src_path.resolve()  # file may not exist on disk; compare string form

    for entry in db:
        entry_dir = entry.get("directory", "")
        entry_file = entry.get("file", "")
        try:
            entry_path = _normalize_path(entry_file, entry_dir)
        except OSError:
            entry_path = Path(entry_file)

        if entry_path == src_path:
            return entry

    # Second pass: basename comparison (handles minor path discrepancies).
    src_basename = src_path.name
    for entry in db:
        entry_file = entry.get("file", "")
        if Path(entry_file).name == src_basename:
            return entry

    return None


def get_raw_flags(entry: dict) -> list[str]:
    """
    Extract the raw flag tokens from a compile_commands.json entry.

    Returns all tokens except the compiler executable (index 0) and the
    source file argument.  The caller is responsible for further filtering.
    """
    arguments: list[str] | None = entry.get("arguments")
    if arguments is None:
        command = entry.get("command", "")
        arguments = _parse_command_string(command)

    if not arguments:
        return []

    # Drop compiler executable (index 0) and the source file token.
    src_file = entry.get("file", "")
    raw: list[str] = []
    for token in arguments[1:]:
        # Skip the source file itself (it will be specified via --src to emit_ir.sh).
        if token == src_file or (src_file and Path(token).name == Path(src_file).name):
            continue
        raw.append(token)

    return raw


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Extract per-TU compile flags from compile_commands.json.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument(
        "--compile-db",
        required=True,
        metavar="PATH",
        help="Path to compile_commands.json",
    )
    parser.add_argument(
        "--src",
        required=True,
        metavar="FILE",
        help="Source file to look up in the compile database",
    )
    parser.add_argument(
        "--format",
        choices=["shell", "json", "lines"],
        default="shell",
        help=(
            "Output format: 'shell' (space-separated, shell-quoted), 'json' list, "
            "or 'lines' (one flag per line, for array consumption) (default: shell)"
        ),
    )
    parser.add_argument(
        "--working-dir",
        metavar="DIR",
        default=None,
        help="Working directory for resolving relative --src paths (default: cwd)",
    )
    args = parser.parse_args()

    # Load compile database.
    db_path = Path(args.compile_db)
    if not db_path.exists():
        sys.stderr.write(f"Error: compile database not found: {db_path}\n")
        sys.exit(1)

    try:
        db = json.loads(db_path.read_text())
    except json.JSONDecodeError as exc:
        sys.stderr.write(f"Error: invalid JSON in {db_path}: {exc}\n")
        sys.exit(1)

    if not isinstance(db, list):
        sys.stderr.write(f"Error: expected a JSON array in {db_path}\n")
        sys.exit(1)

    # Find the entry for the requested source file.
    entry = find_entry(db, args.src, args.working_dir)
    if entry is None:
        sys.stderr.write(f"Error: '{args.src}' not found in {db_path} ({len(db)} entries)\n")
        sys.exit(2)

    # Extract and filter flags.
    raw = get_raw_flags(entry)
    flags = _extract_flags(raw)

    # Output.
    if args.format == "json":
        print(json.dumps(flags))
    elif args.format == "lines":
        for f in flags:
            print(f)
    else:
        # Shell format: space-join of individually shell-quoted tokens.
        print(" ".join(shlex.quote(f) for f in flags))


if __name__ == "__main__":
    main()

#!/usr/bin/env python3
# /// script
# requires-python = ">=3.10"
# dependencies = ["pyyaml>=6.0"]
# ///
"""
Generate proof-of-concept C programs from zeroize-audit findings.

Each PoC demonstrates that a finding is exploitable by reading sensitive
data that should have been zeroized. PoCs exit 0 when the secret persists
(exploitable) and exit 1 when the data has been wiped (not exploitable).

Usage:
  uv run --no-project generate_poc.py \\
    --findings <findings.json> \\
    --compile-db <compile_commands.json> \\
    --out <output_dir> \\
    [--categories CAT1,CAT2,...] \\
    [--config <config.yaml>]

Exit codes:
  0  PoCs generated successfully
  1  Invalid input (bad JSON, missing required fields)
  2  No exploitable findings in the selected categories
  3  Output directory error
"""

import argparse
import json
import os
import re
import subprocess
import sys
import textwrap
from pathlib import Path
from typing import Any

try:
    import yaml
except ImportError:
    yaml = None  # type: ignore[assignment]

# ---------------------------------------------------------------------------
# Categories that support PoC generation
# ---------------------------------------------------------------------------
EXPLOITABLE_CATEGORIES = frozenset(
    [
        "MISSING_SOURCE_ZEROIZE",
        "OPTIMIZED_AWAY_ZEROIZE",
        "STACK_RETENTION",
        "REGISTER_SPILL",
        "SECRET_COPY",
        "MISSING_ON_ERROR_PATH",
        "PARTIAL_WIPE",
        "NOT_ON_ALL_PATHS",
        "INSECURE_HEAP_ALLOC",
        "LOOP_UNROLLED_INCOMPLETE",
        "NOT_DOMINATING_EXITS",
    ]
)

# ---------------------------------------------------------------------------
# Defaults
# ---------------------------------------------------------------------------
_DEFAULT_SECRET_FILL: int = 0xAA
_DEFAULT_SOURCE_INCLUSION_THRESHOLD: int = 5000
_DEFAULT_STACK_PROBE_MAX: int = 4096
_DEFAULT_MIN_CONFIDENCE: str = "likely"

_CONFIDENCE_ORDER = {"confirmed": 0, "likely": 1, "needs_review": 2}

_TOOLS_DIR = Path(__file__).resolve().parent


# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------


def _load_config(config_path: str | None) -> dict[str, Any]:
    """Load a YAML config file and return the poc_generation section."""
    if not config_path:
        return {}
    path = Path(config_path)
    if yaml is None:
        sys.stderr.write(
            "Error: --config requires pyyaml. run via uv run --no-project, which provides pyyaml\n"
        )
        sys.exit(1)
    if not path.exists():
        sys.stderr.write(f"Error: config file not found: {path}\n")
        sys.exit(1)
    with open(path) as f:
        data = yaml.safe_load(f) or {}
    return data.get("poc_generation", {})


def _get_compile_flags(compile_db: str, src_file: str) -> list[str] | None:
    """Call extract_compile_flags.py and return flags as a list, or None on failure."""
    script = _TOOLS_DIR / "extract_compile_flags.py"
    if not script.exists():
        sys.stderr.write(f"Warning: compile flag extractor not found: {script}\n")
        return None
    try:
        result = subprocess.run(
            [
                sys.executable,
                str(script),
                "--compile-db",
                compile_db,
                "--src",
                src_file,
                "--format",
                "json",
            ],
            capture_output=True,
            text=True,
            timeout=30,
        )
        if result.returncode != 0:
            sys.stderr.write(
                f"Warning: extract_compile_flags.py exited with code {result.returncode}"
                f" for {src_file}\n"
            )
            return None
        return json.loads(result.stdout)
    except subprocess.TimeoutExpired:
        sys.stderr.write(f"Warning: extract_compile_flags.py timed out for {src_file}\n")
        return None
    except json.JSONDecodeError as exc:
        sys.stderr.write(
            f"Warning: extract_compile_flags.py returned invalid JSON for {src_file}: {exc}\n"
        )
        return None
    except OSError as exc:
        sys.stderr.write(f"Warning: failed to run extract_compile_flags.py for {src_file}: {exc}\n")
        return None


def _count_lines(path: str) -> int:
    """Return the number of lines in a file, or 0 if unreadable."""
    try:
        with open(path) as f:
            return sum(1 for _ in f)
    except OSError:
        return 0


def _extract_function_signature(src_file: str, line: int) -> str | None:
    """
    Attempt to extract the function signature surrounding the given line number.
    Returns the function name if found, or None.
    """
    try:
        with open(src_file) as f:
            lines = f.readlines()
    except OSError:
        return None

    # Search backwards from the finding line to find a function definition
    start = max(0, line - 30)
    end = min(len(lines), line + 5)
    region = "".join(lines[start:end])

    # Match C/C++ function definitions: return_type func_name(params) {
    pattern = re.compile(
        r"(?:^|\n)\s*"
        r"(?:static\s+|inline\s+|extern\s+|__attribute__\s*\([^)]*\)\s+)*"
        r"(?:(?:const\s+|unsigned\s+|signed\s+|volatile\s+)*\w[\w\s*&]*?)\s+"
        r"(\w+)\s*\([^)]*\)\s*(?:\{|$)",
        re.MULTILINE,
    )
    matches = list(pattern.finditer(region))
    if matches:
        return matches[-1].group(1)
    return None


def _is_cpp_file(src_file: str) -> bool:
    """Return True if the source file appears to be C++."""
    ext = Path(src_file).suffix.lower()
    return ext in (".cpp", ".cxx", ".cc", ".C", ".hpp", ".hxx")


def _is_rust_file(src_file: str) -> bool:
    """Return True if the source file appears to be Rust."""
    return Path(src_file).suffix.lower() == ".rs"


def _relative_source_path(src_file: str, out_dir: str) -> str:
    """Compute a relative path from out_dir to src_file."""
    try:
        return os.path.relpath(src_file, out_dir)
    except ValueError:
        return src_file


# ---------------------------------------------------------------------------
# poc_common.h generation
# ---------------------------------------------------------------------------


def _generate_common_header(
    secret_fill: int = _DEFAULT_SECRET_FILL, stack_probe_max: int = _DEFAULT_STACK_PROBE_MAX
) -> str:
    return textwrap.dedent(f"""\
        #ifndef POC_COMMON_H
        #define POC_COMMON_H

        #include <stdio.h>
        #include <stdlib.h>
        #include <string.h>
        #include <stdint.h>

        #define SECRET_FILL_BYTE 0x{secret_fill:02X}
        #define STACK_PROBE_MAX  {stack_probe_max}

        #define POC_PASS() do {{ \\
            fprintf(stderr, "POC PASS: secret persists (exploitable)\\n"); \\
            exit(0); \\
        }} while (0)

        #define POC_FAIL() do {{ \\
            fprintf(stderr, "POC FAIL: secret was wiped (not exploitable)\\n"); \\
            exit(1); \\
        }} while (0)

        /* Read through a volatile pointer to prevent the compiler from
           optimizing away the verification read. Returns non-zero if any
           byte in [ptr, ptr+len) is non-zero. */
        static int volatile_read_nonzero(const void *ptr, size_t len) {{
            const volatile unsigned char *p = (const volatile unsigned char *)ptr;
            int found = 0;
            for (size_t i = 0; i < len; i++) {{
                if (p[i] != 0) {{
                    found = 1;
                }}
            }}
            return found;
        }}

        /* Read through volatile pointer checking for the secret fill pattern. */
        static int volatile_read_has_secret(const void *ptr, size_t len) {{
            const volatile unsigned char *p = (const volatile unsigned char *)ptr;
            int count = 0;
            for (size_t i = 0; i < len; i++) {{
                if (p[i] == SECRET_FILL_BYTE) {{
                    count++;
                }}
            }}
            /* Consider it a match if >= 50% of bytes are the fill pattern */
            return count >= (int)(len / 2);
        }}

        /* Dump hex to stderr for diagnostics. */
        static void hex_dump(const char *label, const void *ptr, size_t len) {{
            const unsigned char *p = (const unsigned char *)ptr;
            fprintf(stderr, "%s (%zu bytes):", label, len);
            for (size_t i = 0; i < len && i < 64; i++) {{
                if (i % 16 == 0) fprintf(stderr, "\\n  ");
                fprintf(stderr, "%02x ", p[i]);
            }}
            if (len > 64) fprintf(stderr, "\\n  ... (%zu more bytes)", len - 64);
            fprintf(stderr, "\\n");
        }}

        /* Probe the stack for residual secret data from a prior call frame.
           Must be __attribute__((noinline, noclone)) so the compiler cannot
           merge this frame with the caller. */
        __attribute__((noinline))
        #if defined(__GNUC__) && !defined(__clang__)
        __attribute__((noclone))
        #endif
        static int stack_probe(size_t frame_size) {{
            if (frame_size > STACK_PROBE_MAX) frame_size = STACK_PROBE_MAX;
            volatile unsigned char probe[STACK_PROBE_MAX];
            /* Do NOT initialize — we want to read whatever is on the stack */
            int count = 0;
            for (size_t i = 0; i < frame_size; i++) {{
                if (probe[i] == SECRET_FILL_BYTE) {{
                    count++;
                }}
            }}
            return count >= (int)(frame_size / 4);  /* 25% threshold */
        }}

        /* Fill a buffer with the secret marker pattern. */
        static void fill_secret(void *buf, size_t len) {{
            memset(buf, SECRET_FILL_BYTE, len);
        }}

        /* Check whether heap memory retains secret data after free+realloc.
           Do NOT compile with ASan — it poisons freed memory and hides the bug. */
        static int heap_residue_check(size_t alloc_size) {{
            void *ptr = malloc(alloc_size);
            if (!ptr) return 0;
            fill_secret(ptr, alloc_size);
            free(ptr);
            void *ptr2 = malloc(alloc_size);
            if (!ptr2) return 0;
            int found = volatile_read_has_secret(ptr2, alloc_size);
            hex_dump("Heap residue after free+realloc", ptr2,
                     alloc_size > 64 ? 64 : alloc_size);
            free(ptr2);
            return found;
        }}

        #endif /* POC_COMMON_H */
    """)


# ---------------------------------------------------------------------------
# Per-category PoC generators
# ---------------------------------------------------------------------------


class PoCGenerator:
    """Base class for per-category PoC generators."""

    category: str = ""
    opt_level: str = "-O0"

    def __init__(
        self, finding: dict[str, Any], compile_db: str, out_dir: str, config: dict[str, Any]
    ):
        self.finding = finding
        self.compile_db = compile_db
        self.out_dir = out_dir
        self.config = config
        self.finding_id = finding.get("id", "unknown")
        self.src_file = finding.get("file", "")
        self.line = finding.get("line", 0)
        self.symbol = finding.get("symbol")
        self.requires_manual = False
        self.adjustment_notes: str | None = None

    def _func_name(self) -> str | None:
        if self.symbol:
            return self.symbol
        return _extract_function_signature(self.src_file, self.line)

    def _source_include_path(self) -> str:
        return _relative_source_path(self.src_file, self.out_dir)

    def _use_source_inclusion(self) -> bool:
        threshold = self.config.get(
            "source_inclusion_threshold", _DEFAULT_SOURCE_INCLUSION_THRESHOLD
        )
        return _count_lines(self.src_file) <= threshold

    def _flags_str(self) -> str:
        flags = _get_compile_flags(self.compile_db, self.src_file)
        if flags is None:
            return ""
        # Filter out optimization flags — we set our own
        return " ".join(f for f in flags if not re.match(r"^-O[0-3sg]$", f))

    def _poc_filename(self) -> str:
        safe_id = re.sub(r"[^a-zA-Z0-9_-]", "_", self.finding_id)
        ext = ".cpp" if _is_cpp_file(self.src_file) else ".c"
        return f"poc_{safe_id}_{self.category.lower()}{ext}"

    def _compiler_var(self) -> str:
        return "$(CXX)" if _is_cpp_file(self.src_file) else "$(CC)"

    def _include_directive(self) -> str:
        func = self._func_name()
        if self._use_source_inclusion():
            return f'#include "{self._source_include_path()}"'
        return f"/* Link against object file containing {func or 'target function'} */"

    def _build_poc_source(self, comment_lines: list[str], body_lines: list[str]) -> str:
        """Assemble a PoC C source file with correct indentation."""
        parts: list[str] = []
        parts.append("/* " + comment_lines[0])
        for cl in comment_lines[1:]:
            parts.append(" * " + cl)
        parts.append(" */")
        parts.append('#include "poc_common.h"')
        parts.append(self._include_directive())
        parts.append("")
        parts.append("int main(void) {")
        for bl in body_lines:
            if bl == "":
                parts.append("")
            else:
                parts.append("    " + bl)
        parts.append("}")
        parts.append("")
        return "\n".join(parts)

    def generate(self) -> tuple[str, str]:
        """Generate PoC source code. Returns (filename, source_code)."""
        raise NotImplementedError

    def makefile_target(self, filename: str) -> str:
        """Return a Makefile target string for this PoC."""
        binary = Path(filename).stem
        flags = self._flags_str()
        compiler = self._compiler_var()
        return (
            f"{binary}: {filename} poc_common.h\n\t{compiler} {self.opt_level} {flags} -o $@ $<\n"
        )

    def manifest_entry(self, filename: str) -> dict[str, Any]:
        """Return a manifest entry for this PoC."""
        entry: dict[str, Any] = {
            "finding_id": self.finding_id,
            "category": self.category,
            "file": filename,
            "makefile_target": Path(filename).stem,
            "compile_opt": self.opt_level,
            "requires_manual_adjustment": self.requires_manual,
        }
        if self.adjustment_notes:
            entry["adjustment_notes"] = self.adjustment_notes
        return entry


class MissingSourceZeroizePoC(PoCGenerator):
    category = "MISSING_SOURCE_ZEROIZE"
    opt_level = "-O0"

    def generate(self) -> tuple[str, str]:
        func = self._func_name()
        filename = self._poc_filename()
        comment = [
            f"PoC for finding {self.finding_id}: {self.category}",
            f"Source: {self.src_file}:{self.line}",
            "Strategy: Call function at -O0, volatile-read buffer after return,",
            "          verify secret persists.",
        ]

        if func:
            body = [
                "unsigned char secret_buf[256];",
                "fill_secret(secret_buf, sizeof(secret_buf));",
                "",
                "/* Call the function that handles the secret */",
                f"{func}(/* TODO: fill in arguments */);",
                "",
                "/* Check if the secret buffer still contains data */",
                "if (volatile_read_nonzero(secret_buf, sizeof(secret_buf)))",
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                f"Fill in arguments for {func}() call and adjust "
                "secret_buf to point to the actual sensitive variable."
            )
        else:
            body = [
                "/* TODO: call the function that handles the secret */",
                "/* TODO: volatile-read the secret buffer after return */",
                "/* if (volatile_read_nonzero(ptr, len)) POC_PASS(); else POC_FAIL(); */",
                'fprintf(stderr, "PoC requires manual adjustment\\n");',
                "exit(1);",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                "Could not determine function signature. "
                "Fill in function call and secret buffer check."
            )

        return filename, self._build_poc_source(comment, body)


class OptimizedAwayZeroizePoC(PoCGenerator):
    category = "OPTIMIZED_AWAY_ZEROIZE"

    def __init__(self, *args: Any, **kwargs: Any):
        super().__init__(*args, **kwargs)
        compiler_ev = self.finding.get("compiler_evidence", {}) or {}
        diff_summary = compiler_ev.get("diff_summary", "")
        match = re.search(r"O([1-3s])", diff_summary)
        if match:
            self.opt_level = f"-O{match.group(1)}"
        else:
            self.opt_level = "-O2"

    def generate(self) -> tuple[str, str]:
        func = self._func_name()
        filename = self._poc_filename()
        comment = [
            f"PoC for finding {self.finding_id}: {self.category}",
            f"Source: {self.src_file}:{self.line}",
            f"Strategy: Compile at {self.opt_level} where the wipe vanishes,",
            "          call function, volatile-read buffer.",
        ]

        if func:
            body = [
                "unsigned char secret_buf[256];",
                "fill_secret(secret_buf, sizeof(secret_buf));",
                "",
                "/* Call function that contains the wipe the compiler removes */",
                f"{func}(/* TODO: fill in arguments */);",
                "",
                "/* At this opt level the compiler has removed the wipe.",
                "   Volatile-read the buffer to see if secret persists. */",
                "if (volatile_read_nonzero(secret_buf, sizeof(secret_buf)))",
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                f"Fill in arguments for {func}(). "
                f"Compile at {self.opt_level} where the wipe disappears."
            )
        else:
            body = [
                "/* TODO: call function whose wipe is optimized away */",
                'fprintf(stderr, "PoC requires manual adjustment\\n");',
                "exit(1);",
            ]
            self.requires_manual = True
            self.adjustment_notes = "Could not determine function signature."

        return filename, self._build_poc_source(comment, body)


class StackRetentionPoC(PoCGenerator):
    category = "STACK_RETENTION"
    opt_level = "-O2"

    def generate(self) -> tuple[str, str]:
        func = self._func_name()
        filename = self._poc_filename()
        evidence = self.finding.get("evidence", "")
        frame_match = re.search(r"(\d+)\s*bytes?\s*(?:frame|stack|alloc)", evidence)
        frame_size = frame_match.group(1) if frame_match else "256"

        comment = [
            f"PoC for finding {self.finding_id}: {self.category}",
            f"Source: {self.src_file}:{self.line}",
            "Strategy: Call function, immediately call stack_probe() with",
            "          matching frame size to detect residual secrets.",
        ]

        if func:
            body = [
                "/* Call the function that leaves secrets on the stack */",
                f"{func}(/* TODO: fill in arguments */);",
                "",
                "/* Immediately probe the stack for residual secret data */",
                f"if (stack_probe({frame_size}))",
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                f"Fill in arguments for {func}(). "
                f"Frame size {frame_size} is estimated from evidence; adjust if needed."
            )
        else:
            body = [
                "/* TODO: call the function that retains secrets on stack */",
                f"if (stack_probe({frame_size}))",
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = "Could not determine function signature."

        return filename, self._build_poc_source(comment, body)


class RegisterSpillPoC(PoCGenerator):
    category = "REGISTER_SPILL"
    opt_level = "-O2"

    def generate(self) -> tuple[str, str]:
        func = self._func_name()
        filename = self._poc_filename()
        evidence = self.finding.get("evidence", "")
        offset_match = re.search(r"-(\d+)\(%[re][sb]p\)", evidence)
        spill_offset = offset_match.group(1) if offset_match else "64"

        comment = [
            f"PoC for finding {self.finding_id}: {self.category}",
            f"Source: {self.src_file}:{self.line}",
            "Strategy: Like stack retention but probe the specific spill",
            "          offset region from ASM evidence.",
        ]

        if func:
            body = [
                "/* Call the function that spills secrets to stack */",
                f"{func}(/* TODO: fill in arguments */);",
                "",
                "/* Probe the specific spill offset region */",
                f"if (stack_probe({spill_offset}))",
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                f"Fill in arguments for {func}(). "
                f"Spill offset {spill_offset} from ASM evidence; adjust if needed."
            )
        else:
            body = [
                "/* TODO: call the function that spills registers to stack */",
                f"if (stack_probe({spill_offset}))",
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = "Could not determine function signature."

        return filename, self._build_poc_source(comment, body)


class SecretCopyPoC(PoCGenerator):
    category = "SECRET_COPY"
    opt_level = "-O0"

    def generate(self) -> tuple[str, str]:
        func = self._func_name()
        filename = self._poc_filename()
        comment = [
            f"PoC for finding {self.finding_id}: {self.category}",
            f"Source: {self.src_file}:{self.line}",
            "Strategy: Call function at -O0, verify original may be wiped,",
            "          volatile-read the copy destination.",
        ]

        if func:
            body = [
                "/* Call function; it copies the secret internally */",
                f"{func}(/* TODO: fill in arguments */);",
                "",
                "/* The original may be wiped, but the copy destination persists.",
                "   TODO: point this at the actual copy destination buffer. */",
                "unsigned char *copy_dest = NULL; /* TODO: set to copy destination */",
                "if (copy_dest && volatile_read_has_secret(copy_dest, 256))",
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                f"Fill in arguments for {func}() and set copy_dest to "
                "point to the buffer where the secret is copied."
            )
        else:
            body = [
                "/* TODO: call the function that copies the secret */",
                "/* TODO: volatile-read the copy destination after return */",
                'fprintf(stderr, "PoC requires manual adjustment\\n");',
                "exit(1);",
            ]
            self.requires_manual = True
            self.adjustment_notes = "Could not determine function signature or copy destination."

        return filename, self._build_poc_source(comment, body)


class MissingOnErrorPathPoC(PoCGenerator):
    category = "MISSING_ON_ERROR_PATH"
    opt_level = "-O0"

    def generate(self) -> tuple[str, str]:
        func = self._func_name()
        filename = self._poc_filename()
        comment = [
            f"PoC for finding {self.finding_id}: {self.category}",
            f"Source: {self.src_file}:{self.line}",
            "Strategy: Force the error path via controlled input,",
            "          volatile-read buffer after error return.",
        ]

        if func:
            body = [
                "unsigned char secret_buf[256];",
                "fill_secret(secret_buf, sizeof(secret_buf));",
                "",
                "/* Force the error path via controlled input.",
                "   TODO: set up inputs that trigger the error return. */",
                f"int ret = {func}(/* TODO: error-triggering arguments */);",
                "",
                'fprintf(stderr, "Function returned: %d\\n", ret);',
                'hex_dump("Secret buffer after error return", secret_buf,',
                "         sizeof(secret_buf));",
                "",
                "/* After error return the secret should have been wiped */",
                "if (volatile_read_has_secret(secret_buf, sizeof(secret_buf)))",
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                f"Fill in error-triggering arguments for {func}(). "
                "The error path must be taken to demonstrate missing cleanup."
            )
        else:
            body = [
                "/* TODO: call function with error-triggering inputs */",
                "/* TODO: volatile-read buffer after error return */",
                'fprintf(stderr, "PoC requires manual adjustment\\n");',
                "exit(1);",
            ]
            self.requires_manual = True
            self.adjustment_notes = "Could not determine function signature."

        return filename, self._build_poc_source(comment, body)


class PartialWipePoC(PoCGenerator):
    category = "PARTIAL_WIPE"
    opt_level = "-O0"

    def generate(self) -> tuple[str, str]:
        func = self._func_name()
        filename = self._poc_filename()
        evidence = self.finding.get("evidence", "")

        # Try to extract wiped vs full sizes from evidence
        size_matches = re.findall(r"(\d+)\s*bytes?", evidence)
        if len(size_matches) >= 2:
            wiped_size = size_matches[0]
            full_size = size_matches[1]
        else:
            wiped_size = "8"
            full_size = "256"

        comment = [
            f"PoC for finding {self.finding_id}: {self.category}",
            f"Source: {self.src_file}:{self.line}",
            "Strategy: Fill full buffer with secret, call function, volatile-read",
            "          the tail beyond the incorrectly-sized wipe.",
        ]

        if func:
            body = [
                f"unsigned char buf[{full_size}];",
                f"fill_secret(buf, {full_size});",
                "",
                "/* Call function that partially wipes the buffer */",
                f"{func}(/* TODO: fill in arguments */);",
                "",
                f"/* The wipe covers only {wiped_size} bytes of {full_size}.",
                "   Check the tail beyond the wiped region. */",
                f"if (volatile_read_has_secret(buf + {wiped_size}, {full_size} - {wiped_size}))",
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                f"Fill in arguments for {func}(). "
                f"Wiped size {wiped_size} and full size {full_size} are estimated "
                "from evidence; adjust if needed."
            )
        else:
            body = [
                f"unsigned char buf[{full_size}];",
                f"fill_secret(buf, {full_size});",
                "",
                "/* TODO: call the function that partially wipes the buffer */",
                "",
                f"/* Check tail beyond the {wiped_size}-byte wipe */",
                f"if (volatile_read_has_secret(buf + {wiped_size}, {full_size} - {wiped_size}))",
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                "Could not determine function signature. "
                f"Wiped size {wiped_size} and full size {full_size} are estimated; "
                "adjust if needed."
            )

        return filename, self._build_poc_source(comment, body)


class NotOnAllPathsPoC(PoCGenerator):
    category = "NOT_ON_ALL_PATHS"
    opt_level = "-O0"

    def generate(self) -> tuple[str, str]:
        func = self._func_name()
        filename = self._poc_filename()
        evidence = self.finding.get("evidence", "")

        # Try to extract uncovered path line from evidence
        line_match = re.search(r"line (\d+)", evidence)
        uncovered_line = line_match.group(1) if line_match else "unknown"

        comment = [
            f"PoC for finding {self.finding_id}: {self.category}",
            f"Source: {self.src_file}:{self.line}",
            "Strategy: Force execution down the uncovered path that lacks the wipe,",
            "          then volatile-read the secret buffer.",
        ]

        if func:
            body = [
                "unsigned char secret_buf[256];",
                "fill_secret(secret_buf, sizeof(secret_buf));",
                "",
                "/* Force the uncovered path (no wipe).",
                f"   TODO: set up inputs that take the path at line {uncovered_line}. */",
                f"{func}(/* TODO: path-forcing arguments */);",
                "",
                "/* After taking the uncovered path the secret should persist */",
                "if (volatile_read_has_secret(secret_buf, sizeof(secret_buf)))",
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                f"Fill in arguments for {func}() that force execution through "
                f"the uncovered path (line {uncovered_line}). "
                "Identify which inputs bypass the wipe."
            )
        else:
            body = [
                "/* TODO: call function with inputs that take the uncovered path */",
                "/* TODO: volatile-read buffer after return */",
                'fprintf(stderr, "PoC requires manual adjustment\\n");',
                "exit(1);",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                "Could not determine function signature. "
                "Identify inputs that force the uncovered path."
            )

        return filename, self._build_poc_source(comment, body)


class InsecureHeapAllocPoC(PoCGenerator):
    category = "INSECURE_HEAP_ALLOC"
    opt_level = "-O0"

    def generate(self) -> tuple[str, str]:
        func = self._func_name()
        filename = self._poc_filename()
        evidence = self.finding.get("evidence", "")

        # Extract allocation size and allocator from evidence
        size_match = re.search(r"(\d+)", evidence)
        alloc_size = size_match.group(1) if size_match else "256"
        alloc_match = re.search(r"(malloc|calloc|realloc)", evidence)
        allocator = alloc_match.group(1) if alloc_match else "malloc"

        comment = [
            f"PoC for finding {self.finding_id}: {self.category}",
            f"Source: {self.src_file}:{self.line}",
            "Strategy: Demonstrate heap residue — allocate, fill with secret, free,",
            "          re-allocate same size, check if secret persists.",
            "NOTE: Do NOT compile with ASan (it poisons freed memory).",
        ]

        body = [
            f"/* Demonstrate that {allocator}() leaves secret residue after free */",
            f"if (heap_residue_check({alloc_size}))",
            "    POC_PASS();",
            "else",
            "    POC_FAIL();",
        ]

        if func:
            body.extend(
                [
                    "",
                    "/* Additionally, call the function that uses the insecure allocator",
                    "   and verify residue after it returns. */",
                    f"/* {func}(/ * TODO: fill in arguments * /); */",
                ]
            )
            self.requires_manual = False  # Self-contained heap check works
            self.adjustment_notes = (
                f"The self-contained heap_residue_check() demonstrates the "
                f"vulnerability. Optionally uncomment and fill in {func}() "
                "for a function-specific test."
            )
        else:
            self.requires_manual = False
            self.adjustment_notes = (
                f"Self-contained PoC using heap_residue_check({alloc_size}). "
                "Optionally add a call to the target function for specificity."
            )

        return filename, self._build_poc_source(comment, body)


class LoopUnrolledIncompletePoC(PoCGenerator):
    category = "LOOP_UNROLLED_INCOMPLETE"
    opt_level = "-O2"

    def generate(self) -> tuple[str, str]:
        func = self._func_name()
        filename = self._poc_filename()
        evidence = self.finding.get("evidence", "")

        # Extract covered bytes and object size from evidence
        covered_match = re.search(r"(\d+)\s*consecutive", evidence)
        covered_bytes = covered_match.group(1) if covered_match else "16"
        size_match = re.search(r"object size is (\d+)", evidence)
        full_size = size_match.group(1) if size_match else "256"

        comment = [
            f"PoC for finding {self.finding_id}: {self.category}",
            f"Source: {self.src_file}:{self.line}",
            "Strategy: Compile at -O2 where incomplete loop unrolling occurs.",
            f"          Fill buffer, call function, check tail beyond {covered_bytes}",
            f"          unrolled bytes (object size: {full_size}).",
        ]

        if func:
            body = [
                f"unsigned char buf[{full_size}];",
                f"fill_secret(buf, {full_size});",
                "",
                "/* Call function whose wipe loop is incompletely unrolled at -O2 */",
                f"{func}(/* TODO: fill in arguments */);",
                "",
                f"/* The compiler unrolled {covered_bytes} bytes of the wipe loop",
                f"   but the object is {full_size} bytes. Check the tail. */",
                (
                    f"if (volatile_read_has_secret(buf + {covered_bytes},"
                    f" {full_size} - {covered_bytes}))"
                ),
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                f"Fill in arguments for {func}(). "
                f"Covered bytes {covered_bytes} and object size {full_size} are "
                "estimated from IR evidence; adjust if needed. "
                "Must compile at -O2 for unrolling to occur."
            )
        else:
            body = [
                f"unsigned char buf[{full_size}];",
                f"fill_secret(buf, {full_size});",
                "",
                "/* TODO: call function with incompletely unrolled wipe loop */",
                "",
                f"/* Check tail beyond the {covered_bytes}-byte unrolled region */",
                (
                    f"if (volatile_read_has_secret(buf + {covered_bytes},"
                    f" {full_size} - {covered_bytes}))"
                ),
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                "Could not determine function signature. "
                f"Covered bytes {covered_bytes} and object size {full_size} are "
                "estimated; adjust if needed."
            )

        return filename, self._build_poc_source(comment, body)


class NotDominatingExitsPoC(PoCGenerator):
    category = "NOT_DOMINATING_EXITS"
    opt_level = "-O0"

    def generate(self) -> tuple[str, str]:
        func = self._func_name()
        filename = self._poc_filename()
        evidence = self.finding.get("evidence", "")

        # Extract exit line or path count from CFG evidence
        exit_match = re.search(r"exit at line (\d+)", evidence)
        path_match = re.search(r"(\d+) of (\d+) exit paths", evidence)
        if exit_match:
            exit_info = f"line {exit_match.group(1)}"
        elif path_match:
            exit_info = f"{path_match.group(1)} of {path_match.group(2)} exit paths"
        else:
            exit_info = "an exit path that bypasses the wipe"

        comment = [
            f"PoC for finding {self.finding_id}: {self.category}",
            f"Source: {self.src_file}:{self.line}",
            "Strategy: Force execution through an exit path that bypasses the wipe",
            f"          (CFG evidence: {exit_info}), then volatile-read the secret.",
        ]

        if func:
            body = [
                "unsigned char secret_buf[256];",
                "fill_secret(secret_buf, sizeof(secret_buf));",
                "",
                "/* Force execution through the exit path that bypasses the wipe.",
                f"   CFG shows the wipe does not dominate {exit_info}.",
                "   TODO: set up inputs that reach this exit path. */",
                f"{func}(/* TODO: exit-path-forcing arguments */);",
                "",
                "/* After taking the non-dominated exit the secret should persist */",
                "if (volatile_read_has_secret(secret_buf, sizeof(secret_buf)))",
                "    POC_PASS();",
                "else",
                "    POC_FAIL();",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                f"Fill in arguments for {func}() that force execution through "
                f"{exit_info} (the exit not dominated by the wipe). "
                "Requires understanding of the function's control flow."
            )
        else:
            body = [
                "/* TODO: call function with inputs that reach the non-dominated exit */",
                "/* TODO: volatile-read buffer after return */",
                'fprintf(stderr, "PoC requires manual adjustment\\n");',
                "exit(1);",
            ]
            self.requires_manual = True
            self.adjustment_notes = (
                "Could not determine function signature. "
                "Identify inputs that reach the exit path bypassing the wipe."
            )

        return filename, self._build_poc_source(comment, body)


# ---------------------------------------------------------------------------
# Category -> generator mapping
# ---------------------------------------------------------------------------
_GENERATORS: dict[str, type] = {
    "MISSING_SOURCE_ZEROIZE": MissingSourceZeroizePoC,
    "OPTIMIZED_AWAY_ZEROIZE": OptimizedAwayZeroizePoC,
    "STACK_RETENTION": StackRetentionPoC,
    "REGISTER_SPILL": RegisterSpillPoC,
    "SECRET_COPY": SecretCopyPoC,
    "MISSING_ON_ERROR_PATH": MissingOnErrorPathPoC,
    "PARTIAL_WIPE": PartialWipePoC,
    "NOT_ON_ALL_PATHS": NotOnAllPathsPoC,
    "INSECURE_HEAP_ALLOC": InsecureHeapAllocPoC,
    "LOOP_UNROLLED_INCOMPLETE": LoopUnrolledIncompletePoC,
    "NOT_DOMINATING_EXITS": NotDominatingExitsPoC,
}


# ---------------------------------------------------------------------------
# Makefile generation
# ---------------------------------------------------------------------------


def _generate_makefile(targets: list[dict[str, str]]) -> str:
    """Generate a Makefile for all PoC targets."""
    lines = [
        "# Auto-generated by generate_poc.py",
        "# Build: make all",
        "# Run:   make run",
        "",
        "CC ?= cc",
        "CXX ?= c++",
        "CFLAGS ?= -Wall -Wextra",
        "CXXFLAGS ?= -Wall -Wextra",
        "",
        "BINARIES =",
    ]

    binary_names = []
    target_blocks = []

    for t in targets:
        binary = t["binary"]
        binary_names.append(binary)
        target_blocks.append(t["rule"])

    lines[9] = "BINARIES = " + " ".join(binary_names)
    lines.append("")
    lines.append(".PHONY: all run clean")
    lines.append("")
    lines.append("all: $(BINARIES)")
    lines.append("")

    # Run target
    lines.append("run: all")
    for name in binary_names:
        lines.append(f"\t@echo '--- Running {name} ---'")
        lines.append(f"\t@./{name} && echo 'RESULT: EXPLOITABLE' || echo 'RESULT: NOT EXPLOITABLE'")
    lines.append("")

    # Per-target rules
    for block in target_blocks:
        lines.append(block)
        lines.append("")

    lines.append("clean:")
    lines.append("\trm -f $(BINARIES)")
    lines.append("")

    return "\n".join(lines)


# ---------------------------------------------------------------------------
# Main logic
# ---------------------------------------------------------------------------


def _filter_findings(
    findings: list[dict[str, Any]], categories: frozenset, min_confidence: str | None
) -> list[dict[str, Any]]:
    """Filter findings to only exploitable categories above confidence threshold.

    When min_confidence is None, all findings in the selected categories are
    returned regardless of confidence level.
    """
    result = []
    for f in findings:
        cat = f.get("category", "")
        if cat not in categories:
            continue
        if min_confidence is None:
            result.append(f)
            continue
        threshold = _CONFIDENCE_ORDER.get(min_confidence, 2)
        # Map needs_review boolean to confidence string
        conf = "needs_review" if f.get("needs_review", False) else "likely"
        # Check evidence/compiler_evidence for confirmed signals
        if f.get("compiler_evidence"):
            conf = "confirmed"
        # CFG-backed findings use evidence_source instead of compiler_evidence
        evidence_sources = f.get("evidence_source", [])
        if isinstance(evidence_sources, list) and "cfg" in evidence_sources:
            conf = "confirmed"
        if _CONFIDENCE_ORDER.get(conf, 2) <= threshold:
            result.append(f)
    return result


def run(
    findings_path: str,
    compile_db: str,
    out_dir: str,
    categories: list[str] | None = None,
    config_path: str | None = None,
    no_confidence_filter: bool = False,
) -> int:
    """Main entry point. Returns exit code.

    Args:
        no_confidence_filter: When True, generate PoCs for all findings
            regardless of confidence level.
    """

    # Load findings
    try:
        with open(findings_path) as f:
            data = json.load(f)
    except (OSError, json.JSONDecodeError) as exc:
        sys.stderr.write(f"Error: cannot read findings: {exc}\n")
        return 1

    # Support both top-level array and {findings: [...]} format
    if isinstance(data, list):
        findings = data
    elif isinstance(data, dict):
        findings = data.get("findings", [])
    else:
        sys.stderr.write("Error: findings must be a JSON array or object with 'findings' key\n")
        return 1

    # Load config
    config = _load_config(config_path)
    min_confidence: str | None = (
        None if no_confidence_filter else config.get("min_confidence", _DEFAULT_MIN_CONFIDENCE)
    )
    secret_fill = config.get("secret_fill_byte", _DEFAULT_SECRET_FILL)
    stack_probe_max = config.get("stack_probe_max_size", _DEFAULT_STACK_PROBE_MAX)

    # Determine categories
    if categories:
        selected = frozenset(categories) & EXPLOITABLE_CATEGORIES
    else:
        selected = EXPLOITABLE_CATEGORIES

    # Filter findings
    exploitable = _filter_findings(findings, selected, min_confidence)
    if not exploitable:
        sys.stderr.write("No exploitable findings found in selected categories.\n")
        return 2

    # Create output directory
    try:
        os.makedirs(out_dir, exist_ok=True)
    except OSError as exc:
        sys.stderr.write(f"Error: cannot create output directory: {exc}\n")
        return 3

    # Write poc_common.h
    common_h = _generate_common_header(secret_fill, stack_probe_max)
    with open(os.path.join(out_dir, "poc_common.h"), "w") as f:
        f.write(common_h)

    # Generate PoCs
    makefile_targets: list[dict[str, str]] = []
    manifest_entries: list[dict[str, Any]] = []
    generated_count = 0
    manual_count = 0

    for finding in exploitable:
        cat = finding.get("category", "")
        gen_cls = _GENERATORS.get(cat)
        if gen_cls is None:
            continue

        gen = gen_cls(finding, compile_db, out_dir, config)
        filename, source = gen.generate()

        # Write PoC source
        poc_path = os.path.join(out_dir, filename)
        with open(poc_path, "w") as f:
            f.write(source)

        # Collect Makefile target
        binary = Path(filename).stem
        makefile_targets.append(
            {
                "binary": binary,
                "rule": gen.makefile_target(filename),
            }
        )

        # Collect manifest entry
        manifest_entries.append(gen.manifest_entry(filename))

        generated_count += 1
        if gen.requires_manual:
            manual_count += 1

    # Write Makefile
    makefile_content = _generate_makefile(makefile_targets)
    with open(os.path.join(out_dir, "Makefile"), "w") as f:
        f.write(makefile_content)

    # Write manifest
    manifest = {
        "pocs_generated": generated_count,
        "pocs_requiring_adjustment": manual_count,
        "output_dir": out_dir,
        "categories_covered": sorted(set(e["category"] for e in manifest_entries)),
        "entries": manifest_entries,
    }
    with open(os.path.join(out_dir, "poc_manifest.json"), "w") as f:
        json.dump(manifest, f, indent=2)
        f.write("\n")

    # Summary
    sys.stderr.write(
        f"Generated {generated_count} PoC(s) in {out_dir}/ "
        f"({manual_count} requiring manual adjustment)\n"
    )
    return 0


def main() -> None:
    parser = argparse.ArgumentParser(
        description="Generate proof-of-concept programs from zeroize-audit findings.",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=__doc__,
    )
    parser.add_argument(
        "--findings",
        required=True,
        metavar="PATH",
        help="Path to findings JSON (array or {findings: [...]})",
    )
    parser.add_argument(
        "--compile-db",
        required=True,
        metavar="PATH",
        help="Path to compile_commands.json",
    )
    parser.add_argument(
        "--out",
        required=True,
        metavar="DIR",
        help="Output directory for generated PoCs",
    )
    parser.add_argument(
        "--categories",
        metavar="CAT1,CAT2,...",
        default=None,
        help="Comma-separated list of finding categories (default: all exploitable)",
    )
    parser.add_argument(
        "--config",
        metavar="PATH",
        default=None,
        help="Path to config YAML with poc_generation section",
    )
    parser.add_argument(
        "--no-confidence-filter",
        action="store_true",
        default=False,
        help="Generate PoCs for all findings regardless of confidence level",
    )
    args = parser.parse_args()

    categories = None
    if args.categories:
        categories = [c.strip() for c in args.categories.split(",")]

    sys.exit(
        run(
            args.findings,
            args.compile_db,
            args.out,
            categories=categories,
            config_path=args.config,
            no_confidence_filter=args.no_confidence_filter,
        )
    )


if __name__ == "__main__":
    main()

#!/usr/bin/env bash
set -euo pipefail

# Track data-flow of sensitive variables to detect untracked copies.
#
# Usage:
#   track_dataflow.sh --src path/to/file.c --config config.yaml --out /tmp/dataflow.json
#
# Detects:
# - memcpy/memmove of sensitive buffers
# - Struct assignments (potential copies)
# - Function arguments passed by value
# - Return by value (secrets in return values)

usage() {
  echo "Usage: $0 --src <file> --out <analysis.json> [--config <config.yaml>]" >&2
}

json_escape() {
  local s="$1"
  s="${s//\\/\\\\}"
  s="${s//\"/\\\"}"
  s="${s//$'\n'/\\n}"
  s="${s//$'\t'/\\t}"
  printf '%s' "$s"
}

SRC=""
CONFIG=""
OUT=""

while [[ $# -gt 0 ]]; do
  case "$1" in
    --src)
      SRC="$2"
      shift 2
      ;;
    --config)
      CONFIG="$2"
      shift 2
      ;;
    --out)
      OUT="$2"
      shift 2
      ;;
    *)
      echo "Unknown arg: $1" >&2
      usage
      exit 2
      ;;
  esac
done

if [[ -z "$SRC" || -z "$OUT" ]]; then
  usage
  exit 2
fi

if [[ ! -f "$SRC" ]]; then
  echo "Source file not found: $SRC" >&2
  exit 2
fi

# Load sensitive name patterns from config (if provided)
SENSITIVE_PATTERN="(secret|key|seed|priv|private|sk|shared_secret|nonce|token|pwd|pass)"
if [[ -n "$CONFIG" ]] && [[ -f "$CONFIG" ]]; then
  # Extract patterns from YAML (POSIX-compatible, no grep -P)
  PATTERNS=$(grep -A 20 "^sensitive_name_regex:" "$CONFIG" | sed -n 's/.*"\([^"]*\)".*/\1/p' | head -1 || echo "")
  if [[ -n "$PATTERNS" ]]; then
    SENSITIVE_PATTERN="$PATTERNS"
  else
    echo "WARNING: config file provided but no patterns extracted from $CONFIG" >&2
  fi
fi

# Arrays to collect findings
MEMCPY_COPIES=()
STRUCT_ASSIGNS=()
FUNC_ARGS=()
RETURN_VALUES=()
RETURN_RE='return[[:space:]]+([a-zA-Z_][a-zA-Z0-9_]*)[[:space:]]*;'
CALL_RE='([a-zA-Z_][a-zA-Z0-9_]*)[[:space:]]*\(([^)]*)\)'

# Parse source code
LINE_NUM=0
IN_FUNCTION=""

while IFS= read -r line; do
  ((LINE_NUM++))

  # Skip comments (simple heuristic)
  [[ "$line" =~ ^[[:space:]]*// ]] && continue
  [[ "$line" =~ ^[[:space:]]*\* ]] && continue

  # Track function boundaries
  if [[ "$line" =~ ^[a-zA-Z_][a-zA-Z0-9_]*[[:space:]]+([a-zA-Z_][a-zA-Z0-9_]*)[[:space:]]*\( ]]; then
    IN_FUNCTION="${BASH_REMATCH[1]}"
  fi

  # Detect memcpy/memmove of sensitive data
  if [[ "$line" =~ (memcpy|memmove)[[:space:]]*\([^,]*,[[:space:]]*([a-zA-Z_][a-zA-Z0-9_]*) ]]; then
    FUNC="${BASH_REMATCH[1]}"
    SRC_VAR="${BASH_REMATCH[2]}"
    if [[ "$SRC_VAR" =~ $SENSITIVE_PATTERN ]]; then
      MEMCPY_COPIES+=("{\"line\": $LINE_NUM, \"function\": \"$FUNC\", \"variable\": \"$SRC_VAR\", \"context\": \"$(json_escape "$line")\"}")
    fi
  fi

  # Detect struct assignments (potential copies)
  if [[ "$line" =~ ([a-zA-Z_][a-zA-Z0-9_]*)[[:space:]]*=[[:space:]]*\*([a-zA-Z_][a-zA-Z0-9_]*) ]]; then
    DEST="${BASH_REMATCH[1]}"
    MATCH_SRC="${BASH_REMATCH[2]}"
    if [[ "$MATCH_SRC" =~ $SENSITIVE_PATTERN ]] || [[ "$DEST" =~ $SENSITIVE_PATTERN ]]; then
      STRUCT_ASSIGNS+=("{\"line\": $LINE_NUM, \"dest\": \"$DEST\", \"source\": \"$MATCH_SRC\", \"context\": \"$(json_escape "$line")\"}")
    fi
  fi

  # Detect return by value
  if [[ "$line" =~ $RETURN_RE ]]; then
    RET_VAR="${BASH_REMATCH[1]}"
    if [[ "$RET_VAR" =~ $SENSITIVE_PATTERN ]]; then
      RETURN_VALUES+=("{\"line\": $LINE_NUM, \"function\": \"$IN_FUNCTION\", \"variable\": \"$RET_VAR\", \"context\": \"$(json_escape "$line")\"}")
    fi
  fi

  # Detect function calls with sensitive arguments (simple heuristic)
  if [[ "$line" =~ $CALL_RE ]]; then
    CALLED_FUNC="${BASH_REMATCH[1]}"
    ARGS="${BASH_REMATCH[2]}"
    # Check if any argument matches sensitive pattern
    if [[ "$ARGS" =~ $SENSITIVE_PATTERN ]]; then
      # Extract variable names from arguments
      for arg in ${ARGS//,/ }; do
        arg="${arg#"${arg%%[! ]*}"}" # trim leading spaces
        arg="${arg%"${arg##*[! ]}"}" # trim trailing spaces
        if [[ "$arg" =~ ^[a-zA-Z_][a-zA-Z0-9_]*$ ]] && [[ "$arg" =~ $SENSITIVE_PATTERN ]]; then
          FUNC_ARGS+=("{\"line\": $LINE_NUM, \"called_function\": \"$CALLED_FUNC\", \"argument\": \"$arg\", \"context\": \"$(json_escape "$line")\"}")
        fi
      done
    fi
  fi

done <"$SRC"

# Generate JSON report
mkdir -p "$(dirname "$OUT")"

cat >"$OUT" <<EOF
{
  "source_file": "$SRC",
  "sensitive_pattern": "$SENSITIVE_PATTERN",
  "findings": {
    "memcpy_copies": [
      $(
  IFS=,
  echo "${MEMCPY_COPIES[*]}"
)
    ],
    "struct_assignments": [
      $(
  IFS=,
  echo "${STRUCT_ASSIGNS[*]}"
)
    ],
    "function_arguments": [
      $(
  IFS=,
  echo "${FUNC_ARGS[*]}"
)
    ],
    "return_values": [
      $(
  IFS=,
  echo "${RETURN_VALUES[*]}"
)
    ]
  },
  "summary": {
    "total_copies": $((${#MEMCPY_COPIES[@]} + ${#STRUCT_ASSIGNS[@]} + ${#FUNC_ARGS[@]} + ${#RETURN_VALUES[@]})),
    "memcpy_count": ${#MEMCPY_COPIES[@]},
    "struct_assign_count": ${#STRUCT_ASSIGNS[@]},
    "func_arg_count": ${#FUNC_ARGS[@]},
    "return_value_count": ${#RETURN_VALUES[@]}
  }
}
EOF

# Validate JSON output
if command -v jq &>/dev/null; then
  if ! jq empty "$OUT" 2>/dev/null; then
    echo "ERROR: generated JSON is malformed: $OUT" >&2
    exit 1
  fi
fi

echo "OK: data-flow analysis written to $OUT"

#!/usr/bin/env bash
# validate_rust_toolchain.sh — Preflight check for Rust zeroize-audit prerequisites.
#
# Validates that all tools required by the Rust analysis pipeline are available
# and functional. Outputs a JSON status report.
#
# Exit codes:
#   0  all required tools available (warnings may still be present)
#   1  at least one required tool is missing
#   2  argument error

set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"

usage() {
  cat <<'EOF'
Usage:
  validate_rust_toolchain.sh [options]

Options:
  --manifest <Cargo.toml>  Check that the manifest exists and the crate builds
  --json                   Output machine-readable JSON (default: human-readable)
  --help                   Show this help text

Checks (required):
  - cargo on PATH
  - cargo +nightly available
  - uv on PATH (for Python analysis scripts)

Checks (optional, warning only):
  - rustfilt on PATH (for symbol demangling)
  - cargo-expand on PATH (for macro expansion debugging)

If --manifest is provided, additionally:
  - Manifest file exists
  - cargo check passes for the crate
EOF
}

die_arg() {
  echo "validate_rust_toolchain.sh: $*" >&2
  exit 2
}

MANIFEST=""
JSON_OUTPUT=false

while [[ $# -gt 0 ]]; do
  case "$1" in
    --manifest)
      [[ -n "${2-}" ]] || die_arg "missing value for --manifest"
      MANIFEST="$2"
      shift 2
      ;;
    --json)
      JSON_OUTPUT=true
      shift
      ;;
    --help | -h)
      usage
      exit 0
      ;;
    *)
      die_arg "unknown argument: $1"
      ;;
  esac
done

# ---------------------------------------------------------------------------
# Tool checks
# ---------------------------------------------------------------------------

declare -A TOOL_STATUS
declare -A TOOL_VERSION
ERRORS=()
WARNINGS=()

check_tool() {
  local name="$1"
  local required="$2"
  local cmd="${3:-$name}"

  if command -v "$cmd" &>/dev/null; then
    TOOL_STATUS["$name"]="present"
    local ver
    # Use a separate variable so we can distinguish a version-check failure
    # (e.g. shared-library missing) from the tool simply not being on PATH.
    if ver=$("$cmd" --version 2>/dev/null | head -1); then
      TOOL_VERSION["$name"]="$ver"
    else
      TOOL_VERSION["$name"]="(version check failed)"
      WARNINGS+=("$name is present but '--version' failed — tool may be broken")
    fi
  else
    if [[ "$required" == "true" ]]; then
      TOOL_STATUS["$name"]="missing"
      ERRORS+=("$name is required but not found on PATH")
    else
      TOOL_STATUS["$name"]="missing"
      WARNINGS+=("$name is not found on PATH (optional: ${4:-enhanced analysis})")
    fi
  fi
}

check_tool "cargo" "true"
check_tool "uv" "true"
check_tool "rustfilt" "false" "rustfilt" "Rust symbol demangling in assembly analysis"
check_tool "cargo-expand" "false" "cargo-expand" "macro expansion debugging"

# Check cargo +nightly
NIGHTLY_STATUS="unavailable"
NIGHTLY_VERSION="unknown"
if [[ "${TOOL_STATUS[cargo]}" == "present" ]]; then
  if cargo +nightly --version &>/dev/null 2>&1; then
    NIGHTLY_STATUS="available"
    NIGHTLY_VERSION=$(cargo +nightly --version 2>/dev/null | head -1 || echo "unknown")
  else
    NIGHTLY_STATUS="unavailable"
    ERRORS+=("cargo +nightly is required but the nightly toolchain is not installed (run: rustup toolchain install nightly)")
  fi
fi

# Check that emit/analysis scripts exist
declare -A SCRIPT_STATUS
REQUIRED_SCRIPTS=(
  "emit_rust_mir.sh"
  "emit_rust_ir.sh"
  "emit_rust_asm.sh"
)
OPTIONAL_SCRIPTS=(
  "diff_rust_mir.sh"
  "scripts/check_mir_patterns.py"
  "scripts/check_llvm_patterns.py"
  "scripts/check_rust_asm.py"
  "scripts/semantic_audit.py"
  "scripts/find_dangerous_apis.py"
)

for script in "${REQUIRED_SCRIPTS[@]}"; do
  if [[ -f "$SCRIPT_DIR/$script" ]]; then
    SCRIPT_STATUS["$script"]="present"
  else
    SCRIPT_STATUS["$script"]="missing"
    ERRORS+=("required script $script not found at $SCRIPT_DIR/$script")
  fi
done

for script in "${OPTIONAL_SCRIPTS[@]}"; do
  if [[ -f "$SCRIPT_DIR/$script" ]]; then
    SCRIPT_STATUS["$script"]="present"
  else
    SCRIPT_STATUS["$script"]="missing"
    WARNINGS+=("optional script $script not found at $SCRIPT_DIR/$script")
  fi
done

# Check manifest and crate build (if requested)
MANIFEST_STATUS="not_checked"
BUILD_STATUS="not_checked"
if [[ -n "$MANIFEST" ]]; then
  if [[ -f "$MANIFEST" ]]; then
    MANIFEST_STATUS="present"
    if [[ "$NIGHTLY_STATUS" == "available" ]]; then
      cargo_err=$(mktemp) || {
        ERRORS+=("mktemp failed — cannot capture cargo output")
        cargo_err="/dev/null"
      }
      if cargo +nightly check --manifest-path "$MANIFEST" 2>"$cargo_err"; then
        BUILD_STATUS="pass"
      else
        BUILD_STATUS="fail"
        # Include up to 20 lines of cargo output so callers can diagnose
        # the failure without re-running manually.
        cargo_snippet=$(head -20 "$cargo_err" 2>/dev/null | tr '\n' ' ')
        ERRORS+=("cargo check failed for $MANIFEST: ${cargo_snippet:-see stderr}")
      fi
      rm -f "$cargo_err"
    else
      BUILD_STATUS="skipped"
      WARNINGS+=("cargo check skipped (nightly not available)")
    fi
  else
    MANIFEST_STATUS="missing"
    ERRORS+=("manifest not found: $MANIFEST")
  fi
fi

# ---------------------------------------------------------------------------
# Output
# ---------------------------------------------------------------------------

OVERALL_STATUS="ready"
[[ ${#ERRORS[@]} -gt 0 ]] && OVERALL_STATUS="blocked"

if [[ "$JSON_OUTPUT" == true ]]; then
  # Build tool statuses as JSON
  TOOLS_JSON="{"
  first=true
  for name in cargo uv rustfilt cargo-expand; do
    [[ "$first" == true ]] && first=false || TOOLS_JSON+=","
    TOOLS_JSON+="\"$name\":{\"status\":\"${TOOL_STATUS[$name]:-unknown}\",\"version\":\"${TOOL_VERSION[$name]:-unknown}\"}"
  done
  TOOLS_JSON+="}"

  # Build script statuses as JSON
  SCRIPTS_JSON="{"
  first=true
  for script in "${REQUIRED_SCRIPTS[@]}" "${OPTIONAL_SCRIPTS[@]}"; do
    [[ "$first" == true ]] && first=false || SCRIPTS_JSON+=","
    SCRIPTS_JSON+="\"$script\":\"${SCRIPT_STATUS[$script]:-unknown}\""
  done
  SCRIPTS_JSON+="}"

  # Build errors/warnings arrays using Python for correct JSON escaping.
  # The sed-based approach only escaped double quotes but not backslashes,
  # newlines, or control characters — all of which can appear in cargo output.
  _json_str_array() {
    # Read lines from stdin, emit a JSON array of properly escaped strings.
    python3 -c '
import json, sys
items = [l.rstrip("\n") for l in sys.stdin]
print(json.dumps(items))
'
  }
  ERRORS_JSON=$(printf '%s\n' "${ERRORS[@]+"${ERRORS[@]}"}" | _json_str_array)
  WARNINGS_JSON=$(printf '%s\n' "${WARNINGS[@]+"${WARNINGS[@]}"}" | _json_str_array)

  cat <<EOF
{
  "status": "$OVERALL_STATUS",
  "tools": $TOOLS_JSON,
  "nightly": {"status": "$NIGHTLY_STATUS", "version": "$NIGHTLY_VERSION"},
  "scripts": $SCRIPTS_JSON,
  "manifest": {"status": "$MANIFEST_STATUS", "build": "$BUILD_STATUS"},
  "errors": $ERRORS_JSON,
  "warnings": $WARNINGS_JSON
}
EOF
else
  echo "=== Rust Toolchain Validation ==="
  echo ""
  echo "Tools:"
  for name in cargo uv rustfilt cargo-expand; do
    status="${TOOL_STATUS[$name]:-unknown}"
    version="${TOOL_VERSION[$name]:-}"
    if [[ "$status" == "present" ]]; then
      echo "  [OK]   $name ($version)"
    else
      echo "  [MISS] $name"
    fi
  done
  echo ""
  echo "Nightly: $NIGHTLY_STATUS ($NIGHTLY_VERSION)"
  echo ""
  echo "Scripts:"
  for script in "${REQUIRED_SCRIPTS[@]}"; do
    status="${SCRIPT_STATUS[$script]:-unknown}"
    if [[ "$status" == "present" ]]; then
      echo "  [OK]   $script"
    else
      echo "  [MISS] $script (required)"
    fi
  done
  for script in "${OPTIONAL_SCRIPTS[@]}"; do
    status="${SCRIPT_STATUS[$script]:-unknown}"
    if [[ "$status" == "present" ]]; then
      echo "  [OK]   $script"
    else
      echo "  [MISS] $script (optional)"
    fi
  done

  if [[ -n "$MANIFEST" ]]; then
    echo ""
    echo "Manifest: $MANIFEST ($MANIFEST_STATUS)"
    echo "Build:    $BUILD_STATUS"
  fi

  if [[ ${#ERRORS[@]} -gt 0 ]]; then
    echo ""
    echo "ERRORS:"
    for err in "${ERRORS[@]}"; do
      echo "  - $err"
    done
  fi
  if [[ ${#WARNINGS[@]} -gt 0 ]]; then
    echo ""
    echo "WARNINGS:"
    for warn in "${WARNINGS[@]}"; do
      echo "  - $warn"
    done
  fi
  echo ""
  echo "Overall: $OVERALL_STATUS"
fi

[[ "$OVERALL_STATUS" == "ready" ]]

# Phase 0 — Preflight, Configuration, and Work Directory

## Preconditions

None — this is the first phase.

## Instructions

Spawn agent `zeroize-audit:0-preflight` via `Task` (`subagent_type: "zeroize-audit:0-preflight"`) with:

| Parameter | Value |
|---|---|
| `path` | `{{path}}` |
| `compile_db` | `{{compile_db}}` |
| `cargo_manifest` | `{{cargo_manifest}}` |
| `config` | `{{config}}` |
| `languages` | `{{languages}}` |
| `max_tus` | `{{max_tus}}` |
| `mcp_mode` | `{{mcp_mode}}` |
| `mcp_timeout_ms` | `{{mcp_timeout_ms}}` |
| `mcp_required_for_advanced` | `{{mcp_required_for_advanced}}` |
| `enable_asm` | `{{enable_asm}}` |
| `enable_semantic_ir` | `{{enable_semantic_ir}}` |
| `enable_cfg` | `{{enable_cfg}}` |
| `enable_runtime_tests` | `{{enable_runtime_tests}}` |
| `opt_levels` | `{{opt_levels}}` |
| `poc_categories` | `{{poc_categories}}` |
| `poc_output_dir` | `{{poc_output_dir}}` |
| `baseDir` | `{baseDir}` |

The agent creates the work directory, runs all preflight checks, merges configuration, enumerates TUs, and writes `orchestrator-state.json`.

### What the `0-preflight` agent must do

**Step 1 — Determine language mode** from inputs:
- `compile_db` set and `cargo_manifest` not set → `language_mode=c`
- `cargo_manifest` set and `compile_db` not set → `language_mode=rust`
- Both set → `language_mode=mixed`
- Neither set → **stop the run**: at least one of `compile_db` or `cargo_manifest` is required.

**Step 2 — C/C++ preflight** (skip if `language_mode=rust`):

1. Verify `compile_db` file exists at the given path.
2. Verify at least one entry in the compile DB resolves to an existing source file and working directory.
3. Attempt a trial compilation of one representative TU using its captured flags to confirm the codebase is buildable.
4. Verify `{baseDir}/tools/extract_compile_flags.py` exists and is executable.
5. Verify `{baseDir}/tools/emit_ir.sh` exists and is executable.
6. If `enable_asm=true`: verify `{baseDir}/tools/emit_asm.sh` exists; if missing, set `enable_asm=false` and emit a warning.
7. If `mcp_mode != off`: run `{baseDir}/tools/mcp/check_mcp.sh` to probe MCP availability.
   - If `mcp_mode=require` and MCP is unreachable: **stop the run** and report the MCP failure.
   - If `mcp_mode=prefer` and MCP is unreachable: set `mcp_available=false`, continue, and apply confidence downgrades in the report assembly phase.

**Step 3 — Common preflight** (always):

8. Verify `{baseDir}/tools/generate_poc.py` exists and is executable. If missing: **stop the run** — PoC generation is mandatory.

**Step 4 — Rust preflight** (skip if `language_mode=c`):

9. Verify `cargo_manifest` file exists (must be a `Cargo.toml` path).
10. Run `cargo check --manifest-path <cargo_manifest>` to confirm the crate is buildable. If it fails: **stop the run**.
11. Verify `cargo +nightly --version` succeeds. If not: **stop the run** — nightly toolchain is required for MIR and LLVM IR emission.
    - Note: use `~/.cargo/bin/cargo +nightly` (rustup proxy) rather than a system cargo that may not support the `+toolchain` syntax.
12. Verify `uv --version` succeeds. If not: **stop the run** — `uv` is required to run Python analysis scripts.
13. Verify `{baseDir}/tools/emit_rust_mir.sh` exists and is executable. If missing: **stop the run** — MIR analysis is required.
14. Verify `{baseDir}/tools/emit_rust_ir.sh` exists and is executable. If missing: **stop the run** — LLVM IR analysis is required.
15. For each tool below: if missing or not executable, warn and mark that capability as skipped (do not fail the run):
    - `{baseDir}/tools/emit_rust_asm.sh` — if missing, set `enable_asm=false` for Rust; warn `STACK_RETENTION`/`REGISTER_SPILL` findings will be skipped.
    - `{baseDir}/tools/diff_rust_mir.sh` — if missing, warn that MIR-level optimization comparison will be skipped.
16. For each Python script below: if missing, warn and mark that sub-step as skipped (do not fail the run):
    - `{baseDir}/tools/scripts/semantic_audit.py`
    - `{baseDir}/tools/scripts/find_dangerous_apis.py`
    - `{baseDir}/tools/scripts/check_mir_patterns.py`
    - `{baseDir}/tools/scripts/check_llvm_patterns.py`
    - `{baseDir}/tools/scripts/check_rust_asm.py` — if missing, assembly analysis findings (`STACK_RETENTION`, `REGISTER_SPILL`) will be skipped even if `enable_asm=true`.

**Step 5 — TU / crate enumeration**:

- **C/C++** (skip if `language_mode=rust`): Parse `compile_db` and enumerate all translation units. Apply `max_tus` limit if set. Filter by `languages`. Compute `tu_hash = sha1(source_path)[:8]` for each TU. Run a lightweight grep across TU sources for sensitive name patterns (from merged config) to produce `sensitive_candidates`.
- **Rust** (skip if `language_mode=c`): Compute `rust_tu_hash = sha1(abspath(cargo_manifest))[:8]`. Set `rust_crate_root = dirname(cargo_manifest)`.

**Step 6 — Create work directory**:

```bash
RUN_ID=$(date +%Y%m%d%H%M%S)
WORKDIR="/tmp/zeroize-audit-${RUN_ID}"
mkdir -p "${WORKDIR}"/{mcp-evidence,source-analysis,compiler-analysis,rust-compiler-analysis,report,poc,tests,agent-inputs}
```

**Step 7 — Write `{workdir}/preflight.json`**:

```json
{
  "run_id": "<RUN_ID>",
  "timestamp": "<ISO-8601>",
  "repo": "<path>",
  "language_mode": "<c|rust|mixed>",
  "compile_db": "<compile_db or null>",
  "cargo_manifest": "<cargo_manifest or null>",
  "rust_crate_root": "<dirname(cargo_manifest) or null>",
  "rust_tu_hash": "<hash or null>",
  "opt_levels": ["O0", "O1", "O2"],
  "mcp_mode": "<mcp_mode>",
  "mcp_available": true,
  "enable_asm": true,
  "enable_semantic_ir": false,
  "enable_cfg": false,
  "enable_runtime_tests": false,
  "tu_count": 0,
  "tu_list": [{"file": "/path/to/file.c", "tu_hash": "a1b2c3d4"}],
  "sensitive_candidates": [],
  "tools_verified": ["uv", "cargo+nightly"],
  "notes": ""
}
```

**Step 8 — Write `{workdir}/orchestrator-state.json`** with the full state structure.

Report each preflight failure with the specific check that failed and the remediation step.

**After completion**: The agent's response includes the `workdir` path. Read `{workdir}/orchestrator-state.json` to initialize:

- `workdir` — use for all subsequent phases
- `routing.mcp_available` — MCP probe result
- `routing.tu_count` — number of TUs to process
- `key_file_paths.config` — path to merged config file

## State Update

The `0-preflight` agent writes the initial `orchestrator-state.json`. No additional update needed by the orchestrator.

## Error Handling

| Failure | Behavior |
|---|---|
| Agent fails or times out | Stop the run, report failure |
| Neither `compile_db` nor `cargo_manifest` provided | Stop the run |
| Preflight validation fails | Stop the run (agent reports specific check and remediation) |
| Config load fails | Stop the run |
| Preflight tool check fails | Stop the run |
| MCP unreachable + `mcp_mode=require` | Stop the run |
| MCP unreachable + `mcp_mode=prefer` | Continue — `routing.mcp_available` will be `false` |
| `cargo check` fails (Rust preflight) | Stop the run — crate must be buildable |
| `cargo +nightly` not available (Rust preflight) | Stop the run — nightly required for MIR/IR emission |
| `uv` not available (Rust preflight) | Stop the run — required for Python analysis scripts |
| `emit_rust_asm.sh` missing (Rust preflight) | Warn, set `enable_asm=false` for Rust, continue |
| Python script missing (Rust preflight) | Warn and skip that sub-step, continue |

## Next Phase

Phase 1 — Source Analysis

# Phase 1 — MCP Resolution and Source Analysis

## Preconditions

- Phase 0 complete: `orchestrator-state.json` exists with `phases.0.status = "complete"`
- `{workdir}/preflight.json` exists
- `{workdir}/merged-config.yaml` exists

## Instructions

### Wave 1 — MCP Resolver

Skip if `mcp_mode=off` or `routing.mcp_available=false` or `language_mode=rust` (MCP is C/C++ only).

Write agent inputs to `{workdir}/agent-inputs/mcp-resolver.json`:

```json
{
  "sensitive_candidates": "<from preflight.json sensitive_candidates>"
}
```

Spawn agent `zeroize-audit:1-mcp-resolver` via `Task` (`subagent_type: "zeroize-audit:1-mcp-resolver"`) with:

| Parameter | Value |
|---|---|
| `workdir` | `{workdir}` |
| `repo_root` | `{{path}}` |
| `compile_db` | `{{compile_db}}` |
| `config_path` | `{workdir}/merged-config.yaml` |
| `input_file` | `{workdir}/agent-inputs/mcp-resolver.json` |
| `mcp_timeout_ms` | `{{mcp_timeout_ms}}` |

**After completion**: Read `{workdir}/mcp-evidence/status.json`.

- If `status=failed` and `mcp_mode=require`: **stop the run**.
- If `status=failed` and `mcp_mode=prefer`: set `mcp_available=false`.
- If `status=partial` or `status=success`: set `mcp_available=true`.

### Wave 2a — Source Analyzer (C/C++ only)

Skip if `language_mode=rust`.

Write agent inputs to `{workdir}/agent-inputs/source-analyzer.json`:

```json
{
  "tu_list": "<from preflight.json tu_list>"
}
```

Spawn agent `zeroize-audit:2-source-analyzer` via `Task` (`subagent_type: "zeroize-audit:2-source-analyzer"`) **in the same message as Wave 2b** (parallel launch):

| Parameter | Value |
|---|---|
| `workdir` | `{workdir}` |
| `repo_root` | `{{path}}` |
| `compile_db` | `{{compile_db}}` |
| `config_path` | `{workdir}/merged-config.yaml` |
| `input_file` | `{workdir}/agent-inputs/source-analyzer.json` |
| `mcp_available` | Result from Wave 1 |
| `languages` | `{{languages}}` |
| `max_tus` | `{{max_tus}}` |

### Wave 2b — Rust Source Analyzer (Rust only)

Skip if `language_mode=c`.

Spawn agent `zeroize-audit:2b-rust-source-analyzer` via `Task` (`subagent_type: "zeroize-audit:2b-rust-source-analyzer"`) **in the same message as Wave 2a** (parallel launch):

| Parameter | Value |
|---|---|
| `workdir` | `{workdir}` |
| `repo_root` | `{{path}}` |
| `cargo_manifest` | `{{cargo_manifest}}` |
| `rust_crate_root` | From `preflight.json` |
| `rust_tu_hash` | From `preflight.json` |
| `config_path` | `{workdir}/merged-config.yaml` |
| `baseDir` | `{baseDir}` |

The `2b-rust-source-analyzer` agent must:

1. Attempt rustdoc JSON generation:
   ```bash
   cargo +nightly rustdoc --manifest-path <cargo_manifest> \
     --document-private-items -- -Z unstable-options --output-format json
   ```
   If this fails, warn and skip — proceed with source grep only.
2. Run semantic audit (if rustdoc JSON succeeded):
   ```bash
   uv run {baseDir}/tools/scripts/semantic_audit.py \
     --rustdoc target/doc/<crate>.json \
     --cargo-toml <cargo_manifest> \
     --out {workdir}/source-analysis/rust-semantic-findings.json
   ```
3. Run dangerous API scan:
   ```bash
   uv run {baseDir}/tools/scripts/find_dangerous_apis.py \
     --src <rust_crate_root>/src \
     --out {workdir}/source-analysis/rust-dangerous-api-findings.json
   ```
4. Merge outputs into `{workdir}/source-analysis/sensitive-objects.json` (Rust `SO-NNNN` IDs with offset 5000+), `{workdir}/source-analysis/source-findings.json` (IDs `F-RUST-SRC-NNNN`), and `{workdir}/source-analysis/tu-map.json` (adding `{"<cargo_manifest>": "<rust_tu_hash>"}`).
5. Write `{workdir}/source-analysis/rust-notes.md` summarizing findings and any skipped steps.

**After both Wave 2a and Wave 2b complete**: Read `{workdir}/source-analysis/tu-map.json`.

- If empty (`{}`): no sensitive objects found. Skip to Phase 6 (empty report).
- Determine entry classes in `tu-map.json`:
  - **C/C++ entry**: key is a source file path from `compile_commands.json` (typically `.c`, `.cc`, `.cpp`, `.cxx`).
  - **Rust entry**: key is the `cargo_manifest` path (`.../Cargo.toml`).
- If no C/C++ entries: skip Wave 3 in Phase 2.
- If no Rust entry: skip Wave 3R in Phase 2.
- Otherwise: proceed to Phase 2.

## State Update

Update `orchestrator-state.json`:

```json
{
  "current_phase": 1,
  "routing": {
    "mcp_available": "<updated value>",
    "tu_count": "<count of TUs in tu-map.json>"
  },
  "phases": {
    "1": {"status": "complete", "output": "source-analysis/tu-map.json"}
  }
}
```

## Error Handling

| Failure | Behavior |
|---|---|
| MCP resolver fails + `mcp_mode=require` | Stop the run |
| MCP resolver fails + `mcp_mode=prefer` | Continue with `mcp_available=false` |
| Source analyzer (C/C++) fails | Stop C/C++ analysis — no sensitive object list for C/C++ TUs |
| Rust source analyzer fails | Stop Rust analysis — log failure, continue if C/C++ analysis is also running |
| No sensitive objects found | Skip Phases 2–5, jump to Phase 6 for empty report |

## Next Phase

Phase 2 — Compiler Analysis (if `tu-map.json` is non-empty)

# Phase 2 — Compiler Analysis

## Preconditions

- Phase 1 complete: `tu-map.json` is non-empty
- `{workdir}/source-analysis/sensitive-objects.json` exists
- `{workdir}/source-analysis/source-findings.json` exists

## Instructions

### Wave 3 — TU Compiler Analyzers (C/C++ only, N parallel)

Skip if `language_mode=rust` or `tu-map.json` has no C/C++ entries.

For each C/C++ TU in `{workdir}/source-analysis/tu-map.json`:

1. Create output directory:
   ```bash
   mkdir -p {workdir}/compiler-analysis/<tu_hash>
   ```

2. Write per-TU agent input to `{workdir}/agent-inputs/tu-<tu_hash>.json`:
   ```json
   {
     "sensitive_objects": "<subset of sensitive-objects.json matching this TU>",
     "source_findings": "<subset of source-findings.json matching this TU>"
   }
   ```

3. Spawn agent `zeroize-audit:3-tu-compiler-analyzer` via `Task` (`subagent_type: "zeroize-audit:3-tu-compiler-analyzer"`) with:

| Parameter | Value |
|---|---|
| `workdir` | `{workdir}` |
| `tu_source` | Source file path (from tu-map key) |
| `tu_hash` | TU hash (from tu-map value) |
| `compile_db` | `{{compile_db}}` |
| `config_path` | `{workdir}/merged-config.yaml` |
| `input_file` | `{workdir}/agent-inputs/tu-<tu_hash>.json` |
| `opt_levels` | `{{opt_levels}}` |
| `enable_asm` | `{{enable_asm}}` |
| `enable_semantic_ir` | `{{enable_semantic_ir}}` |
| `enable_cfg` | `{{enable_cfg}}` |
| `baseDir` | `{baseDir}` |

Launch TU agents in parallel using multiple `Task` calls in a single message. **Batching**: if the TU count exceeds 15, launch in batches of 10–15; wait for each batch before launching the next.

**After all TU agents complete**: Verify `{workdir}/compiler-analysis/<tu_hash>/ir-findings.json` exists for each TU. Log any failed TUs but continue.

### Wave 3R — Rust Compiler Analyzer (single agent)

Skip if any of the following are true:
- `language_mode=c`
- `tu-map.json` has no Rust entry (manifest key `.../Cargo.toml`)
- `sensitive-objects.json` is missing or empty
- `sensitive-objects.json` has no Rust objects (IDs `SO-5NNN` / `SO-5000+`)

Spawn agent `zeroize-audit:3b-rust-compiler-analyzer` via `Task` (`subagent_type: "zeroize-audit:3b-rust-compiler-analyzer"`) (after Wave 3 completes or is skipped):

| Parameter | Value |
|---|---|
| `workdir` | `{workdir}` |
| `cargo_manifest` | `{{cargo_manifest}}` |
| `rust_crate_root` | From `preflight.json` |
| `rust_tu_hash` | From `preflight.json` |
| `config_path` | `{workdir}/merged-config.yaml` |
| `opt_levels` | `{{opt_levels}}` |
| `enable_asm` | `{{enable_asm}}` |
| `input_file` | `{workdir}/agent-inputs/rust-compiler.json` (write Rust-subset of sensitive-objects and source-findings before spawn) |
| `baseDir` | `{baseDir}` |

The `3b-rust-compiler-analyzer` agent must run these steps in order. On step failures, write status-bearing error objects to the affected output file(s) and continue.

**Step A — MIR analysis:**
```bash
{baseDir}/tools/emit_rust_mir.sh --manifest <cargo_manifest> --lib --opt O0 \
  --out {workdir}/rust-compiler-analysis/<rust_tu_hash>.mir
uv run {baseDir}/tools/scripts/check_mir_patterns.py \
  --mir {workdir}/rust-compiler-analysis/<rust_tu_hash>.mir \
  --secrets {workdir}/source-analysis/sensitive-objects.json \
  --out {workdir}/rust-compiler-analysis/mir-findings.json
```

**Step B — LLVM IR analysis (O0 vs O2):**
```bash
{baseDir}/tools/emit_rust_ir.sh --manifest <cargo_manifest> --lib --opt O0 \
  --out {workdir}/rust-compiler-analysis/<rust_tu_hash>.O0.ll
{baseDir}/tools/emit_rust_ir.sh --manifest <cargo_manifest> --lib --opt O2 \
  --out {workdir}/rust-compiler-analysis/<rust_tu_hash>.O2.ll
uv run {baseDir}/tools/scripts/check_llvm_patterns.py \
  --o0 {workdir}/rust-compiler-analysis/<rust_tu_hash>.O0.ll \
  --o2 {workdir}/rust-compiler-analysis/<rust_tu_hash>.O2.ll \
  --out {workdir}/rust-compiler-analysis/ir-findings.json
```

**Step C — Assembly analysis** (skip if `enable_asm=false` or `emit_rust_asm.sh` missing):
```bash
{baseDir}/tools/emit_rust_asm.sh --manifest <cargo_manifest> --lib --opt O2 \
  --out {workdir}/rust-compiler-analysis/<rust_tu_hash>.O2.s
uv run {baseDir}/tools/scripts/check_rust_asm.py \
  --asm {workdir}/rust-compiler-analysis/<rust_tu_hash>.O2.s \
  --secrets {workdir}/source-analysis/sensitive-objects.json \
  --out {workdir}/rust-compiler-analysis/asm-findings.json
```

If assembly tools are missing, write `[]` to `asm-findings.json`.

**Step D — Section D coverage survey:** no script covers these patterns, so the agent greps the crate source for them (its Step 6 lists the markers) and writes `coverage-gaps.json` — `[]` when nothing is found. The report's Analysis Coverage section reads that file; without it a crate using an unaudited pattern is indistinguishable from one that has none.

IR finding IDs: `F-RUST-IR-NNNN`. MIR finding IDs: `F-RUST-MIR-NNNN`. Assembly finding IDs: `F-RUST-ASM-NNNN`.

Write `{workdir}/rust-compiler-analysis/notes.md` summarizing all steps, any failures, and key observations.

**After Wave 3R completes**: Verify `mir-findings.json`, `ir-findings.json`, `asm-findings.json`, and `coverage-gaps.json` exist under `{workdir}/rust-compiler-analysis/`. Log if missing, continue.

## State Update

Update `orchestrator-state.json`:

```json
{
  "current_phase": 2,
  "phases": {
    "2": {"status": "complete", "tus_succeeded": "<N>", "tus_failed": "<N>"}
  }
}
```

## Error Handling

| Failure | Behavior |
|---|---|
| One TU agent (C/C++) fails | Continue with remaining TUs |
| All TU agents (C/C++) fail | Proceed — report assembler produces source-only report |
| Rust compiler analyzer (Wave 3R) fails | Log failure, continue — report assembler handles missing `rust-compiler-analysis/` |
| `emit_rust_asm.sh` missing | Write `[]` to `asm-findings.json`, continue — assembly findings skipped |
| MIR or IR emission fails | Write `[]` to that step's output, continue with remaining steps |

## Next Phase

Phase 3 — Interim Report

# Phase 3 — Interim Finding Collection

## Preconditions

- Phase 2 complete (or skipped if no compiler analysis needed)

## Instructions

Spawn agent `zeroize-audit:4-report-assembler` via `Task` (`subagent_type: "zeroize-audit:4-report-assembler"`) with:

| Parameter | Value |
|---|---|
| `workdir` | `{workdir}` |
| `config_path` | `{workdir}/merged-config.yaml` |
| `mcp_available` | From `orchestrator-state.json` routing |
| `mcp_required_for_advanced` | `{{mcp_required_for_advanced}}` |
| `baseDir` | `{baseDir}` |
| `mode` | `interim` |

**After completion**: Verify `{workdir}/report/findings.json` exists. Count findings. If the findings array is empty, skip to Phase 6 for an empty report.

## State Update

Update `orchestrator-state.json`:

```json
{
  "current_phase": 3,
  "routing": {
    "finding_count": "<count from findings.json>"
  },
  "phases": {
    "3": {"status": "complete", "output": "report/findings.json"}
  }
}
```

## Error Handling

| Failure | Behavior |
|---|---|
| Report assembler fails | Surface error to user |

## Next Phase

Phase 4 — PoC Generation (if `finding_count > 0`)

# Phase 4 — PoC Generation

## Preconditions

- Phase 3 complete: `{workdir}/report/findings.json` exists with at least one finding

## Instructions

Spawn agent `zeroize-audit:5-poc-generator` via `Task` (`subagent_type: "zeroize-audit:5-poc-generator"`) with:

| Parameter | Value |
|---|---|
| `workdir` | `{workdir}` |
| `compile_db` | `{{compile_db}}` |
| `config_path` | `{workdir}/merged-config.yaml` |
| `final_report` | `{workdir}/report/findings.json` |
| `poc_categories` | `{{poc_categories}}` |
| `poc_output_dir` | `{{poc_output_dir}}` or `{workdir}/poc/` |
| `baseDir` | `{baseDir}` |

The agent reads each finding and the corresponding source code, then crafts a bespoke PoC program tailored to the specific vulnerability. Each PoC is individually written — not generated from templates.

**After completion**: Verify `{workdir}/poc/poc_manifest.json` exists and contains an entry for each finding.

## State Update

Update `orchestrator-state.json`:

```json
{
  "current_phase": 4,
  "phases": {
    "4": {"status": "complete", "output": "poc/poc_manifest.json"}
  }
}
```

## Error Handling

| Failure | Behavior |
|---|---|
| PoC generator fails | Pipeline stalls — surface error to user |

## Next Phase

Phase 5 — PoC Validation & Verification

# Phase 5 — PoC Validation & Verification

## Preconditions

- Phase 4 complete: `{workdir}/poc/poc_manifest.json` exists

## Instructions

### Step 5a — Compile and Run All PoCs (agent)

Spawn agent `zeroize-audit:5b-poc-validator` via `Task` (`subagent_type: "zeroize-audit:5b-poc-validator"`) with:

| Parameter | Value |
|---|---|
| `workdir` | `{workdir}` |
| `config_path` | `{workdir}/merged-config.yaml` |

**After completion**: Read `{workdir}/poc/poc_validation_results.json`.

If the agent fails, fall back to compiling and running PoCs inline:

```bash
cd {workdir}/poc && make <makefile_target>
./<makefile_target>
echo "Exit code: $?"
```

### Step 5b — Verify PoCs Prove Their Claims (agent)

Spawn agent `zeroize-audit:5c-poc-verifier` via `Task` (`subagent_type: "zeroize-audit:5c-poc-verifier"`) with:

| Parameter | Value |
|---|---|
| `workdir` | `{workdir}` |
| `config_path` | `{workdir}/merged-config.yaml` |
| `validation_results` | `{workdir}/poc/poc_validation_results.json` |

The verifier reads each PoC source file, the corresponding finding, and the original source code to check that the PoC actually tests the claimed vulnerability. It verifies:
- Target variable and function match the finding
- Verification technique is appropriate for the finding category
- Optimization level is correct
- Exit code interpretation is not inverted
- Results are plausible given the finding evidence

**After completion**: Read `{workdir}/poc/poc_verification.json`.

### Step 5c — Present Verification Failures to User

Read `{workdir}/poc/poc_verification.json`. For any PoC with `verified: false`:

1. Use `Read` to show the PoC source file.
2. Present to the user via `AskUserQuestion` with:
   - Finding ID and category
   - PoC file path
   - Which verification checks failed and why
   - The verifier's notes
   - The PoC's runtime result (from `poc_validation_results.json`)

3. Ask the user whether to:
   - **Accept anyway**: Trust the PoC result despite verification failure
   - **Reject**: Discard the PoC result (treat as `no_poc` for this finding)

**Block until the user responds for each failed PoC.**

### Step 5d — Merge Results

Combine validation results (from `poc_validation_results.json`), verification results (from `poc_verification.json`), and user decisions (from Step 5c).

Write `{workdir}/poc/poc_final_results.json`:

```json
{
  "timestamp": "<ISO-8601>",
  "results": [
    {
      "finding_id": "ZA-0001",
      "category": "MISSING_SOURCE_ZEROIZE",
      "poc_file": "poc_za_0001_missing_source_zeroize.c",
      "compile_success": true,
      "exit_code": 0,
      "validation_result": "exploitable",
      "verification": {
        "verified": true,
        "checks": { "...": "pass" },
        "notes": "PoC correctly targets session_key in handle_key()"
      }
    },
    {
      "finding_id": "ZA-0003",
      "category": "OPTIMIZED_AWAY_ZEROIZE",
      "poc_file": "poc_za_0003_optimized_away_zeroize.c",
      "compile_success": true,
      "exit_code": 1,
      "validation_result": "rejected",
      "verification": {
        "verified": false,
        "checks": { "optimization_level": "fail" },
        "notes": "Compiled at -O0 but wipe disappears at -O2. User rejected PoC result."
      }
    }
  ]
}
```

Validation result mapping:

- `compile_success=true, exit_code=0, verified=true` → `"exploitable"`
- `compile_success=true, exit_code=1, verified=true` → `"not_exploitable"`
- `compile_success=true, verified=false, user accepted` → original result (`"exploitable"` or `"not_exploitable"`)
- `compile_success=true, verified=false, user rejected` → `"rejected"`
- `compile_success=false` → `"compile_failure"`

## State Update

Update `orchestrator-state.json`:

```json
{
  "current_phase": 5,
  "phases": {
    "5": {"status": "complete", "output": "poc/poc_final_results.json"}
  }
}
```

## Error Handling

| Failure | Behavior |
|---|---|
| Validator agent fails | Fall back to inline compilation for all PoCs |
| Verifier agent fails | Skip verification, use validation results only (warn in report) |
| Individual PoC compile failure | Record in results, continue with others |

## Next Phase

Phase 6 — Final Report

# Phase 6 — Report Finalization

## Preconditions

- Phase 5 complete (or skipped if zero findings): `poc_final_results.json` exists or findings are empty

## Instructions

Spawn agent `zeroize-audit:4-report-assembler` via `Task` (`subagent_type: "zeroize-audit:4-report-assembler"`) with:

| Parameter | Value |
|---|---|
| `workdir` | `{workdir}` |
| `config_path` | `{workdir}/merged-config.yaml` |
| `mcp_available` | From `orchestrator-state.json` routing |
| `mcp_required_for_advanced` | `{{mcp_required_for_advanced}}` |
| `baseDir` | `{baseDir}` |
| `mode` | `final` |
| `poc_results` | `{workdir}/poc/poc_final_results.json` |

**After completion**: Verify `{workdir}/report/final-report.md` and updated `{workdir}/report/findings.json` exist.

## State Update

Update `orchestrator-state.json`:

```json
{
  "current_phase": 6,
  "phases": {
    "6": {"status": "complete", "output": "report/final-report.md"}
  }
}
```

## Error Handling

| Failure | Behavior |
|---|---|
| Report assembler fails | Surface error to user |

## Next Phase

Phase 7 — Test Generation (if `enable_runtime_tests=true` and `finding_count > 0`)

# Phase 7 — Test Generation

## Preconditions

- Phase 6 complete
- `enable_runtime_tests=true`
- Finding count > 0

## Instructions

Spawn agent `zeroize-audit:6-test-generator` via `Task` (`subagent_type: "zeroize-audit:6-test-generator"`) with:

| Parameter | Value |
|---|---|
| `workdir` | `{workdir}` |
| `compile_db` | `{{compile_db}}` |
| `config_path` | `{workdir}/merged-config.yaml` |
| `final_report` | `{workdir}/report/findings.json` |
| `baseDir` | `{baseDir}` |

## State Update

Update `orchestrator-state.json`:

```json
{
  "current_phase": 7,
  "phases": {
    "7": {"status": "complete", "output": "tests/"}
  }
}
```

## Error Handling

| Failure | Behavior |
|---|---|
| Test generator fails | Report is still available without tests |

## Next Phase

Phase 8 — Return Results (handled inline by dispatcher)