differential-review

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)

Quick Reference

Codebase Size Strategy

Risk Level Triggers

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)

Agents

differential-review:adversarial-modeler — Models attacker perspectives and builds exploit scenarios for HIGH RISK code changes. Follows the 5-step adversarial methodology (attacker model, attack vectors, exploitability rating, exploit scenario, baseline cross-reference) and produces structured vulnerability reports. Delegate to this agent when Phase 5 analysis is needed on high-risk changes, passing that full namespaced name as subagent_type — a bare adversarial-modeler is unregistered and the dispatch fails at runtime.

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)

Standard Review (Medium Codebase)

Deep Audit (Large, Critical Change)

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.