@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/fix-review/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: fix-review
+description: Verify remediation commits against security audit findings and confirm fixes without introducing regressions.
+allowed-tools:
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - Bash
+  - WebFetch
+---
+
+# Fix Review
+
+Differential analysis to verify commits address security findings without introducing bugs.
+
+## When to Use
+
+- Reviewing fix branches against security audit reports
+- Validating that remediation commits actually address findings
+- Checking if specific findings (TOB-XXX format) have been fixed
+- Analyzing commit ranges for bug introduction patterns
+- Cross-referencing code changes with audit recommendations
+
+## When NOT to Use
+
+- Initial security audits (use audit-context-building or differential-review)
+- Code review without a specific baseline or finding set
+- Greenfield development with no prior audit
+- Documentation-only changes
+
+---
+
+## Rationalizations (Do Not Skip)
+
+| Rationalization | Why It's Wrong | Required Action |
+|-----------------|----------------|-----------------|
+| "The commit message says it fixes TOB-XXX" | Messages lie; code tells truth | Verify the actual code change addresses the finding |
+| "Small fix, no new bugs possible" | Small changes cause big bugs | Analyze all changes for anti-patterns |
+| "I'll check the important findings" | All findings matter | Systematically check every finding |
+| "The tests pass" | Tests may not cover the fix | Verify fix logic, not just test status |
+| "Same developer, they know the code" | Familiarity breeds blind spots | Fresh analysis of every change |
+
+---
+
+## Quick Reference
+
+### Input Requirements
+
+| Input | Required | Format |
+|-------|----------|--------|
+| Source commit | Yes | Git commit hash or ref (baseline before fixes) |
+| Target commit(s) | Yes | One or more commit hashes to analyze |
+| Security report | No | Local path, URL, or Google Drive link |
+
+### Finding Status Values
+
+| Status | Meaning |
+|--------|---------|
+| FIXED | Code change directly addresses the finding |
+| PARTIALLY_FIXED | Some aspects addressed, others remain |
+| NOT_ADDRESSED | No relevant changes found |
+| CANNOT_DETERMINE | Insufficient context to verify |
+
+---
+
+## Workflow
+
+### Phase 1: Input Gathering
+
+Collect required inputs from user:
+
+```
+Source commit:  [hash/ref before fixes]
+Target commit:  [hash/ref to analyze]
+Report:         [optional: path, URL, or "none"]
+```
+
+If user provides multiple target commits, process each separately with the same source.
+
+### Phase 2: Report Retrieval
+
+When a security report is provided, retrieve it based on format:
+
+**Local file (PDF, MD, JSON, HTML):**
+Read the file directly using the Read tool. Claude processes PDFs natively.
+
+**URL:**
+Fetch web content using the WebFetch tool.
+
+**Google Drive URL that fails:**
+See `references/report-parsing.md` for Google Drive fallback logic using `gdrive` CLI.
+
+### Phase 3: Finding Extraction
+
+Parse the report to extract findings:
+
+**Trail of Bits format:**
+- Look for "Detailed Findings" section
+- Extract findings matching pattern: `TOB-[A-Z]+-[0-9]+`
+- Capture: ID, title, severity, description, affected files
+
+**Other formats:**
+- Numbered findings (Finding 1, Finding 2)
+- Severity-based sections (Critical, High, Medium, Low)
+- JSON with `findings` array
+
+See `references/report-parsing.md` for detailed parsing strategies.
+
+### Phase 4: Commit Analysis
+
+For each target commit, analyze the commit range:
+
+```bash
+# Get commit list from source to target
+git log <source>..<target> --oneline
+
+# Get full diff
+git diff <source>..<target>
+
+# Get changed files
+git diff <source>..<target> --name-only
+```
+
+For each commit in the range:
+1. Examine the diff for bug introduction patterns
+2. Check for security anti-patterns (see `references/bug-detection.md`)
+3. Map changes to relevant findings
+
+### Phase 5: Finding Verification
+
+For each finding in the report:
+
+1. **Identify relevant commits** - Match by:
+   - File paths mentioned in finding
+   - Function/variable names in finding description
+   - Commit messages referencing the finding ID
+
+2. **Verify the fix** - Check that:
+   - The root cause is addressed (not just symptoms)
+   - The fix follows the report's recommendation
+   - No new vulnerabilities are introduced
+
+3. **Assign status** - Based on evidence:
+   - FIXED: Clear code change addresses the finding
+   - PARTIALLY_FIXED: Some aspects fixed, others remain
+   - NOT_ADDRESSED: No relevant changes
+   - CANNOT_DETERMINE: Need more context
+
+4. **Document evidence** - For each finding:
+   - Commit hash(es) that address it
+   - Specific file and line changes
+   - How the fix addresses the root cause
+
+See `references/finding-matching.md` for detailed matching strategies.
+
+### Phase 6: Output Generation
+
+Generate two outputs:
+
+**1. Report file (`FIX_REVIEW_REPORT.md`):**
+
+```markdown
+# Fix Review Report
+
+**Source:** <commit>
+**Target:** <commit>
+**Report:** <path or "none">
+**Date:** <date>
+
+## Executive Summary
+
+[Brief overview: X findings reviewed, Y fixed, Z concerns]
+
+## Finding Status
+
+| ID | Title | Severity | Status | Evidence |
+|----|-------|----------|--------|----------|
+| TOB-XXX-1 | Finding title | High | FIXED | abc123 |
+| TOB-XXX-2 | Another finding | Medium | NOT_ADDRESSED | - |
+
+## Bug Introduction Concerns
+
+[Any potential bugs or regressions detected in the changes]
+
+## Per-Commit Analysis
+
+### Commit abc123: "Fix reentrancy in withdraw()"
+
+**Files changed:** contracts/Vault.sol
+**Findings addressed:** TOB-XXX-1
+**Concerns:** None
+
+[Detailed analysis]
+
+## Recommendations
+
+[Any follow-up actions needed]
+```
+
+**2. Conversation summary:**
+
+Provide a concise summary in the conversation:
+- Total findings: X
+- Fixed: Y
+- Not addressed: Z
+- Concerns: [list any bug introduction risks]
+
+---
+
+## Bug Detection
+
+Analyze commits for security anti-patterns. Key patterns to watch:
+- Access control weakening (modifiers removed)
+- Validation removal (require/assert deleted)
+- Error handling reduction (try/catch removed)
+- External call reordering (state after call)
+- Integer operation changes (SafeMath removed)
+- Cryptographic weakening
+
+See `references/bug-detection.md` for comprehensive detection patterns and examples.
+
+---
+
+## Integration with Other Skills
+
+**differential-review:** For initial security review of changes (before audit)
+
+**issue-writer:** To format findings into formal audit reports
+
+**audit-context-building:** For deep context when analyzing complex fixes
+
+---
+
+## Tips for Effective Reviews
+
+**Do:**
+- Verify the actual code change, not just commit messages
+- Check that fixes address root causes, not symptoms
+- Look for unintended side effects in adjacent code
+- Cross-reference multiple findings that may interact
+- Document evidence for every status assignment
+
+**Don't:**
+- Trust commit messages as proof of fix
+- Skip findings because they seem minor
+- Assume passing tests mean correct fixes
+- Ignore changes outside the "fix" scope
+- Mark FIXED without clear evidence
+
+---
+
+## Reference Files
+
+For detailed guidance, consult:
+
+- **`references/finding-matching.md`** - Strategies for matching commits to findings
+- **`references/bug-detection.md`** - Comprehensive anti-pattern detection
+- **`references/report-parsing.md`** - Parsing different report formats, Google Drive fallback

package/Ai Agent Workflow/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]
+```