npm - @elizaos/skills - Versions diffs - 2.0.0-alpha.10 - Mend

@elizaos/skills 2.0.0-alpha.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (291) hide show

package/skills/security-differential-review/skills/differential-review/methodology.md ADDED Viewed

@@ -0,0 +1,234 @@
+# Differential Review Methodology
+Detailed phase-by-phase workflow for security-focused code review.
+## Pre-Analysis: Baseline Context Building
+**FIRST ACTION - Build complete baseline understanding:**
+If `audit-context-building` skill is available:
+```bash
+# Checkout baseline commit
+git checkout <baseline_commit>
+# Invoke audit-context-building skill on baseline codebase
+# Scope = entire relevant project (e.g., packages/contracts/contracts/ for Solidity, src/ for Rust, etc.)
+audit-context-building --scope [entire project or main contract directory] --focus invariants,trust-boundaries,validation-patterns,call-graphs,state-flows
+# Examples:
+# For Solidity: audit-context-building --scope packages/contracts/contracts
+# For Rust: audit-context-building --scope src
+# For full repo: audit-context-building --scope .
+```
+**Capture from baseline analysis:**
+- System-wide invariants (what must ALWAYS be true across all code)
+- Trust boundaries and privilege levels (who can do what)
+- Validation patterns (what gets checked where - defense-in-depth)
+- Complete call graphs for critical functions (who calls what)
+- State flow diagrams (how state changes)
+- External dependencies and trust assumptions
+**Why this matters:**
+- Understand what the code was SUPPOSED to do before changes
+- Identify implicit security assumptions in baseline
+- Detect when changes violate baseline invariants
+- Know which patterns are system-wide vs local
+- Catch when changes break defense-in-depth
+**Store baseline context for reference during differential analysis.**
+After baseline analysis, checkout back to head commit to analyze changes.
+---
+## Phase 0: Intake & Triage
+**Extract changes:**
+```bash
+# For commit range
+git diff <base>..<head> --stat
+git log <base>..<head> --oneline
+# For PR
+gh pr view <number> --json files,additions,deletions
+# Get all changed files
+git diff <base>..<head> --name-only
+```
+**Assess codebase size:**
+```bash
+find . -name "*.sol" -o -name "*.rs" -o -name "*.go" -o -name "*.ts" | wc -l
+```
+**Classify complexity:**
+- **SMALL**: <20 files → Deep analysis (read all deps)
+- **MEDIUM**: 20-200 files → Focused analysis (1-hop deps)
+- **LARGE**: 200+ files → Surgical (critical paths only)
+**Risk score each file:**
+- **HIGH**: Auth, crypto, external calls, value transfer, validation removal
+- **MEDIUM**: Business logic, state changes, new public APIs
+- **LOW**: Comments, tests, UI, logging
+---
+## Phase 1: Changed Code Analysis
+For each changed file:
+1. **Read both versions** (baseline and changed)
+2. **Analyze each diff region:**
+   ```
+   BEFORE: [exact code]
+   AFTER: [exact code]
+   CHANGE: [behavioral impact]
+   SECURITY: [implications]
+   ```
+3. **Git blame removed code:**
+   ```bash
+   # When was it added? Why?
+   git log -S "removed_code" --all --oneline
+   git blame <baseline> -- file.sol | grep "pattern"
+   ```
+   **Red flags:**
+   - Removed code from "fix", "security", "CVE" commits → CRITICAL
+   - Recently added (<1 month) then removed → HIGH
+4. **Check for regressions (re-added code):**
+   ```bash
+   git log -S "added_code" --all -p
+   ```
+   Pattern: Code added → removed for security → re-added now = REGRESSION
+5. **Micro-adversarial analysis** for each change:
+   - What attack did removed code prevent?
+   - What new surface does new code expose?
+   - Can modified logic be bypassed?
+   - Are checks weaker? Edge cases covered?
+6. **Generate concrete attack scenarios:**
+   ```
+   SCENARIO: [attack goal]
+   PRECONDITIONS: [required state]
+   STEPS:
+     1. [specific action]
+     2. [expected outcome]
+     3. [exploitation]
+   WHY IT WORKS: [reference code change]
+   IMPACT: [severity + scope]
+   ```
+---
+## Phase 2: Test Coverage Analysis
+**Identify coverage gaps:**
+```bash
+# Production code changes (exclude tests)
+git diff <range> --name-only | grep -v "test"
+# Test changes
+git diff <range> --name-only | grep "test"
+# For each changed function, search for tests
+grep -r "test.*functionName" test/ --include="*.sol" --include="*.js"
+```
+**Risk elevation rules:**
+- NEW function + NO tests → Elevate risk MEDIUM→HIGH
+- MODIFIED validation + UNCHANGED tests → HIGH RISK
+- Complex logic (>20 lines) + NO tests → HIGH RISK
+---
+## Phase 3: Blast Radius Analysis
+**Calculate impact:**
+```bash
+# Count callers for each modified function
+grep -r "functionName(" --include="*.sol" . | wc -l
+```
+**Classify blast radius:**
+- 1-5 calls: LOW
+- 6-20 calls: MEDIUM
+- 21-50 calls: HIGH
+- 50+ calls: CRITICAL
+**Priority matrix:**
+| Change Risk | Blast Radius | Priority | Analysis Depth |
+|-------------|--------------|----------|----------------|
+| HIGH | CRITICAL | P0 | Deep + all deps |
+| HIGH | HIGH/MEDIUM | P1 | Deep |
+| HIGH | LOW | P2 | Standard |
+| MEDIUM | CRITICAL/HIGH | P1 | Standard + callers |
+---
+## Phase 4: Deep Context Analysis
+**If `audit-context-building` skill is available**, invoke it to help answer all the questions below for each HIGH RISK changed function:
+```bash
+# Run audit-context-building on the changed function and its dependencies
+audit-context-building --scope [file containing changed function] --focus flow-analysis,call-graphs,invariants,root-cause
+```
+**The audit-context-building skill will help you answer:**
+1. **Map complete function flow:**
+   - Entry conditions (preconditions, requires, modifiers)
+   - State reads (which variables accessed)
+   - State writes (which variables modified)
+   - External calls (to contracts, APIs, system)
+   - Return values and side effects
+2. **Trace internal calls:**
+   - List all functions called
+   - Recursively map their flows
+   - Build complete call graph
+3. **Trace external calls:**
+   - Identify trust boundaries crossed
+   - List assumptions about external behavior
+   - Check for reentrancy risks
+4. **Identify invariants:**
+   - What must ALWAYS be true?
+   - What must NEVER happen?
+   - Are invariants maintained after changes?
+5. **Five Whys root cause:**
+   - WHY was this code changed?
+   - WHY did the original code exist?
+   - WHY might this break?
+   - WHY is this approach chosen?
+   - WHY could this fail in production?
+**If `audit-context-building` skill is NOT available**, manually perform the line-by-line analysis above using Read, Grep, and code tracing.
+**Cross-cutting pattern detection:**
+```bash
+# Find repeated validation patterns
+grep -r "require.*amount > 0" --include="*.sol" .
+grep -r "onlyOwner" --include="*.sol" .
+# Check if any removed in diff
+git diff <range> | grep "^-.*require.*amount > 0"
+```
+**Flag if removal breaks defense-in-depth.**
+---
+**Next steps:**
+- For HIGH RISK changes, proceed to [adversarial.md](adversarial.md)
+- For report generation, see [reporting.md](reporting.md)

package/skills/security-differential-review/skills/differential-review/patterns.md ADDED Viewed

@@ -0,0 +1,300 @@
+# Common Vulnerability Patterns
+Quick reference for detecting common security issues in code changes.
+**Specialized Pattern Resources:**
+For specific contexts, reference these additional pattern databases:
+**Domain-Specific:**
+- `domain-specific-audits/defi-bridges/resources/` - 127 bridge-specific findings
+- `domain-specific-audits/tick-math/resources/` - 81 tick math findings
+- `domain-specific-audits/merkle-trees/resources/` - 67 merkle tree findings
+- [Check `domain-specific-audits/skills/` for additional domains]
+**Solidity-Specific:**
+- `not-so-smart-contracts` - Automated Solidity vulnerability detectors
+- `token-integration-analyzer` - Token integration safety patterns
+- `building-secure-contracts/development-guidelines` - Solidity best practices
+These complement the generic patterns below.
+---
+## Security Regressions
+**Pattern:** Previously removed code is re-added
+**Detection:**
+```bash
+# Code previously removed for security
+git log -S "pattern" --all --grep="security\|fix\|CVE"
+```
+**Red flags:**
+- Commit message contains "security", "fix", "CVE", "vulnerability"
+- Code removed <6 months ago
+- No explanation in current PR for re-addition
+**Example:**
+```solidity
+// Removed in commit abc123 "Fix reentrancy CVE-2024-1234"
+// Re-added in current PR
+function emergencyWithdraw() {
+    // REGRESSION: Reentrancy vulnerability re-introduced
+}
+```
+---
+## Double Decrease/Increase Bugs
+**Pattern:** Same accounting operation twice for same event
+**Detection:** Look for two state updates in related functions for same logical action
+**Example:**
+```solidity
+// Request exit
+function requestExit() {
+    balance[user] -= amount;  // First decrease
+}
+// Process exit
+function processExit() {
+    balance[user] -= amount;  // Second decrease - BUG!
+}
+```
+**Impact:** User balance decremented twice, protocol loses funds
+---
+## Missing Validation
+**Pattern:** Removed `require`/`assert`/`check` without replacement
+**Detection:**
+```bash
+git diff <range> | grep "^-.*require"
+git diff <range> | grep "^-.*assert"
+git diff <range> | grep "^-.*revert"
+```
+**Questions to ask:**
+- Was validation moved elsewhere?
+- Is it redundant (defensive programming)?
+- Does removal expose vulnerability?
+**Example:**
+```diff
+function withdraw(uint256 amount) {
+-   require(amount > 0, "Zero amount");
+-   require(amount <= balance[msg.sender], "Insufficient");
+    balance[msg.sender] -= amount;
+}
+```
+**Risk:** Zero-amount withdrawals, underflow attacks now possible
+---
+## Underflow/Overflow
+**Pattern:** Arithmetic without SafeMath or checks
+**Detection:**
+- Look for `+`, `-`, `*`, `/` in Solidity <0.8.0
+- Check if SafeMath removed
+- Look for unchecked blocks in Solidity >=0.8.0
+**Example:**
+```solidity
+// Solidity 0.7 without SafeMath
+balance[user] -= amount;  // Can underflow if amount > balance
+// Solidity 0.8+ with unchecked
+unchecked {
+    balance[user] -= amount;  // Deliberately bypasses overflow check
+}
+```
+**Risk:** Integer wrap-around leads to incorrect balances
+---
+## Reentrancy
+**Pattern:** External call before state update
+**Detection:** Look for CEI (Checks-Effects-Interactions) pattern violations
+**Example:**
+```solidity
+// VULNERABLE: External call before state update
+function withdraw() {
+    uint amount = balances[msg.sender];
+    (bool success,) = msg.sender.call{value: amount}("");  // External call FIRST
+    require(success);
+    balances[msg.sender] = 0;  // State update AFTER
+}
+// SAFE: State update before external call
+function withdraw() {
+    uint amount = balances[msg.sender];
+    balances[msg.sender] = 0;  // State update FIRST
+    (bool success,) = msg.sender.call{value: amount}("");  // External call AFTER
+    require(success);
+}
+```
+**Impact:** Attacker can recursively call withdraw() before balance is zeroed
+---
+## Access Control Bypass
+**Pattern:** Removed or relaxed permission checks
+**Detection:**
+```bash
+git diff <range> | grep "^-.*onlyOwner"
+git diff <range> | grep "^-.*onlyAdmin"
+git diff <range> | grep "^-.*require.*msg.sender"
+```
+**Questions:**
+- Who can now call this function?
+- What's the new trust model?
+- Was check moved to caller?
+**Example:**
+```diff
+- function setConfig(uint value) external onlyOwner {
++ function setConfig(uint value) external {
+      config = value;
+  }
+```
+**Risk:** Any user can now modify critical configuration
+---
+## Race Conditions / Front-Running
+**Pattern:** State-dependent logic without protection
+**Detection:** Look for two-step processes without commit-reveal or timelocks
+**Example:**
+```solidity
+// Step 1: Approve
+function approve(address spender, uint amount) {
+    allowance[msg.sender][spender] = amount;
+}
+// Step 2: User can front-run between approval changes
+// Attacker sees tx changing approval from 100 to 50
+// Front-runs to spend 100, then spends 50 after = 150 total
+```
+**Risk:** MEV/front-running exploits state transitions
+---
+## Timestamp Manipulation
+**Pattern:** Security logic depending on `block.timestamp`
+**Detection:**
+```bash
+grep -r "block.timestamp" --include="*.sol"
+grep -r "now\b" --include="*.sol"  # Solidity <0.7
+```
+**Example:**
+```solidity
+// VULNERABLE
+require(block.timestamp > deadline, "Too early");
+// Miner can manipulate timestamp by ~15 seconds
+// SAFER
+require(block.number > deadlineBlock, "Too early");
+// Block numbers are harder to manipulate
+```
+**Risk:** Miners can manipulate timestamps within tolerance
+---
+## Unchecked Return Values
+**Pattern:** External call without checking success
+**Detection:**
+```bash
+git diff <range> | grep "\.call\|\.send\|\.transfer"
+```
+**Example:**
+```solidity
+// VULNERABLE
+token.transfer(user, amount);  // Ignores return value
+// SAFE
+require(token.transfer(user, amount), "Transfer failed");
+// Or use SafeERC20 wrapper
+```
+**Risk:** Silent failures lead to inconsistent state
+---
+## Denial of Service
+**Pattern:** Unbounded loops, external call reverts blocking execution
+**Detection:**
+- Arrays that grow without limit
+- Loops over user-controlled array
+- Critical function depends on external call success
+**Example:**
+```solidity
+// DOS: Attacker adds many users, making loop too expensive
+function distributeRewards() {
+    for (uint i = 0; i < users.length; i++) {
+        users[i].transfer(reward);  // Runs out of gas
+    }
+}
+```
+**Risk:** Function becomes unusable due to gas limits
+---
+## Quick Detection Commands
+**Find removed security checks:**
+```bash
+git diff <range> | grep "^-" | grep -E "require|assert|revert"
+```
+**Find new external calls:**
+```bash
+git diff <range> | grep "^+" | grep -E "\.call|\.delegatecall|\.staticcall"
+```
+**Find changed access modifiers:**
+```bash
+git diff <range> | grep -E "onlyOwner|onlyAdmin|internal|private|public|external"
+```
+**Find arithmetic changes:**
+```bash
+git diff <range> | grep -E "\+|\-|\*|/"
+```
+---
+**For detailed analysis workflow, see [methodology.md](methodology.md)**
+**For building exploit scenarios, see [adversarial.md](adversarial.md)**