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