Differential Security Review
Security-focused code review for PRs, commits, and diffs.
Core Principles Risk-First: Focus on auth, crypto, value transfer, external calls Evidence-Based: Every finding backed by git history, line numbers, attack scenarios Adaptive: Scale to codebase size (SMALL/MEDIUM/LARGE) Honest: Explicitly state coverage limits and confidence level 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 - Detailed phase-by-phase workflow (Phases 0-4) adversarial.md - Attacker modeling and exploit scenarios (Phase 5) reporting.md - Report structure and formatting (Phase 6) patterns.md - Common vulnerability patterns reference
For first-time users: Start with 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.