solidity-argus 0.1.0

package/skills/vulnerability-patterns/unused-variables/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: unused-variables
+description: - Contract declares state variables, local variables, function parameters, or imports that are never referenced
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Presence of Unused Variables
+
+## Preconditions
+- Contract declares state variables, local variables, function parameters, or imports that are never referenced
+- OR: return values from function calls are silently discarded
+
+## Vulnerable Pattern
+```solidity
+contract Vault {
+    uint256 public totalDeposits;
+    uint256 public unusedCounter; // Declared but never read or written
+
+    function deposit(uint256 amount, bytes memory data) external {
+        // `data` parameter never used — possible missing validation
+        totalDeposits += amount;
+    }
+
+    function process() external {
+        // Return value from transfer silently discarded
+        // This may indicate missing success check
+        IERC20(token).transfer(recipient, amount);
+
+        uint256 result = _calculate();
+        // `result` computed but never used — missing logic?
+    }
+}
+```
+
+## Detection Heuristics
+1. Search for state variables that are never referenced in any function (only declared)
+2. Search for function parameters that are never used in the function body
+3. Search for local variables that are assigned but never read
+4. Check for return values from external calls that are not captured or checked
+5. For each unused variable, determine: is it dead code (safe to remove) or does it indicate missing logic (a bug)?
+6. Check compiler warnings for unused variable alerts
+
+## False Positives
+- The variable is part of an interface implementation and must be declared for signature compatibility even if unused
+- The variable is used in a commented-out or conditional compilation path
+- The variable is reserved for future use and documented as such
+- Function parameters prefixed with `_` to explicitly mark as unused (e.g., `function hook(uint256 /* _amount */)`)
+
+## Remediation
+- For dead code: remove the unused variable entirely
+- For missing logic: implement the intended use (e.g., check the return value, use the parameter for validation)
+- For interface-required but unused parameters: use the unnamed parameter syntax
+```solidity
+// Remove dead state variables
+// uint256 public unusedCounter; — DELETE
+
+// Unnamed parameters for interface compliance
+function onERC721Received(
+    address,     // operator — unused
+    address,     // from — unused
+    uint256,     // tokenId — unused
+    bytes memory  // data — unused
+) external pure returns (bytes4) {
+    return this.onERC721Received.selector;
+}
+
+// Check return values — use SafeERC20 for non-compliant tokens
+bool success = IERC20(token).transfer(recipient, amount);
+require(success);
+```

package/skills/vulnerability-patterns/use-of-deprecated-functions/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: use-of-deprecated-functions
+description: - Contract uses Solidity functions, keywords, or language features that have been deprecated or removed
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Use of Deprecated Functions
+
+## Preconditions
+- Contract uses Solidity functions, keywords, or language features that have been deprecated or removed
+- The deprecated feature may behave differently than expected or may not compile on newer Solidity versions
+
+## Vulnerable Pattern
+```solidity
+pragma solidity ^0.4.24;
+
+contract Legacy {
+    function destroy() external {
+        // suicide is deprecated — renamed to selfdestruct
+        // selfdestruct itself is now deprecated post-Dencun
+        suicide(msg.sender);
+    }
+
+    function getHash(bytes memory data) external view returns (bytes32) {
+        return sha3(data);  // Deprecated — use keccak256
+    }
+
+    function getBlockHash(uint256 n) external view returns (bytes32) {
+        return block.blockhash(n);  // Deprecated — use blockhash(n)
+    }
+
+    function getRemainingGas() external view returns (uint256) {
+        return msg.gas;  // Deprecated — use gasleft()
+    }
+}
+```
+
+| Deprecated | Replacement |
+|---|---|
+| `suicide(address)` | `selfdestruct(address)` (also deprecated) |
+| `block.blockhash(uint)` | `blockhash(uint)` |
+| `sha3(...)` | `keccak256(...)` |
+| `callcode(...)` | `delegatecall(...)` |
+| `throw` | `revert()` |
+| `msg.gas` | `gasleft()` |
+| `constant` (function modifier) | `view` |
+| `var` | Explicit type name |
+
+## Detection Heuristics
+1. Search for each deprecated keyword: `suicide`, `sha3`, `block.blockhash`, `callcode`, `throw`, `msg.gas`, `constant` (as function modifier), `var`
+2. Search for `selfdestruct` — while it's the replacement for `suicide`, it is itself deprecated post-Dencun and non-functional on some chains
+3. Check compiler warnings for deprecation notices
+4. Flag any usage and recommend the modern replacement
+
+## False Positives
+- The deprecated function appears in comments or documentation, not in executable code
+- The contract is intentionally targeting an old Solidity version where the deprecated feature is still standard
+- Interface definitions that reference deprecated patterns for backward compatibility
+
+## Remediation
+- Replace each deprecated function with its modern equivalent (see table above)
+- For `selfdestruct`: remove reliance entirely, as it is deprecated and non-functional on some chains post-Dencun
+- Upgrade the Solidity version to benefit from compiler enforcement of modern syntax
+```solidity
+// Modern equivalents
+pragma solidity 0.8.24;
+
+contract Modern {
+    function getHash(bytes memory data) external pure returns (bytes32) {
+        return keccak256(data);
+    }
+
+    function getBlockHash(uint256 n) external view returns (bytes32) {
+        return blockhash(n);
+    }
+
+    function getRemainingGas() external view returns (uint256) {
+        return gasleft();
+    }
+}
+```

package/skills/vulnerability-patterns/weak-sources-randomness/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: weak-sources-randomness
+description: - Contract generates \"random\" values using on-chain data: `block.timestamp`, `blockhash`, `block.difficulty` / `block.prevrandao`, `block.number`, or combinations thereof
+---
+<!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
+
+# Weak Sources of Randomness from Chain Attributes
+
+## Preconditions
+- Contract generates "random" values using on-chain data: `block.timestamp`, `blockhash`, `block.difficulty` / `block.prevrandao`, `block.number`, or combinations thereof
+- The random value determines outcomes with economic value (lotteries, games, minting, distributions)
+
+## Vulnerable Pattern
+```solidity
+function drawLottery() external {
+    // All inputs are deterministic and publicly visible
+    // Another contract can compute the same value in the same tx
+    uint256 random = uint256(keccak256(abi.encodePacked(
+        block.timestamp,
+        block.prevrandao,
+        msg.sender
+    ))) % 100;
+
+    if (random < 5) {
+        _payWinner(msg.sender);
+    }
+}
+
+// Attacker contract
+contract Exploit {
+    function attack(Lottery target) external {
+        // Compute the same "random" value before calling
+        uint256 random = uint256(keccak256(abi.encodePacked(
+            block.timestamp,
+            block.prevrandao,
+            address(this)
+        ))) % 100;
+
+        // Only call if we'll win
+        if (random < 5) {
+            target.drawLottery();
+        }
+    }
+}
+```
+
+## Detection Heuristics
+1. Search for `block.timestamp`, `block.prevrandao`, `block.difficulty`, `blockhash`, `block.number` used as inputs to `keccak256` or arithmetic operations producing a "random" value
+2. Check if the resulting value determines an outcome with economic impact (winner selection, token distribution, NFT rarity, game outcome)
+3. If randomness is derived exclusively from on-chain data, flag it — a contract in the same transaction can compute the identical value
+4. Check if `blockhash` is used for a future block (returns 0 for blocks not yet mined) or a block older than 256 blocks (also returns 0)
+5. Check if validators/miners can influence the inputs to bias the outcome
+
+## False Positives
+- Chainlink VRF or another verifiable randomness oracle is used
+- On-chain data is combined with an off-chain commit-reveal scheme (the on-chain part alone doesn't determine the outcome)
+- The randomness doesn't determine anything with economic value
+- `block.prevrandao` on PoS Ethereum provides sufficient entropy for the specific use case (not for high-value outcomes)
+
+## Remediation
+- Use Chainlink VRF (Verifiable Random Function) for provably fair randomness
+- Implement a commit-reveal scheme: users commit hashed choices, reveal in a later block
+- Never use `block.timestamp`, `blockhash`, or `block.prevrandao` alone for randomness in high-value contexts
+```solidity
+import {VRFConsumerBaseV2} from "@chainlink/contracts/src/v0.8/vrf/VRFConsumerBaseV2.sol";
+
+contract FairLottery is VRFConsumerBaseV2 {
+    function requestRandom() external {
+        requestRandomWords(keyHash, subId, confirmations, gasLimit, 1);
+    }
+
+    function fulfillRandomWords(uint256, uint256[] memory randomWords) internal override {
+        uint256 winner = randomWords[0] % participants.length;
+        _payWinner(participants[winner]);
+    }
+}
+```

package/skills/vulnerability-patterns/weird-tokens/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: weird-tokens
+description: Non-standard ERC20 behaviors, integration pitfalls, and token-handling safeguards.
+---
+<!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->
+
+# Weird ERC20 Tokens Reference
+
+Tokens that don't behave like standard ERC20. Integrating with these requires special handling.
+
+## Quick Reference Table
+
+| Pattern | Example Tokens | Risk | Mitigation |
+|---------|---------------|------|------------|
+| Missing return values | USDT, BNB, OMG | Silent failures | SafeERC20 |
+| Fee on transfer | STA, PAXG, SAFEMOON | Balance mismatch | Measure before/after |
+| Rebasing | AMPL, stETH, OHM | Cached balance wrong | Don't cache balances |
+| Pausable | BNB, ZIL | DOS | Handle gracefully |
+| Blocklist | USDC, USDT | User funds frozen | Document risk |
+| Upgradeable | USDC, USDT | Behavior can change | Monitor upgrades |
+| Flash mintable | DAI | Infinite supply attacks | Check total supply |
+| Multiple addresses | TUSD | Accounting errors | Verify canonical address |
+| Low decimals | USDC (6), GUSD (2) | Precision loss | Handle decimals explicitly |
+| High decimals | YAM-V2 (24) | Overflow risk | Check bounds |
+| Approval race | USDT, KNC | Front-running | Set to 0 first |
+| Revert on zero | LEND | Unexpected reverts | Check amount > 0 |
+| Non-string metadata | MKR | Type errors | Handle bytes32 |
+| ERC777 hooks | imBTC | Reentrancy | Treat as untrusted |
+
+---
+
+## Detailed Patterns
+
+### 1. Missing Return Values
+
+**Tokens:** USDT, BNB, OMG, BADGER
+
+**Problem:**
+```solidity
+// Returns nothing, but ERC20 interface expects bool
+function transfer(address to, uint value) public {
+    // ... no return statement
+}
+```
+
+**Exploit:**
+```solidity
+// This compiles but fails at runtime for USDT
+IERC20(usdt).transfer(to, amount);  // Reverts: expected return data
+```
+
+**Fix:**
+```solidity
+import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+using SafeERC20 for IERC20;
+
+IERC20(usdt).safeTransfer(to, amount);  // Works
+```
+
+---
+
+### 2. Fee on Transfer
+
+**Tokens:** STA, PAXG, SAFEMOON, most "reflection" tokens
+
+**Problem:**
+```solidity
+function transfer(address to, uint value) public returns (bool) {
+    uint fee = value * feePercent / 100;
+    _transfer(msg.sender, feeCollector, fee);
+    _transfer(msg.sender, to, value - fee);
+    return true;
+}
+```
+
+**Exploit:**
+```solidity
+// User deposits 100, protocol credits 100
+// But only 98 actually arrived (2% fee)
+// User can withdraw 100, stealing 2 from protocol
+function deposit(uint amount) external {
+    token.transferFrom(msg.sender, address(this), amount);
+    balances[msg.sender] += amount;  // WRONG!
+}
+```
+
+**Fix:**
+```solidity
+function deposit(uint amount) external {
+    uint balanceBefore = token.balanceOf(address(this));
+    token.transferFrom(msg.sender, address(this), amount);
+    uint received = token.balanceOf(address(this)) - balanceBefore;
+    balances[msg.sender] += received;  // Credit actual amount
+}
+```
+
+---
+
+### 3. Rebasing Tokens
+
+**Tokens:** AMPL, stETH (rebases), OHM, AAVE aTokens
+
+**Problem:**
+```solidity
+// Balance changes without any transfers
+function rebase(int supplyDelta) external {
+    totalSupply = totalSupply + supplyDelta;
+    // All balances scale proportionally
+}
+```
+
+**Exploit:**
+```solidity
+// Protocol caches balance
+uint cachedBalance = steth.balanceOf(address(this));
+
+// ... time passes, rebase happens ...
+
+// Cached balance is now wrong
+// Can lead to accounting errors, insolvency
+```
+
+**Fix:**
+- Don't cache balances
+- Use wrapper tokens (wstETH instead of stETH)
+- Track shares, not absolute amounts
+
+---
+
+### 4. Pausable Tokens
+
+**Tokens:** BNB, ZIL, USDC (admin can pause)
+
+**Problem:**
+```solidity
+modifier whenNotPaused() {
+    require(!paused, "Paused");
+    _;
+}
+
+function transfer(address to, uint value) public whenNotPaused {
+    // ...
+}
+```
+
+**Impact:**
+- Protocol can be DOS'd if token pauses
+- User funds stuck
+- Liquidations fail
+
+**Fix:**
+- Have emergency withdrawal that doesn't rely on transfers
+- Document risk to users
+- Consider timelock on protocol side
+
+---
+
+### 5. Blocklist/Blacklist Tokens
+
+**Tokens:** USDC, USDT (compliance blacklists)
+
+**Problem:**
+```solidity
+function transfer(address to, uint value) public {
+    require(!blacklisted[msg.sender], "Blacklisted");
+    require(!blacklisted[to], "Blacklisted");
+    // ...
+}
+```
+
+**Impact:**
+- Blacklisted users can't withdraw
+- Protocol holding funds for blacklisted user is stuck
+
+**Fix:**
+- Document risk
+- Consider allowing admin rescue to different address
+- Use wrapper tokens where possible
+
+---
+
+### 6. Upgradeable Tokens
+
+**Tokens:** USDC, USDT, many newer tokens
+
+**Problem:**
+- Token logic can change after integration
+- New fee mechanisms could be added
+- Pausability could be added
+
+**Impact:**
+- Your integration assumptions may break post-upgrade
+
+**Fix:**
+- Monitor token upgrades
+- Have upgrade handlers in your protocol
+- Test against upgraded implementations
+
+---
+
+### 7. Flash Mintable Tokens
+
+**Tokens:** DAI (flash mint), some wrapped tokens
+
+**Problem:**
+```solidity
+function flashLoan(uint amount) external {
+    _mint(msg.sender, amount);
+    IFlashBorrower(msg.sender).onFlashLoan(amount);
+    _burn(msg.sender, amount);
+}
+```
+
+**Impact:**
+- Attacker can temporarily have infinite tokens
+- Breaks governance (voting with flash minted tokens)
+- Price manipulation
+
+**Fix:**
+- Use TWAP for prices
+- Snapshot voting tokens before proposals
+- Check totalSupply before/after for sanity
+
+---
+
+### 8. Approval Race Condition
+
+**Tokens:** USDT requires setting to 0 first
+
+**Problem:**
+```solidity
+// USDT's approve reverts if allowance > 0 and newValue > 0
+function approve(address spender, uint value) public {
+    require(value == 0 || allowance[msg.sender][spender] == 0);
+    // ...
+}
+```
+
+**Fix:**
+```solidity
+// Always set to 0 first
+token.approve(spender, 0);
+token.approve(spender, newAmount);
+
+// Or use SafeERC20
+token.safeIncreaseAllowance(spender, amount);
+```
+
+---
+
+### 9. ERC777 Hooks (Reentrancy)
+
+**Tokens:** imBTC, any ERC777
+
+**Problem:**
+```solidity
+// ERC777 calls hooks on sender and receiver
+function _send(address from, address to, uint256 amount) internal {
+    _callTokensToSend(from, to, amount);  // HOOK - reentrancy!
+    _transfer(from, to, amount);
+    _callTokensReceived(from, to, amount);  // HOOK - reentrancy!
+}
+```
+
+**Impact:**
+- Reentrancy even without ETH transfers
+- imBTC was exploited via this
+
+**Fix:**
+- Treat ERC777 transfers as untrusted external calls
+- Apply CEI pattern
+- Use ReentrancyGuard
+
+---
+
+## Integration Checklist
+
+When integrating any token:
+
+- [ ] Check for missing return values (SafeERC20)
+- [ ] Check for fee-on-transfer (measure actual received)
+- [ ] Check for rebasing (don't cache balances)
+- [ ] Check for pausability (emergency paths)
+- [ ] Check for blocklists (document risk)
+- [ ] Check for upgradeability (monitor changes)
+- [ ] Check for flash minting (use TWAP)
+- [ ] Check for ERC777 hooks (reentrancy guard)
+- [ ] Check decimals (6, 8, 18, 24 all exist)
+- [ ] Check approval behavior (set to 0 first for USDT)
+
+## Resources
+
+- **weird-erc20:** <https://github.com/d-xo/weird-erc20>
+- **Token Integration Checklist:** <https://github.com/crytic/building-secure-contracts/blob/master/development-guidelines/token_integration.md>