solidity-argus 0.1.8 → 0.3.0

package/skills/vulnerability-patterns/cross-chain-bridge-vulnerabilities/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: cross-chain-bridge-vulnerabilities
+description: Cross-chain bridge vulnerabilities including missing chain ID validation, cross-chain replay attacks, unverified bridge messages, and hardcoded bridge addresses
+category: vulnerability-pattern
+pattern_category: logic-error
+detection_rules:
+  - regex: '(abi\.encodePacked|keccak256)\s*\([^)]*(?!.*\b(block\.chainid|chainId)\b)[^)]*\)'
+    severity: High
+    confidence: Medium
+    description: Cross-chain message hash constructed without chain ID - signatures or proofs can be replayed on other chains where the contract is deployed at the same address
+  - regex: 'ecrecover\s*\([^)]*(?!.*\b(chainId|block\.chainid)\b)[^)]*\)'
+    severity: High
+    confidence: Medium
+    description: Signature recovery without chain-specific binding - ecrecover call does not reference chainId, allowing signed messages to be replayed across chain forks or L2 deployments
+  - regex: '(onMessageReceived|_processMessage|receiveMessage|handleBridgeMessage)\s*\('
+    severity: Critical
+    confidence: High
+    description: Bridge message receiver function detected - verify the caller is the authorized bridge contract and the source chain/sender are validated before processing
+  - regex: 'address\s+(constant|immutable)\s+\w*(bridge|Bridge|BRIDGE|relay|Relay|messenger|Messenger)\w*\s*='
+    severity: Medium
+    confidence: High
+    description: Hardcoded bridge or relay address - if the bridge contract is upgraded or redeployed, this contract cannot adapt without redeployment
+---
+
+# Cross-Chain Bridge Vulnerability Patterns
+
+## Overview
+
+Bridge systems expand trust boundaries across chains, consensus assumptions, and message formats. A single validation error in message authentication can mint unbacked assets, unlock escrowed collateral, or allow arbitrary calls on destination chains. Because bridges often custody large TVL, exploit impact is frequently catastrophic.
+
+Two themes dominate bridge incidents: insufficient domain separation and weak message authenticity checks. Domain separation prevents a proof or signature from one context (chain, contract, epoch) from being reused in another. Authenticity checks ensure only approved bridge infrastructure and source identities can trigger state transitions.
+
+Bridge security review should treat every inbound message as adversarial by default. Validation must bind the message to source chain, source sender, destination chain, destination contract, nonce, and replay state. Any omitted field becomes a likely replay or forgery surface.
+
+## Key Attack Vectors
+
+- Message hash construction that omits `chainId` or equivalent domain fields.
+- Signature verification via `ecrecover` without chain-specific binding.
+- Receiver handlers that trust `msg.sender` without verifying authorized bridge endpoint.
+- Missing validation of source chain and source application address.
+- Replayable messages due to absent nonce consumption or idempotency checks.
+- Hardcoded bridge addresses that become stale after upgrades or migrations.
+- Weak upgrade controls on bridge config, relayers, and validator sets.
+- Message parsers that decode calldata but do not enforce strict schema/version.
+
+### Typical Replay Attack Flow
+
+1. Attacker observes a valid signed bridge message on Chain A -> Chain B.
+2. Message does not include robust domain separation fields.
+3. Attacker replays the same payload on another deployment or fork.
+4. Destination contract accepts the message as valid.
+5. Funds are minted or released multiple times.
+6. Accounting diverges from source-chain lock state.
+
+### Typical Authentication Bypass Flow
+
+1. Bridge receiver exposes `handleBridgeMessage` style function.
+2. Function checks payload structure but not trusted caller/source identity.
+3. Attacker calls function directly with crafted message.
+4. Contract executes privileged state change (mint, transfer, config update).
+5. Attack completes without compromising bridge validators.
+
+## Detection Heuristics
+
+### Domain Separation Checks
+
+- Search message hash construction for inclusion of `block.chainid` or canonical `chainId` field.
+- Confirm hash binds destination contract address and source chain identifiers.
+- Verify signatures use EIP-712 domain separators with `chainId` and `verifyingContract`.
+- Flag ad-hoc `abi.encodePacked` payloads with ambiguous or incomplete fields.
+
+### Signature Verification Checks
+
+- Review `ecrecover` call sites for explicit domain-bound message digests.
+- Ensure recovered signer is validated against current authorized signer set.
+- Check for malleability handling and strict `s` value constraints where needed.
+- Confirm nonce or message ID is consumed exactly once.
+
+### Receiver Authorization Checks
+
+- Require `msg.sender == trustedBridge` or equivalent allowlist enforcement.
+- Validate source chain ID and source sender embedded in payload.
+- Confirm message ordering and replay protection against duplicate IDs.
+- Ensure receiver functions are `nonReentrant` if they trigger external calls.
+
+### Configuration and Upgrade Checks
+
+- Flag immutable or constant bridge addresses for systems that expect migrations.
+- Validate admin setter functions are timelocked and role-gated.
+- Check event emissions for all config changes (bridge, relayer, validator set).
+- Review emergency pause controls and recovery workflows.
+
+### Concrete Code Smells
+
+```solidity
+bytes32 digest = keccak256(abi.encodePacked(amount, recipient, nonce));
+address signer = ecrecover(digest, v, r, s); // no chain binding
+```
+
+```solidity
+function handleBridgeMessage(bytes calldata payload) external {
+    // missing require(msg.sender == trustedBridge)
+    _process(payload);
+}
+```
+
+```solidity
+address immutable bridgeMessenger = 0x1234...; // no upgrade path
+```
+
+### Audit Checklist
+
+- Is message identity globally unique across chains and contracts?
+- Can the same proof be replayed on forks or sibling deployments?
+- Are source app addresses validated against chain-scoped allowlists?
+- Is every successful message marked consumed atomically?
+- Can governance safely rotate bridge endpoints and signer sets?
+
+## Prevention
+
+### Message Schema Hardening
+
+- Use typed message structs with explicit fields: source chain, destination chain, source app, destination app, nonce, payload hash.
+- Hash using EIP-712 domain separation when signatures are involved.
+- Reject unknown schema versions to avoid parsing ambiguity.
+- Enforce strict decoding with size and range checks.
+
+### Authentication and Replay Controls
+
+- Verify caller is the designated bridge endpoint contract.
+- Validate source chain ID and sender against immutable or governable allowlists.
+- Consume message IDs in a replay map before external side effects.
+- Make message execution idempotent where practical.
+
+### Configurability with Safety
+
+- Prefer configurable bridge addresses over hardcoded constants.
+- Protect config updates with timelock and multi-sig governance.
+- Emit detailed events on every trust-boundary change.
+- Add two-step ownership transfer for bridge admin roles.
+
+### Hardened Receiver Example
+
+```solidity
+function handleBridgeMessage(
+    uint256 sourceChainId,
+    address sourceApp,
+    uint256 nonce,
+    bytes calldata payload,
+    bytes calldata proof
+) external nonReentrant {
+    require(msg.sender == trustedBridge, "Unauthorized bridge caller");
+    require(allowedSourceChains[sourceChainId], "Unsupported source chain");
+    require(allowedSourceApps[sourceChainId][sourceApp], "Unsupported source app");
+
+    bytes32 messageId = keccak256(
+        abi.encode(
+            block.chainid,
+            sourceChainId,
+            sourceApp,
+            address(this),
+            nonce,
+            keccak256(payload)
+        )
+    );
+
+    require(!consumed[messageId], "Replay");
+    require(verifyProof(messageId, proof), "Invalid proof");
+
+    consumed[messageId] = true;
+    _executePayload(payload);
+}
+```
+
+### Operational Defenses
+
+- Continuously monitor duplicate message IDs across chains.
+- Run chaos tests with forked deployments and stale bridge configs.
+- Maintain emergency pause for inbound message processing.
+- Reconcile bridge accounting between lock and mint sides on a schedule.
+
+## Real-World Examples
+
+### Wormhole (2022)
+
+- Reference: https://rekt.news/wormhole-rekt/
+- Forged verification path enabled minting of unbacked wrapped assets.
+- Lesson: proof and signature validation must be strict, domain-separated, and invariant-tested.
+
+### Nomad (2022)
+
+- Reference: https://rekt.news/nomad-rekt/
+- Message validation assumptions failed, enabling widespread unauthorized message replay/copycat draining.
+- Lesson: receiver authenticity checks and replay protection are critical at every handler entry point.
+
+### Additional Bridge Incident Patterns
+
+- Bridge key-management failures (validator compromise).
+- Config drift between source and destination chain deployments.
+- Insufficient upgrade controls introducing unreviewed trust paths.
+
+### Pattern-to-Impact Mapping
+
+- `missing-chain-id-validation` -> cross-chain replay of otherwise valid messages.
+- `replay-across-chains` -> signature reuse on forks/L2 mirrors.
+- `unverified-bridge-message` -> direct unauthorized execution on destination chain.
+- `hardcoded-bridge-address` -> operational failure or unsafe hotfix pressure during upgrades.
+
+## References
+
+- Rekt News Wormhole: https://rekt.news/wormhole-rekt/
+- Rekt News Nomad: https://rekt.news/nomad-rekt/
+- EIP-712 typed structured data hashing: https://eips.ethereum.org/EIPS/eip-712
+- OpenZeppelin access control patterns: https://docs.openzeppelin.com/contracts/4.x/access-control
+- Chainlink CCIP security overview: https://docs.chain.link/ccip
+- NIST guidance on replay resistance concepts: https://csrc.nist.gov/
+- Trail of Bits bridge security research: https://blog.trailofbits.com/

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

@@ -1,6 +1,18 @@
 ---
 name: default-visibility
-description: - Functions or state variables are declared without an explicit visibility specifier
+description: '- Functions or state variables are declared without an explicit visibility specifier'
+pattern_category: access-control
+detection_rules:
+  - regex: 'function\s+\w+\s*\('
+    severity: Informational
+    confidence: Low
+    swc: SWC-100
+    description: Generic function declaration signal for manual default visibility review (legacy SWC-100/SWC-108 context)
+  - regex: 'function\s+\w+\s*\([^)]*\)\s*\{'
+    severity: Medium
+    confidence: Low
+    swc: SWC-100
+    description: Function without explicit visibility specifier — defaults to public in older Solidity versions
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

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

@@ -1,6 +1,13 @@
 ---
 name: delegatecall-untrusted-callee
-description: - Contract uses `delegatecall`
+description: "Contract uses delegatecall with potentially untrusted callee"
+pattern_category: delegatecall
+detection_rules:
+  - regex: 'delegatecall'
+    severity: High
+    confidence: High
+    swc: SWC-112
+    description: Delegatecall usage where callee trust boundary must be verified
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/dos-gas-limit/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: dos-gas-limit
-description: - Contract iterates over a dynamic array or mapping whose size can grow unboundedly
+description: '- Contract iterates over a dynamic array or mapping whose size can grow unboundedly'
+pattern_category: dos
+detection_rules:
+  - regex: 'for\s*\([^)]*\.length'
+    severity: Medium
+    confidence: Low
+    swc: SWC-128
+    description: Loop bounded by dynamic length may become unexecutable at scale
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/dos-revert/SKILL.md

@@ -1,6 +1,19 @@
 ---
 name: dos-revert
-description: - Critical contract logic depends on an external call succeeding
+description: Denial-of-service attacks through unexpected reverts in external calls
+pattern_category: dos
+source_url: https://github.com/kadenzipfel/smart-contract-vulnerabilities
+source_license: MIT
+imported_at: "2025-01-15T00:00:00Z"
+detection_rules:
+  - regex: 'require\(.*\.send'
+    severity: Medium
+    confidence: Medium
+    description: Require-on-send pattern can cause full-transaction DoS
+  - regex: 'for\s*\('
+    severity: Low
+    confidence: Low
+    description: Loop construct that may combine with external calls for DoS risk
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/erc4626-exchange-rate-manipulation/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: erc4626-exchange-rate-manipulation
+description: "ERC-4626 integrations are exploited by manipulating share price or conversion state to mint, borrow, or redeem at distorted rates."
+category: vulnerability-pattern
+pattern_category: erc4626
+source_url: "https://github.com/bailsec/BailSec"
+source_license: "CC0"
+imported_at: "2025-02-20T00:00:00Z"
+detection_rules:
+  - regex: "(convertToShares|convertToAssets|previewDeposit|previewWithdraw|totalAssets\\()"
+    severity: "High"
+    description: "Critical ERC-4626 conversion surfaces requiring manipulation resistance"
+  - regex: "flashLoan\\(|flash\\s*loan|donat(e|ion)"
+    severity: "High"
+    description: "Capital-amplified exchange-rate manipulation preconditions"
+  - regex: 'balanceOf.*address.*this.*totalAssets|asset\.balanceOf'
+    severity: High
+    confidence: Medium
+    description: Vault totalAssets derived from balanceOf — vulnerable to donation attack to inflate share price
+  - regex: 'mulDiv|roundUp|roundDown|FullMath'
+    severity: Medium
+    confidence: Medium
+    description: Custom rounding math in vault share calculations — potential rounding errors favoring attacker
+  - regex: 'shares\s*=\s*(assets|amount)\b'
+    severity: Critical
+    confidence: Medium
+    description: Direct asset-to-share mapping without virtual offset — first depositor can inflate share price
+  - regex: '\.transfer\(address\(this\)|\.safeTransfer\(address\(this\)'
+    severity: High
+    confidence: Medium
+    description: Direct token transfer to vault bypassing deposit accounting — enables donation attack
+  - regex: 'totalSupply\(\)\s*==\s*0|totalAssets\(\)\s*==\s*0'
+    severity: Medium
+    confidence: Medium
+    description: Empty vault state check without minimum deposit or dead share enforcement
+---
+<!-- Source: BailSec audit reports (CC0) -->
+
+# ERC4626 Exchange Rate Manipulation Vulnerabilities
+
+## Overview
+This pattern targets vault systems that rely on ERC-4626 share/asset conversion, especially when those conversions are consumed by lending, collateral, or routing logic. Attackers manipulate the apparent exchange rate (or timing of its update) so victims mint too few shares, borrow against mispriced collateral, or absorb bad debt. The exploit usually combines one of: flash liquidity, share supply edge cases, stale accounting, rounding asymmetry, or permissive user-specified share parameters.
+
+The core failure is trusting conversion outputs as if they were immutable and manipulation-resistant under adversarial flow ordering.
+
+## Common Patterns
+- User-facing functions accept shares as input without robust slippage/min-out protection.
+- Vault share price can be inflated/deflated between preview and execution.
+- First-user or low-liquidity states create nonlinear price jumps.
+- Protocol treats ERC-4626 collateral as safe despite supply concentration and flash accessibility.
+
+## Detection Heuristics
+- Trace every use of `convertToShares/Assets` and `preview*` into borrow limits, liquidation, and accounting updates.
+- Check for same-tx manipulability of `totalAssets` or effective share supply.
+- Verify min-out controls for both assets and shares on deposit/withdraw flows.
+- Stress-test empty, near-empty, and first-deposit states with fuzzed ordering.
+
+## Examples from Audits
+- Share-price inflation path where a victim specifying share quantity could be induced to supply more assets than intended.
+- ERC-4626 collateral market where flash-loan control of share supply enabled bad-debt creation through exchange-rate distortion.
+- Vault inflation scenario where fee accrual and conversion math created attacker-favorable rounding for later users.
+
+## Remediation
+Require explicit user slippage bounds on both assets and shares. Add anti-manipulation checks that compare pre/post conversion expectations and reject large deltas within the same transaction context. Introduce bootstrap protections for first deposits (seed shares, dead shares, or guarded initialization). For lending integrations, gate collateral eligibility, cap concentration, and add oracle or TWAP defenses around vault share pricing. Finally, test conversion invariants under adversarial ordering and flash-capital assumptions.

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,19 @@
 ---
 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"
+detection_rules:
+  - regex: 'flashLoan\('
+    severity: High
+    confidence: High
+    description: Flash loan primitive usage that can amplify economic attacks
+  - regex: 'balanceOf\(address\(this\)\)'
+    severity: Medium
+    confidence: Medium
+    description: In-transaction balance checks often used in flash-loan-sensitive logic
 ---
 
 <!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->

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) -->