vulnerability-base

name	vulnerability-base
description	Core foundation loaded by all sub-auditor agents (reentrancy, logic, oracle, etc.). Provides: Iron Laws, Code4rena finding template, severity classification, and quality standards. Auto-loaded when sub-auditors write findings to .vigilo/findings/. Ensures consistent output format across all auditors - NO PoC code, scenario only.

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

# [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

// 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