solidity-argus 0.1.0

package/skills/vulnerability-patterns/insufficient-gas-griefing/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: insufficient-gas-griefing
+description: - Contract relays or forwards calls on behalf of users (meta-transactions, multisig execution, relayer patterns)
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Insufficient Gas Griefing
+
+## Preconditions
+- Contract relays or forwards calls on behalf of users (meta-transactions, multisig execution, relayer patterns)
+- The relayer/executor controls how much gas is forwarded to the sub-call
+- Replay protection (nonce/hash marking) occurs before or regardless of sub-call success
+- No minimum gas requirement is enforced before the sub-call
+
+## Vulnerable Pattern
+```solidity
+function execute(address target, bytes calldata data, uint256 gasLimit) external {
+    // Replay protection BEFORE sub-call — marks as executed regardless
+    require(!executed[nonce], "already executed");
+    executed[nonce] = true;
+    nonce++;
+
+    // Relayer can provide just enough gas for the outer tx to succeed
+    // but insufficient gas for the inner call — it silently fails
+    (bool success,) = target.call{gas: gasLimit}(data);
+    // success is false, but the nonce is already consumed
+    // The action is permanently censored
+}
+```
+
+## Detection Heuristics
+1. Identify relayer/meta-transaction patterns: functions that execute calls on behalf of other users
+2. Check if the function marks a nonce/hash as used BEFORE the sub-call succeeds — this enables permanent censorship
+3. Check if there's a `gasleft()` validation before the sub-call (e.g., `require(gasleft() >= requiredGas + overhead)`)
+4. Look for multisig `execute` functions where the executor controls gas forwarding
+5. Check if `.call{gas: X}` is used where `X` comes from the caller — the caller can set it too low
+
+## False Positives
+- Replay protection only marks the nonce after confirming sub-call success
+- The function enforces a minimum gas requirement before the sub-call
+- The sub-call failure is propagated (e.g., `require(success)`) so the outer tx also reverts, preserving the nonce
+- The gas parameter is fixed or validated against a minimum
+
+## Remediation
+- Enforce minimum gas before sub-calls: `require(gasleft() >= gasLimit + OVERHEAD)`
+- Only mark nonces/hashes as used AFTER confirming sub-call success
+- Propagate sub-call failures to revert the outer transaction when appropriate
+- Use EIP-150 rule awareness: the caller retains 1/64 of gas, so forward at least `gasLimit * 64/63`
+```solidity
+function execute(address target, bytes calldata data, uint256 gasLimit) external {
+    require(gasleft() >= gasLimit + 10000, "insufficient gas");
+
+    (bool success, bytes memory result) = target.call{gas: gasLimit}(data);
+
+    // Only mark as executed if sub-call succeeded
+    if (success) {
+        executed[nonce] = true;
+        nonce++;
+    }
+}
+```

package/skills/vulnerability-patterns/lack-of-precision/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: lack-of-precision
+description: - Contract performs integer arithmetic (division, fee calculations, reward distributions)
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Lack of Precision
+
+## Preconditions
+- Contract performs integer arithmetic (division, fee calculations, reward distributions)
+- Division is performed before multiplication, OR
+- Numerators can be smaller than denominators (producing zero), OR
+- No fixed-point scaling (WAD/RAY) is used for fractional calculations
+
+## Vulnerable Pattern
+```solidity
+function calculateFee(uint256 amount, uint256 daysEarly) external view returns (uint256) {
+    // Division BEFORE multiplication — truncates intermediate result
+    uint256 dailyRate = amount / 365; // Loses precision
+    uint256 fee = dailyRate * daysEarly; // Error compounds
+
+    // Correct: amount * daysEarly / 365 (multiply first)
+    return fee;
+}
+
+function distribute(uint256 reward, uint256 totalShares) external {
+    for (uint256 i = 0; i < holders.length; i++) {
+        // If reward < totalShares, this is always 0
+        uint256 share = reward / totalShares * balances[holders[i]];
+        _transfer(holders[i], share);
+    }
+}
+```
+
+## Detection Heuristics
+1. Search for division operations (`/`) in arithmetic expressions
+2. Check if division appears before multiplication in the same expression — this loses precision
+3. Check if the numerator can be smaller than the denominator — the result truncates to zero
+4. Look for fee, reward, interest, or share calculations without scaling factors (e.g., 1e18)
+5. Check rounding direction: does truncation favor the protocol or the user? In fee/debt calculations, rounding should favor the protocol; in reward/credit calculations, it should favor the user
+
+## False Positives
+- Multiplication is performed before division in the correct order
+- Fixed-point math libraries (WAD = 1e18, RAY = 1e27) are used to maintain precision
+- The numerator is guaranteed to be larger than the denominator by prior validation
+- The precision loss is intentionally accepted and documented (e.g., dust amounts)
+
+## Remediation
+- Always multiply before dividing: `amount * rate / divisor` instead of `amount / divisor * rate`
+- Use fixed-point math with scaling factors (1e18 for WAD, 1e27 for RAY)
+- Round in favor of the protocol for fees/debts, in favor of users for rewards/credits
+- Use `mulDiv` from OpenZeppelin or PRBMath for safe full-precision multiplication then division
+```solidity
+// Correct: multiply first, then divide
+uint256 fee = amount * daysEarly / 365;
+
+// With scaling for precision
+uint256 WAD = 1e18;
+uint256 scaledRate = (amount * WAD) / totalSupply;
+uint256 reward = (scaledRate * userBalance) / WAD;
+```

package/skills/vulnerability-patterns/logic-errors/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: logic-errors
+description: Protocol logic bug patterns, exploit examples, and invariant-driven review strategies.
+---
+
+<!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Logic Bug Exploits
+
+## Overview
+
+Logic bugs are flaws in business logic that allow unintended behavior. Unlike pattern-based vulnerabilities (reentrancy, overflow), these require understanding the protocol's intended behavior to identify.
+
+**Key insight:** Logic bugs are the hardest to find automatically and cause the largest losses.
+
+---
+
+## Attack Patterns
+
+### 1. Incorrect State Machine
+
+```solidity
+// VULNERABLE: Can withdraw multiple times
+enum Status { Pending, Approved, Withdrawn }
+mapping(uint256 => Status) public requestStatus;
+
+function withdraw(uint256 requestId) external {
+    require(requestStatus[requestId] == Status.Approved, "Not approved");
+    // Missing: requestStatus[requestId] = Status.Withdrawn;
+    payable(msg.sender).transfer(amounts[requestId]);
+}
+```
+
+### 2. Order of Operations
+
+```solidity
+// VULNERABLE: Update after external call
+function redeem(uint256 shares) external {
+    uint256 assets = convertToAssets(shares);
+    asset.transfer(msg.sender, assets);  // External call first
+    _burn(msg.sender, shares);           // State update after
+}
+
+// SECURE: CEI pattern
+function redeem(uint256 shares) external {
+    uint256 assets = convertToAssets(shares);
+    _burn(msg.sender, shares);           // State update first
+    asset.transfer(msg.sender, assets);  // External call after
+}
+```
+
+### 3. Accounting Errors
+
+```solidity
+// VULNERABLE: Doesn't account for existing balance
+function deposit() external payable {
+    balances[msg.sender] = msg.value;  // Overwrites, doesn't add!
+}
+
+// SECURE
+function deposit() external payable {
+    balances[msg.sender] += msg.value;
+}
+```
+
+### 4. Precision Loss
+
+```solidity
+// VULNERABLE: Division before multiplication
+function calculateReward(uint256 amount, uint256 rate) external pure returns (uint256) {
+    return amount / 1000 * rate;  // Loses precision
+}
+
+// SECURE: Multiplication before division
+function calculateReward(uint256 amount, uint256 rate) external pure returns (uint256) {
+    return amount * rate / 1000;
+}
+```
+
+### 5. Edge Case Handling
+
+```solidity
+// VULNERABLE: Division by zero when totalSupply is 0
+function pricePerShare() external view returns (uint256) {
+    return totalAssets() / totalSupply();  // Reverts if no shares
+}
+
+// SECURE
+function pricePerShare() external view returns (uint256) {
+    uint256 supply = totalSupply();
+    return supply == 0 ? 1e18 : totalAssets() * 1e18 / supply;
+}
+```
+
+---
+
+## Real Exploits
+
+### Nomad Bridge (Aug 2022) — $190M
+
+**What happened:**
+- Routine upgrade initialized `confirmAt` mapping with zero
+- Zero was a valid "confirmed" state
+- Anyone could submit fake messages as "already proven"
+- Mass exploitation by hundreds of addresses
+
+**Root cause:** Invalid initialization treated as valid state
+
+```solidity
+// The bug: messages[_messageHash] = 0 was treated as confirmed
+function process(bytes memory _message) public returns (bool _success) {
+    bytes32 _messageHash = keccak256(_message);
+    require(acceptableRoot(messages[_messageHash]), "not accepted");
+    // 0 passed acceptableRoot check!
+}
+```
+
+**Lesson:** Be explicit about valid states. Zero should not be a valid confirmed state.
+
+### Compound (Sept 2021) — $80M+
+
+**What happened:**
+- Upgrade introduced bug in reward distribution
+- `comptroller.compAccrued()` returned wrong values
+- Users could claim excessive COMP rewards
+
+**Root cause:** Incorrect accounting in upgrade
+
+**Lesson:** Test upgrades extensively. State transitions are dangerous.
+
+### Level Finance (May 2023) — $1.1M
+
+**What happened:**
+- Referral reward calculation bug
+- Could claim referral rewards multiple times
+- Self-referral exploit
+
+**Root cause:** Missing state update after reward claim
+
+### Saddle Finance (Apr 2022) — $10M
+
+**What happened:**
+- Virtual price calculation bug in meta-pool
+- Attacker manipulated LP token value
+- Withdrew more than deposited
+
+**Root cause:** Incorrect share calculation with rounding
+
+---
+
+## Detection Checklist
+
+### State Machine
+- [ ] Are all state transitions explicitly handled?
+- [ ] Can states be skipped or repeated?
+- [ ] Is there a state that represents "completed" to prevent re-execution?
+- [ ] Are default/zero values handled as invalid states?
+
+### Accounting
+- [ ] Does deposit add to existing balance (not overwrite)?
+- [ ] Does withdrawal subtract correctly?
+- [ ] Are shares/assets conversions precise?
+- [ ] Is totalSupply/totalAssets always consistent?
+
+### Math & Precision
+- [ ] Is multiplication done before division?
+- [ ] Are there division-by-zero possibilities?
+- [ ] Is precision loss handled (rounding direction)?
+- [ ] Are there overflow possibilities in intermediate calculations?
+
+### Edge Cases
+- [ ] What happens with zero amounts?
+- [ ] What happens with very small/large values?
+- [ ] What happens on first deposit (empty pool)?
+- [ ] What happens on last withdrawal (drain pool)?
+- [ ] What happens with self-referral/self-liquidation?
+
+### Protocol-Specific
+- [ ] Can rewards be claimed multiple times?
+- [ ] Can positions be liquidated incorrectly?
+- [ ] Are fees calculated and deducted correctly?
+- [ ] Can users bypass intended restrictions?
+
+## Finding Logic Bugs
+
+### 1. Understand Intended Behavior
+- Read docs, comments, specs
+- What SHOULD happen?
+- What are the invariants?
+
+### 2. Trace State Changes
+- Follow every state variable modification
+- Map out the state machine
+- Find missing transitions
+
+### 3. Test Boundaries
+- Zero values
+- Max values
+- First/last operations
+- Empty states
+
+### 4. Question Assumptions
+- "Users won't do X" — They will
+- "This value can't be zero" — It can
+- "This is called after Y" — Is it enforced?
+
+### 5. Think Like an Attacker
+- What's the most valuable exploit?
+- What if I could control X?
+- What if I did operations out of order?
+
+---
+
+## Secure Patterns
+
+### Explicit State Machine
+
+```solidity
+enum State { Created, Active, Completed, Cancelled }
+
+modifier inState(State expected) {
+    require(state == expected, "Invalid state");
+    _;
+}
+
+function complete() external inState(State.Active) {
+    state = State.Completed;  // Explicit transition
+    // Do completion logic
+}
+```
+
+### Invariant Checks
+
+```solidity
+function _checkInvariants() internal view {
+    assert(totalAssets >= totalLiabilities);
+    assert(totalShares == 0 || totalAssets > 0);
+    // Add protocol-specific invariants
+}
+
+function deposit(uint256 assets) external {
+    // ... deposit logic ...
+    _checkInvariants();
+}
+```
+
+### CEI Pattern (Checks-Effects-Interactions)
+
+```solidity
+function withdraw(uint256 amount) external {
+    // CHECKS
+    require(balances[msg.sender] >= amount, "Insufficient");
+    
+    // EFFECTS
+    balances[msg.sender] -= amount;
+    
+    // INTERACTIONS
+    payable(msg.sender).transfer(amount);
+}
+```
+
+---
+
+## References
+
+- [Nomad Hack Analysis (samczsun)](https://www.paradigm.xyz/2022/08/how-to-drain-almost-1-billion)
+- [Compound Bug Post-Mortem](https://www.comp.xyz/t/compound-comptroller-bug-post-mortem/2284)
+- [Trail of Bits: Not So Smart Contracts](https://github.com/crytic/not-so-smart-contracts)
+
+## Validation Heuristics (kadenzipfel)
+
+## Preconditions
+- Contract uses `require()` statements for input or state validation
+- The `require` condition is overly restrictive (rejects valid inputs) or too loose (accepts invalid inputs)
+- OR: `require()` validates return values from external contracts whose behavior doesn't match assumptions
+
+## Vulnerable Pattern
+```solidity
+// Overly restrictive: blocks legitimate use case
+function withdraw(uint256 amount) external {
+    // Fails if user has exactly the required amount (should be >=)
+    require(balances[msg.sender] > amount, "insufficient");
+    balances[msg.sender] -= amount;
+    payable(msg.sender).transfer(amount);
+}
+
+// External contract assumption mismatch
+function processPayment(IERC20 token, uint256 amount) external {
+    // Assumes transfer returns true, but some tokens don't return a value
+    // require reverts on tokens like USDT
+    require(token.transfer(msg.sender, amount), "failed");
+}
+
+// Missing error message
+function setRate(uint256 rate) external {
+    require(rate > 0); // No error message — difficult to debug
+}
+```
+
+## Detection Heuristics
+1. For each `require()`, verify the condition matches the documented business logic (e.g., `>` vs `>=`, `<` vs `<=`)
+2. Check if `require()` validates an external call's return value — verify the external contract actually returns what's expected
+3. Look for `require()` without error messages — while not a vulnerability, it makes debugging difficult
+4. Check if overly strict requirements can DoS critical paths (e.g., withdrawals, liquidations)
+5. Check chained contract calls: does an upstream contract provide inputs that could fail downstream `require` checks?
+
+## False Positives
+- The `require` condition exactly matches the specification
+- The strictness is intentional and documented
+- The error message is omitted in a pre-0.8.4 contract for gas optimization (custom errors not yet available)
+
+## Remediation
+- Verify each `require` condition against the specification: `>` vs `>=`, `<` vs `<=`
+- Add descriptive error messages or use custom errors (Solidity >=0.8.4)
+- For external call validations, use SafeERC20 or similar wrappers that handle non-standard return values
+```solidity
+function withdraw(uint256 amount) external {
+    require(balances[msg.sender] >= amount, "insufficient balance");
+    balances[msg.sender] -= amount;
+    payable(msg.sender).transfer(amount);
+}
+
+// Solidity >=0.8.4: custom errors for gas efficiency
+error InsufficientBalance(uint256 available, uint256 requested);
+
+function withdrawV2(uint256 amount) external {
+    if (balances[msg.sender] < amount)
+        revert InsufficientBalance(balances[msg.sender], amount);
+    balances[msg.sender] -= amount;
+    payable(msg.sender).transfer(amount);
+}
+```

package/skills/vulnerability-patterns/missing-protection-signature-replay/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: missing-protection-signature-replay
+description: - Contract verifies ECDSA signatures for authorization
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Missing Protection Against Signature Replay
+
+## Preconditions
+- Contract verifies ECDSA signatures for authorization
+- The signed message does not include a nonce, OR does not include the contract address, OR does not include the chain ID
+- No mechanism tracks which signatures have been processed
+
+## Vulnerable Pattern
+```solidity
+function executeWithSig(address to, uint256 amount, bytes memory sig) external {
+    // Missing: nonce, contract address, and chain ID in hash
+    // Same signature can be replayed on same contract, other contracts, or other chains
+    bytes32 hash = keccak256(abi.encodePacked(to, amount));
+    address signer = ECDSA.recover(hash, sig);
+    require(signer == authorizer, "invalid sig");
+
+    // No nonce tracking — same signature can be submitted repeatedly
+    _transfer(to, amount);
+}
+```
+
+## Detection Heuristics
+1. Search for `ecrecover` or `ECDSA.recover` usage
+2. Examine what is included in the signed hash — check for:
+   - Nonce: is there a per-signer incrementing nonce? Flag if absent (enables same-contract replay)
+   - Contract address (`address(this)`): flag if absent (enables cross-contract replay)
+   - Chain ID (`block.chainid`): flag if absent (enables cross-chain replay)
+3. Check if processed signatures/hashes are tracked in a mapping to prevent reuse
+4. Check if EIP-712 domain separator is used (it includes contract address and chain ID automatically)
+5. Verify that the nonce is incremented BEFORE execution, not after (to prevent reentrancy-based replay)
+
+## False Positives
+- EIP-712 domain separator is used with proper nonce tracking (covers address + chainId + nonce)
+- The signed message includes all three: nonce, contract address, and chain ID
+- The signature authorizes a one-time action that is inherently non-replayable (e.g., EIP-2612 permit with deadline and nonce)
+
+## Remediation
+- Include nonce, `address(this)`, and `block.chainid` in the signed message hash
+- Track processed nonces per signer in a mapping
+- Use EIP-712 structured data signing with a domain separator
+```solidity
+mapping(address => uint256) public nonces;
+
+function executeWithSig(address to, uint256 amount, bytes memory sig) external {
+    uint256 nonce = nonces[msg.sender]++;
+    bytes32 hash = keccak256(abi.encodePacked(
+        to, amount, nonce, address(this), block.chainid
+    ));
+    bytes32 ethHash = ECDSA.toEthSignedMessageHash(hash);
+    address signer = ECDSA.recover(ethHash, sig);
+    require(signer == authorizer, "invalid sig");
+    _transfer(to, amount);
+}
+```

package/skills/vulnerability-patterns/msgvalue-loop/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: msgvalue-loop
+description: - `msg.value` is referenced inside a loop (`for`, `while`) or in a function called multiple times within a single external call
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# msg.value Reuse in Loops
+
+## Preconditions
+- `msg.value` is referenced inside a loop (`for`, `while`) or in a function called multiple times within a single external call
+- The contract has an existing ETH balance or the logic assumes `msg.value` is "spent" per iteration
+
+## Vulnerable Pattern
+```solidity
+function batchBuy(uint256[] calldata ids) external payable {
+    for (uint256 i = 0; i < ids.length; i++) {
+        // msg.value is the SAME on every iteration — it never decreases
+        // If price == 1 ETH and user sends 1 ETH, they can buy N items
+        require(msg.value >= price, "insufficient payment");
+        _mint(msg.sender, ids[i]);
+    }
+    // User paid 1 ETH but bought N items
+}
+
+// Payable multicall — same issue
+function multicall(bytes[] calldata calls) external payable {
+    for (uint256 i = 0; i < calls.length; i++) {
+        // msg.value forwarded to each sub-call — reused each time
+        (bool s,) = address(this).delegatecall(calls[i]);
+        require(s);
+    }
+}
+```
+
+## Detection Heuristics
+1. Search for `msg.value` usage inside `for`, `while`, or `do-while` loops
+2. Search for `msg.value` in functions that are called via `delegatecall` in a loop (multicall patterns)
+3. Check if `msg.value` is used in a `require` check inside a loop — passes on every iteration after a single payment
+4. Search for internal functions that reference `msg.value` and are called multiple times from a payable external function
+5. Check if the contract subtracts from a local tracking variable instead of relying on `msg.value` directly
+
+## False Positives
+- The function tracks remaining value in a local variable and decrements it per iteration (e.g., `remaining -= price`)
+- `msg.value` is only referenced once outside any loop
+- The loop is guaranteed to execute exactly once
+- The function validates total cost against `msg.value` before the loop (e.g., `require(msg.value == price * ids.length)`)
+
+## Remediation
+- Track remaining ETH in a local variable and decrement per operation
+- Validate total cost upfront: `require(msg.value == price * count)`
+- In multicall patterns, ensure `msg.value` is consumed only once, or use a tracking variable
+```solidity
+function batchBuy(uint256[] calldata ids) external payable {
+    uint256 totalCost = price * ids.length;
+    require(msg.value >= totalCost, "insufficient payment");
+
+    for (uint256 i = 0; i < ids.length; i++) {
+        _mint(msg.sender, ids[i]);
+    }
+
+    // Refund excess
+    if (msg.value > totalCost) {
+        payable(msg.sender).transfer(msg.value - totalCost);
+    }
+}
+```

package/skills/vulnerability-patterns/off-by-one/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: off-by-one
+description: - Contract uses loops with boundary conditions, comparison operators at thresholds, or array index calculations
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Off-By-One Errors
+
+## Preconditions
+- Contract uses loops with boundary conditions, comparison operators at thresholds, or array index calculations
+- The boundary/comparison is off by exactly one from the intended behavior
+
+## Vulnerable Pattern
+```solidity
+// Skips the last element
+function processAll() external {
+    for (uint256 i = 0; i < users.length - 1; i++) {
+        // Should be i < users.length
+        // Last user is never processed
+        _distribute(users[i]);
+    }
+}
+
+// Off-by-one in threshold check
+function liquidate(uint256 ratio) external {
+    // Should be ratio < MIN_RATIO (liquidate when below)
+    // Using <= means accounts AT the minimum are also liquidated
+    require(ratio <= MIN_RATIO, "healthy");
+    _liquidate();
+}
+
+// Out-of-bounds access
+function getLastUser() external view returns (address) {
+    return users[users.length]; // Should be users.length - 1
+}
+```
+
+## Detection Heuristics
+1. For every loop, check the boundary condition: `< length` vs `<= length` vs `< length - 1`
+2. `< length - 1` skips the last element — flag unless intentional
+3. `<= length` goes out of bounds on array access — flag always
+4. For comparison operators at thresholds (`>`, `>=`, `<`, `<=`), verify the boundary matches the specification (e.g., "greater than" vs "greater than or equal to")
+5. Check pagination logic for fence-post errors: does the first page start at 0 or 1? Does the last batch include the final element?
+6. Look for `length - 1` on arrays that could be empty — this underflows to `type(uint256).max` in unchecked contexts or reverts in checked contexts
+
+## False Positives
+- The boundary is intentionally exclusive (e.g., `< length - 1` to skip the sentinel/last element by design)
+- The comparison operator matches the documented specification exactly
+- The code is iterating over pairs (`i < length - 1` to compare `arr[i]` with `arr[i+1]`)
+
+## Remediation
+- Verify each boundary condition against the specification or documented intent
+- Be explicit about inclusive vs exclusive bounds in comments
+- Guard against empty array underflow: check `length > 0` before `length - 1`
+```solidity
+function processAll() external {
+    for (uint256 i = 0; i < users.length; i++) {
+        _distribute(users[i]);
+    }
+}
+
+// Explicit about boundary semantics
+function liquidate(uint256 ratio) external {
+    require(ratio < MIN_RATIO, "healthy"); // Strictly below = liquidatable
+    _liquidate();
+}
+```