audit-system 2.0.0

package/obsidian-vault/novel-patterns/pattern-mutation-framework.md

@@ -0,0 +1,316 @@
+# Pattern Mutation Framework
+
+tags: #novel-patterns #mutation #creativity #framework
+
+---
+
+## Overview
+Novel vulnerabilities often emerge from combining or mutating known patterns. This framework provides systematic approaches to discover new attack vectors through pattern transformation.
+
+---
+
+## Mutation Strategy 1: Feature Composition
+
+### Concept
+Combine two existing features to create an emergent vulnerability.
+
+### Method
+```
+1. List all features: F1, F2, F3, ..., Fn
+2. For each pair (Fi, Fj):
+   - Can Fi's output become Fj's input unexpectedly?
+   - Does Fi change state that Fj depends on?
+   - Can Fi front-run or back-run Fj?
+3. Test promising combinations
+```
+
+### Example: Flash Loan + Governance
+```
+Flash Loan (Feature A):
+  → Provides large capital temporarily
+  → Must be repaid in same transaction
+
+Governance (Feature B):
+  → Requires token threshold to propose
+  → Voting power proportional to holdings
+
+Composition Attack:
+  1. Flash loan governance token
+  2. Submit malicious proposal
+  3. Vote with flash-loaned power
+  4. Repay flash loan
+  5. Proposal executes after timelock
+  
+Result: Governance manipulation without holding tokens
+```
+
+### Composition Matrix
+| Feature A | Feature B | Potential Attack |
+|-----------|-----------|------------------|
+| Flash Loan | Price Oracle | Price manipulation |
+| Flash Loan | Reward Distribution | Reward harvesting |
+| Reentrancy | Upgradeable | Self-destruct proxy |
+| Staking | Transfer | Double voting power |
+| Time Lock | Emergency Pause | Race condition |
+
+---
+
+## Mutation Strategy 2: Context Shifting
+
+### Concept
+Take a pattern that exists in one context and apply it to a different context.
+
+### Method
+```
+1. Identify known vulnerability pattern P
+2. Identify contexts where P is NOT expected: C1, C2, C3
+3. Ask: "Could P work in context Cn?"
+4. Test the shifted pattern
+```
+
+### Context Shift Examples
+
+#### Reentrancy in View Functions (Read-Only Reentrancy)
+```
+Original Context: State-changing functions
+Shifted Context: View functions
+Novel Attack: Manipulate state → call view → state still stale → profit
+```
+
+#### Integer Overflow in Governance
+```
+Original Context: ERC20 balances
+Shifted Context: Vote counting
+Novel Attack: Overflow vote counts to manipulate proposals
+```
+
+#### Access Control in Callbacks
+```
+Original Context: Admin functions
+Shifted Context: Token callbacks (ERC777, ERC721)
+Novel Attack: Unauthorized actions via callback hooks
+```
+
+---
+
+## Mutation Strategy 3: Parameter Manipulation
+
+### Concept
+Vary the parameters of a known attack to find new vectors.
+
+### Method
+```
+For each attack parameter:
+- What if it's zero?
+- What if it's maximum (type(uint256).max)?
+- What if it's boundary value (1, -1)?
+- What if it's manipulated during the attack?
+```
+
+### Parameter Exploration
+
+#### Attack Timing
+```
+Instead of: Attack at beginning
+Try: Attack in middle, Attack at end, Attack split across blocks
+```
+
+#### Attack Scale
+```
+Instead of: Attack with large amount
+Try: Attack with dust amount, Attack with exact threshold
+```
+
+#### Attack Sequence
+```
+Instead of: A → B → C
+Try: A → C → B, B → A → C, Parallel execution
+```
+
+---
+
+## Mutation Strategy 4: Trust Boundary Violation
+
+### Concept
+Exploit assumptions about which contracts/users are trusted.
+
+### Method
+```
+1. Identify all trust assumptions
+2. Ask "what if this trust is misplaced?"
+3. Test untrusted input at trust boundaries
+```
+
+### Trust Boundary Patterns
+
+#### Malicious Token
+```
+Assumption: ERC20 tokens behave normally
+Violation: Token with hooks, fees, or callbacks
+Result: Reentrancy, accounting errors
+```
+
+#### Malicious Oracle
+```
+Assumption: Oracle price is accurate
+Violation: Manipulable oracle, stale data
+Result: Liquidation manipulation, undercollateralized loans
+```
+
+#### Malicious User Contract
+```
+Assumption: Users are EOAs or benign contracts
+Violation: Attacker controls contract with hooks
+Result: Reentrancy, gas griefing
+```
+
+---
+
+## Mutation Strategy 5: State Space Exploration
+
+### Concept
+Explore combinations of state variables to find invalid states.
+
+### Method
+```
+1. Define all state variables: S1, S2, S3, ..., Sn
+2. Define valid ranges for each
+3. Explore edge cases:
+   - All minimum
+   - All maximum
+   - Mixed extremes
+   - Transition states
+```
+
+### State Mutation Examples
+
+#### Empty States
+```
+Scenario: First user interaction
+Test: Does protocol handle empty/zero states correctly?
+Attack: First depositor exploit, division by zero
+```
+
+#### Maximum States
+```
+Scenario: Maximum values reached
+Test: Does protocol handle overflow, gas limits?
+Attack: Block protocol with max deposits
+```
+
+#### Race Conditions
+```
+Scenario: Multiple users simultaneously
+Test: Is state update atomic?
+Attack: Double withdrawal, reward stealing
+```
+
+---
+
+## Mutation Strategy 6: Economic Game Theory
+
+### Concept
+Model the system as a game and find Nash equilibria that harm the protocol.
+
+### Method
+```
+1. Identify players and their strategies
+2. Calculate payoffs for each strategy combination
+3. Find dominant strategies for attackers
+4. Check if honest participation is rational
+```
+
+### Economic Attacks
+
+#### MEV Extraction
+```
+Attack: Sandwich user's trade
+Mutation: Sandwich liquidation, governance votes, claims
+```
+
+#### Governance Attacks
+```
+Attack: Buy tokens, vote, sell
+Mutation: Flash loan governance, vote delegation manipulation
+```
+
+#### Liquidity Attacks
+```
+Attack: Remove liquidity at critical moment
+Mutation: Just-in-time liquidity, liquidity sniping
+```
+
+---
+
+## Practical Application
+
+### Step-by-Step Mutation Process
+
+```
+Step 1: Catalog Known Patterns
+- List all known vulnerabilities for protocol type
+- Document standard mitigations
+
+Step 2: Generate Mutations
+- Apply each mutation strategy
+- Generate 3-5 variations per strategy
+
+Step 3: Feasibility Check
+- Which mutations are technically possible?
+- Which have economic incentive?
+- Which bypass existing mitigations?
+
+Step 4: Prioritize Testing
+- Rank by likelihood of success
+- Rank by potential impact
+- Test top 3-5 mutations
+
+Step 5: Document Results
+- Successful mutations → poc/
+- Failed mutations → failed-hypotheses/
+```
+
+### Mutation Worksheet
+
+```markdown
+## Pattern: [Base Pattern]
+
+### Context Shift
+- Original: [Context A]
+- Shifted: [Context B]
+- Feasibility: [High/Medium/Low]
+- Notes: [Why or why not]
+
+### Feature Composition
+- Feature A: [Feature]
+- Feature B: [Feature]
+- Combined Effect: [What happens]
+- Feasibility: [High/Medium/Low]
+
+### Parameter Manipulation
+- Parameter: [Which parameter]
+- Variation: [How varied]
+- Result: [Effect]
+
+### Trust Boundary
+- Assumption: [What is assumed]
+- Violation: [How to violate]
+- Exploit: [Attack vector]
+```
+
+---
+
+## Integration with Novel Discovery
+
+Use this framework within the 6-phase discovery process:
+- **Phase 3 (Economic):** Economic game theory mutations
+- **Phase 4 (State Machine):** State space exploration
+- **Phase 5 (Composition):** Feature composition
+- **Phase 2 (Break Assumptions):** Trust boundary violation
+
+---
+
+## Links
+- [[attack-patterns/state-inconsistency]] — Base pattern for mutations
+- [[invariant-catalog/defi-invariants]] — Test invariants against mutations
+- [[../skills/novel-discovery]] — Full discovery framework

package/obsidian-vault/reports/_template.md

@@ -0,0 +1,92 @@
+# Audit Report: [Protocol Name]
+
+tags: #report #audit
+
+---
+
+## Executive Summary
+**Protocol:** [Name]  
+**Date:** [Date]  
+**Auditor:** [Name]  
+**Scope:** [Files audited]  
+**Total Findings:** CRITICAL: X | HIGH: X | MEDIUM: X | LOW: X | INFO: X
+
+---
+
+## Findings Summary
+
+| ID | Severity | Title | Status |
+|---|---|---|---|
+| C-01 | CRITICAL | [Title] | Open |
+| H-01 | HIGH | [Title] | Open |
+| M-01 | MEDIUM | [Title] | Open |
+
+---
+
+## Detailed Findings
+
+### [C-01] CRITICAL — [Title]
+
+**Location:** `Contract.sol` :: `functionName()` :: line N
+
+**Description:**  
+[Clear explanation of the vulnerability]
+
+**Root Cause:**  
+[Technical reason why this exists]
+
+**Impact:**  
+[What an attacker can achieve and economic damage]
+
+**Attack Vector:**
+```
+1. Attacker calls X with Y
+2. Contract state becomes inconsistent
+3. Attacker calls Z to extract funds
+4. Loss: [amount]
+```
+
+**PoC (Foundry):**
+```solidity
+function test_C01_exploit() public {
+    // setup
+    
+    // attack
+    
+    // assert
+    assertGt(attacker.balance, 0);
+}
+```
+
+**Recommendation:**
+```solidity
+// Fixed version
+function fixedFunction() external nonReentrant {
+    // CEI pattern
+    uint256 amount = balances[msg.sender];
+    balances[msg.sender] = 0;  // Effect first
+    payable(msg.sender).call{value: amount}("");  // Then interact
+}
+```
+
+---
+
+## Appendix
+
+### Methodology
+1. Manual code review
+2. Static analysis (Slither)
+3. Fuzz testing (Foundry)
+4. Invariant testing
+5. PoC development
+
+### Tools Used
+- Foundry
+- Slither  
+- Echidna
+
+---
+
+## Links
+- [[vulnerabilities/]]
+- [[poc/]]

package/obsidian-vault/test-strategies/fuzzing.md

@@ -0,0 +1,75 @@
+# Fuzzing Strategy
+
+tags: #strategy #testing #fuzzing
+
+---
+
+## Overview
+Fuzzing automatically tests functions with random inputs to find edge cases and unexpected behavior. In Foundry, it runs hundreds/thousands of times per test.
+
+---
+
+## When to Fuzz
+
+Use fuzz tests when:
+- Function accepts numerical inputs
+- Function has complex branching logic
+- You want to find edge cases you can't imagine
+- Testing invariants across many states
+
+---
+
+## Foundry Fuzz Config (foundry.toml)
+
+```toml
+[fuzz]
+runs = 10000        # More runs = better coverage
+max_test_rejects = 65536
+seed = 0x1234
+
+[invariant]
+runs = 500
+depth = 50          # Calls per run
+```
+
+---
+
+## Fuzz Target Priority
+
+### Highest Value Targets
+1. `withdraw()` / `claim()` — any function moving funds
+2. `swap()` — exchange functions
+3. `liquidate()` — liquidation logic
+4. `borrow()` — lending logic
+5. `mint()` / `burn()` — supply modification
+
+---
+
+## Bounding Inputs
+
+```solidity
+// Always bound to prevent wasted runs
+amount = bound(amount, 1, type(uint128).max);
+user = address(uint160(bound(uint256(user), 1, type(uint160).max)));
+```
+
+---
+
+## Echidna Integration
+
+```yaml
+# echidna.yaml
+testLimit: 50000
+seqLen: 100
+shrinkLimit: 5000
+filterFunctions: ["setUp"]
+
+# Run:
+# echidna . --contract FuzzTarget --config echidna.yaml
+```
+
+---
+
+## Links
+- [[skills/test-generator]]
+- [[vulnerabilities/reentrancy]]

package/obsidian-vault/vulnerabilities/access-control.md

@@ -0,0 +1,122 @@
+# Access Control
+
+tags: #vulnerability #high #critical #access-control
+
+---
+
+## Summary
+Access control vulnerabilities occur when sensitive functions lack proper authorization checks, allowing unauthorized actors to execute privileged operations.
+
+---
+
+## Pattern Recognition
+
+### Code Signals
+- `public` functions that should be `internal` or `onlyOwner`
+- Missing modifiers on admin functions
+- Modifier logic that can be bypassed
+- `tx.origin` used instead of `msg.sender`
+- Role checks missing or incorrectly implemented
+
+### Detection Query for Claude
+```
+Which functions modify critical state or move funds?
+Do all of them have proper access modifiers?
+Can the modifier be bypassed (e.g., through delegatecall)?
+Is tx.origin used anywhere?
+```
+
+---
+
+## Variants
+
+### Missing Modifier
+Function performs sensitive action with no access check at all.
+
+### Broken Modifier Logic
+```solidity
+modifier onlyOwner() {
+    require(msg.sender == owner || owner == address(0)); // WRONG: anyone when owner not set
+    _;
+}
+```
+
+### Uninitialized Owner
+Owner is never set in constructor, defaults to `address(0)`, anyone can become owner.
+
+### tx.origin Bypass
+```solidity
+require(tx.origin == owner); // Bypassed via phishing
+```
+
+### Delegatecall Context Confusion
+Proxy calls implementation — `msg.sender` changes context, breaking access checks.
+
+---
+
+## Attack Strategy
+
+```
+1. Identify functions with weak or missing access control
+2. Call function directly from attacker EOA
+3. OR deploy attacker contract to bypass tx.origin check
+4. Execute privileged action (drain funds, set new owner, pause protocol)
+```
+
+---
+
+## Detection Signals
+- `function X() public` with no modifier on state-changing operation
+- `initialize()` or `setup()` functions with no protection
+- `owner` never assigned in constructor
+- Access checks using `tx.origin`
+
+---
+
+## PoC Template
+
+```solidity
+function test_accessControlBypass() public {
+    address attacker = makeAddr("attacker");
+
+    vm.startPrank(attacker);
+    target.sensitiveAdminFunction(); // Should revert but doesn't
+    vm.stopPrank();
+
+    // Assert unauthorized action succeeded
+    assertEq(target.owner(), attacker);
+}
+```
+
+---
+
+## Fix
+
+```solidity
+// Use OpenZeppelin Ownable or AccessControl
+import "@openzeppelin/contracts/access/Ownable.sol";
+
+contract Fixed is Ownable {
+    function sensitiveFunction() external onlyOwner {
+        // safe
+    }
+}
+
+// For roles:
+import "@openzeppelin/contracts/access/AccessControl.sol";
+bytes32 public constant ADMIN_ROLE = keccak256("ADMIN_ROLE");
+// use hasRole(ADMIN_ROLE, msg.sender)
+```
+
+---
+
+## Real World Examples
+- Parity Multisig (2017) — $30M
+- Compound (2021) — $80M governance
+- Nomad Bridge (2022) — $190M
+
+---
+
+## Links
+- [[attack-patterns/privilege-escalation]]
+- [[vulnerabilities/signature-replay]]

package/obsidian-vault/vulnerabilities/flash-loan-attack.md

@@ -0,0 +1,66 @@
+# Flash Loan Attack
+
+tags: #vulnerability #critical #flashloan #defi
+
+---
+
+## Summary
+Flash loans allow borrowing unlimited capital within a single transaction with zero collateral. Attackers use this to amplify economic attacks that would otherwise require enormous capital.
+
+---
+
+## Pattern Recognition
+
+### Code Signals
+- Single-block price dependency
+- Collateral valued at spot DEX price
+- Governance that acts in same block as proposal
+- Reward calculations based on snapshot that can be gamed
+
+---
+
+## Attack Strategy
+
+```
+1. Identify what asset/position can be inflated with capital
+2. Calculate if profit > flash loan fee (0.09% Uniswap, 0.05% Aave)
+3. Flash borrow enough to move the market
+4. Execute attack
+5. Repay + keep profit
+```
+
+---
+
+## PoC Template
+
+```solidity
+contract FlashLoanAttacker {
+    IUniswapV3Pool pool;
+    IVulnerable target;
+
+    function attack() external {
+        pool.flash(address(this), 1_000_000e18, 0, "");
+    }
+
+    function uniswapV3FlashCallback(uint256 fee0, uint256, bytes calldata) external {
+        // Execute attack with flash loaned funds
+        // ...
+
+        // Repay
+        IERC20(token).transfer(address(pool), 1_000_000e18 + fee0);
+    }
+}
+```
+
+---
+
+## Fix
+- Use TWAP oracle (30+ minute window)
+- Add time delay between actions
+- Use Chainlink price feeds
+
+---
+
+## Links
+- [[vulnerabilities/oracle-manipulation]]
+- [[attack-patterns/price-manipulation]]