Back to Details

pravidhi-bug-review-pipeline

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Bug Review Pipeline

漏洞审查流程

A three-phase adversarial code review system. Three agents check each other's work to produce a reliable, deduplicated bug report.
一个包含三个阶段的对抗式代码审查系统。三个Agent互相检查工作，以生成可靠、去重的漏洞报告。

Overview

概述

Phase 1: Bug Finder     → ./issues/YYYY-MM-DD-report.md
Phase 2: Bug Adversary  → ./issues/YYYY-MM-DD-refutation.md  
Phase 3: Arbiter        → ./issues/YYYY-MM-DD-final.md
All output files use today's date. Run each phase sequentially — each agent reads the previous agent's output.
阶段1：漏洞查找Agent → ./issues/YYYY-MM-DD-report.md
阶段2：漏洞对抗Agent → ./issues/YYYY-MM-DD-refutation.md  
阶段3：仲裁Agent → ./issues/YYYY-MM-DD-final.md
所有输出文件均使用当日日期。按顺序运行每个阶段——每个Agent会读取前一个Agent的输出结果。

Setup

准备工作

Before running any phase, ensure the output directory exists:
bash
mkdir -p ./issues
If the user has not specified a codebase path, ask them which directory or files to analyze. If they say "this repo" or similar, use the current working directory.
在运行任何阶段之前，请确保输出目录已存在：
bash
mkdir -p ./issues
如果用户未指定代码库路径，请询问他们要分析哪个目录或文件。如果用户说“此仓库”或类似表述，则使用当前工作目录。

Phase 1 — Bug Finder

阶段1 —— 漏洞查找Agent

Goal: Maximize bug discovery. Cast a wide net. False positives are acceptable; missed bugs are not.
Read: 
agents/bug-finder.md
Inputs: Codebase files (read recursively from target directory)
Output: 
./issues/YYYY-MM-DD-report.md
目标： 最大化漏洞发现范围。尽可能全面排查，允许出现误报，但不能遗漏漏洞。
参考文档： 
agents/bug-finder.md
输入： 代码库文件（从目标目录递归读取）
输出： 
./issues/YYYY-MM-DD-report.md

Scoring

评分规则

SeverityPointsExamples
Low+1Edge cases, cosmetic issues, minor inconsistencies
Medium+5Functional bugs, data issues, performance problems
Critical+10Security vulns, data loss, crashes
严重程度分值示例
低+1边缘情况、外观问题、轻微不一致
中+5功能性漏洞、数据问题、性能缺陷
关键+10安全漏洞、数据丢失、程序崩溃

What to look for

检查要点

  • Security: Injection flaws, auth bypass, hardcoded secrets, insecure deserialization, path traversal
  • Correctness: Off-by-one errors, null/undefined handling, incorrect logic, wrong operator use
  • Data integrity: Race conditions, incorrect transactions, missing validation, lossy type coercion
  • Error handling: Swallowed exceptions, missing error states, no retry logic
  • Performance: N+1 queries, unbounded loops, memory leaks, blocking I/O
  • API contracts: Incorrect HTTP status codes, missing required fields, type mismatches
  • Dependencies: Outdated packages with known CVEs, version conflicts
  • Config/Infra: Missing env var validation, insecure defaults, overly broad permissions
  • 安全方面： 注入漏洞、身份验证绕过、硬编码密钥、不安全的反序列化、路径遍历
  • 正确性： 差一错误、空值/未定义处理、逻辑错误、运算符使用错误
  • 数据完整性： 竞态条件、事务处理错误、缺失验证、有损类型转换
  • 错误处理： 被吞掉的异常、缺失错误状态、无重试逻辑
  • 性能： N+1查询、无限循环、内存泄漏、阻塞式I/O
  • API契约： HTTP状态码错误、缺失必填字段、类型不匹配
  • 依赖项： 存在已知CVE的过时包、版本冲突
  • 配置/基础设施： 缺失环境变量验证、不安全的默认设置、权限过宽

Report format

报告格式

markdown
undefined
markdown
undefined

Bug Report — YYYY-MM-DD

漏洞报告 —— YYYY-MM-DD

Summary

摘要

  • Total bugs found: N
  • Critical: N | Medium: N | Low: N
  • Total score: N
  • 发现的漏洞总数：N
  • 关键：N | 中：N | 低：N
  • 总得分：N

BUG-001 — [Short Title]

BUG-001 —— [简短标题]

Location: 
path/to/file.ext:line_number

Severity: Critical / Medium / Low
Points: 10 / 5 / 1
Description:
What the bug is and why it's a problem.
Evidence:
code snippet if relevant
Suggested Fix:
How to resolve it.
[repeat for all bugs]
位置： 
path/to/file.ext:line_number

严重程度： 关键 / 中 / 低
分值： 10 / 5 / 1
描述：
漏洞内容及其影响。
证据：
相关代码片段
修复建议：
解决方法。
[所有漏洞重复上述格式]

Total Score: N

总得分：N


---

---

Phase 2 — Bug Adversary

阶段2 —— 漏洞对抗Agent

Goal: Eliminate false positives by challenging every reported bug.
Read: 
agents/bug-adversary.md
Inputs: 
./issues/YYYY-MM-DD-report.md
+ the codebase
Output: 
./issues/YYYY-MM-DD-refutation.md
目标： 通过质疑每一个报告的漏洞，消除误报。
参考文档： 
agents/bug-adversary.md
输入： 
./issues/YYYY-MM-DD-report.md
+ 代码库
输出： 
./issues/YYYY-MM-DD-refutation.md

Scoring

评分规则

OutcomePoints
Successfully disprove a bug+[bug's original score]
Wrongly dismiss a real bug−2× [bug's original score]
The 2× penalty means only challenge bugs you're confident about.
结果分值
成功证明漏洞不成立+[原漏洞分值]
错误驳回真实漏洞−2× [原漏洞分值]
2倍惩罚意味着仅对您有把握的漏洞提出质疑。

Strategies for disproving bugs

证明漏洞不成立的策略

  • Show the bug is unreachable (guarded by conditions, dead code, env constraints)
  • Show the "issue" is intentional design with documented reasoning
  • Show the test suite already covers the scenario
  • Show the framework/library handles it automatically
  • Show the impact is negligible given the deployment context
  • Confirm the fix already exists elsewhere in the codebase
  • 证明该漏洞无法触发（受条件限制、死代码、环境约束）
  • 证明该“问题”是有文档说明的有意设计
  • 证明测试套件已覆盖该场景
  • 证明框架/库会自动处理该问题
  • 证明在部署环境中影响可忽略不计
  • 确认代码库中已存在修复方案

Refutation report format

质疑报告格式

markdown
undefined
markdown
undefined

Bug Refutation — YYYY-MM-DD

漏洞质疑报告 —— YYYY-MM-DD

Summary

摘要

  • Bugs reviewed: N
  • Disproved: N (score gained: +N)
  • Accepted: N (real bugs remaining)
  • Final score: N
  • 审查的漏洞数：N
  • 已证明不成立：N（得分增加：+N）
  • 已确认：N（剩余真实漏洞）
  • 最终得分：N

BUG-001 — [Title from report]

BUG-001 —— [报告中的标题]

Original severity/points: Critical / 10
Counter-argument:
Why this is NOT a bug (or why the risk is negligible).
Confidence: 85%
Risk calculation: +10 if correct, −20 if wrong → EV = 0.85×10 − 0.15×20 = +5.5 → DISPROVE
Decision: DISPROVE / ACCEPT
Points: +N / 0
[repeat for all bugs]
原严重程度/分值： 关键 / 10
反驳理由：
为什么这不是漏洞（或风险可忽略不计）。
可信度： 85%
风险计算： +10（正确时），−20（错误时）→ 期望值 = 0.85×10 − 0.15×20 = +5.5 → 提出质疑
决策： 质疑不成立 / 确认有效
分值： +N / 0
[所有漏洞重复上述格式]

Accepted bugs (verified real issues)

已确认的漏洞（经核实的真实问题）

  • BUG-XXX: [title] — Medium
  • BUG-XXX: [title] — Critical

---
  • BUG-XXX: [标题] —— 中
  • BUG-XXX: [标题] —— 关键

---

Phase 3 — Arbiter

阶段3 —— 仲裁Agent

Goal: Final verdict on all disputed and accepted bugs.
Read: 
agents/arbiter.md
Inputs: Both previous reports + the codebase
Output: 
./issues/YYYY-MM-DD-final.md
目标： 对所有有争议和已确认的漏洞给出最终裁决。
参考文档： 
agents/arbiter.md
输入： 前两份报告 + 代码库
输出： 
./issues/YYYY-MM-DD-final.md

Arbitration approach

仲裁方法

For each bug, weigh:
  1. The Bug Finder's original evidence
  2. The Adversary's counter-argument
  3. The actual code (ground truth)
Give benefit of the doubt to the Bug Finder for Critical severity bugs (better safe than sorry). Apply stricter scrutiny to Low severity items.
针对每个漏洞，权衡以下因素：
  1. 漏洞查找Agent的原始证据
  2. 对抗Agent的反驳理由
  3. 实际代码（客观事实）
对于关键严重程度的漏洞，优先采信漏洞查找Agent的结论（宁可信其有）。对低严重程度的项目则进行更严格的审查。

Final report format

最终报告格式

markdown
undefined
markdown
undefined

Final Bug Review — YYYY-MM-DD

最终漏洞审查报告 —— YYYY-MM-DD

Executive Summary

执行摘要

  • Confirmed real bugs: N
  • Dismissed as false positives: N
  • Critical issues requiring immediate attention: N
  • 已确认的真实漏洞：N
  • 已驳回的误报：N
  • 需要立即处理的关键问题：N

Confirmed Bugs

已确认的漏洞

BUG-001 — [Title]

BUG-001 —— [标题]

Severity: Critical / Medium / Low
Location: 
file:line
Finder's claim: [summary]
Skeptic's counter: [summary]
Arbiter's analysis: [reasoning]
VERDICT: REAL BUG
Confidence: High / Medium / Low
Action required: [what to do]
严重程度： 关键 / 中 / 低
位置： 
file:line
查找Agent的主张： [摘要]
对抗Agent的反驳： [摘要]
仲裁Agent的分析： [推理过程]
裁决：真实漏洞
可信度： 高 / 中 / 低
需采取的行动： [具体操作]

Dismissed (False Positives)

已驳回的漏洞（误报）

BUG-00N — [Title]

BUG-00N —— [标题]

VERDICT: NOT A BUG
Reason: [why it was dismissed]
裁决：非漏洞
理由： [驳回原因]

Prioritized Action List

优先级行动列表

  1. [Critical] BUG-XXX — [title]
  2. [Critical] BUG-XXX — [title]
  3. [Medium] BUG-XXX — [title] ...

---
  1. [关键] BUG-XXX —— [标题]
  2. [关键] BUG-XXX —— [标题]
  3. [中] BUG-XXX —— [标题] ...

---

Running the full pipeline

运行完整流程

When the user asks to run the bug review pipeline on a codebase:
  1. Identify scope — Confirm what files/directories to analyze
  2. Read relevant code — Load the target codebase files
  3. Run Phase 1 — Act as Bug Finder; produce the report
  4. Run Phase 2 — Act as Bug Adversary; challenge the report
  5. Run Phase 3 — Act as Arbiter; produce final verdicts
  6. Present results — Summarize the final confirmed bug list to the user
Tell the user upfront that the pipeline has three phases and give status updates as each completes.
Note: If the codebase is large (>50 files or >5,000 lines), consider running Phase 1 on focused subsystems (auth, data layer, API endpoints) rather than all files at once, to maintain analysis quality.
当用户要求在代码库上运行漏洞审查流程时：
  1. 确定范围 —— 确认要分析的文件/目录
  2. 读取相关代码 —— 加载目标代码库文件
  3. 运行阶段1 —— 扮演漏洞查找Agent，生成报告
  4. 运行阶段2 —— 扮演漏洞对抗Agent，质疑报告
  5. 运行阶段3 —— 扮演仲裁Agent，给出最终裁决
  6. 呈现结果 —— 向用户总结最终确认的漏洞列表
提前告知用户该流程包含三个阶段，并在每个阶段完成后更新状态。
注意： 如果代码库规模较大（超过50个文件或5000行代码），考虑针对重点子系统（身份验证、数据层、API端点）运行阶段1，而非一次性分析所有文件，以保证分析质量。

Tips for quality output

输出高质量结果的技巧

  • Cite exact line numbers whenever possible — vague locations reduce actionability
  • Include code snippets as evidence for non-obvious bugs
  • Rate impact in context — a SQL injection in an internal admin tool is still Critical, but a TOCTOU race on a read-only endpoint may be Low
  • Track bug IDs consistently across all three reports (BUG-001, BUG-002, etc.)
  • Don't merge bugs — if two related issues have distinct root causes, report them separately
For agent-specific instructions and scoring details, see the 
agents/
directory.
  • 尽可能引用精确的行号 —— 模糊的位置会降低可操作性
  • 包含代码片段 作为非明显漏洞的证据
  • 结合上下文评估影响 —— 内部管理工具中的SQL注入仍属于关键漏洞，但只读端点上的TOCTOU竞态条件可能属于低严重程度
  • 在所有三份报告中保持漏洞ID的一致性（BUG-001、BUG-002等）
  • 不要合并漏洞 —— 如果两个相关问题有不同的根本原因，请分别报告
有关Agent的具体说明和详细评分规则，请查看
agents/
目录。