hex-audit 0.6.3 → 0.8.0

package/dist/skills/fuzz/references/template-map.md

@@ -0,0 +1,121 @@
+# Template Map
+
+Maps each generated file to its role in the inheritance chain and generation phase.
+
+## Inheritance Chain
+
+```
+Base (is StringUtils, Clamp, Deployer, Math)
+        └─► Snapshots (is Base)
+              └─► Properties (is PropertiesAsserts, Snapshots)
+                    └─► <Contract>Handler (is Properties)   — one per target contract
+                          └─► Handlers (is <all handlers>)  — aggregator + actor switching
+                                ├─► FuzzTester (is Handlers)       — Echidna/Medusa entry point
+                                └─► FoundryTester (is Test, Handlers) — Foundry quick debug/PoC entry point
+```
+
+## File Descriptions
+
+### Core files (scaffolded, then refined)
+
+| File | Phase | Role |
+|---|---|---|
+| `Actor.sol` | Step 5 + Step 6 | Actor contract representing a user. Holds ETH, has `forceSendETH`, ERC-721/1155 receivers, flash loan callback. Copied in Step 5 and then modified with protocol-specific approvals and setup needs. |
+| `Base.sol` | Step 5 + Step 6 + Step 9 | Constants, state variables, ghost struct, actor management, contract instances. Copied in Step 5, wired in Step 6, and extended in Step 9. |
+| `README.md` | Step 5 | Reader-facing overview of the generated suite, its key files, and the standard commands to run it. Intended for users or agents who did not build the harness originally. |
+| `Snapshots.sol` | Step 5 + Step 6 + Step 9 | Before/after state tracking. Copied in Step 5, kept minimal in Step 6, and populated during invariant generation. |
+| `Properties.sol` | Step 5 + Step 6 + Step 9 | Property container. Copied in Step 5, kept minimal in Step 6, and populated with checks in Step 9. |
+| `handlers/Handlers.sol` | Step 5 + Step 6 + Step 7 | Aggregator copied in Step 5, then populated from the selected contracts so it imports and inherits all generated handler stubs. It can be adjusted in Step 6 if needed and refined again in Step 7. |
+| `handlers/<Contract>Handler.sol` | Step 5 + Step 7 | Per-contract handler file in `{SUITE_DIR}`. Stub handler templates are generated in Step 5 from `.hex/fuzz/fizz_data/entry-point-selection.json`, then replaced or rewritten in Step 7. |
+| `harness/<Contract>Harness.sol` | Step 9 (conditional) | Harness contract that inherits from a target contract and exposes private/internal state needed by a property. Created only when strictly necessary. When present, `Base.sol` instantiates the harness instead of the target contract. |
+| `FuzzTester.sol` | Step 5 | Echidna/Medusa entry point. Copied in Step 5 and never modified. Inherits everything through `Handlers`. |
+| `FoundryTester.sol` | Step 5 | Foundry quick debug and PoC harness. Copied in Step 5 and never modified structurally, but used actively during Step 8 and Step 10 to debug coverage gaps and validate hypotheses. Inherits everything through `Handlers`. |
+
+### Workflow metadata (generated during the workflow)
+
+| File | Phase | Role |
+|---|---|---|
+| `.hex/fuzz/fizz_data/contracts.json` | Step 2 | Extracted contract/function inventory used as the structural input for selection and later analysis. |
+| `.hex/fuzz/fizz_data/entry-point-selection.json` | Step 4 | Auto-accepted selection of contracts and functions that limits handler generation only. |
+| `.hex/fuzz/fizz_data/protocol-understanding.md` | Step 3 fallback | Persisted protocol understanding notes when the Hex protocol model (`.hex/model/protocol.json`) is unavailable. |
+| `.hex/fuzz/fizz_data/hex-invariants.json` | Step 3 | The accepted Hex invariants for this run (`hex invariant list --status accepted --json`). |
+| `.hex/fuzz/PROPERTIES.md` | Step 9c | English property spec; every entry carries the `(INV-NNN)` it fuzzes. |
+
+### Utility files (static, not edited)
+
+| File | Role |
+|---|---|
+| `utils/Clamp.sol` | Clamping functions: `clampBetween`, `clampLt`, `clampLte`, `clampGt`, `clampGte` (uint256 + int256). |
+| `utils/Hevm.sol` | Cheatcode interface (`vm.prank`, `vm.roll`, `vm.warp`, `vm.label`, etc.). |
+| `utils/PropertiesAsserts.sol` | Assertion helpers for properties: `t()`, `eq()`, `neq()`, `gt()`, `gte()`, `lt()`, `lte()`. |
+| `utils/Logger.sol` | Event-based logging for fuzzer trace output. |
+| `utils/Math.sol` | Math helpers (`abs`, etc.). |
+| `utils/StringUtils.sol` | Number-to-string conversion for log messages. |
+| `utils/Deployer.sol` | Deployment helpers. |
+| `utils/DecimalPrinter.sol` | Decimal formatting for uint values. |
+| `utils/EnumerableSet.sol` | OpenZeppelin-style enumerable set for tracking addresses/uints. |
+| `utils/MockERC20.sol` | Simple mintable ERC20 mock for external token dependencies, seeded balances, and token-donation edge cases in the generated harness. |
+
+### Config files (project root)
+
+| File | Role |
+|---|---|
+| `echidna.yaml` | Echidna fuzzer configuration. Points to `FuzzTester` as test target. |
+| `medusa.json` | Medusa fuzzer configuration. Points to `FuzzTester` as test target. |
+
+## Output Structure
+
+```
+.hex/fuzz/
+├── PROPERTIES.md                # English property spec, one entry per accepted invariant
+└── fizz_data/
+
+.hex/fuzz/fizz_data/
+├── hex-invariants.json          # Accepted Hex invariants for this run
+├── contracts.json               # Extracted contract/function inventory
+├── entry-point-selection.json   # Auto-accepted handler-generation scope
+├── protocol-understanding.md    # Fallback understanding notes when needed
+├── corpus_echidna/
+├── corpus_medusa/
+├── crytic-export/
+├── logs_medusa/
+└── ...
+
+./
+├── echidna.yaml
+├── medusa.json
+└── ...
+
+test/fizz/
+├── README.md            # Human/agent-oriented suite overview and runbook
+├── Actor.sol
+├── Base.sol             # Contract declarations, setup, ghosts, helpers
+├── Properties.sol       # Invariant checks
+├── Snapshots.sol        # Before/after state tracking
+├── FuzzTester.sol       # Echidna/Medusa entry point
+├── FoundryTester.sol    # Foundry quick debug/PoC harness
+├── handlers/
+│   ├── Handlers.sol     # Aggregator — inherits all per-contract handlers
+│   ├── VaultHandler.sol # Example: handlers for Vault contract
+│   └── TokenHandler.sol # Example: handlers for Token contract
+├── harness/             # Optional — only created when properties need private/internal access
+│   └── VaultHarness.sol # Example: exposes internal state from Vault
+└── utils/
+    ├── Clamp.sol        # Clamping helpers (clampBetween, clampLt, etc.)
+    ├── DecimalPrinter.sol
+    ├── Deployer.sol
+    ├── EnumerableSet.sol
+    ├── Hevm.sol         # Cheatcode interface
+    ├── Logger.sol
+    ├── Math.sol
+    ├── MockERC20.sol    # Mintable ERC20 mock for external token dependencies
+    ├── PropertiesAsserts.sol
+    └── StringUtils.sol
+```
+
+## Generation Phases Summary
+
+1. **Template copy** — The full template scaffold and fuzzer config are copied into place.
+2. **Core refinement** — `Base.sol`, `Actor.sol`, `Snapshots.sol`, `Properties.sol`, and `Handlers.sol` are modified to match the target protocol. `FuzzTester.sol` is the static fuzzer entry point — copied once and never modified. `FoundryTester.sol` is the debugging harness — also never modified structurally, but used actively in Steps 8 and 10.
+3. **Handler gen** — Selected-contract handler stubs are replaced with protocol-specific handlers, and `Handlers.sol` is refined with the final imports and inheritance.
+4. **Invariant gen** — `Properties.sol` gets invariant checks, `Snapshots.sol` gets tracked state, `Base.sol` gets ghosts, and handler files get ghost and snapshot wiring.

package/dist/skills/fuzz/scripts/ensure_foundry.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# ensure_foundry.sh — Ensure Foundry (forge), foundry.toml, and forge-std are available.
+# Usage: ensure_foundry.sh [PROJECT_ROOT]
+# Exit 0 on success, exit 1 with guidance if not.
+
+set -euo pipefail
+
+PROJECT_ROOT="${1:-.}"
+
+if [ ! -d "$PROJECT_ROOT" ]; then
+    echo "ERROR: project root does not exist: $PROJECT_ROOT"
+    exit 1
+fi
+
+# 1. Check forge is installed
+if ! command -v forge &>/dev/null; then
+    echo "ERROR: forge not found in PATH."
+    echo ""
+    echo "Install Foundry:"
+    echo "  curl -L https://foundry.paradigm.xyz | bash"
+    echo "  foundryup"
+    echo ""
+    echo "Or see: https://www.getfoundry.sh/introduction/installation"
+    exit 1
+fi
+
+FORGE_VERSION=$(forge --version 2>&1 | head -1)
+echo "Foundry detected: $FORGE_VERSION"
+
+# 2. Create a compatible foundry.toml if missing
+if [ ! -f "$PROJECT_ROOT/foundry.toml" ]; then
+    echo "foundry.toml not found — creating one in $PROJECT_ROOT ..."
+    cd "$PROJECT_ROOT"
+    HH_CONFIG=""
+    if [ -f "hardhat.config.ts" ]; then
+        HH_CONFIG="hardhat.config.ts"
+    elif [ -f "hardhat.config.js" ]; then
+        HH_CONFIG="hardhat.config.js"
+    fi
+
+    if [ -n "$HH_CONFIG" ]; then
+        echo "Hardhat project detected — writing a Foundry-compatible config..."
+
+        # Hardhat-compatible layout per Foundry docs.
+        SRC_DIR=$(grep -oP "sources\s*:\s*['\"]?\K[^'\"',}]+" "$HH_CONFIG" 2>/dev/null | head -1 || true)
+        SRC_DIR="${SRC_DIR#./}"
+        if [ -z "$SRC_DIR" ]; then
+            if [ -d "contracts" ]; then
+                SRC_DIR="contracts"
+            elif [ -d "src" ]; then
+                SRC_DIR="src"
+            else
+                SRC_DIR="contracts"
+            fi
+        fi
+
+        ARTIFACTS_DIR=$(grep -oP "artifacts\s*:\s*['\"]?\K[^'\"',}]+" "$HH_CONFIG" 2>/dev/null | head -1 || true)
+        ARTIFACTS_DIR="${ARTIFACTS_DIR#./}"
+        if [ -z "$ARTIFACTS_DIR" ]; then
+            ARTIFACTS_DIR="out"
+        fi
+
+        SOLC_VERSION=$(perl -0ne 'print "$1\n" if /version\s*:\s*["'"'"']([^"'"'"']+)["'"'"']/s' "$HH_CONFIG" 2>/dev/null | head -1 || true)
+        OPTIMIZER_ENABLED=$(perl -0ne 'print "$1\n" if /optimizer\s*:\s*\{.*?enabled\s*:\s*(true|false)/s' "$HH_CONFIG" 2>/dev/null | head -1 || true)
+        OPTIMIZER_RUNS=$(perl -0ne 'print "$1\n" if /optimizer\s*:\s*\{.*?runs\s*:\s*(\d+)/s' "$HH_CONFIG" 2>/dev/null | head -1 || true)
+        EVM_VERSION=$(perl -0ne 'print "$1\n" if /evmVersion\s*:\s*["'"'"']([^"'"'"']+)["'"'"']/s' "$HH_CONFIG" 2>/dev/null | head -1 || true)
+
+        LIBS="[\"node_modules\", \"lib\"]"
+
+        REMAPPINGS=""
+        if [ -d "node_modules/@openzeppelin/contracts" ]; then
+            REMAPPINGS="$REMAPPINGS\"@openzeppelin/contracts/=node_modules/@openzeppelin/contracts/\","
+        fi
+        if [ -d "node_modules/@openzeppelin/contracts-upgradeable" ]; then
+            REMAPPINGS="$REMAPPINGS\"@openzeppelin/contracts-upgradeable/=node_modules/@openzeppelin/contracts-upgradeable/\","
+        fi
+
+        cat > foundry.toml <<EOF
+[profile.default]
+src = "${SRC_DIR}"
+out = "${ARTIFACTS_DIR}"
+libs = ${LIBS}
+EOF
+
+        if [ -n "$SOLC_VERSION" ]; then
+            echo "solc = \"${SOLC_VERSION}\"" >> foundry.toml
+        fi
+        if [ -n "$OPTIMIZER_ENABLED" ]; then
+            echo "optimizer = ${OPTIMIZER_ENABLED}" >> foundry.toml
+        fi
+        if [ -n "$OPTIMIZER_RUNS" ]; then
+            echo "optimizer_runs = ${OPTIMIZER_RUNS}" >> foundry.toml
+        fi
+        if [ -n "$EVM_VERSION" ]; then
+            echo "evm_version = \"${EVM_VERSION}\"" >> foundry.toml
+        fi
+        if [ -n "$REMAPPINGS" ]; then
+            REMAPPINGS="${REMAPPINGS%,}"
+            echo "remappings = [${REMAPPINGS}]" >> foundry.toml
+        fi
+
+        echo "foundry.toml configured for Hardhat layout (src=${SRC_DIR}, out=${ARTIFACTS_DIR}, libs=node_modules+lib)."
+    else
+        echo "Non-Hardhat project detected — writing a default Foundry config..."
+        cat > foundry.toml <<EOF
+[profile.default]
+src = "src"
+out = "out"
+libs = ["lib"]
+EOF
+    fi
+else
+    echo "foundry.toml detected."
+fi
+
+# 3. Check forge-std is installed (required by FoundryTester.sol)
+if [ ! -d "$PROJECT_ROOT/lib/forge-std" ]; then
+    echo "forge-std not found — installing..."
+    cd "$PROJECT_ROOT"
+    forge install foundry-rs/forge-std
+    echo "forge-std installed."
+else
+    echo "forge-std detected."
+fi
+exit 0

package/dist/skills/fuzz/scripts/estimate_cost.js

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+/**
+ * estimate_cost.js
+ *
+ * Prints and writes a rough cost estimate for a Fizz run based on the
+ * selected entry points and the subagent model tier. Numbers are ballpark —
+ * actual cost varies with handler complexity, rerun cycles, coverage churn,
+ * and orchestrator context size.
+ *
+ * Usage:
+ *   node estimate_cost.js <PROJECT_ROOT> [--meta-dir <dir>] [--model <sonnet|opus>] [--mode <guided|automatic>] [--output <path>]
+ *
+ * Defaults:
+ *   --meta-dir   .hex/fuzz/fizz_data
+ *   --model      sonnet
+ *   --mode       automatic
+ *   --output     <meta-dir>/cost-estimate.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ――― Pricing (USD per million tokens, Anthropic list price) ―――
+const PRICING = {
+    sonnet: { input: 3, output: 15 },
+    opus: { input: 15, output: 75 },
+};
+
+// ――― Per-stage baseline token usage (thousands, medium codebase = 1.0x) ―――
+// Derived from observed Fizz runs in fizz-workspace/.
+const STAGES = [
+    { name: 'Protocol Analyzer (conditional)',  count: 1, in_k: 50,  out_k: 8,  note: 'skipped when .hex/model/protocol.json exists' },
+    { name: 'Discovery agents',                 count: 5, in_k: 80,  out_k: 12, note: 'read all sources + handlers' },
+    { name: 'Synthesizer',                      count: 1, in_k: 50,  out_k: 12, note: 'merges 5 discovery outputs' },
+    { name: 'Implementers',                     count: 2, in_k: 60,  out_k: 15, note: 'edit Base / Snapshots / Properties / handlers' },
+    { name: 'Report Writer',                    count: 1, in_k: 30,  out_k: 8,  note: 'synthesizes final report' },
+    { name: 'Orchestrator overhead',            count: 1, in_k: 250, out_k: 40, note: 'parent agent across all steps' },
+];
+
+// ――― Argument parsing ―――
+
+const args = process.argv.slice(2);
+if (args.length === 0 || args[0] === '--help') {
+    console.log('Usage: node estimate_cost.js <PROJECT_ROOT> [--meta-dir <dir>] [--model <sonnet|opus>] [--mode <guided|automatic>] [--output <path>]');
+    process.exit(0);
+}
+
+const projectRoot = path.resolve(args[0]);
+let metaRelDir = '.hex/fuzz/fizz_data'; // Hex: was 'fizz_data'
+let model = 'sonnet';
+let mode = 'automatic';
+let outputPath = '';
+
+for (let i = 1; i < args.length; i++) {
+    if (args[i] === '--meta-dir' && args[i + 1]) { metaRelDir = args[++i]; }
+    else if (args[i] === '--model' && args[i + 1]) { model = args[++i].toLowerCase(); }
+    else if (args[i] === '--mode' && args[i + 1]) { mode = args[++i].toLowerCase(); }
+    else if (args[i] === '--output' && args[i + 1]) { outputPath = path.resolve(args[++i]); }
+}
+
+if (!PRICING[model]) {
+    console.error(`Unknown --model: ${model}. Expected 'sonnet' or 'opus'.`);
+    process.exit(1);
+}
+
+const metaDir = path.join(projectRoot, metaRelDir);
+const selectionPath = path.join(metaDir, 'entry-point-selection.json');
+if (!outputPath) {
+    outputPath = path.join(metaDir, 'cost-estimate.md');
+}
+
+// ――― Read selection ―――
+
+let contractCount = 0;
+let functionCount = 0;
+if (fs.existsSync(selectionPath)) {
+    try {
+        const selection = JSON.parse(fs.readFileSync(selectionPath, 'utf8'));
+        contractCount = selection.length;
+        for (const c of selection) functionCount += (c.functions || []).length;
+    } catch (e) {
+        console.error(`Failed to parse ${selectionPath}: ${e.message}`);
+        process.exit(1);
+    }
+} else {
+    console.error(`entry-point-selection.json not found at ${selectionPath} — producing a generic estimate with no scaling.`);
+}
+
+// ――― Size bucket ―――
+
+function sizeBucket(f) {
+    if (f < 20) return { label: 'small',  scale: 0.7 };
+    if (f < 50) return { label: 'medium', scale: 1.0 };
+    if (f < 100) return { label: 'large', scale: 1.4 };
+    return              { label: 'xl',     scale: 1.8 };
+}
+const bucket = sizeBucket(functionCount);
+const scale = bucket.scale;
+
+// ――― Compute per-stage and totals ―――
+
+const price = PRICING[model];
+let totalInK = 0;
+let totalOutK = 0;
+const rows = STAGES.map(s => {
+    const inK = s.count * s.in_k * scale;
+    const outK = s.count * s.out_k * scale;
+    totalInK += inK;
+    totalOutK += outK;
+    const costUsd = (inK * price.input + outK * price.output) / 1000;
+    return { ...s, inK, outK, costUsd };
+});
+const totalUsd = (totalInK * price.input + totalOutK * price.output) / 1000;
+const lowUsd = totalUsd * 0.7;
+const highUsd = totalUsd * 1.5;
+
+// ――― Format output ―――
+
+function fmtK(k) { return `${k.toFixed(1).replace(/\.0$/, '')}k`; }
+function fmtUsd(v) { return `$${v.toFixed(2)}`; }
+
+function pad(s, n) { return String(s).padEnd(n); }
+function padL(s, n) { return String(s).padStart(n); }
+
+const header = `| Stage                              | Count | Input    | Output  | Cost     |`;
+const sep    = `|------------------------------------|-------|----------|---------|----------|`;
+const bodyLines = rows.map(r => (
+    `| ${pad(r.name, 34)} | ${padL(r.count, 5)} | ${padL(fmtK(r.inK), 8)} | ${padL(fmtK(r.outK), 7)} | ${padL(fmtUsd(r.costUsd), 8)} |`
+));
+const totalLine = `| ${pad('TOTAL', 34)} | ${padL('', 5)} | ${padL(fmtK(totalInK), 8)} | ${padL(fmtK(totalOutK), 7)} | ${padL(fmtUsd(totalUsd), 8)} |`;
+
+const md = [
+    `# Cost Estimate`,
+    ``,
+    `Model: **${model}** (${fmtUsd(price.input)}/M input, ${fmtUsd(price.output)}/M output)`,
+    `Mode: **${mode}**`,
+    `Selected contracts: **${contractCount}**`,
+    `Selected functions: **${functionCount}** — scale ${scale}x (${bucket.label})`,
+    ``,
+    header,
+    sep,
+    ...bodyLines,
+    totalLine,
+    ``,
+    `**Estimated total: ${fmtUsd(totalUsd)}** — expected range ${fmtUsd(lowUsd)} – ${fmtUsd(highUsd)}`,
+    ``,
+    `These numbers are Anthropic list-price estimates for the subagents and a rough orchestrator overhead share. Actual cost varies with: coverage-iteration cycles (Step 8), re-runs after compile errors, handler complexity, whether the Hex protocol model skipped the Protocol Analyzer, and prompt-cache hit rate. Treat this as a ballpark, not a commitment.`,
+    ``,
+].join('\n');
+
+// ――― Write file + print ―――
+
+fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+fs.writeFileSync(outputPath, md);
+
+process.stdout.write(md);
+process.stdout.write(`\nWrote: ${outputPath}\n`);