cli-jaw 0.1.0

package/skills_ref/differential-review/skills/differential-review/patterns.md

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

package/skills_ref/differential-review/skills/differential-review/reporting.md

@@ -0,0 +1,369 @@
+# Report Generation (Phase 6)
+
+Comprehensive markdown report structure and formatting guidelines.
+
+---
+
+## Report Structure
+
+Generate markdown report with these mandatory sections:
+
+### 1. Executive Summary
+
+- Severity distribution table
+- Risk assessment (CRITICAL/HIGH/MEDIUM/LOW)
+- Final recommendation (APPROVE/REJECT/CONDITIONAL)
+- Key metrics (test gaps, blast radius, red flags)
+
+**Template:**
+```markdown
+# Executive Summary
+
+| Severity | Count |
+|----------|-------|
+| 🔴 CRITICAL | X |
+| 🟠 HIGH | Y |
+| 🟡 MEDIUM | Z |
+| 🟢 LOW | W |
+
+**Overall Risk:** CRITICAL/HIGH/MEDIUM/LOW
+**Recommendation:** APPROVE/REJECT/CONDITIONAL
+
+**Key Metrics:**
+- Files analyzed: X/Y (Z%)
+- Test coverage gaps: N functions
+- High blast radius changes: M functions
+- Security regressions detected: P
+```
+
+---
+
+### 2. What Changed
+
+- Commit timeline with visual
+- File summary table
+- Lines changed stats
+
+**Template:**
+```markdown
+## What Changed
+
+**Commit Range:** `base..head`
+**Commits:** X
+**Timeline:** YYYY-MM-DD to YYYY-MM-DD
+
+| File | +Lines | -Lines | Risk | Blast Radius |
+|------|--------|--------|------|--------------|
+| file1.sol | +50 | -20 | HIGH | CRITICAL |
+| file2.sol | +10 | -5 | MEDIUM | LOW |
+
+**Total:** +N, -M lines across K files
+```
+
+---
+
+### 3. Critical Findings
+
+For each HIGH/CRITICAL issue:
+
+```markdown
+### [SEVERITY] Title
+
+**File**: path/to/file.ext:lineNumber
+**Commit**: hash
+**Blast Radius**: N callers (HIGH/MEDIUM/LOW)
+**Test Coverage**: YES/NO/PARTIAL
+
+**Description**: [clear explanation]
+
+**Historical Context**:
+- Git blame: Added in commit X (date)
+- Message: "[original commit message]"
+- [Why this code existed]
+
+**Attack Scenario**:
+[Concrete exploitation steps from adversarial.md]
+
+**Proof of Concept**:
+```code demonstrating issue```
+
+**Recommendation**:
+[Specific fix with code]
+```
+
+**Example:**
+```markdown
+### 🔴 CRITICAL: Authorization Bypass in Withdraw
+
+**File**: TokenVault.sol:156
+**Commit**: abc123def
+**Blast Radius**: 23 callers (HIGH)
+**Test Coverage**: NO
+
+**Description**:
+Removed `require(msg.sender == owner)` check allows any user to withdraw funds.
+
+**Historical Context**:
+- Git blame: Added 2024-06-15 (commit def456)
+- Message: "Add owner check per audit finding #45"
+- Code existed to prevent unauthorized withdrawals
+
+**Attack Scenario**:
+1. Attacker calls `withdraw(1000 ether)`
+2. No authorization check (removed)
+3. 1000 ETH transferred to attacker
+4. Protocol funds drained
+
+**Proof of Concept**:
+```solidity
+// As any address
+vault.withdraw(vault.balance());
+// Success - funds stolen
+```
+
+**Recommendation**:
+```solidity
+function withdraw(uint256 amount) external {
++   require(msg.sender == owner, "Unauthorized");
+    // ... rest of function
+}
+```
+```
+
+---
+
+### 4. Test Coverage Analysis
+
+- Coverage statistics
+- Untested changes list
+- Risk assessment
+
+**Template:**
+```markdown
+## Test Coverage Analysis
+
+**Coverage:** X% of changed code
+
+**Untested Changes:**
+| Function | Risk | Impact |
+|----------|------|--------|
+| functionA() | HIGH | No validation tests |
+| functionB() | MEDIUM | Logic untested |
+
+**Risk Assessment:**
+N HIGH-risk functions without tests → Recommend blocking merge
+```
+
+---
+
+### 5. Blast Radius Analysis
+
+- High-impact functions table
+- Dependency graph
+- Impact quantification
+
+**Template:**
+```markdown
+## Blast Radius Analysis
+
+**High-Impact Changes:**
+| Function | Callers | Risk | Priority |
+|----------|---------|------|----------|
+| transfer() | 89 | HIGH | P0 |
+| validate() | 45 | MEDIUM | P1 |
+```
+
+---
+
+### 6. Historical Context
+
+- Security-related removals
+- Regression risks
+- Commit message red flags
+
+**Template:**
+```markdown
+## Historical Context
+
+**Security-Related Removals:**
+- Line 45: `require` removed (added 2024-03 for CVE-2024-1234)
+- Line 78: Validation removed (added 2023-12 "security hardening")
+
+**Regression Risks:**
+- Code pattern removed in commit X, re-added in commit Y
+```
+
+---
+
+### 7. Recommendations
+
+- Immediate actions (blocking)
+- Before production (tracking)
+- Technical debt (future)
+
+**Template:**
+```markdown
+## Recommendations
+
+### Immediate (Blocking)
+- [ ] Fix CRITICAL issue in TokenVault.sol:156
+- [ ] Add tests for withdraw() function
+
+### Before Production
+- [ ] Security audit of auth changes
+- [ ] Load test blast radius functions
+
+### Technical Debt
+- [ ] Refactor validation pattern consistency
+```
+
+---
+
+### 8. Analysis Methodology
+
+- Strategy used (DEEP/FOCUSED/SURGICAL)
+- Files analyzed
+- Coverage estimate
+- Techniques applied
+- Limitations
+- Confidence level
+
+**Template:**
+```markdown
+## Analysis Methodology
+
+**Strategy:** FOCUSED (80 files, medium codebase)
+
+**Analysis Scope:**
+- Files reviewed: 45/80 (56%)
+- HIGH RISK: 100% coverage
+- MEDIUM RISK: 60% coverage
+- LOW RISK: Excluded
+
+**Techniques:**
+- Git blame on all removals
+- Blast radius calculation
+- Test coverage analysis
+- Adversarial modeling for HIGH RISK
+
+**Limitations:**
+- Did not analyze external dependencies
+- Limited to 1-hop caller analysis
+
+**Confidence:** HIGH for analyzed scope, MEDIUM overall
+```
+
+---
+
+### 9. Appendices
+
+- Commit reference table
+- Key definitions
+- Contact info
+
+---
+
+## Formatting Guidelines
+
+**Tables:** Use markdown tables for structured data
+
+**Code blocks:** Always include syntax highlighting
+```solidity
+// Solidity code
+```
+```rust
+// Rust code
+```
+
+**Status indicators:**
+- ✅ Complete
+- ⚠️ Warning
+- ❌ Failed/Blocked
+
+**Severity:**
+- 🔴 CRITICAL
+- 🟠 HIGH
+- 🟡 MEDIUM
+- 🟢 LOW
+
+**Before/After comparisons:**
+```markdown
+**BEFORE:**
+```code
+old code
+```
+
+**AFTER:**
+```code
+new code
+```
+```
+
+**Line number references:** Always include
+- Format: `file.sol:L123`
+- Link to commit: `file.sol:L123 (commit abc123)`
+
+---
+
+## File Naming and Location
+
+**Priority order for output:**
+1. Current working directory (if project repo)
+2. User's Desktop
+3. `~/.claude/skills/differential-review/output/`
+
+**Filename format:**
+```
+<PROJECT>_DIFFERENTIAL_REVIEW_<DATE>.md
+
+Example: VeChain_Stargate_DIFFERENTIAL_REVIEW_2025-12-26.md
+```
+
+---
+
+## User Notification Template
+
+After generating report:
+
+```markdown
+Report generated successfully!
+
+📄 File: [filename]
+📁 Location: [path]
+📏 Size: XX KB
+⏱️ Review Time: ~X hours
+
+Summary:
+- X findings (Y critical, Z high)
+- Final recommendation: APPROVE/REJECT/CONDITIONAL
+- Confidence: HIGH/MEDIUM/LOW
+
+Next steps:
+- Review findings in detail
+- Address CRITICAL/HIGH issues before merge
+- Consider chaining with issue-writer for stakeholder report
+```
+
+---
+
+## Integration with issue-writer
+
+After generating differential review, transform into audit report:
+
+```bash
+issue-writer --input DIFFERENTIAL_REVIEW_REPORT.md --format audit-report
+```
+
+This creates polished documentation for non-technical stakeholders.
+
+---
+
+## Error Handling
+
+If file write fails:
+1. Try Desktop location
+2. Try temp directory
+3. As last resort, output full report to chat
+4. Notify user to save manually
+
+**Always prioritize persistent artifact generation over ephemeral chat output.**