cli-jaw 0.1.6 → 0.1.8

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

@@ -1,220 +0,0 @@
----
-name: differential-review
-description: >
-  Performs security-focused differential review of code changes (PRs, commits, diffs).
-  Adapts analysis depth to codebase size, uses git history for context, calculates
-  blast radius, checks test coverage, and generates comprehensive markdown reports.
-  Automatically detects and prevents security regressions.
-allowed-tools:
-  - Read
-  - Write
-  - Grep
-  - Glob
-  - Bash
----
-
-# Differential Security Review
-
-Security-focused code review for PRs, commits, and diffs.
-
-## Core Principles
-
-1. **Risk-First**: Focus on auth, crypto, value transfer, external calls
-2. **Evidence-Based**: Every finding backed by git history, line numbers, attack scenarios
-3. **Adaptive**: Scale to codebase size (SMALL/MEDIUM/LARGE)
-4. **Honest**: Explicitly state coverage limits and confidence level
-5. **Output-Driven**: Always generate comprehensive markdown report file
-
----
-
-## Rationalizations (Do Not Skip)
-
-| Rationalization | Why It's Wrong | Required Action |
-|-----------------|----------------|-----------------|
-| "Small PR, quick review" | Heartbleed was 2 lines | Classify by RISK, not size |
-| "I know this codebase" | Familiarity breeds blind spots | Build explicit baseline context |
-| "Git history takes too long" | History reveals regressions | Never skip Phase 1 |
-| "Blast radius is obvious" | You'll miss transitive callers | Calculate quantitatively |
-| "No tests = not my problem" | Missing tests = elevated risk rating | Flag in report, elevate severity |
-| "Just a refactor, no security impact" | Refactors break invariants | Analyze as HIGH until proven LOW |
-| "I'll explain verbally" | No artifact = findings lost | Always write report |
-
----
-
-## Quick Reference
-
-### Codebase Size Strategy
-
-| Codebase Size | Strategy | Approach |
-|---------------|----------|----------|
-| SMALL (<20 files) | DEEP | Read all deps, full git blame |
-| MEDIUM (20-200) | FOCUSED | 1-hop deps, priority files |
-| LARGE (200+) | SURGICAL | Critical paths only |
-
-### Risk Level Triggers
-
-| Risk Level | Triggers |
-|------------|----------|
-| HIGH | Auth, crypto, external calls, value transfer, validation removal |
-| MEDIUM | Business logic, state changes, new public APIs |
-| LOW | Comments, tests, UI, logging |
-
----
-
-## Workflow Overview
-
-```
-Pre-Analysis → Phase 0: Triage → Phase 1: Code Analysis → Phase 2: Test Coverage
-    ↓              ↓                    ↓                        ↓
-Phase 3: Blast Radius → Phase 4: Deep Context → Phase 5: Adversarial → Phase 6: Report
-```
-
----
-
-## Decision Tree
-
-**Starting a review?**
-
-```
-├─ Need detailed phase-by-phase methodology?
-│  └─ Read: methodology.md
-│     (Pre-Analysis + Phases 0-4: triage, code analysis, test coverage, blast radius)
-│
-├─ Analyzing HIGH RISK change?
-│  └─ Read: adversarial.md
-│     (Phase 5: Attacker modeling, exploit scenarios, exploitability rating)
-│
-├─ Writing the final report?
-│  └─ Read: reporting.md
-│     (Phase 6: Report structure, templates, formatting guidelines)
-│
-├─ Looking for specific vulnerability patterns?
-│  └─ Read: patterns.md
-│     (Regressions, reentrancy, access control, overflow, etc.)
-│
-└─ Quick triage only?
-   └─ Use Quick Reference above, skip detailed docs
-```
-
----
-
-## Quality Checklist
-
-Before delivering:
-
-- [ ] All changed files analyzed
-- [ ] Git blame on removed security code
-- [ ] Blast radius calculated for HIGH risk
-- [ ] Attack scenarios are concrete (not generic)
-- [ ] Findings reference specific line numbers + commits
-- [ ] Report file generated
-- [ ] User notified with summary
-
----
-
-## Integration
-
-**audit-context-building skill:**
-- Pre-Analysis: Build baseline context
-- Phase 4: Deep context on HIGH RISK changes
-
-**issue-writer skill:**
-- Transform findings into formal audit reports
-- Command: `issue-writer --input DIFFERENTIAL_REVIEW_REPORT.md --format audit-report`
-
----
-
-## Example Usage
-
-### Quick Triage (Small PR)
-```
-Input: 5 file PR, 2 HIGH RISK files
-Strategy: Use Quick Reference
-1. Classify risk level per file (2 HIGH, 3 LOW)
-2. Focus on 2 HIGH files only
-3. Git blame removed code
-4. Generate minimal report
-Time: ~30 minutes
-```
-
-### Standard Review (Medium Codebase)
-```
-Input: 80 files, 12 HIGH RISK changes
-Strategy: FOCUSED (see methodology.md)
-1. Full workflow on HIGH RISK files
-2. Surface scan on MEDIUM
-3. Skip LOW risk files
-4. Complete report with all sections
-Time: ~3-4 hours
-```
-
-### Deep Audit (Large, Critical Change)
-```
-Input: 450 files, auth system rewrite
-Strategy: SURGICAL + audit-context-building
-1. Baseline context with audit-context-building
-2. Deep analysis on auth changes only
-3. Blast radius analysis
-4. Adversarial modeling
-5. Comprehensive report
-Time: ~6-8 hours
-```
-
----
-
-## When NOT to Use This Skill
-
-- **Greenfield code** (no baseline to compare)
-- **Documentation-only changes** (no security impact)
-- **Formatting/linting** (cosmetic changes)
-- **User explicitly requests quick summary only** (they accept risk)
-
-For these cases, use standard code review instead.
-
----
-
-## Red Flags (Stop and Investigate)
-
-**Immediate escalation triggers:**
-- Removed code from "security", "CVE", or "fix" commits
-- Access control modifiers removed (onlyOwner, internal → external)
-- Validation removed without replacement
-- External calls added without checks
-- High blast radius (50+ callers) + HIGH risk change
-
-These patterns require adversarial analysis even in quick triage.
-
----
-
-## Tips for Best Results
-
-**Do:**
-- Start with git blame for removed code
-- Calculate blast radius early to prioritize
-- Generate concrete attack scenarios
-- Reference specific line numbers and commits
-- Be honest about coverage limitations
-- Always generate the output file
-
-**Don't:**
-- Skip git history analysis
-- Make generic findings without evidence
-- Claim full analysis when time-limited
-- Forget to check test coverage
-- Miss high blast radius changes
-- Output report only to chat (file required)
-
----
-
-## Supporting Documentation
-
-- **[methodology.md](methodology.md)** - Detailed phase-by-phase workflow (Phases 0-4)
-- **[adversarial.md](adversarial.md)** - Attacker modeling and exploit scenarios (Phase 5)
-- **[reporting.md](reporting.md)** - Report structure and formatting (Phase 6)
-- **[patterns.md](patterns.md)** - Common vulnerability patterns reference
-
----
-
-**For first-time users:** Start with [methodology.md](methodology.md) to understand the complete workflow.
-
-**For experienced users:** Use this page's Quick Reference and Decision Tree to navigate directly to needed content.

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

@@ -1,203 +0,0 @@
-# Adversarial Vulnerability Analysis (Phase 5)
-
-Structured methodology for finding vulnerabilities through attacker modeling.
-
-**When to use:** After completing deep context analysis (Phase 4), apply this to all HIGH RISK changes.
-
----
-
-## 1. Define Specific Attacker Model
-
-**WHO is the attacker?**
-- Unauthenticated external user
-- Authenticated regular user
-- Malicious administrator
-- Compromised contract/service
-- Front-runner/MEV bot
-
-**WHAT access/privileges do they have?**
-- Public API access only
-- Authenticated user role
-- Specific permissions/tokens
-- Contract call capabilities
-
-**WHERE do they interact with the system?**
-- Specific HTTP endpoints
-- Smart contract functions
-- RPC interfaces
-- External APIs
-
----
-
-## 2. Identify Concrete Attack Vectors
-
-```
-ENTRY POINT: [Exact function/endpoint attacker can access]
-
-ATTACK SEQUENCE:
-1. [Specific API call/transaction with parameters]
-2. [How this reaches the vulnerable code]
-3. [What happens in the vulnerable code]
-4. [Impact achieved]
-
-PROOF OF ACCESSIBILITY:
-- Show the function is public/external
-- Demonstrate attacker has required permissions
-- Prove attack path exists through actual interfaces
-```
-
----
-
-## 3. Rate Realistic Exploitability
-
-**EASY:** Exploitable via public APIs with no special privileges
-- Single transaction/call
-- Common user access level
-- No complex conditions required
-
-**MEDIUM:** Requires specific conditions or elevated privileges
-- Multiple steps or timing requirements
-- Elevated but obtainable privileges
-- Specific system state needed
-
-**HARD:** Requires privileged access or rare conditions
-- Admin/owner privileges needed
-- Rare edge case conditions
-- Significant resources required
-
----
-
-## 4. Build Complete Exploit Scenario
-
-```
-ATTACKER STARTING POSITION:
-[What the attacker has at the beginning]
-
-STEP-BY-STEP EXPLOITATION:
-Step 1: [Concrete action through accessible interface]
-  - Command: [Exact call/request]
-  - Parameters: [Specific values]
-  - Expected result: [What happens]
-
-Step 2: [Next action]
-  - Command: [Exact call/request]
-  - Why this works: [Reference to code change]
-  - System state change: [What changed]
-
-Step 3: [Final impact]
-  - Result: [Concrete harm achieved]
-  - Evidence: [How to verify impact]
-
-CONCRETE IMPACT:
-[Specific, measurable impact - not "could cause issues"]
-- Exact amount of funds drained
-- Specific privileges escalated
-- Particular data exposed
-```
-
----
-
-## 5. Cross-Reference with Baseline Context
-
-From baseline analysis (see [methodology.md](methodology.md#pre-analysis-baseline-context-building)), check:
-- Does this violate a system-wide invariant?
-- Does this break a trust boundary?
-- Does this bypass a validation pattern?
-- Is this a regression of a previous fix?
-
----
-
-## Vulnerability Report Template
-
-Generate this for each finding:
-
-```markdown
-## [SEVERITY] Vulnerability Title
-
-**Attacker Model:**
-- WHO: [Specific attacker type]
-- ACCESS: [Exact privileges]
-- INTERFACE: [Specific entry point]
-
-**Attack Vector:**
-[Step-by-step exploit through accessible interfaces]
-
-**Exploitability:** EASY/MEDIUM/HARD
-**Justification:** [Why this rating]
-
-**Concrete Impact:**
-[Specific, measurable harm - not theoretical]
-
-**Proof of Concept:**
-```code
-// Exact code to reproduce
-```
-
-**Root Cause:**
-[Reference specific code change at file.sol:L123]
-
-**Blast Radius:** [N callers affected]
-**Baseline Violation:** [Which invariant/pattern broken]
-```
-
----
-
-## Example: Complete Adversarial Analysis
-
-**Change:** Removed `require(amount > 0)` check from `withdraw()` function
-
-### 1. Attacker Model
-- **WHO:** Unauthenticated external user
-- **ACCESS:** Can call public contract functions
-- **INTERFACE:** `withdraw(uint256 amount)` at 0x1234...
-
-### 2. Attack Vector
-**ENTRY POINT:** `withdraw(0)`
-
-**ATTACK SEQUENCE:**
-1. Call `withdraw(0)` from attacker address
-2. Code bypasses amount check (removed)
-3. Withdraw event emitted with 0 amount
-4. Accounting updated incorrectly
-
-**PROOF:** Function is `external`, no auth required
-
-### 3. Exploitability
-**RATING:** EASY
-- Single transaction
-- Public function
-- No special state required
-
-### 4. Exploit Scenario
-**ATTACKER POSITION:** Has user account with 0 balance
-
-**EXPLOITATION:**
-```solidity
-Step 1: attacker.withdraw(0)
-  - Passes removed validation
-  - Emits Withdraw(user, 0)
-  - Updates withdrawnAmount[user] += 0
-
-Step 2: Off-chain indexer sees Withdraw event
-  - Credits attacker for 0 withdrawal
-  - But accounting thinks withdrawal happened
-
-Step 3: Accounting mismatch exploited
-  - Total supply decremented
-  - User balance not changed
-  - System invariants broken
-```
-
-**IMPACT:**
-- Protocol accounting corrupted
-- Can be used to manipulate LP calculations
-- Estimated $50K impact on pool prices
-
-### 5. Baseline Violation
-- Violates invariant: "All withdrawals must transfer non-zero value"
-- Breaks validation pattern: Amount checks present in all other value transfers
-- Regression: Check added in commit abc123 "Fix zero-amount exploit"
-
----
-
-**Next:** Document all findings in final report (see [reporting.md](reporting.md))

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

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