vulnerability-base

# Vulnerability Analysis Foundation This skill provides the core standards that ALL vulnerability auditors must follow. --- ## Iron Laws (NO EXCEPTIONS) ### 1. NO FINDING WITHOUT CODE EVIDENCE ``` WRONG: "The function might be vulnerable" RIGHT: "withdraw() at src/Vault.sol:156 updates balance after external call" ``` Every finding MUST include: - Exact file path - Function name - Line numbers - Code snippet with `@audit` annotation ### 2. NO SCENARIO WITHOUT CONCRETE STEPS ``` WRONG: "Attacker could exploit this" RIGHT: "1. Call X with value Y 2. State becomes Z 3. Attacker profits" ``` Every attack scenario MUST include: - Numbered steps (1, 2, 3...) - Specific function calls - Parameter values - State changes ### 3. NO POC CODE - SCENARIO ONLY ``` WRONG: Writing Foundry test code in findings RIGHT: Writing detailed attack scenario for main agent to generate PoC ``` You generate **attack scenarios**. The main agent generates PoC code. ### 4. NO DOLLAR AMOUNTS IN IMPACT ``` WRONG: "Attacker profits $1.5M" RIGHT: "Attacker drains entire vault TVL" ``` Use qualitative impact descriptions only. --- ## Rationalization Table (REJECT THESE EXCUSES) | Excuse | Reality | |--------|---------| | "It's unlikely" | MEV bots automate attacks 24/7 | | "Low value at risk" | TVL can grow; vulnerability remains | | "It's by design" | Document as risk if undocumented | | "Frontend prevents this" | On-chain must be secure standalone | | "Admin is trusted" | Admin keys get compromised | | "I'll check later" | Check NOW or miss critical bugs | --- ## Output Directory Structure Write findings to `.vigilo/findings/` with this structure: ``` .vigilo/findings/ ├── high/ │ └── {auditor-type}/ │ └── {Severity}-{id}-{title}.md ├── medium/ │ └── {auditor-type}/ │ └── {Severity}-{id}-{title}.md └── low/ └── {auditor-type}/ └── {Severity}-{id}-{title}.md ``` **Filename format**: `{Severity}-{id}-{kebab-case-title}.md` Examples: - `.vigilo/findings/high/logic/H-01-donation-attack-inflated-collateral.md` - `.vigilo/findings/high/reentrancy/H-01-withdraw-callback-drain.md` - `.vigilo/findings/medium/oracle/M-01-stale-price-check.md` --- ## Iron Law: One Finding = One File **NEVER combine multiple findings in a single file.** ``` ❌ WRONG: reentrancy-findings.md (multiple findings in one file) ❌ WRONG: H-01.md (missing descriptive title) ✅ RIGHT: H-01-withdraw-reentrancy.md ✅ RIGHT: H-02-callback-state-desync.md ✅ RIGHT: M-01-missing-cei-pattern.md ``` **Filename format**: `{Severity}-{id}-{kebab-case-title}.md` - Severity: H (High), M (Medium), L (Low) - id: Sequential within your auditor scope (01, 02, 03...) - Title: Short kebab-case description (2-5 words) **This same format is used for**: - Attack scenario files: `.vigilo/findings/{severity}/{auditor}/H-01-title.md` - PoC test files: `test/poc/H-01-title.t.sol` - PoC validation logs: `.vigilo/poc/H-01-title.md` --- ## Finding Template ```markdown # [H/M/L]-XX: [Descriptive Title] ## Summary [1-2 sentence description of the vulnerability] ## Vulnerability Detail ### Root Cause [Technical explanation of why this vulnerability exists] ### Code Location - File: `src/Contract.sol` - Function: `vulnerableFunction()` - Lines: 142-156 ```solidity // @audit [Annotation explaining the issue] function vulnerableFunction() external { // vulnerable code here } ``` ## Impact - **Likelihood**: [High/Medium/Low] - [Justification] - **Impact**: [High/Medium/Low] - [Justification] - **Severity**: [HIGH/MEDIUM/LOW] ## Attack Scenario ### Preconditions - [Initial state item 1] - [Initial state item 2] ### Attack Steps 1. [Concrete step with function call and parameters] 2. [State change that occurs] 3. [Next action] 4. [Final state / attacker benefit] ### Expected Impact - [Qualitative description of damage - NO dollar amounts] ## Recommended Mitigation ```solidity // Fixed version function vulnerableFunction() external { // secure code here } ``` ``` --- ## Severity Classification | Severity | Criteria | |----------|----------| | **High** | Direct fund loss, fund loss with minimal conditions, or permanent DoS | | **Medium** | Conditional fund loss, temporary DoS, or significant protocol malfunction | | **Low** | Minor issues, informational, gas optimizations | --- ## Quality Checklist Before completing your analysis, verify: - [ ] Every finding has `file:line` reference - [ ] Every finding has code snippet with `@audit` annotation - [ ] Every attack scenario has numbered steps - [ ] Every step has concrete values (not "some amount") - [ ] NO PoC code included (main agent generates this) - [ ] NO dollar amounts in impact (use "entire TVL", "all user funds") - [ ] Severity matches classification criteria - [ ] Mitigation is provided and correct