@elizaos/skills 2.0.0-alpha.3

package/skills/security-fix-review/skills/fix-review/references/bug-detection.md

@@ -0,0 +1,408 @@
+# Bug Detection Patterns
+
+Anti-patterns to detect when analyzing commits for bug introduction.
+
+## Overview
+
+When reviewing fix commits, look for changes that may introduce new bugs or security vulnerabilities. These patterns represent common ways that "fixes" can make things worse.
+
+---
+
+## Security Anti-Patterns
+
+### Access Control Weakening
+
+**Pattern:** Removal or weakening of access restrictions
+
+**Detection:**
+```bash
+# Search for removed access modifiers
+git diff <source>..<target> | grep "^-" | grep -E "(onlyOwner|onlyAdmin|require\(msg\.sender|auth|access)"
+
+# Search for visibility changes
+git diff <source>..<target> | grep -E "^[-+].*(public|external|internal|private)"
+```
+
+**Examples:**
+```diff
+- function withdraw() external onlyOwner {
++ function withdraw() external {
+```
+
+```diff
+- require(msg.sender == owner, "Not owner");
++ // Removed for gas optimization
+```
+
+**Risk:** Privilege escalation, unauthorized access
+
+---
+
+### Validation Removal
+
+**Pattern:** Removal of input validation or precondition checks
+
+**Detection:**
+```bash
+# Search for removed require/assert statements
+git diff <source>..<target> | grep "^-" | grep -E "(require|assert|revert|throw)"
+
+# Search for removed if-checks
+git diff <source>..<target> | grep "^-" | grep -E "if\s*\("
+```
+
+**Examples:**
+```diff
+- require(amount > 0, "Zero amount");
+- require(amount <= balance, "Insufficient balance");
+  balance -= amount;
+```
+
+```diff
+- if (input == null) throw new IllegalArgumentException();
+  process(input);
+```
+
+**Risk:** Input bypass, unexpected states, crashes
+
+---
+
+### Error Handling Reduction
+
+**Pattern:** Removal or weakening of error handling
+
+**Detection:**
+```bash
+# Search for removed try/catch
+git diff <source>..<target> | grep "^-" | grep -E "(try|catch|except|finally)"
+
+# Search for removed error checks
+git diff <source>..<target> | grep "^-" | grep -E "(error|Error|err|Err)"
+```
+
+**Examples:**
+```diff
+- try {
+    result = riskyOperation();
+- } catch (Exception e) {
+-   logger.error("Operation failed", e);
+-   return fallbackValue;
+- }
++ result = riskyOperation();
+```
+
+**Risk:** Silent failures, unhandled exceptions, crashes
+
+---
+
+### External Call Reordering
+
+**Pattern:** State updates moved after external calls (reentrancy risk)
+
+**Detection:**
+```bash
+# Search for external calls followed by state changes
+git diff <source>..<target> | grep -A10 "\.call\|\.transfer\|\.send"
+```
+
+**Examples:**
+```diff
+- balance[msg.sender] = 0;
+- (bool success,) = msg.sender.call{value: amount}("");
++ (bool success,) = msg.sender.call{value: amount}("");
++ balance[msg.sender] = 0;  // State change after external call!
+```
+
+**Risk:** Reentrancy attacks
+
+---
+
+### Integer Operation Changes
+
+**Pattern:** Removal of overflow/underflow protection
+
+**Detection:**
+```bash
+# Search for SafeMath removal
+git diff <source>..<target> | grep "^-" | grep -E "(SafeMath|safeAdd|safeSub|safeMul|safeDiv)"
+
+# Search for unchecked blocks
+git diff <source>..<target> | grep -E "unchecked\s*\{"
+```
+
+**Examples:**
+```diff
+- using SafeMath for uint256;
+- balance = balance.sub(amount);
++ balance = balance - amount;  // No overflow protection
+```
+
+```diff
+- total = total + amount;  // Solidity 0.8 has built-in checks
++ unchecked {
++   total = total + amount;  // Disabled overflow check
++ }
+```
+
+**Risk:** Integer overflow/underflow
+
+---
+
+### Cryptographic Weakening
+
+**Pattern:** Changes to cryptographic operations that reduce security
+
+**Detection:**
+```bash
+# Search for crypto-related changes
+git diff <source>..<target> | grep -E "(hash|Hash|encrypt|decrypt|sign|verify|random|nonce|salt|key|Key)"
+
+# Search for algorithm names
+git diff <source>..<target> | grep -E "(SHA|MD5|AES|RSA|ECDSA|keccak)"
+```
+
+**Examples:**
+```diff
+- bytes32 hash = keccak256(abi.encodePacked(nonce, data));
++ bytes32 hash = keccak256(abi.encodePacked(data));  // Removed nonce!
+```
+
+```diff
+- return crypto.createHash('sha256').update(data).digest();
++ return crypto.createHash('md5').update(data).digest();  // Weak hash!
+```
+
+**Risk:** Hash collisions, signature bypass, predictability
+
+---
+
+### Memory Safety Issues
+
+**Pattern:** Changes that introduce memory safety bugs
+
+**Detection:**
+```bash
+# Search for buffer/array operations
+git diff <source>..<target> | grep -E "(malloc|free|memcpy|strcpy|buffer|array\[)"
+
+# Search for bounds checks
+git diff <source>..<target> | grep "^-" | grep -E "(length|size|bounds|index)"
+```
+
+**Examples:**
+```diff
+- if (index < array.length) {
+    return array[index];
+- }
+```
+
+```diff
+- strncpy(dest, src, sizeof(dest) - 1);
++ strcpy(dest, src);  // No bounds check!
+```
+
+**Risk:** Buffer overflow, use-after-free, out-of-bounds access
+
+---
+
+### Concurrency Issues
+
+**Pattern:** Removal of synchronization or race condition introduction
+
+**Detection:**
+```bash
+# Search for lock/synchronization changes
+git diff <source>..<target> | grep -E "(lock|Lock|mutex|synchronized|atomic|volatile)"
+
+# Search for removed synchronization
+git diff <source>..<target> | grep "^-" | grep -E "(lock|synchronized)"
+```
+
+**Examples:**
+```diff
+- synchronized (this) {
+    counter++;
+- }
++ counter++;  // No synchronization!
+```
+
+**Risk:** Race conditions, data corruption
+
+---
+
+## General Bug Patterns
+
+### Logic Inversion
+
+**Pattern:** Boolean logic changed incorrectly
+
+**Detection:**
+```bash
+# Search for condition changes
+git diff <source>..<target> | grep -E "^[-+].*if\s*\(|^[-+].*\?|^[-+].*&&|^[-+].*\|\|"
+```
+
+**Examples:**
+```diff
+- if (isValid) {
++ if (!isValid) {
+    process();
+  }
+```
+
+```diff
+- return a && b;
++ return a || b;
+```
+
+---
+
+### Off-by-One Errors
+
+**Pattern:** Boundary conditions changed incorrectly
+
+**Detection:**
+```bash
+# Search for comparison operators
+git diff <source>..<target> | grep -E "^[-+].*(<=|>=|<|>|==)"
+```
+
+**Examples:**
+```diff
+- for (i = 0; i < length; i++)
++ for (i = 0; i <= length; i++)  // Off-by-one!
+```
+
+```diff
+- if (index < array.length)
++ if (index <= array.length)  // Off-by-one!
+```
+
+---
+
+### Null/Undefined Handling
+
+**Pattern:** Removal of null checks
+
+**Detection:**
+```bash
+# Search for null checks
+git diff <source>..<target> | grep "^-" | grep -E "(null|NULL|nil|None|undefined)"
+```
+
+**Examples:**
+```diff
+- if (obj == null) return defaultValue;
+  return obj.getValue();  // Potential NPE
+```
+
+---
+
+### Resource Leaks
+
+**Pattern:** Removal of cleanup code
+
+**Detection:**
+```bash
+# Search for resource management
+git diff <source>..<target> | grep "^-" | grep -E "(close|Close|dispose|Dispose|free|Free|release|Release)"
+```
+
+**Examples:**
+```diff
+  file = open(path)
+- try:
+    data = file.read()
+- finally:
+-   file.close()
+```
+
+---
+
+## Analysis Workflow
+
+### Step 1: Get the Diff
+
+```bash
+git diff <source>..<target> > changes.diff
+```
+
+### Step 2: Scan for Anti-Patterns
+
+Run detection commands for each pattern category:
+
+```bash
+# Security patterns
+grep "^-" changes.diff | grep -E "(require|assert|onlyOwner|auth)"
+grep "^-" changes.diff | grep -E "(try|catch|except)"
+
+# Logic patterns
+grep -E "^[-+].*if\s*\(" changes.diff
+grep -E "^[-+].*(<=|>=|<|>)" changes.diff
+```
+
+### Step 3: Manual Review
+
+For each detected pattern:
+1. Read the surrounding context
+2. Understand the intent of the change
+3. Determine if the pattern indicates a bug
+4. Document findings
+
+### Step 4: Rate Severity
+
+| Severity | Criteria |
+|----------|----------|
+| Critical | Exploitable security vulnerability |
+| High | Security regression or data loss risk |
+| Medium | Logic error with limited impact |
+| Low | Code smell, minor issue |
+| Info | Observation, no immediate risk |
+
+---
+
+## False Positive Handling
+
+Not every detected pattern is a bug. Consider:
+
+**Intentional changes:**
+- Removing redundant validation
+- Simplifying error handling
+- Refactoring for clarity
+
+**Context matters:**
+- Is the removed check truly necessary?
+- Is there equivalent protection elsewhere?
+- Does the surrounding code handle the case?
+
+**Verify with:**
+1. Read the full commit context
+2. Check commit message for explanation
+3. Look for replacement logic
+4. Consider the broader codebase
+
+---
+
+## Reporting Format
+
+For each detected concern:
+
+```markdown
+### Bug Introduction Concern
+
+**Pattern:** [Pattern name]
+**Commit:** [hash]
+**File:** [path:line]
+**Severity:** [Critical/High/Medium/Low/Info]
+
+**Change:**
+```diff
+[relevant diff snippet]
+```
+
+**Analysis:**
+[Explanation of why this is concerning]
+
+**Recommendation:**
+[Suggested action]
+```

package/skills/security-fix-review/skills/fix-review/references/finding-matching.md

@@ -0,0 +1,298 @@
+# Finding Matching Strategies
+
+Techniques for matching security findings to code commits.
+
+## Overview
+
+Matching findings to commits requires multiple approaches since:
+- Commit messages may not reference finding IDs
+- Findings may span multiple files
+- Multiple commits may partially address a single finding
+- A single commit may address multiple findings
+
+---
+
+## Matching Approaches
+
+### 1. Direct ID Reference
+
+Search commit messages for finding IDs:
+
+```bash
+# Search for TOB-style IDs in commit messages
+git log <source>..<target> --grep="TOB-" --oneline
+
+# Search for generic finding references
+git log <source>..<target> --grep="[Ff]inding" --oneline
+git log <source>..<target> --grep="[Ff]ix" --oneline
+```
+
+**Confidence:** High when found, but many commits lack explicit references.
+
+### 2. File Path Matching
+
+Match findings by affected files:
+
+```bash
+# Get files changed in commit range
+git diff <source>..<target> --name-only
+
+# Compare with files mentioned in finding
+# Finding: "The vulnerability exists in contracts/Vault.sol"
+# Check: Does any commit modify contracts/Vault.sol?
+```
+
+**Workflow:**
+1. Extract file paths from finding description
+2. List changed files in commit range
+3. Identify commits touching those files
+4. Analyze those commits in detail
+
+### 3. Function/Symbol Matching
+
+Match by function or variable names:
+
+```bash
+# Search for function name in diffs
+git log <source>..<target> -p | grep -A5 -B5 "function withdraw"
+
+# Search for specific patterns
+git log <source>..<target> -S "functionName" --oneline
+```
+
+**Extract symbols from findings:**
+- Function names: `withdraw()`, `transfer()`, `validateInput()`
+- Variable names: `balance`, `owner`, `allowance`
+- Contract/class names: `Vault`, `TokenManager`
+
+### 4. Code Pattern Matching
+
+Match by vulnerability pattern:
+
+```bash
+# Finding mentions "missing require statement"
+# Search for added require statements
+git diff <source>..<target> | grep "^+" | grep "require"
+
+# Finding mentions "reentrancy"
+# Search for state changes and external calls
+git diff <source>..<target> | grep -E "(\.call|\.transfer|\.send)"
+```
+
+---
+
+## Matching Workflow
+
+### Step 1: Extract Finding Metadata
+
+For each finding, extract:
+
+| Field | Example |
+|-------|---------|
+| ID | TOB-CLIENT-1 |
+| Title | Missing access control in withdraw() |
+| Severity | High |
+| Files | contracts/Vault.sol:L45-L67 |
+| Functions | withdraw(), _validateCaller() |
+| Pattern | Access control |
+| Recommendation | Add onlyOwner modifier |
+
+### Step 2: Search for Direct Matches
+
+```bash
+# Check for ID in commit messages
+git log <source>..<target> --grep="TOB-CLIENT-1" --oneline
+
+# Check for title keywords
+git log <source>..<target> --grep="access control" --oneline
+git log <source>..<target> --grep="withdraw" --oneline
+```
+
+### Step 3: Identify Relevant Commits
+
+For each file mentioned in the finding:
+
+```bash
+# Get commits that modified the file
+git log <source>..<target> --oneline -- contracts/Vault.sol
+
+# Get the diff for that file
+git diff <source>..<target> -- contracts/Vault.sol
+```
+
+### Step 4: Analyze Fix Quality
+
+For each potentially matching commit:
+
+1. **Read the full diff** - Understand what changed
+2. **Compare with recommendation** - Does the fix follow the suggested approach?
+3. **Check completeness** - Are all instances of the vulnerability fixed?
+4. **Verify correctness** - Is the fix itself correct (no logic errors)?
+
+---
+
+## Status Assignment Criteria
+
+### FIXED
+
+Assign when:
+- Code change directly addresses the root cause
+- Fix follows the report's recommendation (or equivalent)
+- All instances of the vulnerability are addressed
+- No obvious issues with the fix itself
+
+**Evidence required:**
+- Commit hash
+- File and line numbers
+- Brief explanation of how fix addresses the finding
+
+### PARTIALLY_FIXED
+
+Assign when:
+- Some instances fixed, others remain
+- Fix addresses symptoms but not root cause
+- Fix is incomplete (missing edge cases)
+- Fix works but doesn't follow best practice
+
+**Evidence required:**
+- What was fixed (with commit hash)
+- What remains unfixed
+- Specific gaps in the fix
+
+### NOT_ADDRESSED
+
+Assign when:
+- No commits modify relevant files
+- Changes to relevant files don't address the finding
+- Finding relates to architecture/design not changed
+
+**Evidence required:**
+- Confirmation that relevant files were checked
+- Brief explanation of why no fix was found
+
+### CANNOT_DETERMINE
+
+Assign when:
+- Finding is ambiguous
+- Code changes are unclear
+- Requires runtime analysis to verify
+- Need additional context from developers
+
+**Evidence required:**
+- What was analyzed
+- Specific questions that need answers
+- Suggested next steps
+
+---
+
+## Complex Scenarios
+
+### Multiple Commits for One Finding
+
+When several commits contribute to fixing a single finding:
+
+1. List all relevant commits
+2. Analyze each contribution
+3. Determine if combined effect is FIXED or PARTIALLY_FIXED
+4. Document each commit's contribution
+
+**Example:**
+```
+TOB-XXX-1: Access control vulnerability in withdraw()
+
+Commits:
+- abc123: Added onlyOwner modifier
+- def456: Added balance check
+- ghi789: Added event emission
+
+Combined: FIXED
+- abc123 addresses the core access control issue
+- def456 adds defense in depth
+- ghi789 improves auditability
+```
+
+### One Commit for Multiple Findings
+
+When a single commit addresses multiple findings:
+
+1. Analyze the commit once
+2. Map specific changes to each finding
+3. Assign status to each finding individually
+4. Reference the same commit in multiple findings
+
+### Interacting Findings
+
+When findings are related and fixes may interact:
+
+1. Identify the relationship
+2. Analyze fixes together
+3. Check for conflicts or regressions
+4. Document the interaction
+
+**Example:**
+```
+TOB-XXX-1: Reentrancy in withdraw()
+TOB-XXX-2: Missing balance validation
+
+These interact: A reentrancy fix might break the balance check
+Analysis: Commit abc123 uses checks-effects-interactions pattern
+Result: Both findings addressed without conflict
+```
+
+---
+
+## Handling Ambiguity
+
+### When Finding Description is Vague
+
+1. Search for related patterns in the codebase
+2. Look for commit messages mentioning the issue
+3. Check if any changes seem security-related
+4. Mark as CANNOT_DETERMINE if unclear
+
+### When Multiple Interpretations Exist
+
+1. Document both interpretations
+2. Analyze against both
+3. Note which interpretation the fix addresses
+4. Flag for developer clarification if needed
+
+### When Fix Differs from Recommendation
+
+The fix may be valid even if different from the recommendation:
+
+1. Understand the recommended approach
+2. Analyze the actual fix
+3. Determine if it addresses the root cause
+4. Mark as FIXED if effective, note the difference
+
+---
+
+## Git Commands Reference
+
+```bash
+# List commits in range
+git log <source>..<target> --oneline
+
+# Search commit messages
+git log <source>..<target> --grep="pattern" --oneline
+
+# Get files changed
+git diff <source>..<target> --name-only
+
+# Get full diff
+git diff <source>..<target>
+
+# Get diff for specific file
+git diff <source>..<target> -- path/to/file
+
+# Search for code changes
+git log <source>..<target> -S "code_pattern" --oneline
+
+# Get commit details
+git show <commit> --stat
+git show <commit> -p
+
+# Blame specific lines
+git blame <commit> -- path/to/file
+```