@vigolium/piolium 0.0.1

package/skills/zeroize-audit/references/mcp-analysis.md

@@ -0,0 +1,221 @@
+# 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
+python {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
+python {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.

package/skills/zeroize-audit/references/poc-generation.md

@@ -0,0 +1,470 @@
+# 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.