solidity-argus 0.1.0

package/skills/vulnerability-patterns/oracle-manipulation/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: oracle-manipulation
+description: Oracle manipulation techniques, case studies, and secure pricing integration controls for DeFi.
+---
+
+<!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Oracle Manipulation Exploits
+
+## Overview
+
+Oracle manipulation attacks exploit price feeds to extract value. Attackers manipulate the price source, then use the manipulated price to profit (liquidations, swaps, borrows).
+
+**Total Losses:** $500M+ across DeFi
+
+---
+
+## Attack Patterns
+
+### 1. Spot Price Manipulation
+
+Using AMM spot prices directly instead of TWAPs.
+
+```solidity
+// VULNERABLE: Spot price from Uniswap
+function getPrice() external view returns (uint256) {
+    (uint112 reserve0, uint112 reserve1,) = pair.getReserves();
+    return reserve1 * 1e18 / reserve0;  // Manipulatable in same tx!
+}
+```
+
+**Fix:** Use TWAP (Time-Weighted Average Price) or Chainlink.
+
+### 2. Flash Loan + Price Manipulation
+
+1. Flash loan large amount
+2. Swap to manipulate AMM price
+3. Interact with victim protocol using manipulated price
+4. Swap back, repay flash loan
+5. Profit
+
+### 3. Stale Price Data
+
+```solidity
+// VULNERABLE: No freshness check
+function getPrice(address token) external view returns (uint256) {
+    (, int256 price,,,) = priceFeed.latestRoundData();
+    return uint256(price);  // Could be hours old!
+}
+
+// SECURE: Freshness validation
+function getPrice(address token) external view returns (uint256) {
+    (
+        uint80 roundId,
+        int256 price,
+        ,
+        uint256 updatedAt,
+        uint80 answeredInRound
+    ) = priceFeed.latestRoundData();
+    
+    require(price > 0, "Invalid price");
+    require(updatedAt > block.timestamp - MAX_DELAY, "Stale price");
+    require(answeredInRound >= roundId, "Stale round");
+    
+    return uint256(price);
+}
+```
+
+### 4. TWAP Manipulation (Low Liquidity)
+
+Even TWAPs can be manipulated if:
+- Liquidity is low
+- TWAP window is short
+- Attacker controls multiple blocks (MEV)
+
+---
+
+## Real Exploits
+
+### Harvest Finance (Oct 2020) — $34M
+
+**What happened:**
+- Attacker used flash loans to manipulate Curve pool prices
+- Harvest used Curve spot price for USDC/USDT
+- Deposited at manipulated (low) price, withdrew at normal price
+
+**Root cause:** Spot price oracle on low-liquidity pool
+
+**Lesson:** Never use spot prices. Use TWAPs with sufficient window.
+
+### Mango Markets (Oct 2022) — $116M
+
+**What happened:**
+- Attacker manipulated MNGO perpetual price on Mango
+- Used inflated collateral value to borrow all assets
+- Price manipulation was within protocol rules (no external oracle)
+
+**Root cause:** Self-referential oracle (own perp price as collateral value)
+
+**Lesson:** Don't use your own market prices as oracle for that same market.
+
+### Inverse Finance (Apr 2022) — $15.6M
+
+**What happened:**
+- Attacker manipulated INV/ETH SushiSwap price
+- Used manipulated price to borrow DOLA
+- TWAP window was only 25 minutes
+
+**Root cause:** Short TWAP window on low-liquidity pair
+
+**Lesson:** TWAP window must be long enough to make manipulation unprofitable.
+
+### bZx (Multiple 2020) — $8M+
+
+**What happened:**
+- Series of attacks using flash loans to manipulate prices
+- Borrowed, manipulated, liquidated in single transaction
+
+**Root cause:** Spot price oracles vulnerable to flash loan manipulation
+
+---
+
+## Detection Checklist
+
+- [ ] Does the contract use spot prices from AMMs?
+- [ ] Is Chainlink used? Are staleness checks implemented?
+- [ ] If TWAP is used, what's the window? (< 30 min = risky)
+- [ ] Is the oracle source low liquidity?
+- [ ] Can price be manipulated within a single transaction?
+- [ ] Are there freshness checks on price data?
+- [ ] Is `answeredInRound >= roundId` checked?
+- [ ] Does the protocol validate price sanity (bounds, deviation)?
+
+## Secure Patterns
+
+### Chainlink with Full Validation
+
+```solidity
+function getPrice(address token) public view returns (uint256) {
+    AggregatorV3Interface feed = priceFeeds[token];
+    require(address(feed) != address(0), "No feed");
+    
+    (
+        uint80 roundId,
+        int256 price,
+        ,
+        uint256 updatedAt,
+        uint80 answeredInRound
+    ) = feed.latestRoundData();
+    
+    // Validation
+    require(price > 0, "Invalid price");
+    require(updatedAt > 0, "Round not complete");
+    require(answeredInRound >= roundId, "Stale round");
+    require(block.timestamp - updatedAt < HEARTBEAT, "Stale price");
+    
+    return uint256(price);
+}
+```
+
+### Circuit Breakers
+
+```solidity
+uint256 public lastPrice;
+uint256 public constant MAX_DEVIATION = 10; // 10%
+
+function getPriceWithCircuitBreaker() external returns (uint256) {
+    uint256 newPrice = oracle.getPrice();
+    
+    if (lastPrice > 0) {
+        uint256 deviation = newPrice > lastPrice 
+            ? (newPrice - lastPrice) * 100 / lastPrice
+            : (lastPrice - newPrice) * 100 / lastPrice;
+        require(deviation <= MAX_DEVIATION, "Price deviation too high");
+    }
+    
+    lastPrice = newPrice;
+    return newPrice;
+}
+```
+
+---
+
+## References
+
+- [samczsun: Taking undercollateralized loans](https://samczsun.com/taking-undercollateralized-loans-for-fun-and-for-profit/)
+- [Chainlink Best Practices](https://docs.chain.link/data-feeds/selecting-data-feeds)
+- [Euler Oracle Manipulation (Omniscia)](https://omniscia.io/reports/euler-finance-oracle-manipulation/)
+
+## Supplemental Heuristics (kadenzipfel)
+
+## Preconditions
+- Transaction inputs are visible in the public mempool before block inclusion
+- The outcome of the function depends on transaction ordering
+- An attacker can profit by observing and front-running (or sandwiching) the victim's transaction
+
+## Vulnerable Pattern
+```solidity
+// DEX swap without slippage protection
+function swap(address tokenIn, address tokenOut, uint256 amountIn) external {
+    // No minimum output amount — attacker sandwiches:
+    // 1. Front-run: buy tokenOut (price goes up)
+    // 2. Victim's swap executes at worse price
+    // 3. Back-run: sell tokenOut (profit from price impact)
+    uint256 amountOut = getAmountOut(amountIn);
+    IERC20(tokenIn).transferFrom(msg.sender, address(this), amountIn);
+    IERC20(tokenOut).transfer(msg.sender, amountOut);
+}
+
+// On-chain secret submission
+function submitAnswer(bytes32 answer) external {
+    // Answer visible in mempool — anyone can copy it
+    require(keccak256(abi.encodePacked(answer)) == targetHash);
+    _reward(msg.sender);
+}
+
+// ERC20 approval race condition
+// User approves 100, wants to change to 50
+// Attacker sees approve(50) in mempool, spends 100, then spends 50 = 150 total
+```
+
+## Detection Heuristics
+1. Search for DEX/swap functions: check for slippage protection (`minAmountOut` parameter) and deadline parameters — flag if absent
+2. Search for on-chain submissions of secrets, answers, or bids — these are observable in the mempool
+3. Search for ERC20 `approve` patterns: check if the contract sets allowance to zero before setting a new value
+4. Look for auction/bidding logic where observing others' bids provides an advantage
+5. Identify any function where the order of execution matters and inputs are publicly visible before inclusion
+
+## False Positives
+- Transaction is submitted via a private mempool (Flashbots Protect, MEV Blocker)
+- Commit-reveal scheme is used: commitment hash submitted first, reveal in a later block
+- Slippage protection with `minAmountOut` and `deadline` parameters are present
+- The function's outcome is order-independent (e.g., simple deposit into a vault at a fixed rate)
+
+## Remediation
+- For DEX operations: require `minAmountOut` and `deadline` parameters for slippage protection
+- For secret submissions: use commit-reveal schemes (hash commitment first, reveal later)
+- For ERC20 approvals: use `increaseAllowance`/`decreaseAllowance` or set to zero first
+- Consider Flashbots or private transaction relays for MEV-sensitive operations
+```solidity
+function swap(
+    address tokenIn, address tokenOut, uint256 amountIn,
+    uint256 minAmountOut, // Slippage protection
+    uint256 deadline       // Time protection
+) external {
+    require(block.timestamp <= deadline, "expired");
+    uint256 amountOut = getAmountOut(amountIn);
+    require(amountOut >= minAmountOut, "slippage");
+    // ... execute swap
+}
+```

package/skills/vulnerability-patterns/outdated-compiler-version/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: outdated-compiler-version
+description: - Contract is compiled with a Solidity version significantly behind the latest stable release
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Outdated Compiler Version
+
+## Preconditions
+- Contract is compiled with a Solidity version significantly behind the latest stable release
+- The compiler version used has known bugs or is missing important security features
+
+## Vulnerable Pattern
+```solidity
+// Old version missing built-in overflow checks
+pragma solidity 0.7.6;
+
+contract Token {
+    mapping(address => uint256) public balances;
+
+    function transfer(address to, uint256 amount) external {
+        // No overflow protection — 0.7.x lacks built-in checks
+        // Requires manual SafeMath usage
+        balances[msg.sender] -= amount;
+        balances[to] += amount;
+    }
+}
+
+// Slightly newer but still has known bugs
+pragma solidity 0.8.0;
+// 0.8.0 had ABI encoding bugs fixed in later patches
+```
+
+## Detection Heuristics
+1. Check the `pragma solidity` version in all contract files
+2. Compare against the latest stable Solidity release — flag if significantly outdated
+3. Cross-reference the exact version against the Solidity known bugs list
+4. Check if the contract misses key safety features from newer versions:
+   - <0.8.0: no built-in overflow/underflow checks
+   - <0.8.4: no custom errors (gas efficiency)
+   - <0.8.20: no PUSH0 opcode support
+5. Flag if the version has known critical bugs (check https://solidity.readthedocs.io/en/latest/bugs.html)
+
+## False Positives
+- The version is intentionally chosen for compatibility with a specific deployment target or toolchain
+- The version is recent (within 1-2 minor versions of latest) and has no known critical bugs
+- The project has documented reasons for the specific version choice
+
+## Remediation
+- Upgrade to the latest stable Solidity version unless there's a specific compatibility constraint
+- Cross-reference the current version against the known bugs list before and after upgrading
+- When upgrading across major boundaries (e.g., 0.7 to 0.8), review all arithmetic for compatibility with built-in overflow checks
+```solidity
+// Use latest stable version
+pragma solidity 0.8.24;
+
+contract Token {
+    mapping(address => uint256) public balances;
+
+    function transfer(address to, uint256 amount) external {
+        balances[msg.sender] -= amount; // Built-in overflow check
+        balances[to] += amount;
+    }
+}
+```

package/skills/vulnerability-patterns/overflow-underflow/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: overflow-underflow
+description: - Solidity <0.8.0 without SafeMath, OR
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Integer Overflow and Underflow
+
+## Preconditions
+- Solidity <0.8.0 without SafeMath, OR
+- Arithmetic inside `unchecked { }` blocks, OR
+- Arithmetic inside `assembly { }` / Yul blocks, OR
+- Type downcasting (e.g., `uint8(uint256Var)`), OR
+- Shift operators (`<<`, `>>`) on values near type boundaries
+
+## Vulnerable Pattern
+```solidity
+// Pre-0.8.0: wraps silently
+uint256 balance = 0;
+balance -= 1; // Underflows to 2^256 - 1
+
+// Post-0.8.0 bypass via unchecked block
+unchecked {
+    uint256 x = type(uint256).max;
+    x += 1; // Wraps to 0, no revert
+}
+
+// Type downcast truncation (all versions)
+uint256 big = 256;
+uint8 small = uint8(big); // Silently truncates to 0
+
+// Assembly arithmetic (all versions)
+assembly {
+    let x := sub(0, 1) // Underflows to max uint256
+}
+```
+
+## Detection Heuristics
+1. Check the Solidity version: if <0.8.0, flag ALL arithmetic operations not wrapped in SafeMath
+2. If >=0.8.0, search for `unchecked` blocks and audit every arithmetic operation inside them
+3. Search for `assembly` blocks and audit all `add`, `sub`, `mul`, `div`, `shl`, `shr` operations within
+4. Search for type downcasts: patterns like `uint8(`, `uint16(`, `int8(`, etc. — verify the source value is bounds-checked before casting
+5. Search for shift operations (`<<`, `>>`) and verify the operand cannot overflow the target type
+6. Check if overflow-induced reverts on critical paths could cause DoS
+
+## False Positives
+- Solidity >=0.8.0 arithmetic outside of `unchecked` and `assembly` blocks (automatically checked)
+- `unchecked` blocks used only for loop counter increments (`i++`) where overflow is impossible due to bounded loop
+- Downcasts where the value is validated to fit the target type before casting (e.g., `require(x <= type(uint8).max)`)
+- Assembly arithmetic on values with proven bounds
+
+## Remediation
+- For Solidity <0.8.0: use OpenZeppelin's `SafeMath` for all arithmetic
+- For >=0.8.0: minimize `unchecked` blocks to only provably safe operations (e.g., bounded loop counters)
+- Use OpenZeppelin's `SafeCast` library for all type downcasts
+- Validate bounds before assembly arithmetic
+```solidity
+// Safe downcast
+import {SafeCast} from "@openzeppelin/contracts/utils/math/SafeCast.sol";
+uint8 small = SafeCast.toUint8(big); // Reverts if big > 255
+```

package/skills/vulnerability-patterns/reentrancy/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: reentrancy
+description: Reentrancy attack patterns, real incidents, and defensive coding checks for Solidity protocols.
+---
+
+<!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Reentrancy Exploits
+
+## Overview
+
+Reentrancy occurs when an external call allows the callee to re-enter the calling function before state updates complete.
+
+**Types:**
+1. **Classic reentrancy** - Same function called again
+2. **Cross-function** - Different function in same contract
+3. **Cross-contract** - Function in different contract sharing state
+4. **Read-only** - View function returns stale state during reentrancy
+
+---
+
+## The DAO Hack (2016)
+
+**Loss:** ~$60M (3.6M ETH)
+**Root Cause:** Classic reentrancy
+
+### Vulnerable Code
+```solidity
+function withdraw(uint _amount) public {
+    require(balances[msg.sender] >= _amount);
+    
+    // External call BEFORE state update
+    (bool success,) = msg.sender.call{value: _amount}("");
+    require(success);
+    
+    // State update AFTER - never reached during reentrancy
+    balances[msg.sender] -= _amount;
+}
+```
+
+### Attack
+```solidity
+contract Attacker {
+    DAO dao;
+    
+    function attack() external payable {
+        dao.deposit{value: 1 ether}();
+        dao.withdraw(1 ether);
+    }
+    
+    receive() external payable {
+        if (address(dao).balance >= 1 ether) {
+            dao.withdraw(1 ether);  // Re-enter before balance update
+        }
+    }
+}
+```
+
+### Fix: CEI Pattern
+```solidity
+function withdraw(uint _amount) public {
+    require(balances[msg.sender] >= _amount);
+    
+    balances[msg.sender] -= _amount;  // State update FIRST
+    
+    (bool success,) = msg.sender.call{value: _amount}("");
+    require(success);
+}
+```
+
+---
+
+## Cream Finance (2021)
+
+**Loss:** ~$130M
+**Root Cause:** Cross-contract reentrancy via AMP token (ERC777)
+
+### Vulnerable Pattern
+```solidity
+// Cream's borrow function
+function borrow(uint amount) external {
+    // Check collateral
+    require(getAccountLiquidity(msg.sender) >= amount);
+    
+    // Transfer tokens (ERC777 calls receiver hook)
+    token.transfer(msg.sender, amount);  // REENTRANCY HERE
+    
+    // Update borrow balance
+    borrowBalances[msg.sender] += amount;
+}
+```
+
+### Attack Flow
+1. Attacker deposits collateral
+2. Calls `borrow()` for AMP token
+3. AMP's ERC777 hook triggers during transfer
+4. In hook, attacker deposits more collateral + borrows again
+5. Second borrow succeeds because first borrow's balance not updated yet
+6. Repeat until drained
+
+### Fix
+```solidity
+function borrow(uint amount) external nonReentrant {
+    require(getAccountLiquidity(msg.sender) >= amount);
+    borrowBalances[msg.sender] += amount;  // Update FIRST
+    token.transfer(msg.sender, amount);
+}
+```
+
+---
+
+## Fei Protocol / Ondo Finance (2022)
+
+**Loss:** ~$80M
+**Root Cause:** Read-only reentrancy
+
+### Concept
+```solidity
+// Protocol A's view function
+function getExchangeRate() public view returns (uint) {
+    return totalAssets / totalShares;  // Reads state
+}
+
+// Protocol B uses this
+function deposit() external {
+    uint rate = protocolA.getExchangeRate();  // Gets STALE rate
+    uint shares = amount * rate;
+    // ...
+}
+```
+
+### Attack Flow
+1. Attacker calls `withdraw()` on Protocol A
+2. During callback (before state update), call Protocol B
+3. Protocol B queries Protocol A's exchange rate
+4. Rate is stale (doesn't reflect pending withdrawal)
+5. Attacker gets more shares than deserved
+
+### Fix
+- Check invariants in view functions
+- Use mutex that view functions also respect
+- Snapshot state at start of transaction
+
+---
+
+## Rari Fuse (2022)
+
+**Loss:** ~$80M
+**Root Cause:** Cross-function reentrancy
+
+### Pattern
+```solidity
+function exitMarket(address cToken) external {
+    // Check no borrows
+    require(borrowBalances[msg.sender][cToken] == 0);
+    
+    // Update membership
+    markets[msg.sender][cToken] = false;
+}
+
+function borrow(address cToken, uint amount) external {
+    require(markets[msg.sender][cToken] == true);  // Must be in market
+    
+    // Transfer - REENTRANCY POINT
+    cToken.transfer(msg.sender, amount);
+    
+    borrowBalances[msg.sender][cToken] += amount;
+}
+```
+
+### Attack
+1. Enter market, deposit collateral
+2. Call `borrow()` 
+3. In callback, call `exitMarket()` - passes because borrow balance not yet updated
+4. Now out of market but have borrowed funds
+5. Collateral released, borrow never repaid
+
+---
+
+## Detection Checklist
+
+- [ ] Map all external calls in each function
+- [ ] Check state updates happen BEFORE external calls
+- [ ] Verify `nonReentrant` modifier on vulnerable functions
+- [ ] Check for ERC777/ERC721 callback hooks
+- [ ] Look for cross-function shared state
+- [ ] Check view functions for read-only reentrancy
+- [ ] Verify flash loan callbacks don't enable reentrancy
+
+---
+
+## Patterns by Token Type
+
+| Token Type | Reentrancy Vector |
+|------------|-------------------|
+| ETH | `call{value:}()` |
+| ERC777 | `tokensToSend`, `tokensReceived` hooks |
+| ERC721 | `onERC721Received` |
+| ERC1155 | `onERC1155Received`, batch operations |
+| Flash loans | Callback functions |
+
+---
+
+## Resources
+
+- **DeFiHackLabs:** `submodules/DeFiHackLabs/test/Reentrancy/`
+- **learn-evm-attacks:** `submodules/learn-evm-attacks/test/Reentrancy/`
+- **SWC-107:** <https://swcregistry.io/docs/SWC-107>
+
+## Detection Heuristics (kadenzipfel)
+
+## Preconditions
+- Contract makes an external call (ETH transfer, token transfer, `.call()`, `.send()`, `.transfer()`, callback hook)
+- State is modified after the external call, not before
+- No reentrancy guard (`nonReentrant` modifier) on the function
+- For cross-function: two or more functions share state, and at least one makes an external call before updating that shared state
+- For cross-contract: Contract B reads Contract A's state, and A makes an external call before updating it
+- For read-only: Contract A has a reentrancy guard but updates state after an external call; Contract B reads A's state without sharing the same lock
+
+## Vulnerable Pattern
+```solidity
+// Single-function reentrancy
+function withdraw() external {
+    uint256 bal = balances[msg.sender];
+    // External call BEFORE state update
+    (bool success,) = msg.sender.call{value: bal}("");
+    require(success);
+    // State update AFTER external call — attacker reenters withdraw()
+    // and balances[msg.sender] is still the original value
+    balances[msg.sender] = 0;
+}
+
+// Hidden external calls that trigger callbacks:
+// ERC721._safeMint() -> onERC721Received()
+// ERC1155.safeTransferFrom() -> onERC1155Received()
+// ERC777 token transfers -> tokensReceived() hook
+```
+
+## Detection Heuristics
+1. Identify all external calls: `.call()`, `.send()`, `.transfer()`, token transfers, `_safeMint()`, `_safeTransfer()`, ERC777/ERC1155 safe transfers
+2. For each external call, check if any state variable is written AFTER the call in the same function
+3. If state is written after an external call, check if a `nonReentrant` guard is present on the function — flag if absent
+4. Check for cross-function reentrancy: does the function share state with other functions that could be called during the reentrant window?
+5. Check for cross-contract reentrancy: does any other contract read this contract's state that is stale during the external call?
+6. Check for hidden callbacks: `_safeMint`, `_safeTransfer`, ERC777 hooks, ERC1155 hooks — these are external calls even though they don't look like `.call()`
+
+## False Positives
+- State is updated BEFORE the external call (checks-effects-interactions pattern correctly followed)
+- `nonReentrant` modifier is applied to the function
+- The external call target is a trusted, immutable contract (e.g., WETH) with no callback mechanism
+- The function is `view`/`pure` and cannot modify state
+- The only state read after reentry is already finalized (e.g., immutable variables)
+
+## Remediation
+- Apply the checks-effects-interactions pattern: perform all state changes before any external call
+- Add OpenZeppelin's `ReentrancyGuard` with `nonReentrant` modifier to all functions that make external calls
+- For cross-contract reentrancy, use a shared reentrancy lock across contracts or ensure state is finalized before external calls
+```solidity
+function withdraw() external nonReentrant {
+    uint256 bal = balances[msg.sender];
+    balances[msg.sender] = 0;  // State update BEFORE external call
+    (bool success,) = msg.sender.call{value: bal}("");
+    require(success);
+}
+```