Preface¶

When conducting security reviews of PRs, the common practice is to open the diff, scan through the newly added logic, and then judge based on intuition that “the changes are small and the impact is manageable”. This step easily overlooks two things: why those deleted lines existed in the first place, and how many callers the modified function actually has in the repository.

For the former, you need git blame / git log -S—otherwise, a “refactoring that deletes validation” might accidentally erase a security fix from six months prior. For the latter, you need to quantitatively count callers—otherwise, a signature change to a validation function could spread through the call chain to unexpected modules. Trail of Bits codified this audit habit into the Agent Skill differential-review: instead of deciding the level of scrutiny based on the number of lines in the PR, it determines analysis depth based on risk level, git history, and blast radius, and enforces a Markdown report with supporting evidence.

What It Is¶

One-sentence definition: differential-review performs security-focused differential reviews of PRs, commits, and diffs. It adaptively analyzes depth based on repository scale, supplements context using git history, calculates the blast radius of changes, checks for test coverage gaps, and generates a complete Markdown report.

It is maintained by Trail of Bits, and listed in the Code Auditing category of the trailofbits/skills plugin marketplace. The plugin author is Omar Inuwa, and the current version number in .claude-plugin/plugin.json is 1.1.1. Source code directory:
https://github.com/trailofbits/skills/tree/main/plugins/differential-review/skills/differential-review

The official description matches the SKILL.md, plugin README, and documentation site Differential Review: it conducts security reviews of code changes, detects security regressions, quantifies blast radius, and identifies untested modified code.

It follows the universal SKILL.md format, so it can be loaded in Claude Code, Codex CLI, Cursor, and other tools that support Agent Skill directories. When used as a Claude Code plugin, it also includes slash commands and the adversarial-modeler sub-agent; if you only copy the SKILL.md, these two features may not be included, depending on your actual installation method.

The workflow follows git diff and is not tied to a single language. The accompanying patterns.md and examples mostly use smart contracts (Solidity); the scale assessment command in methodology.md counts the number of .sol / .rs / .go / .ts files. When reviewing web services, Rust, or Go repositories, the risk classification and phase process still apply, but you should cross-reference the vulnerability pattern list by language, and do not directly apply the onlyOwner detection from Solidity to other stacks.

Core Features and Highlights¶

Based on SKILL.md, methodology.md, adversarial.md, reporting.md, and the plugin README, its capabilities can be summarized as follows. The documentation uses progressive disclosure: the entry file only includes a cheat sheet and decision tree, and loads the full-length content by phase to avoid overwhelming users with all the methodology at once.

1. Risk-based triage, not diff size¶

The Skill lists “fast-tracking small PRs” as a must-reject rationalization, with the reasoning that Heartbleed was only two lines long. Classification is based on risk, not line count.

The documentation also explicitly states: Refactors are analyzed as HIGH risk until proven LOW. Refactors often break invariants.

Repository scale determines the analysis strategy, separate from the risk classification axis:

Small repositories can be thoroughly examined; for large repositories with rewritten authentication logic, only follow critical paths, and it is recommended to first run the audit-context-building from the same marketplace to establish a baseline.

2. Use git history to catch security regressions¶

Phase 1 requires comparing the baseline version and the current version when reviewing each changed section, and running git blame / git log -S on deleted code: when was this code added, what was the commit message, and was it a security fix?

Immediate red flags include:
- Deletions originating from commits tagged with security, CVE, or fix
- Removal of access control modifiers (e.g., onlyOwner, or internal changed to external)
- Validation removed with no replacement
- New external calls added without checks
- HIGH-risk changes with a blast radius of 50+ callers

The documentation cites a typical regression case: a length validation with the comment “Security fix: validate length to prevent overflow (CVE-…)” was deleted during a “performance-focused refactor”. git blame can link it back to the original CVE fix commit; only looking at the new code makes it easy to miss this regression.

Detection ideas come from patterns.md, for example:

# Patterns that were previously removed for security reasons and have reappeared
git log -S "pattern" --all --grep="security\|fix\|CVE"

# Deleted require / assert / revert statements in a diff
git diff <range> | grep "^-" | grep -E "require|assert|revert"

3. Quantitatively calculate blast radius¶

Phase 3 requires quantifying impact based on the number of calls to the modified function, rather than verbally claiming “the impact is small”:

The priority matrix combines “change risk × blast radius” into P0/P1/P2. HIGH-risk changes with CRITICAL blast radius require thorough analysis and full dependency review; MEDIUM-risk changes with many callers also require including the callers in the analysis. The counting example in methodology.md uses grep to count occurrences of function names, filtered to .sol files for smart contract scenarios.

4. Uncovered tests raise risk ratings¶

Phase 2 formalizes test gaps as risk rules, rather than treating tests as “someone else’s job”:
- New function with no tests: MEDIUM risk upgraded to HIGH
- Validation modified but tests unchanged: HIGH risk
- Complex logic (over 20 lines) with no tests: HIGH risk

The report must list uncovered functions, and use this information to decide whether to recommend blocking the merge.

5. HIGH-risk changes require adversarial modeling and mandatory reporting¶

The full workflow is Pre-Analysis + Phase 0 through Phase 6:

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

Phase 5 requires specifying a concrete attacker model (who, what permissions, which entry point), rather than vague statements like “there may be risks”. Exploitability is rated as EASY / MEDIUM / HARD. The adversarial-modeler agent in the plugin specializes in this step, and should only be enabled for HIGH-risk changes.

Phase 6 mandates generating a Markdown file, and prohibits only verbal explanations in the chat. The report follows a fixed nine-section structure: executive summary (including APPROVE / REJECT / CONDITIONAL), change description, high-severity findings, test coverage, blast radius, historical context, recommendations, methodology and limitations, and appendix. Each high-severity finding must include file line numbers, commits, blast radius, test coverage, attack scenarios, and recommended fixes.

The output filename format is <project>_DIFFERENTIAL_REVIEW_<date>.md, with the documentation example being VeChain_Stargate_DIFFERENTIAL_REVIEW_2025-12-26.md. The write priority is: current repository working directory → user’s Desktop → ~/.claude/skills/differential-review/output/. If writing to files fails, fall back to the chat and prompt the user to save manually.

Five core principles are listed in the entry file: Risk-First, Evidence-Based, Adaptive, Honest (state coverage and confidence clearly), and Output-Driven.

Installation and Activation¶

Claude Code¶

Official marketplace installation has two steps. First, add the Trail of Bits plugin marketplace:

/plugin marketplace add trailofbits/skills

Then install this plugin:

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

You can also run /plugin menu to browse first before installing. /plugin is a Claude Code command, not a system shell command. The documentation site reminds you that individual plugins will not appear in the menu before you add the marketplace.

The calling example in the Quick Start is:

/diff-review

The plugin command file commands/diff-review.md has the name trailofbits:diff-review, and the parameter convention is:

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

The Target parameter is required, and can be a PR URL, commit SHA, or diff path; the --baseline parameter is optional for specifying the comparison baseline. The two syntaxes point to the same command, subject to the name shown in the current Claude Code plugin menu.

Codex CLI¶

The repository README states that Codex can directly load Claude’s marketplace, no additional sidecar metadata required:

codex plugin marketplace add trailofbits/skills
codex plugin list
codex plugin add differential-review@trailofbits

The plugin name in the last command matches the plugins/differential-review directory name in the repository.

Universal Skill Installation (Cursor, etc.)¶

The commands on officialskills.sh and skills.sh are:

npx skills add https://github.com/trailofbits/skills --skill differential-review

This command follows the universal Agent Skills directory convention, installing SKILL.md into the skills path used by your current tool. After installation, you can directly describe your review task. Installation counts and scan scores on third-party directories are not official data; use the GitHub README and the linked directory pages as the source of truth for installation commands.

The Skill declares tool permissions as Read, Write, Grep, Glob, Bash, and the review process will run git / gh and search commands. It must be used in a git working copy with repository history, and ensure the assistant has permission to execute these tools.

Typical Usage Examples¶

The following prompts and commands are sourced from the official SKILL.md, plugin README, methodology.md, and documentation site, and can be reproduced based on the current state of the repository.

1. Trigger with natural language, pointing to a diff

Example from the plugin README:

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

In Chinese environments, you can use:

Please use differential-review to conduct a security differential review of main..feature/auth-changes.
First, classify risks by file, run the full process (including git blame and blast radius analysis) for HIGH-risk files,
and finally write the report to a Markdown file, do not only provide conclusions in the chat.

2. Ingestion phase: Clarify the change set

methodology.md requires first extracting changes, then evaluating scale and assigning risk scores to each file:

# Commit range
git diff <base>..<head> --stat
git log <base>..<head> --oneline
git diff <base>..<head> --name-only

# PR
gh pr view <number> --json files,additions,deletions

3. Fast triage for small PRs (official Quick Triage)

Input: A PR with 5 files, 2 HIGH-risk and 3 LOW-risk. Use the Quick Reference from the entry file:
1. Classify by file risk level
2. Only thoroughly analyze the 2 HIGH-risk files
3. Run git blame on deleted code
4. Generate a concise report

The documentation estimates this will take approximately 30 minutes. Even with fast triage, you must perform adversarial analysis if you encounter the red flags mentioned above, and cannot skip steps just because “there are few files”.

4. Standard review for medium-sized repositories

Input: Approximately 80 files, 12 HIGH-risk changes. Use the FOCUSED strategy:
1. Run the full process for HIGH-risk files
2. Perform surface-level scans for MEDIUM-risk changes
3. Skip LOW-risk changes
4. Generate a complete report following the nine-section structure

The documentation estimates this will take approximately 3–4 hours. You can write the request in natural language as:

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

5. Large critical changes: Authentication rewrite

Input: Approximately 450 files, authentication system rewrite. Use the SURGICAL strategy and integrate audit-context-building:
1. First establish context on the baseline commit (invariants, trust boundaries, validation patterns, call graphs)
2. Only thoroughly analyze authentication-related changes
3. Calculate blast radius
4. Conduct adversarial modeling
5. Generate a complete report

The documentation estimates this will take approximately 6–8 hours. Baseline analysis example:

git checkout <baseline_commit>
# If audit-context-building is installed
# Solidity example:
# audit-context-building --scope packages/contracts/contracts --focus invariants,trust-boundaries,validation-patterns,call-graphs,state-flows

Switch back to the head branch to view the diff after analyzing the baseline. If audit-context-building is not available, the documentation requires using Read / Grep to perform the same line-level tracking manually, rather than skipping Pre-Analysis.

6. Convert the review to an audit report after completion

The issue-writer plugin from the same marketplace can convert the differential review report into audit documentation for non-technical stakeholders:

issue-writer --input DIFFERENTIAL_REVIEW_REPORT.md --format audit-report

The documentation site also mentions that fp-check can be used to verify false positives for suspected vulnerabilities during the review. These are separate plugins that require separate installation.

Applicable Scenarios and Notes¶

Suitable For¶

• Security reviews of PRs / commits / diffs before merging
• Suspicions that a change reintroduced an old security fix
• Need to quantitatively evaluate “how many callers will be affected by changing this function”
• Need to document test gaps in modified code when making merge decisions
• HIGH-risk changes involving authentication, payments, external calls, or smart contract visibility, requiring specific adversarial scenarios rather than vague comments

Official cited trigger scenarios include: before merging an authentication system rewrite; when a widely used validation function is deleted; when a smart contract access control modifier is changed from internal to external; triaging a 5-file PR to identify files that require deep analysis; generating evidence-based reports tied to specific line numbers and commits.

Explicitly Not For¶

• Greenfield code from scratch (no baseline for comparison)
• Pure documentation changes
• Formatting / lint changes that only affect appearance
• Scenarios where the user only wants a verbal summary and accepts the associated risks

These cases should use regular code review instead.

Usage Limitations¶

1. Git history is critical to its effectiveness. Shallow clones, squashed commits that lose intermediate history, or review objects not stored in git will significantly weaken blame and regression detection. The Skill lists “git history takes too much time” as a prohibited excuse to skip steps.
2. Be honest about coverage. The principles require clearly stating which files were analyzed, whether LOW-risk changes were excluded, and whether confidence is HIGH or MEDIUM. Do not claim full repository analysis if you do not have enough time.
3. Findings must be locatable. They must include line numbers, commits, and specific attack steps; statements like “input validation may be bypassed” do not meet the quality bar.
4. Reports must be saved to disk. Only providing conclusions in the chat window counts as no deliverable.
5. Solidity patterns are not a universal vulnerability encyclopedia. patterns.md covers regressions, reentrancy, access control, overflow, unchecked return values, timestamp dependencies, etc., with most examples focused on contracts. When reviewing other languages, follow the phase process but replace the pattern list.
6. Sub-agents and slash commands depend on installation path. Marketplace/plugin installations will include commands/diff-review.md and agents/adversarial-modeler.md; if you only sync the Skill directory with npx skills add, you will usually only have SKILL.md and the accompanying methodology/adversarial/reporting/patterns files. Your prompt should specify “generate a report file following the full differential-review phases”.
7. License is CC BY-SA 4.0. The root repository README states that the entire skills suite is licensed under Creative Commons Attribution-ShareAlike 4.0.

Summary¶

differential-review formalizes a concrete workflow: it codifies the steps security teams repeatedly emphasize in differential reviews—risk triage, git blame, blast radius calculation, test gap analysis, adversarial scenario modeling, and documented reporting—into an executable Agent process. It