white-hat-scanner 1.0.1

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "white-hat-scanner",
+  "version": "1.0.1",
+  "description": "Autonomous white-hat security scanner for DeFi protocols",
+  "main": "dist/index.js",
+  "bin": {
+    "white-hat-scanner": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "ts-node src/index.ts",
+    "test": "ts-node src/test/smoke.ts"
+  },
+  "dependencies": {
+    "ioredis": "5.3.2",
+    "node-fetch": "3.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "22.10.0",
+    "ts-node": "10.9.2",
+    "typescript": "5.3.3"
+  }
+}

package/research/bounty-economics.md

@@ -0,0 +1,145 @@
+# Bug Bounty Economics
+
+> Data sourced from Immunefi leaderboard and explore pages — last refreshed **2026-04-03**.
+
+---
+
+## 1. Top Immunefi Earners (All-Time)
+
+| Rank | Handle | Total Earnings | Paid Reports | Avg / Report |
+|------|--------|---------------|-------------|-------------|
+| 1 | Barracuda3172 | $14,439,800 | 7 | ~$2.06M |
+| 2 | RetailDdene2946 | $10,020,000 | 2 | ~$5.01M |
+| 3 | PwningEth | $8,000,000 | 8 | ~$1.00M |
+| 4 | GothicShanon89238 | $4,181,150 | 16 | ~$261K |
+| 5 | LonelySloth *(Elite Auditor)* | $3,612,409 | 60 | ~$60K |
+| 6 | usmannk *(Elite Auditor)* | $3,250,727 | 16 | ~$203K |
+| 7 | Bobface | $3,391,900 | 8 | ~$424K |
+| 8 | ily2 | $3,030,000 | 3 | ~$1.01M |
+| 9 | kankodu *(Elite Auditor)* | $2,681,250 | 17 | ~$158K |
+| 10 | TrustSec | — | — | — |
+| 11 | Paludo0x | — | — | — |
+| 12 | ibrahimatix0x01 | — | — | — |
+
+**Key insight:** The top 3 each averaged ≥ $1M per accepted critical report. RetailDdene2946 earned $10M from just 2 reports — textbook precision strategy.
+
+---
+
+## 2. Current High-Paying Programs (Immunefi, April 2026)
+
+| Protocol | Chain | Max Bounty | Vault TVL | Total Paid | Med. Resolution |
+|----------|-------|-----------|-----------|-----------|----------------|
+| Ethena | Ethereum | **$3,000,000** | $12.4k | Private | Private |
+| SSV Network | Ethereum | **$1,000,000** | $137.5k | Private | Private |
+| DeXe Protocol | Ethereum | **$500,000** | $60.5k | Private | Private |
+| Lombard Finance | Ethereum | **$250,000** | $40k | Private | Private |
+| Ref Finance | NEAR | **$250,000** | $7.8k | $98.9k | 2 weeks |
+| Bitflow | Stacks | **$100,000** | $2.8k | Private | Private |
+| StackingDAO | Stacks | **$100,000** | $2.8k | Private | Private |
+| The Graph | Ethereum | $50,000 | $82.5k | $1.5M | **1 day** |
+| Immunefi Platform | Ethereum | $50,000 | $4.6k | $63.8k | **9 hours** |
+| Hedera | Hedera | $30,000 | $26.7k | Private | Private |
+
+*240 active bounty programs as of data refresh. Programs with public resolution times tend to be fastest payers.*
+
+---
+
+## 3. What Vuln Classes Hit $500K+
+
+Based on historical Immunefi disclosures and leaderboard payouts, critical payouts at the $500K–$10M tier consistently come from:
+
+| Vuln Class | Why it Pays Max | Example Protocols |
+|-----------|----------------|------------------|
+| **Direct fund drain via logic bug** | Arbitrary withdrawal, incorrect accounting, broken invariant lets attacker take all protocol TVL | AMMs, lending protocols |
+| **Bridge exploit / validator takeover** | Cross-chain bridges hold billions in escrow; single message-verification flaw can drain everything | Wormhole ($320M patched), Ronin |
+| **Governance manipulation** | Flash-loan vote, timelock bypass, proposal spam that executes malicious code | DAOs with on-chain governance |
+| **Oracle price manipulation** | TWAP manipulation, sandwich attacks on spot-price oracles feeding liquidation logic | DeFi money markets |
+| **Upgrade proxy misconfiguration** | Unprotected `upgradeTo()`, uninitialized proxy implementation can transfer ownership to attacker | Any UUPS / Transparent proxy |
+| **Signature replay / malleability** | `ecrecover` without nonce or chain-id allows replaying signed messages across chains or re-spending | Permit-based tokens, meta-tx relayers |
+
+---
+
+## 4. Time-to-Payout (Disclosure → Payment)
+
+| Platform | Typical Range | Best Case | Notes |
+|----------|--------------|-----------|-------|
+| Immunefi (managed triage) | 2–6 weeks | 9 hours (Immunefi itself) | Managed triage programs resolve fastest |
+| Immunefi (self-managed) | 4–12 weeks | 1 day (The Graph) | Depends on protocol team responsiveness |
+| HackerOne | 2–8 weeks | Same-day (H1 fast-track) | More mature disclosure SLAs |
+| Direct disclosure | 1–6 months | Varies | No SLA guarantee; ghosting risk |
+
+**Process steps consuming the most time:**
+1. Triage confirmation (can take days if team is small)
+2. Root-cause + fix agreement
+3. Fix deployment + mainnet verification
+4. Payment processing (crypto transfer is fast once approved)
+
+---
+
+## 5. Legal Framework
+
+### Safe Harbor
+Immunefi operates a formal **Safe Harbor** program: protocols that opt in agree not to pursue legal action against researchers who disclose responsibly within scope. As of 2026, ~30+ protocols have opted in. Always verify a specific program's safe harbor status before testing.
+
+- HackerOne programs have their own legal safe harbor language in each program policy.
+- **Always** read the program policy's legal section before starting research.
+
+### Key Jurisdictions
+| Jurisdiction | Relevant Law | Researcher Risk |
+|-------------|-------------|----------------|
+| USA | CFAA (Computer Fraud & Abuse Act) | High if out-of-scope; authorized research generally protected |
+| EU | NIS2 / national cyber laws | Varies by country; Germany / Netherlands generally researcher-friendly |
+| Singapore | Computer Misuse Act | Generally tolerant of authorized research |
+| Cayman Islands | Few crypto-specific laws | Many DeFi entities incorporated here |
+
+**Practical rule:** Stick strictly to in-scope assets. Never exploit a live production system beyond confirming exploitability. Submit PoC to testnets or forked state when possible.
+
+---
+
+## 6. Business Models: Volume vs. Precision
+
+### Model A — Precision (Few Critical Bugs)
+- Target: $500K–$10M per find
+- Focus: Bridges, large lending protocols, canonical cross-chain infrastructure
+- Team size: 1–3 senior researchers
+- Tools: Manual code review + custom fuzzing harnesses + formal verification
+- **RetailDdene2946** is the archetype: $10M from 2 reports
+- Downside: Long dry spells; high variance income
+
+### Model B — Volume (Many Medium/High Bugs)
+- Target: $10K–$100K per find, 4–12 finds per quarter
+- Focus: Long-tail DeFi protocols, new launches, audit competition overlap
+- Team size: 3–8 researchers
+- Tools: Slither + Echidna automation pipeline, rapid triage, templates
+- **LonelySloth** exemplifies this: $3.6M from 60 reports (~$60K avg)
+- Downside: Diminishing returns as low-hanging fruit gets picked
+
+### Model C — Hybrid (Systematic with Precision Escalation)
+- Run automated tooling across many protocols to find low/medium bugs quickly
+- Escalate suspicious patterns to deep manual review for critical potential
+- Use audit competition wins as intelligence on target codebases
+- **Recommended for a team operation**: predictable base income + upside optionality
+
+### Realistic Annual Revenue Estimates (2026)
+| Team Tier | Reports/yr | Avg Payout | Gross Revenue |
+|-----------|-----------|-----------|--------------|
+| Solo beginner | 4–8 | $5K | $20–40K |
+| Solo experienced | 12–24 | $25K | $300K–600K |
+| Small team (3 ppl) | 30–60 | $40K | $1.2M–2.4M |
+| Elite precision team | 3–8 | $500K+ | $1.5M–4M+ |
+
+---
+
+## 7. Notable Historical Payouts
+
+| Year | Protocol | Researcher / Team | Payout | Vuln Type |
+|------|----------|-------------------|--------|-----------|
+| 2022 | Wormhole | External (post-exploit) | N/A — $320M exploited | Signature verification bypass |
+| 2022 | Aurora | pwning.eth | $6,000,000 | Integer overflow in NEAR/EVM bridge |
+| 2022 | Polygon | Leon Spacewalker | $2,000,000 | Double-spend in Plasma bridge |
+| 2023 | Ethereum 2.0 | Various | $250,000 each | Consensus client bugs |
+| 2023 | Arbitrum | Various | $400,000 | Nitro bridge logic |
+| 2024 | Ethena | Barracuda3172 (est.) | $3M+ | Critical smart contract logic |
+| 2024–25 | Multiple | RetailDdene2946 | ~$10M | Critical (undisclosed) |
+
+*Most Immunefi payouts above $1M remain undisclosed per request of the receiving protocol.*

package/research/tooling-landscape.md

@@ -0,0 +1,216 @@
+# Smart Contract Security Tooling Landscape
+
+> Tool versions current as of April 2026. Sources: GitHub repos for Slither (crytic/slither), Echidna (crytic/echidna), Foundry (foundry-rs/foundry).
+
+---
+
+## 1. Slither — Static Analysis
+
+**Repo:** https://github.com/crytic/slither
+**Language:** Python 3.10+
+**Targets:** Solidity ≥ 0.4, Vyper
+**Install:** `pip install slither-analyzer` or `uv tool install slither-analyzer`
+
+### All Detectors (by Impact)
+
+#### HIGH Impact / HIGH Confidence — *Auto-triage as critical leads*
+| # | Detector | What It Finds |
+|---|----------|--------------|
+| 1 | `abiencoderv2-array` | Storage abiencoderv2 array bugs |
+| 2 | `arbitrary-send-erc20` | `transferFrom` with arbitrary `from` |
+| 3 | `array-by-reference` | Modifying storage array by value |
+| 4 | `encode-packed-collision` | `abi.encodePacked` hash collision |
+| 5 | `incorrect-shift` | Wrong parameter order in shift ops |
+| 6 | `multiple-constructors` | Multiple constructor definitions |
+| 7 | `name-reused` | Contract name collision |
+| 8 | `protected-vars` | Unprotected variables |
+| 9 | `public-mappings-nested` | Nested public mappings |
+| 10 | `rtlo` | Right-to-left override Unicode character (malicious code hiding) |
+| 11 | `shadowing-state` | State variable shadowing |
+| 12 | `suicidal` | Anyone can call `selfdestruct` |
+| 13 | `uninitialized-state` | Uninitialized state variables |
+| 14 | `uninitialized-storage` | Uninitialized storage pointers |
+| 15 | `unprotected-upgrade` | Proxy upgrade without access control ⚠️ *Critical bug class* |
+
+#### HIGH Impact / MEDIUM Confidence — *Worth manual follow-up*
+| # | Detector | What It Finds |
+|---|----------|--------------|
+| 16 | `arbitrary-send-erc20-permit` | `transferFrom` + permit with arbitrary `from` |
+| 17 | `arbitrary-send-eth` | ETH sent to arbitrary address |
+| 18 | `controlled-array-length` | Tainted array length assignment |
+| 19 | `controlled-delegatecall` | Attacker-controlled delegatecall target |
+| 20 | `delegatecall-loop` | Payable + delegatecall in loop |
+| 21 | `incorrect-exp` | `^` used as XOR instead of exponentiation |
+| 22 | `incorrect-return` | Wrong `return` in assembly |
+| 23 | `msg-value-loop` | `msg.value` read inside a loop |
+| 24 | `reentrancy-eth` | Classic reentrancy (ETH theft) |
+| 25 | `reentrancy-balance` | Reentrancy with stale balance |
+| 26 | `return-leave` | `return` instead of `leave` in Yul |
+| 27 | `storage-array` | Signed integer storage array compiler bug |
+| 28 | `unchecked-transfer` | ERC20 transfer return value ignored |
+| 29 | `weak-prng` | On-chain randomness predictable |
+
+#### MEDIUM Impact / HIGH Confidence
+| # | Detector | What It Finds |
+|---|----------|--------------|
+| 30 | `domain-separator-collision` | EIP-2612 DOMAIN_SEPARATOR collision |
+| 31 | `enum-conversion` | Dangerous enum cast |
+| 32 | `erc20-interface` | Wrong ERC-20 interface |
+| 33 | `erc721-interface` | Wrong ERC-721 interface |
+| 34 | `incorrect-equality` | Dangerous strict equality (`==` on balances) |
+| 35 | `locked-ether` | Contract receives ETH but has no withdrawal |
+| 36 | `mapping-deletion` | Delete on struct-containing mapping |
+| 37 | `pyth-deprecated-functions` | Pyth oracle deprecated API |
+| 38 | `pyth-unchecked-confidence` | Pyth price confidence not validated |
+| 39 | `pyth-unchecked-publishtime` | Pyth price staleness not checked |
+| 40 | `shadowing-abstract` | Abstract contract state shadowing |
+| 41 | `tautological-compare` | Variable compared to itself |
+| 42 | `tautology` | Boolean tautology / contradiction |
+| 43 | `write-after-write` | Dead write (result immediately overwritten) |
+
+#### MEDIUM Impact / MEDIUM Confidence (selected)
+| # | Detector | What It Finds |
+|---|----------|--------------|
+| 44 | `boolean-cst` | Misuse of boolean constant |
+| 45 | `chronicle-unchecked-price` | Chronicle oracle price not validated |
+| 46 | `constant-function-asm` | `view`/`pure` + assembly writes state |
+| 47 | `constant-function-state` | `view`/`pure` actually changes state |
+| ... | + ~50 more low/info detectors | Code quality, gas, best practices |
+
+**Total detectors: ~100+** across High/Medium/Low/Informational tiers.
+
+### What Slither Does NOT Catch
+- Business logic bugs (protocol-specific invariants)
+- Economic attack vectors (MEV, oracle manipulation requiring live price context)
+- Cross-contract state dependencies requiring transaction simulation
+- Governance attacks (voting math, quorum edge cases)
+- Flash loan attack paths (multi-step economic sequences)
+
+---
+
+## 2. Echidna — Property-Based Fuzzer
+
+**Repo:** https://github.com/crytic/echidna
+**Language:** Haskell; tests Solidity/Vyper
+**Powered by:** Slither (for pre-fuzzing analysis)
+
+### Testing Modes
+| Mode | What It Tests |
+|------|--------------|
+| `property` (default) | `echidna_`-prefixed functions returning `bool` |
+| `assertion` | `assert()` / Foundry `assertX` failures |
+| `foundry` | Foundry `test_` unit tests + `invariant_` stateful tests |
+| `overflow` | Integer over/underflows (Solidity ≥ 0.8) |
+| `optimization` | Maximize return value of `int256`-returning functions |
+| `exploration` | Coverage collection only |
+
+### What Echidna Catches That Slither Misses
+- **Stateful invariant violations**: Protocol-level rules (e.g., "total shares never exceed total assets") that only break after a sequence of transactions
+- **Integer over/underflows** in complex arithmetic paths
+- **Access control edge cases** discovered through random call sequencing
+- **Economic invariants**: e.g., `x * y == k` in AMMs after multiple swaps
+- **Fork-based testing**: Can test against mainnet state forks to catch real-world interaction bugs
+
+### Echidna Workflow
+```bash
+# Write invariant in Solidity
+function echidna_total_supply_never_exceeds_cap() public returns (bool) {
+    return token.totalSupply() <= token.cap();
+}
+
+# Run fuzzer
+echidna MyContract.sol --config echidna.yaml --test-mode property
+```
+
+---
+
+## 3. Foundry Invariant Fuzzing
+
+**Repo:** https://github.com/foundry-rs/foundry
+**Components:** Forge (test/fuzz), Cast (on-chain interaction), Anvil (local node), Chisel (REPL)
+
+### Forge Fuzzing Capabilities
+- **Unit fuzzing**: `forge test` automatically fuzzes function inputs marked with `uint256 fuzzedInput` parameter
+- **Invariant testing**: `invariant_`-prefixed test functions are called across randomized call sequences against a deployed contract system
+- **Forked state testing**: `--fork-url` runs tests against a mainnet fork
+- **Coverage**: `forge coverage` generates line/branch coverage reports
+
+### What Foundry Catches vs Echidna
+| Capability | Foundry | Echidna |
+|-----------|---------|---------|
+| Invariant testing | ✅ | ✅ |
+| Fork-state testing | ✅ (built-in) | ✅ (config option) |
+| Assertion mode | ✅ | ✅ |
+| Corpus persistence | Partial | ✅ Full corpus directory |
+| Coverage guidance | ✅ | ✅ |
+| Speed | ✅ Fast (Rust EVM) | Slower (Haskell) |
+| Custom mutation strategies | Limited | ✅ More configurable |
+| Best for | Integration in CI, broad coverage | Deep invariant campaigns |
+
+---
+
+## 4. Where LLM / Claude Review Adds the Most Value
+
+Static analysis and fuzzing leave significant gaps. LLM-assisted review is highest-signal for:
+
+### High-Value LLM Review Areas
+
+| Category | Why Automation Fails | LLM Advantage |
+|----------|---------------------|---------------|
+| **Business logic correctness** | No tool knows the protocol spec; rules aren't in code | Can reason about intent vs. implementation |
+| **Governance logic** | Quorum, timelock, proposal encoding — context-dependent | Understands multi-step governance flows |
+| **Economic / game-theory attacks** | Flash loans, MEV, incentive manipulation — require reasoning about adversarial actors | Can model "what would a rational attacker do?" |
+| **Fee-on-transfer / rebase token interactions** | Protocol says it handles these; LLM can challenge assumptions | Cross-contract assumption verification |
+| **Access control intent** | Slither flags missing modifiers, but LLM can question whether the right roles have the right permissions | Can map roles to intended access matrix |
+| **Upgrade compatibility** | Storage layout collisions in proxy upgrades; new initializer gaps | Can compare old vs new storage layout |
+| **Cross-chain message validation** | Bridge message parsing, chain-id confusion, replay paths | Can trace message lifecycle across chains |
+| **NatSpec vs implementation divergence** | Comments say one thing; code does another | Direct comparison of documentation to code |
+| **EIP compliance gaps** | Token implements EIP-4626 but misses edge case in `convertToShares` | Can verify against spec line-by-line |
+
+### LLM Prompt Patterns That Work
+```
+"Given this contract, what invariants should always hold? Which ones can you
+verify are enforced, and which ones lack enforcement?"
+
+"Trace the path of funds from deposit to withdrawal. Where could an attacker
+divert funds or extract more than deposited?"
+
+"This contract uses a flash loan in function X. What state changes happen
+before the callback vs after? Is there any state the callback can manipulate
+to extract value?"
+```
+
+---
+
+## 5. Gap Analysis — Vuln Classes With No Good Automated Tool
+
+These are the classes where the most unclaimed bounties still exist:
+
+| Vuln Class | Coverage Today | Gap |
+|-----------|---------------|-----|
+| **Protocol-level economic attacks** | No tool | Requires modeling token economics + adversary incentives; needs human + LLM |
+| **Cross-chain replay / chain confusion** | Partial (chain-id checks) | Full message lifecycle across heterogeneous VMs is unsolved |
+| **Governance takeover paths** | No tool | Requires modeling token distribution + quorum + timelock |
+| **Oracle manipulation profitability** | No tool | Needs real price data + gas modeling to determine if attack is profitable |
+| **Composability bugs** (3+ protocols interacting) | No tool | State space explosion; current fuzzers handle 1–2 contracts well |
+| **Upgrade path correctness** | Slither partial | Full storage slot diff + initializer audit is manual |
+| **MEV extraction paths** | No tool | Block construction awareness required |
+| **Stale oracle price window** | Slither pyth/chronicle detectors | Only covers specific oracle integrations; Chainlink staleness widely missed |
+| **Permit signature abuse across chains** | No tool | EIP-2612 permits are chain-specific but many protocols assume they aren't |
+| **Fee accumulation / rounding attacks** | No tool | Requires modeling fee math over many transactions |
+
+**Build opportunity:** The composability bug class (multi-protocol interaction fuzzing with forked state) has the highest potential payout-per-find ratio and the weakest tooling coverage.
+
+---
+
+## 6. Recommended Toolchain Stack
+
+```
+Recon        → Slither (auto-scan, flag high-confidence issues)
+              → Slither printers: call-graph, inheritance, cfg
+Fuzzing      → Foundry invariant tests (CI integration)
+              → Echidna (deep campaign for high-value targets)
+Simulation   → Anvil (fork mainnet state, simulate attacks)
+LLM Review   → Claude on business logic, governance, economic attack surface
+Reporting    → Slither --checklist --markdown-root for automated findings
+```