cli-jaw 0.1.6 → 0.1.8

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

@@ -1,300 +0,0 @@
-# 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

@@ -1,369 +0,0 @@
-# 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.**