solidity-argus 0.2.0 → 0.3.0

package/skills/vulnerability-patterns/governance-attacks/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: governance-attacks
+description: Governance vulnerabilities including flash-loan voting, timelock bypass, quorum manipulation, and unprotected proposals
+category: vulnerability-pattern
+pattern_category: governance
+detection_rules:
+  - regex: 'function\s+(execute|queue)\s*\([^)]*\)\s+(external|public)[^}]*\{(?![\s\S]*timelock)'
+    severity: High
+    confidence: Medium
+    description: Governance execute/queue function without timelock enforcement - critical governance actions can be executed immediately without delay, enabling flash-loan governance attacks (cf. Beanstalk $182M exploit)
+  - regex: 'function\s+(propose|castVote|castVoteBySig|castVoteWithReason)\s*\('
+    severity: Critical
+    confidence: Medium
+    description: Governance voting or proposal function detected - verify that voting power is snapshot-based (not live balance) to prevent flash-loan governance attacks where attacker borrows tokens, votes, and repays in one transaction (cf. Beanstalk BIP-18 exploit)
+  - regex: '(getVotes|votingPower|balanceOf)\s*\([^)]*\)(?![\s\S]{0,120}(snapshot|Checkpoint|getPastVotes|getPastTotalSupply|blockNumber))'
+    severity: High
+    confidence: Low
+    description: Voting power queried without snapshot or checkpoint mechanism - live balance queries for governance are manipulable via flash loans or token transfers; quorum can be artificially met or circumvented (cf. Build Finance DAO takeover)
+  - regex: 'function\s+propose\s*\([^)]*\)\s+(external|public)(?![\s\S]{0,200}(require|_msgSender|proposalThreshold|getVotes|onlyRole))'
+    severity: Medium
+    confidence: Low
+    description: Proposal creation function without apparent threshold or access check - any address can submit proposals, enabling governance spam or malicious proposal attacks (cf. Audius governance exploit)
+  - regex: 'function\s+(execute|executeProposal)\s*\([^)]*\)\s+(external|public)[^}]*\{(?![\s\S]*(_execute|state\s*==|ProposalState|hasVoted))'
+    severity: High
+    confidence: Medium
+    description: Governance execution without multi-step state machine - proposals can be executed without passing through proper lifecycle states (Pending, Active, Succeeded, Queued, Executed), enabling bypass of voting periods and quorum requirements (cf. Build Finance DAO hostile takeover)
+---
+
+# Governance Attack Patterns
+
+## Overview
+
+On-chain governance is a privileged execution pipeline. Any flaw in how proposals are created, voted, queued, or executed can be equivalent to handing over protocol admin keys. Unlike many isolated bugs, governance flaws often impact treasury control, upgrade authority, risk parameters, and emergency controls in a single exploit path.
+
+Modern attacks exploit the difference between governance latency and liquidity speed. Flash-loan capital allows an attacker to assemble temporary voting power, pass malicious actions, and unwind in one transaction unless voting weight is checkpointed at historical blocks. If timelocks and state transitions are weak, proposals can skip social review windows and execute immediately.
+
+The highest-risk governance systems combine three anti-patterns: live balance voting, weak proposal gating, and permissive execution paths. Auditing governance must focus on lifecycle invariants, not only individual functions. The question is whether every privileged state change requires a full, observable sequence of controls before execution.
+
+## Key Attack Vectors
+
+- Timelock bypass in `execute` or `queue` flows allows immediate execution after proposal success.
+- Flash-loan voting exploits live `balanceOf` semantics when vote power is not snapshot based.
+- Quorum manipulation occurs when total supply or vote weight is read at execution time instead of proposal snapshot time.
+- Unprotected proposal creation enables spam, griefing, and malicious payload staging by any account.
+- Single-step governance design collapses propose-vote-queue-execute into partial paths that skip lifecycle checks.
+- Weak role boundaries allow governance executors to call arbitrary targets with arbitrary calldata and value.
+- Incomplete cancellation rules let compromised proposers preserve malicious proposals through changing conditions.
+- Vote delegation edge cases can mint effective influence if delegation checkpoints are inconsistent.
+- Cross-governance integrations can create circular privilege where one module can reconfigure another's quorum.
+- Emergency guardian paths can become permanent backdoors if sunset logic is absent.
+
+### Typical Exploit Chain
+
+1. Acquire temporary voting power through flash loan or borrow market.
+2. Submit or support a proposal with privileged target calls.
+3. Satisfy quorum using live-balance vote accounting.
+4. Bypass or minimize delay due to weak timelock enforcement.
+5. Execute payload to drain treasury, transfer ownership, or upgrade logic.
+6. Repay borrowed capital and exit before governance can react.
+
+### High-Value Governance Targets
+
+- Treasury transfer executors.
+- Upgrade proxy admin contracts.
+- Oracle and risk parameter setters.
+- Pause and unpause emergency modules.
+- Bridge allowlists and relayer configuration.
+- Fee recipient and distribution routes.
+
+## Detection Heuristics
+
+### Lifecycle Integrity Checks
+
+- Verify a proposal state machine exists with explicit transitions: Pending -> Active -> Succeeded -> Queued -> Executed.
+- Confirm `execute` requires `Succeeded` or `Queued` state and cannot run directly from `Pending` or `Active`.
+- Ensure `queue` enforces a minimum delay through timelock metadata that cannot be zeroed by governance itself in the same proposal.
+- Check replay protections so a proposal cannot execute twice.
+
+### Voting Power Semantics
+
+- Flag direct use of `balanceOf()` in vote calculation paths.
+- Require `getPastVotes()` and `getPastTotalSupply()` at a specific snapshot block.
+- Validate that the snapshot block is set at proposal creation and cannot be user-provided at vote time.
+- Review delegation checkpoint code for overflows, stale checkpoints, and self-delegation assumptions.
+
+### Proposal Gating and Anti-Spam
+
+- Confirm `propose` enforces `proposalThreshold` or role checks.
+- Check whether threshold compares against historical votes, not current balances.
+- Detect absence of proposal deposits, cooldowns, or proposer rate limits in high-noise systems.
+- Verify guardian cancellation rights are bounded and transparent.
+
+### Timelock and Execution Constraints
+
+- Check for `onlyTimelock` or equivalent guard on privileged execution methods.
+- Confirm target/callData hashing includes all fields used at execute time.
+- Validate operation IDs are unique and consumed on execution.
+- Ensure timelock admin rotation itself is timelocked.
+
+### Concrete Code Smells
+
+```solidity
+function castVote(uint256 proposalId, uint8 support) external {
+    uint256 weight = token.balanceOf(msg.sender); // live-balance voting
+    _countVote(proposalId, msg.sender, support, weight);
+}
+
+function execute(uint256 proposalId) external {
+    // no state or timelock checks
+    _execute(proposalId);
+}
+```
+
+```solidity
+function propose(bytes[] calldata calls) external {
+    // no threshold, no role, no deposit
+    _storeProposal(msg.sender, calls);
+}
+```
+
+## Prevention
+
+### Governance Architecture Controls
+
+- Use OpenZeppelin `Governor` with `ERC20Votes` checkpoints and `TimelockController`.
+- Set non-trivial `votingDelay`, `votingPeriod`, and timelock delay based on protocol TVL and response capacity.
+- Keep proposer thresholds dynamic or governance-adjustable, but changes should be timelocked.
+- Separate emergency powers from treasury powers, with explicit expiry of emergency authority.
+
+### Secure Vote Accounting
+
+- Compute voter weight from historical checkpoints only.
+- Freeze quorum math to snapshot-era total supply.
+- Include anti-whale and anti-borrow constraints where applicable (lock periods, staking requirements, escrowed governance).
+- Monitor concentrated delegation changes near snapshot boundaries.
+
+### Execution Hardening
+
+- Gate execution through timelock-only entry points.
+- Require proposal state assertions at each stage.
+- Bind targets, values, calldata, and salt in operation hashes.
+- Prevent same-block queue and execute operations.
+
+### Operational Safeguards
+
+- Add off-chain alerting for proposal creation, queueing, and execution scheduling.
+- Publish human-readable calldata decoders for governance payloads.
+- Maintain an incident playbook for malicious proposal response.
+- Use simulation tooling to preview proposal side effects before queueing.
+
+### Baseline Hardened Pattern
+
+```solidity
+function castVote(uint256 proposalId, uint8 support) external {
+    ProposalCore storage p = _proposals[proposalId];
+    uint256 weight = token.getPastVotes(msg.sender, p.snapshotBlock);
+    require(weight > 0, "No voting power at snapshot");
+    _countVote(proposalId, msg.sender, support, weight);
+}
+
+function queue(uint256 proposalId) external {
+    require(state(proposalId) == ProposalState.Succeeded, "Not succeeded");
+    timelock.schedule(_operationHash(proposalId), MIN_DELAY);
+}
+
+function execute(uint256 proposalId) external {
+    require(state(proposalId) == ProposalState.Queued, "Not queued");
+    timelock.execute(_operationHash(proposalId));
+}
+```
+
+## Real-World Examples
+
+### Beanstalk (2022)
+
+- Reference: https://rekt.news/beanstalk-rekt/
+- Flash-loaned governance power was used to pass and execute a malicious proposal in a compressed timeline.
+- Core lesson: snapshot voting and meaningful timelock delays are non-optional for treasury governance.
+
+### Build Finance DAO Takeover (2022)
+
+- Reference: https://rekt.news/build-finance-rekt/
+- Governance control was captured and treasury assets were redirected by hostile governance actions.
+- Core lesson: weak lifecycle controls and insufficient proposer/voter safeguards enable hostile takeovers.
+
+### Audius Governance Exploit (2022)
+
+- Reference: https://rekt.news/audius-rekt/
+- Governance configuration weakness allowed attacker influence over protocol control paths.
+- Core lesson: proposal and execution authorization must be explicit, layered, and invariant-tested.
+
+### Pattern-to-Exploit Mapping
+
+- `timelock-bypass` -> Beanstalk-like rapid execution risk.
+- `flash-loan-governance` -> temporary capital vote capture.
+- `quorum-manipulation` -> live-balance distortion of quorum and support.
+- `unprotected-proposal` -> governance spam and payload staging.
+- `single-step-governance` -> lifecycle bypass into privileged execution.
+
+## References
+
+- OpenZeppelin Governor docs: https://docs.openzeppelin.com/contracts/4.x/governance
+- OpenZeppelin TimelockController: https://docs.openzeppelin.com/contracts/4.x/api/governance#TimelockController
+- Rekt News Beanstalk: https://rekt.news/beanstalk-rekt/
+- Rekt News Build Finance: https://rekt.news/build-finance-rekt/
+- Rekt News Audius: https://rekt.news/audius-rekt/
+- Trail of Bits governance security discussions: https://blog.trailofbits.com/
+- Sigma Prime solidity security notes: https://github.com/sigp/solidity-security-blog

package/skills/vulnerability-patterns/hash-collision/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: hash-collision
-description: - Contract uses `abi.encodePacked()` to encode data before hashing (typically with `keccak256`)
+description: '- Contract uses `abi.encodePacked()` to encode data before hashing (typically with `keccak256`)'
+pattern_category: logic-error
+detection_rules:
+  - regex: 'abi\.encodePacked\('
+    severity: Medium
+    confidence: Medium
+    swc: SWC-133
+    description: Packed encoding may collide when multiple dynamic arguments are hashed
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/inadherence-to-standards/SKILL.md

@@ -1,6 +1,17 @@
 ---
 name: inadherence-to-standards
-description: - Contract claims to implement a standard (ERC20, ERC721, ERC1155, etc.) but deviates from the specification
+description: '- Contract claims to implement a standard (ERC20, ERC721, ERC1155, etc.) but deviates from the specification'
+pattern_category: token-standard
+detection_rules:
+  - regex: 'IERC20\b'
+    severity: Informational
+    confidence: Low
+    swc: SWC-134
+    description: ERC20 interface usage should be checked for standard compliance assumptions
+  - regex: 'IERC721\b'
+    severity: Informational
+    confidence: Low
+    description: ERC721 interface usage should be checked for standard compliance assumptions
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/incorrect-constructor/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: incorrect-constructor
-description: - Solidity version <0.4.22 where constructors are named functions matching the contract name
+description: '- Solidity version <0.4.22 where constructors are named functions matching the contract name'
+pattern_category: logic-error
+detection_rules:
+  - regex: 'constructor\s*\('
+    severity: Informational
+    confidence: Low
+    swc: SWC-118
+    description: Constructor syntax signal for legacy constructor-name migration review
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/incorrect-inheritance-order/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: incorrect-inheritance-order
-description: - Contract uses multiple inheritance (`is ContractA, ContractB, ...`)
+description: '- Contract uses multiple inheritance (`is ContractA, ContractB, ...`)'
+pattern_category: logic-error
+detection_rules:
+  - regex: 'is\s+\w+\s*,\s*\w+'
+    severity: Informational
+    confidence: Low
+    swc: SWC-125
+    description: Multiple inheritance declaration needing linearization review
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

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

@@ -1,6 +1,17 @@
 ---
 name: insufficient-gas-griefing
-description: - Contract relays or forwards calls on behalf of users (meta-transactions, multisig execution, relayer patterns)
+description: '- Contract relays or forwards calls on behalf of users (meta-transactions, multisig execution, relayer patterns)'
+pattern_category: dos
+detection_rules:
+  - regex: '\.call\{gas:'
+    severity: Medium
+    confidence: Medium
+    swc: SWC-126
+    description: Caller-controlled gas forwarding can censor relayed execution
+  - regex: 'gasleft\(\)'
+    severity: Low
+    confidence: Low
+    description: Gas accounting logic should be checked for griefing resilience
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

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

@@ -1,6 +1,12 @@
 ---
 name: lack-of-precision
-description: - Contract performs integer arithmetic (division, fee calculations, reward distributions)
+description: '- Contract performs integer arithmetic (division, fee calculations, reward distributions)'
+pattern_category: logic-error
+detection_rules:
+  - regex: '/\s*\d+\s*\*'
+    severity: Low
+    confidence: Low
+    description: Division-before-multiplication pattern that can truncate precision
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

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

@@ -1,6 +1,16 @@
 ---
 name: logic-errors
 description: Protocol logic bug patterns, exploit examples, and invariant-driven review strategies.
+pattern_category: logic-error
+detection_rules:
+  - regex: 'if\s*\([^)]*&&[^)]*\|\|'
+    severity: Informational
+    confidence: Low
+    description: Mixed boolean operators in one condition warrant logic review
+  - regex: 'require\(.*,\s*"'
+    severity: Informational
+    confidence: Low
+    description: Guard clauses can reveal critical business-logic invariants
 ---
 
 <!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->

package/skills/vulnerability-patterns/missing-parameter-bounds/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: missing-parameter-bounds
+description: "Protocol parameters are accepted without min/max constraints, allowing invalid or unsafe runtime states."
+category: vulnerability-pattern
+pattern_category: logic-error
+source_url: "https://github.com/bailsec/BailSec"
+source_license: "CC0"
+imported_at: "2025-02-20T00:00:00Z"
+detection_rules:
+  - regex: "function\\s+(set|update|configure|initialize|constructor).*\\{[\\s\\S]{0,400}?(bps|fee|ratio|range|cap|threshold)"
+    severity: "Medium"
+    description: "Configurable economic parameter likely missing explicit bounds"
+  - regex: "require\\(.*<=\\s*(MAX|1e4|10000)"
+    severity: "Low"
+    description: "Use as a companion check to find setters lacking equivalent guardrails"
+---
+<!-- Source: BailSec audit reports (CC0) -->
+
+# Missing Parameter Bounds Vulnerabilities
+
+## Overview
+Missing parameter bounds is a recurring configuration-class vulnerability where contracts accept values that violate economic assumptions, arithmetic safety, or protocol UX constraints. Typical examples include BPS percentages above 100%, negative-style behavior encoded in signed ranges, or credit and share thresholds that can be bypassed in one path but enforced in another. The issue is often not immediate code execution risk, but delayed protocol failure, broken accounting, or user-loss scenarios after governance changes.
+
+A high-risk variant is validation drift: constructor and setter logic differ, so initial deployment can inject invalid values that runtime mutation would reject (or vice versa). This creates non-obvious states auditors miss when they only inspect one code path.
+
+## Common Patterns
+- Constructor omits upper bound checks that exist in a later setter.
+- Setter enforces one invariant but related functions do not re-check post-action states.
+- Signed range parameters increase complexity and permit invalid semantics.
+- Optional token interfaces or assumptions are accepted without compatibility gating.
+
+## Detection Heuristics
+- Build a matrix of each mutable parameter: constructor checks, setter checks, and all usage-site assumptions.
+- Flag any economic parameter lacking explicit min/max and unit documentation.
+- Compare pre-state vs post-state constraints on mutating flows (supply/withdraw/rebalance).
+- Review all checks for consistency in BPS, decimals, and scaling conventions.
+
+## Examples from Audits
+- Bridge bonus percentage accepted in initialization without enforcing BPS cap, allowing values above 10,000.
+- Fee parameter validated in setter but not in constructor, enabling out-of-range deployment state.
+- Credit and liquidity-related validation logic that was difficult to reason about and left bypass opportunities in adjacent paths.
+
+## Remediation
+Define parameter invariants once and reuse them through internal validator functions called by constructor, initializer, setters, and upgrade hooks. Prefer explicit constants (`MIN_*`, `MAX_*`) with unit comments. For safety-critical parameters, add two-step governance updates plus simulation checks before activation. Back this with property tests that fuzz all bounded values and assert protocol invariants remain true after each update. This makes future maintenance safer and prevents silent drift between code paths.

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

@@ -1,6 +1,22 @@
 ---
 name: missing-protection-signature-replay
-description: - Contract verifies ECDSA signatures for authorization
+description: '- Contract verifies ECDSA signatures for authorization'
+pattern_category: signature
+detection_rules:
+  - regex: 'ecrecover\('
+    severity: Medium
+    confidence: High
+    swc: SWC-121
+    description: Signature recovery path requires nonce, chain, and domain separation checks
+  - regex: 'ECDSA\.recover\('
+    severity: Medium
+    confidence: High
+    swc: SWC-121
+    description: Library-based signature recovery still needs replay protection fields
+  - regex: 'permit\(|signTypedData'
+    severity: High
+    confidence: Medium
+    description: Permit or typed data signing — missing nonce allows signature replay
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

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

@@ -1,6 +1,17 @@
 ---
 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
+description: '- `msg.value` is referenced inside a loop (`for`, `while`) or in a function called multiple times within a single external call'
+pattern_category: logic-error
+detection_rules:
+  - regex: 'msg\.value'
+    severity: Low
+    confidence: Low
+    swc: SWC-134
+    description: msg.value usage that may be reused across loop iterations
+  - regex: '(for|while)\s*\('
+    severity: Informational
+    confidence: Low
+    description: Loop context signal for msg.value reuse review
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

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

@@ -1,6 +1,12 @@
 ---
 name: off-by-one
-description: - Contract uses loops with boundary conditions, comparison operators at thresholds, or array index calculations
+description: '- Contract uses loops with boundary conditions, comparison operators at thresholds, or array index calculations'
+pattern_category: logic-error
+detection_rules:
+  - regex: '\.length\s*-\s*1'
+    severity: Low
+    confidence: Low
+    description: Boundary arithmetic near array length that can hide fence-post mistakes
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/oracle-manipulation/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: oracle-manipulation
 description: Oracle manipulation techniques, case studies, and secure pricing integration controls for DeFi.
+pattern_category: oracle-manipulation
 source_url: https://github.com/kadenzipfel/smart-contract-vulnerabilities
 source_license: MIT
 imported_at: "2025-01-15T00:00:00Z"
@@ -14,6 +15,14 @@ detection_rules:
     severity: High
     confidence: High
     description: AMM reserve spot-price usage vulnerable to manipulation
+  - regex: 'observe\(|consult\('
+    severity: Medium
+    confidence: Medium
+    description: TWAP oracle usage — time-weighted average prices can be manipulated via sustained trading pressure
+  - regex: 'priceFeed|oracle.*decimals'
+    severity: Medium
+    confidence: Medium
+    description: Oracle price feed with decimal handling — potential decimal mismatch between oracle and token
 ---
 
 <!-- Source: DeFiFoFum/fofum-solidity-skills (MIT) -->

package/skills/vulnerability-patterns/outdated-compiler-version/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: outdated-compiler-version
-description: - Contract is compiled with a Solidity version significantly behind the latest stable release
+description: '- Contract is compiled with a Solidity version significantly behind the latest stable release'
+pattern_category: logic-error
+detection_rules:
+  - regex: 'pragma solidity 0\.[0-7]\.'
+    severity: Informational
+    confidence: High
+    swc: SWC-102
+    description: Solidity pragma pins to an outdated major/minor compiler line
 ---
 <!-- Source: kadenzipfel/smart-contract-vulnerabilities (MIT) -->
 

package/skills/vulnerability-patterns/overflow-underflow/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: overflow-underflow
 description: Integer overflow and underflow vulnerabilities in Solidity contracts
+pattern_category: logic-error
 source_url: https://github.com/kadenzipfel/smart-contract-vulnerabilities
 source_license: MIT
 imported_at: "2025-01-15T00:00:00Z"