Multi-agent workflow (tracer/resolver/bypass) for secure code review, exploitability triage, and PoC validation in codebases. Use when conducting structured security research or penetration test analysis.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Multi-agent workflow (tracer/resolver/bypass) for secure code review, exploitability triage, and PoC validation in codebases. Use when conducting structured security research or penetration test analysis.
Multi-Agent Security Review
Purpose
This skill defines a coordinated, role-based workflow for finding and validating security issues in codebases. It emphasizes source-to-sink reasoning, explicit gate verification, and only reporting exploitability chains that are demonstrably reachable.
The workflow mirrors a research team:
Tracer maps sources → transformations → sinks, and flags gates.
Resolver evaluates gates and control flow completeness.
Bypass proves exploitability with safe PoCs.
Guardrails
Operate only within explicit scope and permissions.
Prefer non-destructive PoCs and safe payloads.
If a link is hypothetical, label it and keep it out of final findings.
Maintain a chain-of-exploitation log for every candidate issue.
Roles
Primary Agent (You, the human‑facing session)
Owns scope, tasking, and the final report. Aggregates findings, resolves contradictions, and decides what is “real.” This is the agent the user is talking to.
Tracer
Enumerates sources and dangerous sinks, builds candidate chains, and stops at gates it cannot confirm.
Resolver
Evaluates gate logic and control flow. Determines whether input can cross a boundary in practice.
Bypass
Turns a confirmed chain into a reproducible PoC (safe, minimal, and verifiable).
Script Orchestrator (runner output)
The run-multi-agent-review.sh script produces an orchestrator.md file at the end. That file is an automated merge of tracer/resolver/bypass outputs and is the same as the Primary Agent. The Primary Agent should still read and curate that output before final reporting.
not
Coordination Model
Use independent Pi runs for isolation of analysis paths. The Primary Agent owns the sequence and spawns each role as a separate pi process (via pi_run or an SDK session) so each role has a clean context.
Dependency: This workflow expects the pi_run tool to be available (provided by the pi-self extension). If it is missing, interrupt and tell the user to load it, and note that it is bundled in the same pi-skills repo as this skill (avoid downloading arbitrary third-party code to satisfy the dependency).
Recommended approach (programmatic spawning):
Primary Agent defines scope, targets, and expected sinks.
Primary Agent spawns Tracer via pi_run (or SDK createAgentSession).
Tracer enumerates sinks and builds source→sink chains, then produces a Resolver task list for gate verification.
Primary Agent spawns a Resolver per task, writing to resolver-<task-id>.md.
Resolver analyzes gates and control-flow completeness, then produces a Bypass task list for exploitability validation.
Primary Agent spawns a Bypass per task, writing to bypass-<resolver-id>--<bypass-id>.md.
The script orchestrator (runner) can merge outputs into orchestrator.md, but the Primary Agent still curates and emits the final report.
Handoff format (required):
Role: <Tracer|Resolver|Bypass>
Target: <file/module/subsystem>
Summary: <1–3 sentences>
Evidence: <file paths, line ranges, or code references>
Open Questions: <what you could not verify>
Next Actions: <what you recommend>
Workflow (End-to-End)
Automation Hook (Runner from cold)
This skill ships with a runner script at:
~/.pi/agent/skills/multi-agent-security-review/run-multi-agent-review.sh
It supports --parallel <n> to run resolver and bypass tasks concurrently.
Guidance: start with --parallel 2 or --parallel 4 on laptops, and use min(available CPU cores, number of tasks) on larger machines. Avoid setting it so high that it starves your main session or hits provider rate limits.
From a cold session, run it from the repo root (or copy it into the repo as security-review/run-multi-agent-review.sh and chmod +x it). It will spawn tracer → resolver → bypass → orchestrator as independent pi runs and write outputs to security-review/<run-id>/.
Decide batch size before you run anything. If the scope spans multiple major components or languages, split into separate runs. Indicators that you should split:
Multiple top-level products/services (e.g., web UI, native core, backend service).
Distinct trust models (client UI vs server processing vs local SDKs).
Mixed languages/toolchains or very large directories.
The tracer would need to read unrelated contexts to build chains.
You can’t clearly describe a single threat model that covers everything.
Default rule: if you think “this is a lot of context,” it is. Run separate tracers per logical component and only merge at the correlation step.
If splitting, run one tracer per component and keep outputs in separate security-review/<run-id>/ folders; merge findings during correlation.
Establish a shared notes location (repo-local security-review/<run-id>/ folder).
Use independent pi runs for each role and persist outputs as:
Use this after the multi-agent runs complete to promote parking-lot items and produce a final report. This is the exact workflow used in practice and is designed for a cold Primary Agent with no project context.
6) Final Report Drafting (Before Sink Report)
Create a single final report that the user can rely on without reading the raw tracer/resolver/bypass outputs. This report is the authoritative artifact for validated findings and high‑level risk themes.
Purpose
Provide a clean, curated summary of what is real vs. unverified.
Explain cross‑component risk threads (trust‑boundary violations, SSRF, DOM sinks, etc.).
Make preconditions explicit so operational teams can assess exposure.
Inputs
orchestrator.md from each run (for raw merged findings).
Tracer/Resolver/Bypass outputs for evidence and gate validation.
Any external threat context provided by the user (e.g., competitor post).
Process
Validate before you write: Read each orchestrator.md and treat all items as unverified until you personally confirm the source → gate → sink chain in code. Use grep/read to trace the path and verify trust boundaries. Promotion to “Validated” is a Primary Agent responsibility, not the runner’s.
Collect evidence: For each candidate issue, follow the chain from source → transform → sink. Only promote if the trust boundary is clear and gates are verified.
Parking‑lot: plausible but unverified (missing trust boundary or gate proof).
Capture preconditions: note configuration defaults, endpoint exposure, and auth/claim requirements that affect exploitability.
Correlate across components: identify shared choke points (e.g., annotation JSON → web DOM, URL fetch policies across services).
Draft the report with this structure:
Executive summary (1–2 paragraphs).
Correlated threads (bullets with brief explanations).
Validated findings (each with why promoted + impact + preconditions).
Parking‑lot findings (short; include next validation steps).
Recommended next validation pass.
Appendix with evidence references (files/functions/line ranges).
Maintain traceability: Every finding must list evidence that can be opened directly by an engineer.
Output
Write to security-review/final-report.md.
Make it readable in isolation (no reliance on internal notes).
7) Sink Report (Final Step — Post-Final-Report)
Create a sink report after the final report is drafted. The sink report is a focused, high‑level guide for developers and security engineers that highlights the top sinks of concern per component. It is not a vulnerability list; it is a maintenance map that shows where future changes are most likely to introduce security risk.
Purpose
Provide a concise list of the most sensitive sinks (DOM insertion, network fetch, filesystem, command exec).
Show how data reaches each sink with a simple architecture view.
Equip developers to recognize “gotcha” areas during refactors or feature additions.
Required inputs
Tracer outputs for each component (security-review/<run-id>/tracer.md).
Any final report notes to confirm confirmed vs parking‑lot status.
Method (Cold‑Start Playbook)
Read each tracer report and extract the sinks called out in the Summary/Evidence sections.
Group sinks by component (e.g., web UI, core rendering, server backend).
For each component, build a high‑level data‑flow diagram in Mermaid:
Show primary ingress points (e.g., annotations/Instant JSON, URL params, HTML generation payloads).
Show transformation chokepoints (deserialization, parsing, policy checks).
End the diagram at the sink (DOM insertion, network fetch, filesystem write, command execution).
Write the “Top Sinks of Concern” list for each component:
Keep it concise (3–6 items per component).
For each sink, explain why it’s sensitive, and what change patterns are risky.
Call out any important guardrails (sanitizers, allowlists, permissions, or default settings) that make the sink safer or more dangerous.
Mermaid hygiene (important):
Use quoted labels and <br/> for line breaks (GitHub Mermaid is strict).
Escape literal HTML in labels (e.g., use <>).
Add evidence references (file paths and line ranges) for each top sink so engineers can jump to code quickly.
Output
Write to security-review/sink-report.md.
Include Mermaid diagrams and a short summary section per component.
Close with a compact evidence list per component.
Quality bar
The sink report should be actionable for developers even without reading the full security review.
It should be clear where untrusted data enters, where it is transformed, and where it finally lands.
It should emphasize maintenance risk: “if you change this area, you can accidentally re‑introduce X.”
A. Gather outputs
Identify the run folders under security-review/<run-id>/ for each component (web/core/docengine). If the scope is broad, run separate tracers per component and keep outputs separate.
Read the orchestrator.md for each run to collect:
Validated findings
Parking‑lot candidates
Evidence paths/line ranges
Create a working summary (notes or a new report file) that lists each parking‑lot item with its suspected source and sink.
B. Validate parking‑lot items
4. For each parking‑lot item, trace source → sink manually using grep and read:
