solidity-argus 0.2.0 → 0.3.0

package/skills/vulnerability-patterns/fee-on-transfer-tokens/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: fee-on-transfer-tokens
+description: Fee-on-transfer and deflationary token integration pitfalls that break protocol accounting.
+category: vulnerability-pattern
+pattern_category: token-standard
+source_url: https://github.com/bailsec/BailSec
+source_license: CC0
+imported_at: "2026-02-20T00:00:00Z"
+detection_rules:
+  - regex: 'transferFrom\('
+    severity: Medium
+    confidence: Medium
+    description: Token transfer that may receive less than expected with fee-on-transfer tokens
+  - regex: 'safeTransferFrom\('
+    severity: Medium
+    confidence: Medium
+    description: Safe token transfer that may receive less than expected with fee-on-transfer tokens
+---
+
+<!-- Source: BailSec audit reports (CC0) -->
+<!-- Extracted via audit-ingest pipeline from 5 independent protocol audits -->
+
+# Fee-on-Transfer Token Incompatibility
+
+## Overview
+
+Protocols that assume `transferFrom(sender, recipient, amount)` delivers exactly `amount` tokens to the recipient will break when interacting with fee-on-transfer (deflationary) tokens. These tokens deduct a fee during transfer, so the actual received amount is less than the specified amount. This creates accounting mismatches that can lead to insolvency, stuck funds, or exploitation.
+
+**Severity:** Informational to Medium (depends on whether the protocol explicitly supports or excludes these tokens)
+
+**Prevalence:** Found in 5 independent BailSec audits: Gamma UniswapV4, Gamma Vaults, Meuna, Moebius Finance, Terminal Finance DEX.
+
+---
+
+## Vulnerable Pattern
+
+```solidity
+// VULNERABLE: Assumes amount received == amount transferred
+function deposit(address token, uint256 amount) external {
+    IERC20(token).transferFrom(msg.sender, address(this), amount);
+    // If token has 2% fee, contract only received 0.98 * amount
+    // but records the full amount — accounting is now wrong
+    balances[msg.sender] += amount;  // Overstated!
+}
+```
+
+## Secure Pattern
+
+```solidity
+// SECURE: Measures actual received amount
+function deposit(address token, uint256 amount) external {
+    uint256 balanceBefore = IERC20(token).balanceOf(address(this));
+    IERC20(token).transferFrom(msg.sender, address(this), amount);
+    uint256 received = IERC20(token).balanceOf(address(this)) - balanceBefore;
+    balances[msg.sender] += received;  // Correct accounting
+}
+```
+
+## Impact
+
+- **Accounting mismatch**: Protocol records more tokens than it holds, leading to insolvency over time
+- **Failed withdrawals**: Later users cannot withdraw because the contract has fewer tokens than expected
+- **Vault share inflation**: In vault/pool contexts, shares are minted for a larger amount than actually deposited
+- **Arbitrage opportunity**: Attackers can exploit the mismatch to extract value from the protocol
+
+## Affected Token Examples
+
+| Token | Fee Mechanism | Notes |
+|-------|--------------|-------|
+| SAFEMOON | 10% tax on transfer | Reflection + burn + liquidity |
+| STA (Statera) | 1% deflationary burn | Destroyed on each transfer |
+| PAXG | 0.02% transfer fee | Gold-backed, fee goes to Paxos |
+| USDT (potential) | Configurable fee (currently 0) | Has fee infrastructure built-in |
+
+## Detection Checklist
+
+1. Does the contract call `transferFrom()` or `safeTransferFrom()` and then use the `amount` parameter directly?
+2. Is there a `balanceOf(address(this))` check before and after the transfer?
+3. Does the protocol documentation state support for fee-on-transfer tokens?
+4. Are there any allowlists/denylists for supported tokens?
+
+## Remediation
+
+1. **Measure actual received**: Use before/after `balanceOf` to determine the actual amount received
+2. **Document token support**: Explicitly state whether fee-on-transfer tokens are supported
+3. **Token allowlist**: If the protocol only supports standard tokens, enforce an allowlist
+4. **Revert on mismatch**: Add a check that reverts if received amount differs from expected
+
+## References
+
+- [Weird ERC20 Tokens — Fee on Transfer](https://github.com/d-xo/weird-erc20#fee-on-transfer)
+- OpenZeppelin SafeERC20 documentation
+- BailSec audit reports: Gamma, Meuna, Moebius Finance, Terminal Finance DEX

package/skills/vulnerability-patterns/flash-loan-attacks/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: flash-loan-attacks
 description: Flash-loan attack mechanics, exploit archetypes, and mitigations for capital-amplified threats.
+pattern_category: flash-loan
 source_url: https://github.com/kadenzipfel/smart-contract-vulnerabilities
 source_license: MIT
 imported_at: "2025-01-15T00:00:00Z"

package/skills/vulnerability-patterns/floating-pragma/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: floating-pragma
-description: - Deployable contract uses a floating or range pragma (e.g., `pragma solidity ^0.8.0`, `pragma solidity >=0.8.0`)
+description: '- Deployable contract uses a floating or range pragma (e.g., `pragma solidity ^0.8.0`, `pragma solidity >=0.8.0`)'
+pattern_category: logic-error
+detection_rules:
+  - regex: 'pragma solidity \^'
+    severity: Medium
+    confidence: High
+    swc: SWC-103
+    description: Floating pragma via caret version range
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/front-running-attacks/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: front-running-attacks
+description: Front-running and MEV vulnerabilities including missing slippage protection, deadline manipulation, predictable randomness, and commit-reveal weaknesses
+category: vulnerability-pattern
+pattern_category: front-running
+detection_rules:
+  - regex: 'swap\w*\([^)]*,\s*0\s*[,)]'
+    severity: High
+    confidence: High
+    swc: SWC-114
+    description: Swap call with hardcoded zero as minimum output amount - allows unlimited slippage and enables sandwich attacks by MEV bots
+  - regex: '\bdeadline\s*[:=]\s*block\.timestamp\b'
+    severity: Medium
+    confidence: High
+    swc: SWC-114
+    description: Using block.timestamp as transaction deadline provides no protection - validators can hold the transaction indefinitely and execute it when profitable
+  - regex: 'keccak256\(abi\.encodePacked\(block\.(timestamp|number|prevrandao)'
+    severity: High
+    confidence: High
+    swc: SWC-120
+    description: Using block variables (timestamp, number, prevrandao) as entropy in keccak256 - miners and validators can predict or manipulate these values to game randomness-dependent logic
+  - regex: 'function\s+commit\s*\(\s*(uint\d*|int\d*|address|bool|string)\s'
+    severity: Medium
+    confidence: Medium
+    description: Commit function accepts a raw value type instead of a hash - the committed value is visible in transaction calldata, enabling front-running before reveal phase
+---
+
+# Front-Running and MEV Attack Patterns
+
+## Overview
+
+Front-running attacks occur when adversaries observe pending transactions and reorder, insert, or censor their own transactions to extract value. In Ethereum-style public mempools, this behavior is often automated through searchers, builders, and relay infrastructure. If contract logic assumes fair ordering, it will fail under adversarial execution.
+
+MEV exposure is not limited to AMM swaps. Any function where outcome depends on timing, ordering, or visible intent can be exploited: auctions, liquidations, reward claims, randomness games, and commit-reveal schemes. Attackers exploit predictability, not just missing access control.
+
+Security review must model mempool visibility and builder-level ordering power as default assumptions. A safe design either removes ordering sensitivity, bounds downside with strict parameters, or hides actionable information until execution is finalized.
+
+## Key Attack Vectors
+
+- Sandwich attacks against swaps that set `amountOutMin` to zero or near-zero values.
+- Deadline misuse where `deadline == block.timestamp` gives no practical expiration window.
+- Backrun liquidation opportunities caused by stale off-chain quote assumptions.
+- Randomness generation from `block.timestamp`, `block.number`, or `block.prevrandao`.
+- Weak commit-reveal implementations that publish raw secrets during commit phase.
+- Reveal functions without strict phase windows, enabling selective reveal timing.
+- Signature-based order flows missing nonce/domain separation and replay protections.
+- Oracle update races where reads are exploitable between update and settlement.
+
+### Typical Sandwich Flow
+
+1. Victim submits swap with permissive slippage.
+2. Searcher detects intent in mempool.
+3. Searcher submits frontrun trade to move pool price against victim.
+4. Victim executes at degraded price.
+5. Searcher backruns in opposite direction and captures spread.
+6. Net value is extracted from victim through slippage.
+
+### Typical Commit-Reveal Failure
+
+1. User calls `commit(value)` with plaintext value.
+2. Adversary reads calldata before inclusion.
+3. Adversary submits matching or superior action first.
+4. Reveal phase no longer offers secrecy advantage.
+5. Game fairness assumptions break and funds are misallocated.
+
+## Detection Heuristics
+
+### Swap Safety Checks
+
+- Flag any swap invocation where minimum output argument is hardcoded to `0`.
+- Verify slippage bounds are user-defined and validated on-chain.
+- Confirm quote freshness constraints and max price impact checks exist.
+- Detect missing private-orderflow or intent-protection pathways for high-value operations.
+
+### Deadline Robustness
+
+- Detect `deadline = block.timestamp` assignments in routers and adapters.
+- Ensure deadlines are passed from user context and bounded to short windows.
+- Check that stale transactions fail safely after expiration.
+- Verify signatures include explicit expiry fields and are enforced.
+
+### Randomness Integrity
+
+- Flag entropy derived from `block.timestamp`, `block.number`, `blockhash`, `prevrandao` alone.
+- Check whether attacker can influence inclusion timing or validator context.
+- Require verifiable randomness (VRF) or delayed commit-based entropy mixing.
+- Review payout and settlement logic for timing-dependent outcomes.
+
+### Commit-Reveal Correctness
+
+- Commit input should be `bytes32 commitment`, not raw values.
+- Commitment must bind `(value, salt, sender, nonce, domain)`.
+- Reveal must verify preimage and enforce strict phase ordering.
+- Unrevealed commitments should have explicit timeout and penalty semantics.
+
+### Concrete Code Smells
+
+```solidity
+router.swapExactTokensForTokens(
+    amountIn,
+    0, // unlimited slippage
+    path,
+    msg.sender,
+    block.timestamp // ineffective deadline
+);
+```
+
+```solidity
+function random() internal view returns (uint256) {
+    return uint256(keccak256(abi.encodePacked(block.timestamp, msg.sender)));
+}
+```
+
+```solidity
+function commit(uint256 guess) external {
+    commits[msg.sender] = guess; // plaintext commit
+}
+```
+
+### Audit Questions
+
+- If an attacker sees this transaction 5 seconds early, can they profitably reorder around it?
+- Is every user-protective parameter set by caller input rather than contract defaults?
+- Does reveal logic preserve secrecy until reveal, or leak value during commit?
+- Does protocol use secure randomness when value transfer depends on random outcomes?
+
+## Prevention
+
+### Slippage and Execution Controls
+
+- Require non-zero `amountOutMin` derived from bounded slippage tolerance.
+- Validate path and pool depth to avoid toxic route execution.
+- Add max price impact constraints at execution time.
+- Offer private mempool routing for sensitive operations when practical.
+
+### Deadline and Signature Hygiene
+
+- Accept user-provided deadlines and enforce short expiry windows.
+- Include nonce, chain ID, and verifying contract in signed payloads.
+- Reject signatures that are expired or already used.
+- Do not use current block timestamp as the sole deadline source.
+
+### Secure Randomness
+
+- Use Chainlink VRF or equivalent verifiable source for high-value randomness.
+- If VRF is unavailable, use commit-reveal with delayed settlement and slashable non-reveal behavior.
+- Mix entropy with domain separators and sequence numbers.
+- Keep payouts decoupled from miner-influenceable inputs.
+
+### Correct Commit-Reveal Pattern
+
+```solidity
+function commit(bytes32 commitment) external {
+    require(commitPhaseOpen(), "Commit closed");
+    commits[msg.sender] = commitment;
+}
+
+function reveal(uint256 value, bytes32 salt) external {
+    require(revealPhaseOpen(), "Reveal closed");
+    bytes32 expected = keccak256(abi.encodePacked(value, salt, msg.sender, nonce[msg.sender]));
+    require(commits[msg.sender] == expected, "Invalid reveal");
+    nonce[msg.sender] += 1;
+    _settle(value);
+}
+```
+
+### Operational Defenses
+
+- Monitor abnormal slippage and repeated same-block sandwiches.
+- Simulate adversarial ordering in pre-deployment tests.
+- Publish best-practice transaction settings in frontend UX.
+- Use circuit breakers for extreme MEV conditions during volatility spikes.
+
+## Real-World Examples
+
+### AMM Sandwiching (Recurring Across DEXes)
+
+- Pattern: swaps with loose or zero slippage controls.
+- Impact: users receive significantly worse execution than quoted.
+- Lesson: slippage bounds are mandatory user protection, not optional convenience.
+
+### Fairness Breaks in Weak Commit-Reveal Games
+
+- Pattern: commit phase leaks values in calldata.
+- Impact: adversaries preempt outcomes before reveal.
+- Lesson: commitments must be opaque hashes with salts and sender binding.
+
+### Randomness Exploits in On-Chain Games
+
+- Pattern: entropy from miner-influenceable block variables.
+- Impact: validators/searchers skew outcomes for profit.
+- Lesson: use verifiable randomness for value-bearing random outcomes.
+
+### Pattern-to-Impact Mapping
+
+- `missing-slippage-protection` -> sandwich extraction and toxic execution.
+- `missing-deadline` -> delayed execution under changed market conditions.
+- `predictable-randomness` -> manipulable game or reward outcomes.
+- `commit-reveal-weakness` -> pre-reveal information leakage and front-run wins.
+
+## References
+
+- SWC-114 (Transaction order dependence): https://swcregistry.io/docs/SWC-114
+- SWC-120 (Weak randomness): https://swcregistry.io/docs/SWC-120
+- Flash Boys 2.0 paper: https://arxiv.org/abs/1904.05234
+- Paradigm MEV resources: https://www.paradigm.xyz/
+- Ethereum PBS and MEV-Boost research: https://github.com/flashbots/mev-boost
+- Chainlink VRF docs: https://docs.chain.link/vrf
+- Uniswap docs on slippage and execution: https://docs.uniswap.org/

package/skills/vulnerability-patterns/gas-optimization-patterns/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: gas-optimization-patterns
+description: Gas optimization patterns including unbounded loops, storage writes in loops, external calls in loops, and unchecked array growth
+category: vulnerability-pattern
+pattern_category: gas-optimization
+detection_rules:
+  - regex: '(for|while)\s*\([^)]*\w+\.length'
+    severity: High
+    confidence: Medium
+    swc: SWC-128
+    description: Loop iterates over a dynamic array length - if the array can grow unboundedly, the transaction will eventually exceed the block gas limit and permanently revert (DoS)
+  - regex: '(for|while)\s*\([^)]*\)\s*\{[^}]*\w+\s*\[.+\]\s*='
+    severity: Medium
+    confidence: Medium
+    swc: SWC-128
+    description: State variable assignment inside a loop - each SSTORE costs 5000-20000 gas, making the function vulnerable to gas griefing when loop count is attacker-influenced
+  - regex: '(for|while)\s*\([^)]*\)\s*\{[^}]*(\.call\{|\.transfer\(|\.send\()'
+    severity: High
+    confidence: High
+    swc: SWC-128
+    description: External call (call/transfer/send) inside a loop - each external call forwards gas and can revert, enabling a single failing recipient to DoS the entire distribution
+  - regex: '\.push\([^)]*\)'
+    severity: Medium
+    confidence: Low
+    swc: SWC-128
+    description: Dynamic array push without apparent length bound - unbounded array growth enables DoS when the array is later iterated in a single transaction
+---
+
+# Gas Optimization Risk Patterns
+
+## Overview
+
+Gas inefficiency becomes a security issue when costs are attacker-influenced. A function that works for small collections may become permanently uncallable after state growth, effectively creating a denial-of-service condition without any explicit revert logic. In production protocols, these patterns usually emerge in reward distribution, migration scripts, liquidation queues, and accounting loops.
+
+The dangerous class is unbounded iteration over mutable on-chain state, especially when each loop body performs storage writes or external interactions. Gas limits are hard caps at block level, so any architecture that assumes processing "all users" in one transaction eventually fails as adoption grows. Attackers can accelerate that failure by inflating arrays or forcing worst-case paths.
+
+Auditing for gas-related vulnerabilities should treat scalability assumptions as invariants. The key question is whether protocol-critical workflows can always make forward progress under realistic chain conditions. If progress requires a loop that can grow without bound, the protocol has a latent liveness fault.
+
+## Key Attack Vectors
+
+- Unbounded loops over dynamic arrays (`users.length`, `positions.length`) that grow with normal usage.
+- Storage writes inside loops where each iteration incurs expensive `SSTORE` costs.
+- External value transfers in loops that revert on one recipient and block all recipients.
+- Unchecked `.push()` growth on arrays later consumed in single-transaction maintenance jobs.
+- Admin "sweep" functions that try to settle all pending records at once.
+- Reward distributor contracts that compute and write per-user state in one pass.
+- Batch operations without explicit `startIndex` and `batchSize` limits.
+- Emergency recovery functions with O(n) writes to critical storage.
+
+### Common Failure Mode Timeline
+
+1. Protocol ships with loop-based accounting that is cheap at low scale.
+2. State arrays grow over weeks or months through routine activity.
+3. Core maintenance function approaches block gas limit.
+4. Adversary triggers additional growth or worst-case recipients.
+5. Function reverts consistently and becomes unusable.
+6. Treasury, rewards, or risk controls stall until contract migration.
+
+### High-Risk Contract Areas
+
+- Reward claim and distribution modules.
+- Liquidation backlogs and debt settlement queues.
+- Airdrop and vesting payout scripts.
+- Keeper-executed rebalance loops.
+- Governance payout executors.
+
+## Detection Heuristics
+
+### Structural Heuristics
+
+- Flag any `for` or `while` loop using `.length` from storage arrays.
+- Classify loops as unbounded unless there is a hard cap enforced on array growth.
+- Identify loops that modify storage each iteration rather than accumulating in memory.
+- Mark loops with `.call`, `.transfer`, or `.send` as liveness-critical due to external failure coupling.
+
+### Data-Flow Heuristics
+
+- Track whether the loop bound is attacker-influenced (user registration, deposits, mints).
+- Determine whether the function is required for protocol progress (not just optional convenience).
+- Check if failed transfers cause full revert instead of skipping failed recipients.
+- Evaluate if array growth is prunable or monotonic.
+
+### Severity Escalation Signals
+
+- Function is permissionless and called frequently.
+- Loop touches protocol-wide accounting or insolvency controls.
+- There is no pagination path for operators.
+- Keeper bots depend on the function to maintain invariants.
+
+### Concrete Code Smells
+
+```solidity
+function distributeRewards() external {
+    for (uint256 i = 0; i < recipients.length; i++) {
+        // storage write each iteration
+        claimed[recipients[i]] += rewards[recipients[i]];
+        payable(recipients[i]).transfer(rewards[recipients[i]]);
+    }
+}
+```
+
+```solidity
+function register(address user) external {
+    participants.push(user); // no max length
+}
+```
+
+### Auditing Checklist
+
+- Can any loop be split into deterministic chunks?
+- Is each chunk externally callable without privileged trust?
+- Are loop bounds independent from attacker-controlled growth?
+- Are failed external payouts isolated per recipient?
+- Can the system recover if a single recipient is non-payable?
+- Is there an emergency path that remains O(1) or bounded O(k)?
+
+## Prevention
+
+### Architecture Patterns
+
+- Replace push-payment loops with pull-payment claims per user.
+- Use pagination (`start`, `end` or `batchSize`) for all list processing.
+- Bound collection sizes with explicit maximums when feasible.
+- Prefer mappings + counters over ever-growing arrays for membership tracking.
+
+### Loop Hardening
+
+- Cache array length in memory if static during function scope.
+- Accumulate calculations in memory and perform one storage write post-loop where possible.
+- Use unchecked increments only when overflow is impossible and validated.
+- Emit events for skipped recipients instead of reverting entire batch.
+
+### External Call Isolation
+
+- Move external transfers to user-driven `claim()` functions.
+- If batch payout is required, wrap each call and continue on failure.
+- Record failed recipients for retry queues.
+- Avoid coupling core accounting success to transfer success.
+
+### Example Safer Pattern
+
+```solidity
+function processBatch(uint256 start, uint256 batchSize) external {
+    uint256 end = start + batchSize;
+    if (end > recipients.length) end = recipients.length;
+
+    for (uint256 i = start; i < end; i++) {
+        address user = recipients[i];
+        uint256 amount = pending[user];
+        if (amount == 0) continue;
+
+        pending[user] = 0;
+        (bool ok,) = user.call{value: amount}("");
+        if (!ok) {
+            pending[user] = amount;
+            emit PayoutFailed(user, amount);
+        }
+    }
+}
+```
+
+### Operational Mitigations
+
+- Monitor gas usage trends per critical function over time.
+- Add canary tests that simulate large-state stress scenarios.
+- Define upgrade plans for liveness failure before launch.
+- Maintain runbooks for phased processing if backlog spikes.
+
+## Real-World Examples
+
+### Reflection and Dividend Token Incidents
+
+- Recurrent pattern: token contracts iterate over all holders to distribute rewards.
+- Impact: transfers and claims become unusable as holder count grows.
+- Lesson: holder-wide loops are not sustainable in public deployments.
+
+### Airdrop Distribution Failures
+
+- Recurrent pattern: one-shot distribution transactions over large recipient sets.
+- Impact: distributions revert due to gas limits or one reverting recipient.
+- Lesson: merkle claims and pull-based redemption are safer than monolithic payouts.
+
+### DeFi Keeper Stalls
+
+- Recurrent pattern: keeper actions require iterating all stale positions.
+- Impact: risk controls fail to execute under stressed market conditions.
+- Lesson: bounded batches and priority queues are mandatory for keeper reliability.
+
+### Pattern-to-Impact Mapping
+
+- `unbounded-loop` -> protocol function eventually exceeds block gas limit.
+- `storage-write-in-loop` -> gas griefing and escalating execution costs.
+- `external-call-in-loop` -> single recipient can block full batch execution.
+- `unchecked-array-growth` -> latent DoS when arrays are consumed later.
+
+## References
+
+- SWC-128 (DoS with block gas limit): https://swcregistry.io/docs/SWC-128
+- Solidity gas optimization guide: https://docs.soliditylang.org/en/latest/internals/optimizer.html
+- OpenZeppelin PullPayment pattern: https://docs.openzeppelin.com/contracts/4.x/api/security#PullPayment
+- ConsenSys smart contract best practices: https://consensys.github.io/smart-contract-best-practices/
+- Solidity by Example - iterable mappings caveats: https://solidity-by-example.org/
+- Ethereum yellow paper gas model references: https://ethereum.github.io/yellowpaper/paper.pdf