@vigolium/piolium 0.0.1

package/skills/zeroize-audit/prompts/report_template.md

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

package/skills/zeroize-audit/prompts/system.md

@@ -0,0 +1,163 @@
+# 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)
+    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-composer` |
+
+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-composer` 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 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.

package/skills/zeroize-audit/prompts/task.md

@@ -0,0 +1,97 @@
+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 |