Differential Review

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:

# 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:

# 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:

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:

   Copy

   BEFORE: [exact code]
   AFTER: [exact code]
   CHANGE: [behavioral impact]
   SECURITY: [implications]

3. Git blame removed code:

   Copy

   # 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):

   Copy

   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:

   Copy

   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:

# 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:

# 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:

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:

# 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:

# 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

• For report generation, see reporting.md