solidity-argus 0.1.0

package/skills/methodology/report-template/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: report-template
+description: Reusable smart contract audit report structure with severity IDs, finding sections, and appendices.
+---
+<!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
+
+# Audit Report Template
+
+## Header
+
+```markdown
+# Security Audit Report
+
+**Protocol:** [Protocol Name]
+**Version:** [Commit Hash / Version]
+**Auditor:** [Your Name / Firm]
+**Date:** [YYYY-MM-DD]
+**Review Period:** [Start Date] - [End Date]
+
+## Scope
+
+| Contract | SLOC | Purpose |
+|----------|------|---------|
+| Vault.sol | 245 | Main vault logic |
+| Oracle.sol | 89 | Price feed wrapper |
+
+**Out of Scope:**
+- Test files
+- Deployment scripts
+- External dependencies (OpenZeppelin)
+```
+
+---
+
+## Executive Summary
+
+```markdown
+## Executive Summary
+
+[Protocol Name] is a [brief description]. This audit reviewed [X] contracts
+totaling [Y] lines of code.
+
+### Findings Summary
+
+| Severity | Count |
+|----------|-------|
+| Critical | 0 |
+| High | 2 |
+| Medium | 3 |
+| Low | 5 |
+| Informational | 4 |
+
+### Key Observations
+
+- [Positive observation about code quality]
+- [Main concern or risk area]
+- [Recommendation summary]
+```
+
+---
+
+## Finding Format
+
+```markdown
+## [H-01] Title Describing the Vulnerability
+
+### Severity
+**High**
+
+### Location
+`src/Vault.sol:142-156`
+
+### Description
+[Clear explanation of the vulnerability, what's wrong, and why it matters]
+
+The `withdraw()` function sends ETH to the user before updating their balance,
+creating a reentrancy vulnerability:
+
+```solidity
+function withdraw(uint256 amount) external {
+    require(balances[msg.sender] >= amount, "Insufficient");
+    
+    (bool success,) = msg.sender.call{value: amount}("");  // External call
+    require(success, "Transfer failed");
+    
+    balances[msg.sender] -= amount;  // State update AFTER call
+}
+```
+
+### Impact
+An attacker can drain all ETH from the contract by recursively calling
+`withdraw()` before the balance is updated.
+
+**Funds at Risk:** All ETH in contract (~$X at time of audit)
+
+### Proof of Concept
+
+```solidity
+contract Attacker {
+    Vault vault;
+    
+    function attack() external payable {
+        vault.deposit{value: 1 ether}();
+        vault.withdraw(1 ether);
+    }
+    
+    receive() external payable {
+        if (address(vault).balance >= 1 ether) {
+            vault.withdraw(1 ether);
+        }
+    }
+}
+```
+
+### Recommendation
+
+Apply the Checks-Effects-Interactions (CEI) pattern:
+
+```solidity
+function withdraw(uint256 amount) external {
+    require(balances[msg.sender] >= amount, "Insufficient");
+    
+    balances[msg.sender] -= amount;  // State update BEFORE call
+    
+    (bool success,) = msg.sender.call{value: amount}("");
+    require(success, "Transfer failed");
+}
+```
+
+Alternatively, use OpenZeppelin's `ReentrancyGuard`.
+
+### Developer Response
+[Leave space for protocol team to respond]
+```
+
+---
+
+## Finding ID Convention
+
+- `[C-XX]` - Critical
+- `[H-XX]` - High  
+- `[M-XX]` - Medium
+- `[L-XX]` - Low
+- `[I-XX]` - Informational
+- `[G-XX]` - Gas Optimization
+
+---
+
+## Appendix Sections
+
+```markdown
+## Appendix A: Methodology
+
+This audit followed a structured approach:
+1. **Reconnaissance:** Architecture mapping, entry point identification
+2. **Static Analysis:** Slither, compiler warnings
+3. **Manual Review:** Line-by-line review against checklist
+4. **Testing:** Foundry tests for findings
+
+## Appendix B: Tools Used
+
+- Slither v0.10.0
+- Foundry (forge 0.2.0)
+- VS Code with Solidity extensions
+
+## Appendix C: Scope Verification
+
+All in-scope contracts were reviewed. The following were explicitly excluded:
+- [List excluded items]
+
+## Appendix D: Disclaimer
+
+This audit does not guarantee the absence of vulnerabilities. Smart contract
+security is a continuous process, and we recommend ongoing security practices
+including bug bounties, monitoring, and incident response planning.
+```
+
+---
+
+## Quick Checklist for Report Quality
+
+- [ ] All findings have clear titles
+- [ ] Severity is justified
+- [ ] Location includes file:line
+- [ ] Description is understandable by non-experts
+- [ ] Impact quantifies risk where possible
+- [ ] PoC is provided for High/Critical
+- [ ] Recommendation is actionable
+- [ ] Executive summary is concise
+- [ ] Scope is clearly defined

package/skills/methodology/severity-classification/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: severity-classification
+description: Impact-versus-likelihood rubric to classify Solidity findings from informational through critical severity.
+---
+<!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
+
+# Severity Classification Guide
+
+## Overview
+
+Severity is determined by **Impact × Likelihood**.
+
+```
+                    LIKELIHOOD
+                 Low    Medium    High
+          ┌────────┬─────────┬─────────┐
+     High │ Medium │  High   │Critical │
+IMPACT Med│  Low   │ Medium  │  High   │
+      Low │  Info  │   Low   │ Medium  │
+          └────────┴─────────┴─────────┘
+```
+
+---
+
+## Critical
+
+**Definition:** Direct, immediate loss of significant funds without requiring user action.
+
+**Criteria:**
+- Attacker can drain protocol funds
+- No user interaction required
+- Exploit is profitable and repeatable
+- Funds at risk > $100k (or significant % of TVL)
+
+**Examples:**
+- Unprotected withdrawal allowing anyone to drain
+- Price oracle manipulation enabling undercollateralized borrows
+- Reentrancy allowing multiple withdrawals
+
+**Required for Report:**
+- Working Foundry PoC
+- Exact funds at risk calculation
+- Step-by-step attack path
+
+---
+
+## High
+
+**Definition:** Loss of funds requiring specific conditions or user action, OR protocol insolvency risk.
+
+**Criteria:**
+- Attacker can steal user funds (with user action)
+- Protocol can become insolvent
+- Permanent freezing of funds
+- Governance takeover
+
+**Examples:**
+- Frontrunning user transactions for profit
+- Flash loan attack requiring specific market conditions
+- Permanent DOS of critical functions
+- Missing access control on privileged functions
+
+**Required for Report:**
+- PoC or detailed attack scenario
+- Conditions required for exploit
+- Estimated impact
+
+---
+
+## Medium
+
+**Definition:** Conditional loss of funds, protocol disruption, or violation of core invariants.
+
+**Criteria:**
+- Loss of funds under unlikely conditions
+- Temporary DOS of non-critical functions
+- Griefing attacks (cost attacker money too)
+- Breaking of stated invariants
+
+**Examples:**
+- Rounding errors that leak small amounts over time
+- Incorrect fee calculations
+- Missing slippage protection (user can set it)
+- Stale oracle data used briefly
+
+**Required for Report:**
+- Clear explanation of conditions
+- Impact assessment
+- Recommended fix
+
+---
+
+## Low
+
+**Definition:** Minor issues with limited impact, best practice violations.
+
+**Criteria:**
+- No direct loss of funds
+- Code quality issues
+- Missing events
+- Inconsistent behavior (not exploitable)
+- Edge cases with minimal impact
+
+**Examples:**
+- Missing zero-address validation (with no exploit path)
+- Unlocked compiler version
+- Inconsistent naming conventions
+- Missing natspec documentation
+
+**Required for Report:**
+- Issue description
+- Recommended fix
+
+---
+
+## Informational
+
+**Definition:** Gas optimizations, code style, suggestions.
+
+**Criteria:**
+- No security impact
+- Potential improvements
+- Gas savings
+
+**Examples:**
+- Using `++i` instead of `i++`
+- Caching array length in loops
+- Using `calldata` instead of `memory`
+- Redundant checks
+
+---
+
+## Special Categories
+
+### Centralization Risk
+
+**Severity:** Depends on trust model
+
+- Single admin key → High (if not disclosed)
+- Multisig + timelock → Low/Info
+- Documented and accepted → Info
+
+### Compiler/Dependency Issues
+
+**Severity:** Depends on exploitability
+
+- Known vulnerable dependency → Medium-Critical
+- Outdated but not vulnerable → Info
+
+### Gas Griefing
+
+**Severity:** Usually Medium
+
+- Can cause transaction failures
+- Can force users to pay more gas
+- Doesn't result in loss of principal
+
+---
+
+## Severity Comparison: Industry Standards
+
+| This Guide | Code4rena | Sherlock | Immunefi |
+|------------|-----------|----------|----------|
+| Critical | High (3) | High | Critical |
+| High | High (2) | High | High |
+| Medium | Medium | Medium | Medium |
+| Low | Low/QA | Low | Low |
+| Info | Gas/QA | Info | None |
+
+---
+
+## Disputes & Edge Cases
+
+When severity is unclear:
+
+1. **Default to higher severity** when uncertain
+2. **Consider worst-case scenario**
+3. **Account for composability** (other protocols building on top)
+4. **Time-sensitivity** (can it be fixed before exploit?)

package/skills/protocol-patterns/amm-dex/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: amm-dex
+description: AMM and DEX security patterns covering pricing, LP accounting, MEV, and swap invariants.
+---
+<!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
+
+# AMM (Automated Market Maker) Security Guide
+
+## Overview
+
+AMMs (Uniswap, Curve, Balancer) enable permissionless token swaps via liquidity pools. Core security concerns: price manipulation, MEV, impermanent loss, and LP token accounting.
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         AMM POOL                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   x * y = k (Constant Product)                              │
+│                                                             │
+│   ┌─────────┐         ┌─────────┐                          │
+│   │ Token A │ ◄─────► │ Token B │                          │
+│   │ Reserve │         │ Reserve │                          │
+│   └─────────┘         └─────────┘                          │
+│        ▲                   ▲                                │
+│        │                   │                                │
+│   ┌─────────────────────────────┐                          │
+│   │      LP Token Holders       │                          │
+│   └─────────────────────────────┘                          │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Critical Security Areas
+
+### 1. Price Manipulation
+
+**Attack Vectors:**
+- Flash loan price manipulation
+- Sandwich attacks
+- JIT (Just-In-Time) liquidity
+
+**Checklist:**
+- [ ] Is spot price used for anything critical? (Don't!)
+- [ ] Are there TWAP implementations? Are windows sufficient?
+- [ ] Can price be moved significantly in one transaction?
+- [ ] Is slippage protection enforced?
+
+```solidity
+// VULNERABLE: Spot price for external use
+function getPrice() external view returns (uint256) {
+    return reserve1 * 1e18 / reserve0;  // Manipulatable!
+}
+
+// SECURE: Accumulator-based TWAP
+function updateTWAP() internal {
+    uint32 timeElapsed = block.timestamp - lastUpdate;
+    if (timeElapsed > 0) {
+        priceAccumulator += getSpotPrice() * timeElapsed;
+        lastUpdate = block.timestamp;
+    }
+}
+```
+
+### 2. Slippage & MEV
+
+**Attack Vectors:**
+- User sets 0 slippage tolerance
+- Sandwich attacks when slippage is high
+- Deadline not enforced
+
+**Checklist:**
+- [ ] Is minAmountOut enforced?
+- [ ] Is deadline parameter checked?
+- [ ] Are there reasonable slippage bounds?
+- [ ] Is there MEV protection guidance for users?
+
+```solidity
+// VULNERABLE: No deadline check
+function swap(uint256 amountIn, uint256 minAmountOut) external {
+    // Missing deadline check - tx can be held and executed later
+}
+
+// SECURE
+function swap(
+    uint256 amountIn, 
+    uint256 minAmountOut,
+    uint256 deadline
+) external {
+    require(block.timestamp <= deadline, "Expired");
+    // ...
+    require(amountOut >= minAmountOut, "Slippage");
+}
+```
+
+### 3. LP Token Accounting
+
+**Attack Vectors:**
+- First depositor inflation attack
+- LP token value manipulation
+- Donation attacks
+
+**Checklist:**
+- [ ] Is first LP protected from inflation attack?
+- [ ] Are LP tokens calculated correctly with proper rounding?
+- [ ] Can direct token transfers manipulate LP value?
+- [ ] Is minimum liquidity locked (Uniswap pattern)?
+
+```solidity
+// Uniswap V2 first deposit protection
+uint256 public constant MINIMUM_LIQUIDITY = 1000;
+
+function mint() external returns (uint256 liquidity) {
+    uint256 _totalSupply = totalSupply;
+    if (_totalSupply == 0) {
+        liquidity = Math.sqrt(amount0 * amount1) - MINIMUM_LIQUIDITY;
+        _mint(address(0), MINIMUM_LIQUIDITY);  // Lock minimum
+    } else {
+        liquidity = Math.min(
+            amount0 * _totalSupply / _reserve0,
+            amount1 * _totalSupply / _reserve1
+        );
+    }
+}
+```
+
+### 4. Swap Calculations
+
+**Attack Vectors:**
+- Rounding errors favoring trader
+- Fee bypass
+- Incorrect constant product maintenance
+
+**Checklist:**
+- [ ] Is k always maintained or increasing (k_after ≥ k_before)?
+- [ ] Are fees correctly deducted?
+- [ ] Does rounding favor the pool?
+- [ ] Are there precision issues with small amounts?
+
+```solidity
+// VULNERABLE: k can decrease due to rounding
+function swap(uint256 amountIn, uint256 amountOut) external {
+    // ... transfer tokens ...
+    require(reserve0 * reserve1 >= k, "Invalid k");  // Should be >=
+}
+```
+
+### 5. Reentrancy in Swaps
+
+**Attack Vectors:**
+- Callback reentrancy (flash swaps)
+- ERC777/hooks during transfer
+
+**Checklist:**
+- [ ] Is reentrancy guard in place?
+- [ ] Are state updates before external calls?
+- [ ] Are callbacks properly restricted?
+- [ ] Is there ERC777 token support? If so, is it safe?
+
+---
+
+## AMM-Specific Vulnerabilities
+
+### Curve: Read-Only Reentrancy
+
+```solidity
+// Curve's virtual_price can be manipulated during reentrancy
+// Attack: Enter pool → in callback, read virtual_price → it's wrong
+
+// VULNERABLE: Reading Curve virtual_price during callback
+function deposit(uint256 amount) external {
+    uint256 price = curvePool.get_virtual_price();  // Can be manipulated
+    uint256 value = amount * price / 1e18;
+}
+```
+
+### Uniswap V3: Concentrated Liquidity
+
+**Additional concerns:**
+- Tick manipulation
+- Position NFT security
+- Fee calculation across ticks
+
+### Balancer: Weighted Pools
+
+**Additional concerns:**
+- Weight manipulation in managed pools
+- Complex math (power functions)
+- Multiple token interactions
+
+---
+
+## Testing Checklist
+
+### Unit Tests
+- [ ] Swap calculations match expected output
+- [ ] LP mint/burn accounting
+- [ ] Fee collection accurate
+- [ ] Slippage enforcement
+
+### Integration Tests
+- [ ] Multi-hop swaps
+- [ ] Flash swap callbacks
+- [ ] Oracle integrations
+
+### Invariant Tests
+- [ ] k_after ≥ k_before (constant product)
+- [ ] Sum of LP tokens = totalSupply
+- [ ] Reserves match actual balances
+- [ ] No tokens created from nothing
+
+### Attack Simulations
+- [ ] Sandwich attack simulation
+- [ ] Flash loan manipulation
+- [ ] First depositor attack
+
+---
+
+## References
+
+- [Uniswap V2 Core](https://github.com/Uniswap/v2-core)
+- [Uniswap V3 Security](https://github.com/Uniswap/v3-core/tree/main/audits)
+- [Curve Read-Only Reentrancy](https://chainsecurity.com/heartbeats/curve-lp-oracle-manipulation/)
+- [Balancer V2 Security](https://docs.balancer.fi/concepts/security/audits.html)