behavioral-state-analysis

# Behavioral State Analysis (BSA)

Audit smart contracts by extracting behavioral intent, then systematically breaking it across security dimensions.

## When to Use

- Smart contract security audits
- DeFi protocol threat modeling (DEXs, lending, staking, vaults)
- Cross-contract attack surface analysis
- Vulnerability prioritization with confidence scoring

## When NOT to Use

- Pure context building (use audit-context-building)
- Entry point identification only (use entry-point-analyzer)
- Single-dimension only (use semantic-guard-analysis or state-invariant-detection)

## Token Budget Rules

**Follow these strictly to avoid context exhaustion:**

1. **Be terse.** Use bullet points and tables, not prose. No filler sentences.
2. **Smart scope first.** Classify the contract type in Phase 1, then run ONLY relevant engines in Phase 2 (see engine selection matrix below).
3. **Tiered output depth:**
   - Critical/High findings → full detail + PoC code
   - Medium findings → root cause + exploit scenario (no PoC)
   - Low/Info findings → one-line description only
4. **No redundant analysis.** If a dimension has no attack surface (e.g., no value flows = skip ETE), say "N/A" and move on.
5. **Cap Phase 1 output** to ≤30 lines per contract. List invariants and states, skip verbose specification documents.
6. **PoC generation** only for Critical and High severity findings. For others, describe the exploit path in ≤3 steps.
7. **Combine phases in output** — don't repeat findings across phases. Each finding appears once with all metadata inline.

## Pipeline

### Phase 1: Behavioral Decomposition (keep brief)

Extract intent from code and docs. Output per contract:

```
Contract: <Name>
Type: <DeFi/Token/Governance/NFT/Utility/Proxy>
States: [list]
Key Invariants (≤5):
  - <invariant>
Privileged Roles: [list]
Value Entry/Exit Points: [list or "none"]
```

**Then select engines:**

| Contract Type | Run ETE | Run ACTE | Run SITE |
|--------------|---------|----------|----------|
| DeFi (DEX/lending/vault/staking) | Yes | Yes | Yes |
| Token (ERC20/721/1155) | Yes | Lite | Lite |
| Governance/DAO | Lite | Yes | Yes |
| NFT marketplace | Yes | Yes | Lite |
| Utility/Library | No | Lite | Lite |
| Proxy/Upgradeable | No | Yes | Yes |

**Lite** = check only the top-priority item for that engine (see below).

### Phase 2: Threat Modeling (selected engines only)

Run only the engines selected above. For each engine, analyze in this priority order — stop if contract surface is exhausted:

**Economic Threat Engine (ETE):**
1. Value flow tracing — where can value enter/leave? Any sinks or circular flows?
2. Economic invariant verification — does `deposits == withdrawals + balance` hold?
3. Incentive analysis — any rational actor exploits (MEV, sandwich, griefing)?

**Access Control Threat Engine (ACTE):**
1. Unprotected privileged functions — any admin/owner actions callable by anyone?
2. Role escalation paths — can `User → [actions] → Admin`?
3. msg.sender vs tx.origin confusion; signature replay

**State Integrity Threat Engine (SITE):**
1. Non-atomic state updates — partial updates before external calls?
2. Sequence vulnerabilities — initialization bypass, unexpected call ordering?
3. Cross-contract stale data or reentrancy vectors

**Lite mode** = run only item #1 from that engine's list.

### Phase 3: Exploit Verification

For each hypothesis from Phase 2:
- Build attack sequence (≤5 steps)
- For Critical/High: generate minimal Foundry/Hardhat PoC (keep code short — test the specific vuln, not a full test suite)
- Quantify impact: Critical (all funds/system) | High (significant loss/privesc) | Medium (griefing/DOS) | Low (info/best practice)

### Phase 4: Score & Prioritize

Score: `Confidence = (Evidence × Feasibility × Impact) / FP_Rate`

| Factor | 1.0 | 0.7 | 0.4 | 0.1 |
|--------|-----|-----|-----|-----|
| Evidence | Concrete path, no deps | Specific state needed | Pattern-based | Heuristic |
| Feasibility | PoC confirmed | Achievable state | External conditions | Infeasible |

Impact: 5=total loss, 4=partial loss, 3=griefing, 2=info leak, 1=best practice
FP_Rate: 0.05 (known pattern) → 0.15 (moderate) → 0.40 (weak) → 0.60 (heuristic)

**Prioritization:** Report findings ≥10% confidence. Never suppress Impact ≥4.

## Finding Format (use for every finding)

```
### [F-N] Title
Severity: Critical|High|Medium|Low  |  Confidence: X%
Location: contract.sol#L10-L25, functionName()
Root Cause: <1-2 sentences>
Exploit: <numbered steps, ≤5>
Impact: <1 sentence with quantified risk>
Fix: <code diff or 1-2 sentence recommendation>
PoC: <only for Critical/High — minimal test code>
```

## Advanced Checks (run only if relevant to contract type)

- **Cross-contract:** Map external call chains `A→B→C`, test transitive trust
- **Time-based:** `block.timestamp` manipulation, expired signatures, replay
- **Upgradeable:** Storage collisions, re-initialization, migration atomicity

## Mindset

- "Standard function" → can behave non-standardly in context
- "Admin is trusted" → model admin compromise, check excessive powers
- "Known pattern" → novel interactions in specific contexts
- "Small value" → compounds; griefing scales
- "Trusted external contract" → trust boundaries shift; verify actual code