weasel-overview

# Weasel Overview

Project overview and audit scoping for security engineers starting a new audit.

## When to Activate

- Starting a new audit
- User asks "what does this project do?"
- User wants to scope/understand a codebase

## When NOT to Use

- User wants to run static analysis (→ weasel-analyzer)
- User wants to explain specific code (→ weasel-explainer)
- User already understands the project and wants to audit

## Process

### 1. Read Documentation
- README.md - project description, architecture
- docs/ folder if exists
- Comments in main contracts
- **Previous audits** - Check for `audit/`, `audits/`, or audit reports
- **Known issues** - Check `known-issues.md`, issue tracker links

### 2. Map Project Structure
- List all .sol files
- Identify: core contracts vs libraries vs interfaces
- Map inheritance hierarchy
- Note external dependencies (OpenZeppelin, Chainlink, etc.)

### 3. Identify Entry Points

**User Functions** (highest risk - untrusted input):
- deposit(), withdraw(), swap(), transfer()...
- Any external/public that handles value

**Admin Functions** (check access control):
- setFee(), pause(), upgrade()...
- Note: what permissions? onlyOwner? Multisig?

**Callbacks** (reentrancy risk):
- onFlashLoan(), uniswapV3Callback()...
- Any function called by external contracts

### 4. Trace Value Flow
- **Inbound:** How does ETH/tokens enter? (deposit, swap, mint)
- **Outbound:** How does ETH/tokens exit? (withdraw, claim, burn)
- **Internal:** How does value move between contracts?

### 5. Map Trust Boundaries

**Untrusted** - assume malicious:
- Users, external contracts, oracles

**Privileged** - trusted but verify:
- Owner/Admin, Governance, Keepers

**Internal** - trusted:
- Protocol's own contracts, libraries

### 6. Identify Focus Areas

| Project Type | High-Risk Areas |
|--------------|-----------------|
| DeFi/Lending | Liquidation, interest calc, oracles, flash loans |
| DEX/AMM | Price calc, slippage, LP math, fees |
| Staking/Vaults | Deposit/withdraw, rewards, share accounting |
| NFT/Gaming | Minting, randomness, marketplace |
| Governance | Voting, timelock, proposal execution |

## Output Structure

```markdown
# [Project Name] Overview

## Summary
[2-3 sentences: what does this project do?]

## Architecture
- Contract list with purpose
- Key inheritance (ERC4626, Ownable, etc.)
- External dependencies

## Entry Points

### User Functions (Priority: High)
| Function | Contract | Risk |
|----------|----------|------|
| deposit() | Vault.sol:45 | Handles ETH |
| withdraw() | Vault.sol:89 | Sends ETH |

### Admin Functions (Check Access Control)
| Function | Contract | Permission |
|----------|----------|------------|
| setFee() | Vault.sol:120 | onlyOwner |

### Callbacks (Reentrancy Risk)
- onFlashLoan() called by flash lender

## Value Flow
- **In:** ETH via deposit(), tokens via depositToken()
- **Out:** ETH via withdraw(), rewards via claim()

## Trust Model
- **Owner:** Can pause, set fees (max X%)
- **External:** Chainlink oracle (single price feed)

## Audit Focus (Prioritized)
1. [High] Reentrancy in withdraw() - external call before state update
2. [High] Oracle manipulation - single feed, no TWAP
3. [Med] Share inflation - first depositor attack?

## Recommended Audit Order
1. Vault.sol - core logic, highest risk
2. Router.sol - entry point, input validation
3. Token.sol - standard ERC20, lower priority
```

## After Overview

Offer:
- "Run Weasel static analysis?"
- "Deep dive into [highest risk contract]?"
- "Explain specific function?"

## Rationalizations to Reject

| Rationalization | Why It's Wrong |
|-----------------|----------------|
| "I'll skip the libraries, they're standard" | Libraries can be modified or misused. Note them. |
| "This looks like a simple project" | Simple projects can have complex bugs. Be thorough. |
| "README explains everything" | README can be outdated. Verify against actual code. |
| "I'll focus only on the main contract" | Entry points can be anywhere. Map ALL external functions. |
| "Previous audit means it's safe" | Previous audits miss things. Note them, don't rely on them. |
| "I understand the pattern, no need to map it" | Every implementation differs. Map THIS codebase. |