The 6-Phase Pipeline

Understand the application before hunting. Three agents map it from different angles, then their output is synthesized into architecture.md.

• 1a — Overview, tech stack, and a comparable baseline to calibrate against.
• 1b — Trust boundaries, authentication, authorization, privilege separation, bypass mechanisms.
• 1c — Exhaustive inventory of every place untrusted input enters the system.
• architecture.md is injected verbatim into every Phase 2 agent prompt.

Many general agents attack the codebase concurrently, each owning an attack class and/or subsystem. They think like an attacker, not a code reviewer.

• 3–4 agents for a small library; 8–12+ for a large app — split by attack class AND subsystem.
• Each prompt carries the architecture summary, an attack class, starting file paths, the hunting methodology, and the validation rules.
• A hunter can fork a focused research sub-agent to go deep on a subsystem instead of overflowing its own context.

Consolidate duplicates first, then a different agent tries to DISPROVE each finding. Hunters are biased to find; validators are biased to kill false positives.

• Exploitation test — read the actual code; can you construct the exact triggering input?
• Impact test — what does the attacker actually get? "Learns field names" is LOW at best.
• Baseline / mitigation / parser-runtime tests — does another layer already stop it? Verify against the spec, don't reason from intuition.

Two human-readable documents. Keep them short: if the report is longer than the codebase deserves, it's padding.

• REPORT.md — exec summary, baseline comparison, findings table, hardening notes, and what the code does well.
• FINDINGS-DETAIL.md — for every MEDIUM+ finding: full data flow with file:line, exact requests, what the attacker gets.
• Naming what's solid builds trust in the findings you do report.

Every surviving finding becomes a JSON object conforming to report-schema.json, then validate-findings.cjs checks it structurally.

• additionalProperties:false is enforced — extra fields make the output invalid.
• If you can't fill trace with real, source-verified file paths and line numbers, the finding isn't verified enough.
• The validator is a structural check only — factual correctness is Phase 6's job.

The agent that wrote the finding can't catch its own blind spots. A fresh agent re-reads the source and checks every factual claim. This is the final quality gate — do not skip it.

• Verify every trace step: the file exists, the line matches, the scope (function) is right, the description is accurate.
• Verify the payloads would actually work, conditions are complete, and the remediation wouldn't break normal functionality.
• Reconcile REPORT.md and findings.json so the prose and the machine output never disagree.