Differential Review - Trail of Bits Skills

Security-focused differential review of code changes (PRs, commits, diffs) with adaptive depth scaling, git history analysis, blast radius calculation, and comprehensive markdown reports. Automatically detects and prevents security regressions.

Overview

This plugin performs comprehensive security review of code changes by analyzing diffs in the context of the entire codebase. It scales analysis depth based on codebase size, uses git blame to understand why code existed, calculates the impact radius of changes, and identifies test coverage gaps.

Author: Omar Inuwa
Version: 1.0.0

Core Principles

Risk-First

Focus on auth, crypto, value transfer, and external calls before everything else

Evidence-Based

Every finding backed by git history, line numbers, and concrete attack scenarios

Adaptive

Scale analysis depth to codebase size (SMALL/MEDIUM/LARGE)

Output-Driven

Always generate comprehensive markdown report file

When to Use

Use this skill when you need to:

Review PRs, commits, or diffs for security vulnerabilities
Detect security regressions (re-introduced vulnerabilities)
Analyze the blast radius of code changes
Check test coverage gaps for modified code
Perform pre-merge security review for critical changes

Installation

/plugin install trailofbits/skills/plugins/differential-review

Or use the slash command:

/trailofbits:diff-review <pr-url|commit-sha|diff-path> [--baseline <ref>]

Features

Risk-First Analysis

Changes are classified by risk level and prioritized accordingly:

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

Refactors are HIGH risk until proven LOW. Refactoring often breaks invariants.

Git History Analysis

Uses git blame to understand:

Why removed code existed (was it a security fix?)
When it was added (recent or legacy?)
Who authored it (security-aware developer?)
Commit messages revealing intent (CVE fix, security patch?)

Removed code from “security”, “CVE”, or “fix” commits triggers immediate escalation.

Blast Radius Calculation

Quantifies the impact of changes by counting:

Direct callers of modified functions
Transitive callers (functions calling the callers)
Shared state dependencies
Cross-module coupling

Example:

1-5 callers = Low blast radius
5-20 callers = Medium blast radius
20-50 callers = High blast radius
50+ callers = Critical blast radius (requires deep analysis)

Adaptive Depth Scaling

Codebase Size	Strategy	Approach
SMALL (under 20 files)	DEEP	Read all dependencies, full git blame
MEDIUM (20-200)	FOCUSED	1-hop dependencies, priority files only
LARGE (200+)	SURGICAL	Critical paths only, targeted analysis

Workflow

The complete workflow spans Pre-Analysis + Phases 0-6:

Pre-Analysis (Optional)

Build baseline context with audit-context-building skill if available

Phase 0: Intake & Triage

Extract changes, assess size, risk-score files

Phase 1: Changed Code Analysis

Analyze diffs, git blame, check for regressions

Phase 2: Test Coverage Analysis

Identify coverage gaps in modified code

Phase 3: Blast Radius Analysis

Calculate impact by counting callers and dependencies

Phase 4: Deep Context Analysis

Five Whys root cause analysis for HIGH risk changes

Phase 5: Adversarial Analysis

Hunt vulnerabilities with attacker model

Phase 6: Report Generation

Generate comprehensive markdown report

Modular Documentation Architecture

This skill uses progressive disclosure for token efficiency:

SKILL.md

Main entry point with quick reference, decision tree, and quality checklist

methodology.md

Detailed phase-by-phase workflow for Phases 0-4

adversarial.md

Attacker modeling and exploit scenarios for Phase 5

reporting.md

Report structure and formatting for Phase 6

patterns.md

Common vulnerability patterns reference

Load only the documentation you need. Use the decision tree to jump directly to the right phase.

Example Usage

Quick Triage (Small PR)

Review the security implications of this PR:
git diff main..feature/auth-changes

Strategy: Quick Reference only

Classify risk level per file (2 HIGH, 3 LOW)
Focus on 2 HIGH files only
Git blame removed code
Generate minimal report

Time: ~30 minutes

Standard Review (Medium Codebase)

Perform security review of PR #123 with full blast radius analysis

Strategy: FOCUSED (see methodology.md)

Full workflow on HIGH RISK files
Surface scan on MEDIUM
Skip LOW risk files
Complete report with all sections

Time: ~3-4 hours

Deep Audit (Large, Critical Change)

Deep security audit of the auth system rewrite in commit abc123

Strategy: SURGICAL + audit-context-building

Baseline context with audit-context-building
Deep analysis on auth changes only
Blast radius analysis
Adversarial modeling
Comprehensive report

Time: ~6-8 hours

Report Output

The generated markdown report includes:

Executive Summary

High-level overview with severity distribution: X High, Y Medium, Z Low, W Info

Critical Findings

Attack scenarios, PoCs, and exploitation details for high-severity issues

Test Coverage Analysis

Gaps in test coverage for modified code paths

Blast Radius Analysis

Quantified impact with caller counts and dependency graphs

Historical Context

Git blame results showing removed code history and regression risks

Actionable Recommendations

Specific remediation steps with code examples

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.

Rationalizations to Reject

"Small PR, quick review"

Why it’s wrong: Heartbleed was 2 lines
Required action: Classify by RISK, not size

"I know this codebase"

Why it’s wrong: Familiarity breeds blind spots
Required action: Build explicit baseline context

"Git history takes too long"

Why it’s wrong: History reveals regressions
Required action: Never skip Phase 1

"Blast radius is obvious"

Why it’s wrong: You’ll miss transitive callers
Required action: Calculate quantitatively

"No tests = not my problem"

Why it’s wrong: Missing tests = elevated risk rating
Required action: Flag in report, elevate severity

"Just a refactor, no security impact"

Why it’s wrong: Refactors break invariants
Required action: Analyze as HIGH until proven LOW

I'll explain verbally

Why it’s wrong: No artifact = findings lost
Required action: Always write report

Example Vulnerability: Security Regression

Git blame reveals removed security code:

- // Security fix: validate length to prevent overflow (CVE-2023-12345)
- if (input.length > MAX_SIZE) {
-     throw new Error("Input too large");
- }
+ // Refactored for performance
  processInput(input);

Analysis:

Git blame: Removed code added 6 months ago in commit “Fix CVE-2023-12345”
Risk: HIGH - validation removal on a known CVE fix
Impact: Re-introduces buffer overflow vulnerability
Blast radius: 47 callers of processInput()
Verdict: Critical security regression

Example Vulnerability: Access Control Change

- function withdraw() internal {
+ function withdraw() external {
      payable(msg.sender).transfer(balance);
  }

Analysis:

Change: Visibility modifier internal → external
Risk: HIGH - access control modification
Impact: Anyone can now call withdraw(), not just contract itself
Attack scenario: Attacker calls withdraw() directly, drains contract
Severity: Critical

Quality Checklist

Before delivering a differential review:

All changed files analyzed
Git blame on removed security code
Blast radius calculated for HIGH risk changes
Attack scenarios are concrete (not generic)
Findings reference specific line numbers + commits
Report file generated and saved
User notified with summary

Integration with Other Skills

audit-context-building:

Pre-Analysis: Build baseline context before differential review
Phase 4: Deep context on HIGH RISK changes

fp-check:

Verify suspected vulnerabilities found during review

issue-writer:

Transform findings into formal audit reports
Command: issue-writer --input DIFFERENTIAL_REVIEW_REPORT.md --format audit-report

When NOT to Use

Do not use differential-review for:

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.

Audit Context Building - Used for baseline analysis
FP Check - Verify suspected vulnerabilities

​Overview

​Core Principles

Risk-First

Evidence-Based

Adaptive

Output-Driven

​When to Use

​Installation

​Features

​Risk-First Analysis

​Git History Analysis

​Blast Radius Calculation

​Adaptive Depth Scaling

​Workflow

​Modular Documentation Architecture

SKILL.md

methodology.md

adversarial.md

reporting.md

patterns.md

​Example Usage

​Quick Triage (Small PR)

​Standard Review (Medium Codebase)

​Deep Audit (Large, Critical Change)

​Report Output

​Red Flags (Stop and Investigate)

​Rationalizations to Reject

​Example Vulnerability: Security Regression

​Example Vulnerability: Access Control Change

​Quality Checklist

​Integration with Other Skills

​When NOT to Use

​Related Skills

Overview

Core Principles

When to Use

Installation

Features

Risk-First Analysis

Git History Analysis

Blast Radius Calculation

Adaptive Depth Scaling

Workflow

Modular Documentation Architecture

Example Usage

Quick Triage (Small PR)

Standard Review (Medium Codebase)

Deep Audit (Large, Critical Change)

Report Output

Red Flags (Stop and Investigate)

Rationalizations to Reject

Example Vulnerability: Security Regression

Example Vulnerability: Access Control Change

Quality Checklist

Integration with Other Skills

When NOT to Use

Related Skills