solidity-argus 0.1.0

package/skills/vulnerability-patterns/access-control/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: access-control
+description: Access-control exploit patterns and secure authorization approaches for privileged Solidity functions.
+---
+
+<!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Access Control Exploits
+
+## Overview
+
+Access control vulnerabilities occur when unauthorized users can execute privileged functions. These are often the simplest bugs but cause catastrophic losses.
+
+**Total Losses:** $1B+ across DeFi
+
+---
+
+## Attack Patterns
+
+### 1. Missing Access Control
+
+```solidity
+// VULNERABLE: Anyone can call
+function mint(address to, uint256 amount) external {
+    _mint(to, amount);
+}
+
+// SECURE: Access control
+function mint(address to, uint256 amount) external onlyMinter {
+    _mint(to, amount);
+}
+```
+
+### 2. Unprotected Initialize
+
+```solidity
+// VULNERABLE: Anyone can initialize
+function initialize(address _admin) external {
+    admin = _admin;
+}
+
+// SECURE: Initializer modifier
+function initialize(address _admin) external initializer {
+    admin = _admin;
+}
+```
+
+### 3. tx.origin Authentication
+
+```solidity
+// VULNERABLE: tx.origin can be manipulated
+function withdraw() external {
+    require(tx.origin == owner, "Not owner");
+    payable(owner).transfer(address(this).balance);
+}
+
+// Attack: Trick owner into calling attacker's contract
+contract Attacker {
+    function attack(VulnerableContract target) external {
+        target.withdraw();  // tx.origin is still the owner!
+    }
+}
+```
+
+### 4. Privilege Escalation
+
+```solidity
+// VULNERABLE: Admin can make anyone admin
+function setAdmin(address newAdmin) external onlyAdmin {
+    admin = newAdmin;  // No checks on newAdmin
+}
+
+// SECURE: Multi-sig or timelock for admin changes
+```
+
+### 5. Signature Replay
+
+```solidity
+// VULNERABLE: Same signature works multiple times
+function executeWithSig(bytes calldata data, bytes calldata sig) external {
+    address signer = recover(keccak256(data), sig);
+    require(signer == admin, "Invalid sig");
+    // Execute...
+}
+
+// SECURE: Include nonce
+mapping(address => uint256) public nonces;
+
+function executeWithSig(bytes calldata data, uint256 nonce, bytes calldata sig) external {
+    require(nonce == nonces[msg.sender]++, "Invalid nonce");
+    bytes32 hash = keccak256(abi.encode(data, nonce, address(this), block.chainid));
+    address signer = recover(hash, sig);
+    require(signer == admin, "Invalid sig");
+    // Execute...
+}
+```
+
+---
+
+## Real Exploits
+
+### Ronin Bridge (Mar 2022) — $625M
+
+**What happened:**
+- Attackers compromised 5 of 9 validator keys
+- 4 keys from Sky Mavis, 1 from Axie DAO
+- Signed fraudulent withdrawals
+
+**Root cause:** Insufficient key distribution + social engineering
+
+**Lesson:** Multi-sig threshold must assume some keys will be compromised.
+
+### Parity Wallet (Nov 2017) — $150M Frozen
+
+**What happened:**
+- Library contract had unprotected `initWallet()`
+- Random user called it, became owner
+- Called `kill()`, destroyed library
+- All wallets using library became unusable
+
+**Root cause:** Unprotected initialize function on library contract
+
+```solidity
+// The fatal function
+function initWallet(address[] _owners, uint _required, uint _daylimit) {
+    // NO ACCESS CONTROL
+    initMultiowned(_owners, _required);
+}
+```
+
+**Lesson:** ALL contracts need access control, especially libraries.
+
+### Wormhole (Feb 2022) — $326M
+
+**What happened:**
+- Attacker exploited signature verification bug
+- Forged guardian signatures
+- Minted 120k ETH on Solana, bridged to Ethereum
+
+**Root cause:** Improper signature verification in Solana program
+
+### Poly Network (Aug 2021) — $611M
+
+**What happened:**
+- Attacker exploited cross-chain message verification
+- Changed the keeper address to attacker-controlled address
+- Drained assets across multiple chains
+
+**Root cause:** Insufficient validation of cross-chain calls
+
+---
+
+## Detection Checklist
+
+### Function-Level
+- [ ] Does every state-changing function have appropriate access control?
+- [ ] Are there functions without any modifiers that should have them?
+- [ ] Is `onlyOwner`/`onlyAdmin` used consistently?
+- [ ] Can critical functions be called by anyone?
+
+### Initialization
+- [ ] Is `initialize()` protected with `initializer` modifier?
+- [ ] Can initialize be called multiple times?
+- [ ] Is the implementation contract also initialized?
+- [ ] Are all state variables properly set in initialize?
+
+### Authentication
+- [ ] Is `tx.origin` used anywhere? (Almost always wrong)
+- [ ] Are signatures properly validated with nonce/chainId/address?
+- [ ] Can signatures be replayed across chains or contracts?
+- [ ] Is there proper domain separation in signatures?
+
+### Privilege Management
+- [ ] Can admin change critical parameters without timelock?
+- [ ] Is there a way to revoke compromised admin access?
+- [ ] Are role changes logged with events?
+- [ ] Is there role hierarchy that could be exploited?
+
+## Secure Patterns
+
+### OpenZeppelin AccessControl
+
+```solidity
+import "@openzeppelin/contracts/access/AccessControl.sol";
+
+contract Secure is AccessControl {
+    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");
+    
+    constructor() {
+        _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
+    }
+    
+    function mint(address to, uint256 amount) external onlyRole(MINTER_ROLE) {
+        _mint(to, amount);
+    }
+}
+```
+
+### Two-Step Ownership Transfer
+
+```solidity
+address public pendingOwner;
+
+function transferOwnership(address newOwner) external onlyOwner {
+    pendingOwner = newOwner;
+}
+
+function acceptOwnership() external {
+    require(msg.sender == pendingOwner, "Not pending owner");
+    owner = pendingOwner;
+    pendingOwner = address(0);
+}
+```
+
+### Initializer Pattern
+
+```solidity
+import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
+
+contract MyContract is Initializable {
+    address public admin;
+    
+    /// @custom:oz-upgrades-unsafe-allow constructor
+    constructor() {
+        _disableInitializers();  // Protect implementation
+    }
+    
+    function initialize(address _admin) external initializer {
+        admin = _admin;
+    }
+}
+```
+
+---
+
+## References
+
+- [SWC-105: Unprotected Ether Withdrawal](https://swcregistry.io/docs/SWC-105)
+- [SWC-115: Authorization through tx.origin](https://swcregistry.io/docs/SWC-115)
+- [OpenZeppelin Access Control](https://docs.openzeppelin.com/contracts/access-control)
+- [Ronin Post-Mortem](https://roninblockchain.substack.com/p/community-alert-ronin-validators)
+
+## Detection Heuristics (kadenzipfel)
+
+## Preconditions
+- Contract has functions that modify sensitive state (ownership, balances, fees, minting, pausing, protocol parameters)
+- Those functions lack access control modifiers (`onlyOwner`, `onlyRole`, etc.) or `require(msg.sender == ...)` checks
+- OR: access control exists but is incomplete (e.g., role assignments themselves are unprotected)
+
+## Vulnerable Pattern
+```solidity
+address public owner;
+uint256 public feeRate;
+
+// Missing access control — anyone can call
+function setFeeRate(uint256 newRate) external {
+    feeRate = newRate;
+}
+
+// Missing access control — anyone can take ownership
+function setOwner(address newOwner) external {
+    owner = newOwner;
+}
+
+// Incomplete: role grant is unprotected
+function grantRole(address user, bytes32 role) external {
+    // Missing: require(hasRole(ADMIN_ROLE, msg.sender))
+    _roles[role][user] = true;
+}
+```
+
+## Detection Heuristics
+1. Identify all `external` and `public` functions that modify state variables
+2. For each, check if it has an access control modifier (`onlyOwner`, `onlyRole`, `whenNotPaused`, etc.) or an inline `require(msg.sender == ...)` check
+3. If a state-changing function has no access control, flag it — especially if it modifies ownership, balances, fees, or addresses
+4. Check that role/permission management functions themselves are protected (e.g., `grantRole` requires `ADMIN_ROLE`)
+5. Check `initialize()` functions in upgradeable contracts — they must have an `initializer` modifier to prevent re-initialization
+
+## False Positives
+- The function is intentionally permissionless by design (e.g., `deposit()`, `claim()` where anyone should be able to call)
+- Access control is enforced in an internal function that the external function always calls through
+- The contract is an implementation behind a proxy, and access control is enforced at the proxy level
+
+## Remediation
+- Add explicit access control to every state-changing function that should be restricted
+- Use OpenZeppelin's `Ownable` or `AccessControl` for standardized role management
+- Protect `initialize()` with the `initializer` modifier
+- Apply the principle of least privilege: each function should require the minimum role necessary
+```solidity
+import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
+
+contract Secure is Ownable {
+    function setFeeRate(uint256 newRate) external onlyOwner {
+        feeRate = newRate;
+    }
+}
+```

package/skills/vulnerability-patterns/arbitrary-storage-location/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: arbitrary-storage-location
+description: - Contract has a dynamic array in storage
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Write to Arbitrary Storage Location
+
+## Preconditions
+- Contract has a dynamic array in storage
+- User input controls the index used for writing to that array
+- No bounds checking on the index before the write
+- OR: assembly-level `sstore` with a user-controlled slot value
+
+## Vulnerable Pattern
+```solidity
+uint256[] public data;
+address public owner;
+
+function write(uint256 index, uint256 value) external {
+    // User controls index — can compute an index that maps
+    // to any storage slot via the array's storage layout:
+    // array elements start at keccak256(slot_of_length)
+    // attacker calculates index to target owner's slot
+    data[index] = value;
+}
+
+// Assembly variant
+function writeSlot(uint256 slot, uint256 value) external {
+    assembly {
+        sstore(slot, value) // Direct arbitrary storage write
+    }
+}
+```
+
+## Detection Heuristics
+1. Search for dynamic array writes where the index comes from user input or function parameters
+2. Check if the index is bounds-checked before the write (e.g., `require(index < data.length)`)
+3. Search for `sstore` in assembly blocks — check if the slot parameter is user-controlled
+4. Search for `.length` assignments on dynamic arrays (Solidity <0.6.0 allowed `array.length = X`, enabling array expansion to reach any slot)
+5. If an unbounded array write exists, verify whether the array's keccak256-based slot layout could collide with other state variable slots
+
+## False Positives
+- Array index is validated against `array.length` before writing
+- The array uses `push()` only (indices are not user-controlled)
+- Assembly `sstore` uses a hardcoded or internally computed slot
+- Modern Solidity (>=0.6.0) prevents direct `.length` manipulation
+
+## Remediation
+- Always bounds-check array indices: `require(index < data.length)`
+- Use `push()` and `pop()` instead of direct index assignment for dynamic arrays
+- Avoid exposing `sstore` with user-controlled slot values
+- Use mappings instead of arrays when random-access writes are needed
+```solidity
+function safeWrite(uint256 index, uint256 value) external {
+    require(index < data.length, "out of bounds");
+    data[index] = value;
+}
+```

package/skills/vulnerability-patterns/assert-violation/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: assert-violation
+description: - Contract uses `assert()` statements
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Assert Violation
+
+## Preconditions
+- Contract uses `assert()` statements
+- The `assert` condition can be reached through valid program execution (not a true invariant)
+- OR: `assert()` is used to validate user input or external call results instead of `require()`
+
+## Vulnerable Pattern
+```solidity
+function transfer(address to, uint256 amount) external {
+    // WRONG: assert used for input validation — should be require
+    // In Solidity <0.8.0, this consumes ALL remaining gas on failure
+    assert(balances[msg.sender] >= amount);
+
+    balances[msg.sender] -= amount;
+    balances[to] += amount;
+}
+
+function withdraw() external {
+    uint256 bal = balances[msg.sender];
+    balances[msg.sender] = 0;
+    (bool success,) = msg.sender.call{value: bal}("");
+    // WRONG: assert used to check external call result
+    assert(success);
+}
+```
+
+## Detection Heuristics
+1. Search for all `assert(` calls in the codebase
+2. For each, determine whether the condition is a true invariant (mathematically impossible to violate in a correct contract) or an input/state validation
+3. If the condition depends on user input, external call results, or mutable external state, flag it — it should be `require()` instead
+4. Check Solidity version: in <0.8.0, failing `assert` uses the `0xfe` INVALID opcode and consumes ALL remaining gas; in >=0.8.0, it reverts with `Panic(uint256)` error code `0x01` (refunds remaining gas but provides no custom message)
+5. If an `assert` can be triggered by an attacker, check if the gas consumption creates a griefing vector
+
+## False Positives
+- The `assert` checks a genuine invariant (e.g., `assert(totalSupply == sumOfAllBalances)` after a provably correct operation)
+- The condition is mathematically unreachable given the contract's logic
+- Used in test code, not production contracts
+
+## Remediation
+- Use `require()` for input validation and external call checks — it refunds remaining gas and accepts an error message
+- Reserve `assert()` only for invariant checks that should never fail in a correct contract
+- In Solidity >=0.8.4, prefer custom errors with `require` for gas-efficient error handling
+```solidity
+// Correct: require for input validation
+function transfer(address to, uint256 amount) external {
+    require(balances[msg.sender] >= amount, "insufficient balance");
+    balances[msg.sender] -= amount;
+    balances[to] += amount;
+    // assert is appropriate here: totalSupply should never change during transfer
+    assert(balances[msg.sender] + balances[to] == oldSum);
+}
+```

package/skills/vulnerability-patterns/asserting-contract-from-code-size/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: asserting-contract-from-code-size
+description: - Contract uses `extcodesize` or `address.code.length` to check whether an address is an EOA vs. a contract
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Asserting Contract from Code Size
+
+## Preconditions
+- Contract uses `extcodesize` or `address.code.length` to check whether an address is an EOA vs. a contract
+- This check gates access control, anti-bot logic, or security-sensitive operations
+- The check assumes that code size == 0 means EOA
+
+## Vulnerable Pattern
+```solidity
+modifier onlyEOA() {
+    // During constructor execution, extcodesize returns 0
+    // An attacker calling from their constructor bypasses this check
+    require(msg.sender.code.length == 0, "no contracts");
+    _;
+}
+
+function mint() external onlyEOA {
+    _mint(msg.sender, 1);
+}
+
+// Assembly variant
+function isContract(address addr) internal view returns (bool) {
+    uint256 size;
+    assembly { size := extcodesize(addr) }
+    return size > 0; // Returns false during constructor
+}
+```
+
+## Detection Heuristics
+1. Search for `extcodesize`, `.code.length`, or helper functions named `isContract`
+2. Check if the result is used to gate access (e.g., `require(... == 0)` to allow only EOAs)
+3. If used for EOA-only enforcement, flag it — contracts calling from their constructor have code size 0
+4. Also check for `tx.origin == msg.sender` as an alternative EOA check — flag it as incompatible with account abstraction (ERC-4337) and smart contract wallets
+5. Check if the "no contracts" logic protects anything security-sensitive (minting limits, anti-bot, etc.)
+
+## False Positives
+- `extcodesize` is used to check if a contract EXISTS at an address (not to distinguish EOA vs contract)
+- The check is combined with other protections that don't rely solely on code size
+- The function has no security implications if called by a contract
+
+## Remediation
+- There is no fully reliable on-chain method to distinguish EOAs from contracts
+- Redesign logic to not depend on this distinction — make the system work correctly regardless of caller type
+- If EOA-only behavior is truly needed, consider off-chain verification (e.g., signed messages from known EOAs)
+- Remove `isContract` checks from security-critical paths
+```solidity
+// Instead of gating by caller type, use per-address limits
+mapping(address => bool) public hasMinted;
+
+function mint() external {
+    require(!hasMinted[msg.sender], "already minted");
+    hasMinted[msg.sender] = true;
+    _mint(msg.sender, 1);
+}
+```

package/skills/vulnerability-patterns/authorization-txorigin/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: authorization-txorigin
+description: - Contract uses `tx.origin` for authorization or access control checks (e.g., `require(tx.origin == owner)`)
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Authorization Through tx.origin
+
+## Preconditions
+- Contract uses `tx.origin` for authorization or access control checks (e.g., `require(tx.origin == owner)`)
+- A legitimate owner/admin may interact with untrusted external contracts
+
+## Vulnerable Pattern
+```solidity
+contract Wallet {
+    address public owner;
+
+    function transferTo(address to, uint256 amount) external {
+        // tx.origin is the EOA that initiated the entire tx chain
+        // If owner calls MaliciousContract, which calls Wallet.transferTo,
+        // tx.origin is still the owner — check passes
+        require(tx.origin == owner, "not owner");
+        payable(to).transfer(amount);
+    }
+}
+
+contract Attacker {
+    Wallet wallet;
+    // Owner calls this (e.g., via a phishing link)
+    fallback() external {
+        // tx.origin == owner because owner initiated the tx
+        wallet.transferTo(address(this), address(wallet).balance);
+    }
+}
+```
+
+## Detection Heuristics
+1. Search for all instances of `tx.origin` in the codebase
+2. If `tx.origin` is used in a `require`, `if`, or comparison for authorization purposes, flag it
+3. Check if `tx.origin` is compared against privileged addresses (owner, admin, etc.)
+4. Note: `tx.origin == msg.sender` used to verify EOA status is a different pattern (see asserting-contract-from-code-size) — still flag it but for different reasons (breaks with account abstraction)
+
+## False Positives
+- `tx.origin` used only for logging or analytics, not for authorization
+- `tx.origin` used in combination with `msg.sender` checks where `msg.sender` is the primary authorization mechanism
+
+## Remediation
+- Replace `tx.origin` with `msg.sender` for all authorization checks
+- `msg.sender` reflects the immediate caller, not the transaction originator
+```solidity
+function transferTo(address to, uint256 amount) external {
+    require(msg.sender == owner, "not owner"); // Immediate caller check
+    payable(to).transfer(amount);
+}
+```

package/skills/vulnerability-patterns/default-visibility/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: default-visibility
+description: - Functions or state variables are declared without an explicit visibility specifier
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Default Visibility
+
+## Preconditions
+- Functions or state variables are declared without an explicit visibility specifier
+- For functions: Solidity <0.5.0 (compiler does not enforce explicit visibility; defaults to `public`)
+- For state variables: any Solidity version (defaults to `internal`, but developer may have intended `private`)
+- The function or variable performs sensitive operations or holds sensitive data
+
+## Vulnerable Pattern
+```solidity
+// Solidity <0.5.0: function defaults to public
+contract Wallet {
+    address owner;
+
+    // No visibility specified — defaults to public
+    // Anyone can call this and take ownership
+    function initWallet(address _owner) {
+        owner = _owner;
+    }
+
+    // Internal helper exposed as public by default
+    function _sendFunds(address to, uint256 amount) {
+        payable(to).transfer(amount);
+    }
+}
+```
+
+## Detection Heuristics
+1. Check the Solidity version: if <0.5.0, search for functions without `public`, `external`, `internal`, or `private` keywords
+2. For any version, search for state variables without explicit visibility — they default to `internal`
+3. For each function without explicit visibility, check if it modifies state or performs sensitive operations — these are exposed as `public` by default
+4. Look for functions prefixed with `_` (convention for internal) that lack the `internal` keyword
+5. In Solidity >=0.5.0, the compiler requires function visibility — but state variable visibility is still optional
+
+## False Positives
+- Solidity >=0.5.0 contracts: the compiler enforces function visibility, so missing function visibility won't compile
+- State variable intended to be `internal` and correctly defaults to `internal`
+- The function is genuinely intended to be `public`
+
+## Remediation
+- Always specify explicit visibility for all functions and state variables
+- Upgrade to Solidity >=0.5.0 where function visibility is compiler-enforced
+- Review all functions to ensure visibility matches intended access level
+```solidity
+contract Wallet {
+    address private owner;
+
+    function initWallet(address _owner) internal {
+        owner = _owner;
+    }
+
+    function _sendFunds(address to, uint256 amount) private {
+        payable(to).transfer(amount);
+    }
+}
+```

package/skills/vulnerability-patterns/delegatecall-untrusted-callee/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: delegatecall-untrusted-callee
+description: - Contract uses `delegatecall`
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Delegatecall to Untrusted Callee
+
+## Preconditions
+- Contract uses `delegatecall`
+- The target address of the `delegatecall` is derived from user input, function parameters, or a mutable state variable settable by non-admin users
+- OR: a proxy pattern where the implementation address can be changed by unauthorized parties
+
+## Vulnerable Pattern
+```solidity
+// User-controlled delegatecall target
+function forward(address callee, bytes calldata data) external {
+    // Attacker supplies callee = malicious contract
+    // Malicious contract overwrites storage (e.g., slot 0 = owner)
+    (bool success,) = callee.delegatecall(data);
+    require(success);
+}
+
+// Proxy with unprotected implementation setter
+function setImplementation(address _impl) external {
+    // Missing: require(msg.sender == admin)
+    implementation = _impl;
+}
+```
+
+## Detection Heuristics
+1. Search for all `delegatecall` invocations in the codebase
+2. For each, trace the target address: is it hardcoded, immutable, admin-only settable, or user-influenced?
+3. If the target comes from a function parameter, calldata, or storage variable — check that only authorized roles can set it
+4. For proxy contracts, verify that `upgradeTo` / `setImplementation` functions have proper access control
+5. Check storage layout compatibility between the proxy and all possible implementation contracts
+6. Flag any generic forwarding function that passes user-supplied addresses to `delegatecall`
+
+## False Positives
+- `delegatecall` target is hardcoded or immutable (e.g., `address immutable IMPL`)
+- Target is set only in the constructor and cannot be changed
+- Target is restricted to a whitelist of audited contracts
+- Standard proxy patterns (EIP-1967, UUPS, TransparentProxy) with proper access control on upgrades
+
+## Remediation
+- Restrict `delegatecall` targets to trusted, immutable, or admin-only-settable addresses
+- Use established proxy patterns (OpenZeppelin TransparentProxy, UUPS) with proper access control
+- Never expose `delegatecall` with a user-supplied target address
+- Verify storage layout compatibility between proxy and implementation contracts using tools like OpenZeppelin's storage layout checker
+```solidity
+// Safe: immutable implementation
+address immutable implementation;
+constructor(address _impl) {
+    implementation = _impl;
+}
+fallback() external payable {
+    (bool s,) = implementation.delegatecall(msg.data);
+    require(s);
+}
+```