Skip to content
Differential Security Review

Differential Security Review Skill

by Trail of Bits trailofbits/skills

Trail of Bits' security review skill for PRs, commits, and diffs: risk-first analysis with git history, blast radius, and honest coverage limits.

GitHub Docs
Featured Testing & QASecurity
Added to Onei

Install

Install with the skills CLI

One command for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf and dozens of other agents. Needs Node.js; the skill is fetched straight from trailofbits/skills.

$ npx skills add trailofbits/skills --skill differential-review

Run it in a terminal. The CLI finds the agents installed on your machine, asks which ones to add the skill to, and whether to install it into the folder you ran it from or for all your projects.

Other ways to install

  1. Open the skill on GitHub and download the folder that holds its SKILL.md.
  2. Put it at ~/.claude/skills/differential-review/, where Claude Code picks it up in every project.

No scripts or references next to it? Saving the SKILL.md alone as ~/.claude/skills/differential-review/SKILL.md works too.

Using another agent? Its personal skills folder
Codex
~/.agents/skills/
Cursor
~/.cursor/skills/
GitHub Copilot
~/.copilot/skills/
Gemini CLI
~/.gemini/skills/
Windsurf
~/.codeium/windsurf/skills/
OpenCode
~/.config/opencode/skills/
Open folder on GitHub

About

  • Risk-first triage: auth, crypto, value transfer, external calls
  • Every finding backed by git history, line numbers, and an attack scenario
  • Depth scaled to codebase size (SMALL / MEDIUM / LARGE)
  • Blast-radius calculation for each change
  • Test-coverage check on the changed paths
  • Automatic detection of security regressions
  • Markdown report that states coverage limits and confidence

Trail of Bits is a security firm that audits cryptography, smart contracts, and systems software for a living. This skill packages the way they review a diff, so an agent reviewing your pull request works from an auditor's priorities instead of a linter's.

Risk-first, not line-first

A generic review reads a diff top to bottom and comments on whatever it notices. This one starts from where security bugs actually live — authentication and authorisation, cryptographic operations, value transfer, and calls out to external systems — and spends its attention budget there. Changes to a logging format and changes to a signature check are not treated as equally interesting.

Evidence, not vibes

Every finding is expected to carry its justification: the git history that shows how the code got this way, the specific line numbers, and a concrete attack scenario describing how the issue would be exploited. That requirement is what separates a usable review from a list of plausible-sounding concerns, and it is enforced by the skill's own principles rather than left to the model's discretion.

Scaled and honest

The analysis adapts its depth to the size of the codebase — the workflow branches for SMALL, MEDIUM, and LARGE targets — and computes the blast radius of each change rather than treating a diff as self-contained. It checks whether tests actually cover the changed paths, and it explicitly detects security regressions: cases where a protection that existed before the diff no longer holds after it.

The output is a markdown report that states its own coverage limits and confidence level. A review that quietly skipped half the diff is worse than no review, so saying what was not examined is part of the deliverable.

Distribution

Ships in Trail of Bits' Claude Code plugin marketplace alongside their smart-contract security toolkit, GitHub Actions auditor, C/C++ review workers, and false-positive verification skills. Codex can load the same marketplace through its Claude marketplace compatibility.

Try it

Once installed, ask your agent something like:

Do a security review of the changes on this branch against main — I care most about the new webhook signature verification and the session handling it touches.

SKILL.md

The instructions your agent loads, as published by Trail of Bits.

SKILL.md
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)
│  └─ Or delegate to: adversarial-modeler agent
│     (Autonomous attacker modeling with concrete exploit scenarios)
│
├─ 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

---

Agents

`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.

---

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.

Install

Related Skills

See all Differential Security Review alternatives

Skill: Zeroize Audit

by Trail of Bits

Finds secrets left in memory in C, C++ and Rust — including wipes the compiler deleted — and requires IR or assembly evidence before calling one optimized away.

Security

Skill: Supply Chain Risk Auditor

by Trail of Bits

Audits npm, PyPI and Go dependencies for advisories, abandoned upstreams, publisher concentration and install-time scripts — measured by scripts, not estimated.

Security

Skill: Constant-Time Analysis

by Trail of Bits

Compiles cryptographic code and reads the emitted assembly for variable-time instructions, then triages which flagged operations actually touch secrets.

Security

Skill: OpenAI security-best-practices

by OpenAI

OpenAI's skill for language- and framework-specific secure coding: detect the stack, load the matching reference guidance, then write secure-by-default code, flag critical issues passively, or produce a prioritised vulnerability report with fixes.

DevelopmentSecurity
Browse all skills →