differential-review

差分安全审查

针对 PR、提交和差异的安全代码审查。

核心原则

1. 风险优先：重点关注身份验证、加密、价值转移和外部调用
2. 基于证据：每项发现都有 Git 历史、行号和攻击场景作为依据
3. 自适应：根据代码库规模调整审查深度（SMALL/MEDIUM/LARGE）
4. 诚实：明确说明覆盖范围限制和置信度
5. 以输出为导向：始终生成完整的 Markdown 报告文件

---

合理化借口（切勿跳过）

合理化借口	错在哪里	必须采取的行动
“PR 很小，快速审查一下就行”	Heartbleed 只涉及 2 行代码	按风险而非规模分类
“我了解这个代码库”	熟悉会造成盲点	明确建立基线背景
“Git 历史太耗时”	历史记录能揭示回归问题	绝不跳过阶段 1
“影响范围显而易见”	你会漏掉传递调用方	进行定量计算
“没有测试不关我的事”	缺少测试意味着风险评级升高	在报告中标明，并提高严重性
“只是重构，不影响安全”	重构会破坏不变量	在证明风险低之前，按高风险分析
“我口头说明就行”	没有文档，发现就会丢失	始终撰写报告

---

快速参考

代码库规模策略

代码库规模	策略	方法
SMALL（<20 个文件）	深入	阅读所有依赖项，完整查看 Git blame
MEDIUM（20-200 个文件）	聚焦	查看 1 跳依赖项和优先文件
LARGE（200+ 个文件）	精简	仅检查关键路径

风险等级触发条件

风险等级	触发条件
高	身份验证、加密、外部调用、价值转移、移除验证
中	业务逻辑、状态变更、新增公共 API
低	注释、测试、UI、日志记录

---

工作流概览

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

---

决策树

开始审查了吗？

├─ 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: differential-review: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

---

Agent

differential-review:adversarial-modeler — 为高风险代码变更建模攻击者视角， 并构建利用场景。遵循 5 步对抗分析方法（攻击者模型、攻击向量、可利用性评级、 利用场景、基线交叉比对），并生成结构化漏洞报告。当高风险变更需要进行第 5 阶段 分析时，将任务委托给此 Agent，并将完整的命名空间名称作为 subagent_type 传入—— 未注册的裸名称 adversarial-modeler 会导致运行时分发失败。

---

质量检查清单

交付前：

• 已分析所有变更文件
• 已对移除的安全代码执行 Git blame
• 已计算高风险变更的影响范围
• 攻击场景具体明确（而非泛泛而谈）
• 发现中包含具体行号和提交
• 已生成报告文件
• 已向用户通知摘要

---

集成

audit-context-building 技能：

• 分析前：建立基线背景
• 阶段 4：深入分析高风险变更的背景

issue-writer 技能：

• 将发现转换为正式审计报告
• 命令：issue-writer --input DIFFERENTIAL_REVIEW_REPORT.md --format audit-report

---

使用示例

快速分级（小型 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

标准审查（中型代码库）

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

深度审计（大型关键变更）

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

---

不适用此技能的情况

• 全新代码（没有可供比较的基线）
• 仅修改文档（不影响安全）
• 格式调整/代码检查（仅外观上的变更）
• 用户明确只要求快速摘要（用户接受相应风险）

遇到这些情况时，请使用标准代码审查。

---

危险信号（立即停止并调查）

需要立即升级处理的触发条件：

• 从包含“security”“CVE”或“fix”的提交中移除代码
• 移除访问控制修饰符（onlyOwner、internal → external）
• 移除验证且未提供替代措施
• 新增外部调用但未添加检查
• 影响范围大（50+ 个调用方）且变更为高风险

即使是快速分级，这些情况也需要进行对抗分析。

---

获得最佳结果的提示

建议：

• 对已删除的代码，先查看 git blame
• 尽早评估影响范围，以便确定优先级
• 生成具体的攻击场景
• 引用具体的行号和提交
• 如实说明覆盖范围的限制
• 始终生成输出文件

避免：

• 跳过 git 历史分析
• 在没有证据的情况下提出笼统的发现
• 时间有限时声称已完成全面分析
• 忘记检查测试覆盖率
• 忽略影响范围大的变更
• 只在聊天中输出报告（必须生成文件）

---

参考文档

• methodology.md - 详细的分阶段工作流（阶段 0-4）
• adversarial.md - 攻击者建模和漏洞利用场景（阶段 5）
• reporting.md - 报告结构和格式（阶段 6）
• patterns.md - 常见漏洞模式参考

---

首次使用的用户： 从 methodology.md 开始，了解完整工作流。

有经验的用户： 使用本页的快速参考和决策树，直接查找所需内容。