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

Output Structure

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