differential-review
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseDifferential Security Review
差异化安全审查
Security-focused code review for PRs, commits, and diffs.
针对PR、提交和代码差异的安全导向型代码审查。
Core Principles
核心原则
- Risk-First: Focus on auth, crypto, value transfer, external calls
- Evidence-Based: Every finding backed by git history, line numbers, attack scenarios
- Adaptive: Scale to codebase size (SMALL/MEDIUM/LARGE)
- Honest: Explicitly state coverage limits and confidence level
- Output-Driven: Always generate comprehensive markdown report file
- 风险优先：聚焦认证（auth）、加密（crypto）、价值转移、外部调用
- 基于证据：所有发现均有Git历史、行号、攻击场景作为支撑
- 自适应调整：根据代码库规模（SMALL/MEDIUM/LARGE）调整分析策略
- 客观透明：明确说明审查覆盖范围限制及置信度
- 输出导向：始终生成完整的Markdown报告文件
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 |
| 常见误区 | 错误原因 | 要求动作 |
|---|---|---|
| "小型PR，快速审查" | Heartbleed漏洞仅涉及2行代码 | 按风险等级分类，而非PR规模 |
| "我熟悉这个代码库" | 熟悉度会导致思维盲区 | 构建明确的基准上下文 |
| "Git历史分析太耗时" | 历史记录可揭示回归问题 | 绝不跳过阶段1 |
| "影响半径显而易见" | 会遗漏间接调用者 | 进行量化计算 |
| "没有测试与我无关" | 缺失测试会提升风险等级 | 在报告中标记，提高严重程度 |
| "只是重构，无安全影响" | 重构会破坏原有约束 | 除非证明为低风险，否则按高风险分析 |
| "我会口头解释" | 无书面记录会导致发现的问题丢失 | 务必撰写报告 |
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 |
| 代码库规模 | 策略 | 实施方式 |
|---|---|---|
| 小型（<20个文件） | 深度分析 | 查看所有依赖，完整Git Blame |
| 中型（20-200个文件） | 聚焦分析 | 1级依赖，优先处理关键文件 |
| 大型（200+个文件） | 精准分析 | 仅关注关键路径 |
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 |
| 风险等级 | 触发场景 |
|---|---|
| 高风险 | 认证（Auth）、加密（Crypto）、外部调用、价值转移、验证逻辑移除 |
| 中风险 | 业务逻辑、状态变更、新增公开API |
| 低风险 | 注释、测试、UI、日志 |
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预分析 → 阶段0：分类筛选 → 阶段1：代码分析 → 阶段2：测试覆盖率
↓ ↓ ↓ ↓
阶段3：影响半径分析 → 阶段4：深度上下文分析 → 阶段5：对抗性分析 → 阶段6：报告生成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)
│
├─ 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开始审查前？
├─ 需要详细的分阶段方法论？
│ └─ 阅读：methodology.md
│ (预分析 + 阶段0-4：分类筛选、代码分析、测试覆盖率、影响半径)
│
├─ 分析高风险变更？
│ └─ 阅读：adversarial.md
│ (阶段5：攻击者建模、漏洞利用场景、可利用性评级)
│
├─ 撰写最终报告？
│ └─ 阅读：reporting.md
│ (阶段6：报告结构、模板、格式指南)
│
├─ 查找特定漏洞模式？
│ └─ 阅读：patterns.md
│ (回归问题、重入漏洞、访问控制、溢出等)
│
└─ 仅需快速分类筛选？
└─ 使用上方快速参考，跳过详细文档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
交付前确认：
- 所有变更文件已分析
- 已对移除的安全代码执行Git Blame
- 已为高风险变更计算影响半径
- 攻击场景具体明确（非泛泛而谈）
- 发现的问题关联了具体行号及提交记录
- 已生成报告文件
- 已向用户发送摘要通知
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
audit-context-building 技能：
- 预分析阶段：构建基准上下文
- 阶段4：针对高风险变更开展深度上下文分析
issue-writer 技能：
- 将发现的问题转换为正式审计报告
- 命令：
issue-writer --input DIFFERENTIAL_REVIEW_REPORT.md --format audit-report
Example Usage
示例用法
Quick Triage (Small PR)
快速分类筛选（小型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输入：5个文件的PR，2个高风险文件
策略：使用快速参考
1. 按文件分类风险等级（2个高风险，3个低风险）
2. 仅聚焦2个高风险文件
3. 对移除的代码执行Git Blame
4. 生成极简报告
耗时：约30分钟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输入：80个文件，12项高风险变更
策略：聚焦分析（参见methodology.md）
1. 对高风险文件执行完整工作流
2. 对中风险文件进行表面扫描
3. 跳过低风险文件
4. 生成包含所有章节的完整报告
耗时：约3-4小时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输入：450个文件，认证系统重写
策略：精准分析 + audit-context-building
1. 使用audit-context-building构建基准上下文
2. 仅对认证变更进行深度分析
3. 开展影响半径分析
4. 进行对抗性建模
5. 生成全面报告
耗时：约6-8小时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.
- 全新代码库（Greenfield code）（无基准可对比）
- 仅文档变更（无安全影响）
- 格式/代码规范调整（仅 cosmetic 变更）
- 用户明确要求仅提供快速摘要（用户已接受风险）
上述场景请使用标准代码审查流程。
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.
需立即升级处理的触发条件：
- 从标记为“security”、“CVE”或“fix”的提交中移除代码
- 移除访问控制修饰符（如onlyOwner从internal改为external）
- 移除验证逻辑且未替换
- 新增无检查的外部调用
- 影响半径大（50+调用者）且为高风险变更
即使在快速分类筛选中，上述模式也需开展对抗性分析。
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)
建议：
- 从对移除代码执行Git Blame开始
- 尽早计算影响半径以确定优先级
- 生成具体的攻击场景
- 关联具体行号和提交记录
- 如实说明覆盖范围限制
- 始终生成输出文件
避免：
- 跳过Git历史分析
- 生成无证据的泛泛发现
- 时间有限时声称已完成全面分析
- 忘记检查测试覆盖率
- 遗漏大影响半径的变更
- 仅在聊天中发送报告（必须生成文件）
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.
- methodology.md - 详细的分阶段工作流（阶段0-4）
- adversarial.md - 攻击者建模与漏洞利用场景（阶段5）
- reporting.md - 报告结构与格式指南（阶段6）
- patterns.md - 常见漏洞模式参考
首次使用用户： 先阅读methodology.md以了解完整工作流。
经验用户： 使用本页面的快速参考和决策树直接跳转至所需内容。