behavioral-state-analysis

name	behavioral-state-analysis
description	Token-efficient smart contract security auditing via Behavioral State Analysis (BSA). Scopes analysis to contract type, runs only relevant threat engines, and uses tiered output depth. Use for auditing smart contracts, security reviews, or DeFi threat modeling.

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