Raptor Loop Hunt

RAPTOR Auto-Research Vuln Hunt

A natural-language agent loop for security research. A generic "find bugs" prompt lets the model fall back to its defaults — single pass, mid-level altitude, converge fast, summarize, stop. Those defaults are wrong for vuln hunting. This skill replaces them with an explicit search procedure: traverse every altitude, generate then adversarially verify from raw, run isolated parallel reasoners, and keep a persistent ledger so each loop is net-new coverage instead of rediscovery.

The prompt is the program. In an agentic system the model's "algorithm" is whatever you tell it to be. This skill specifies that algorithm. Follow the structure; the quality comes from the structure, not from any single clever instruction.

When to use

Use for any "go deep / find everything / audit this thoroughly" security request against a codebase. Don't use for a quick triage, a single known-CVE reproduction, or a one-file sanity check — those want /scan or /understand --hunt directly. This is the heavy, looping, high-coverage mode.

The core loop

Run this as a loop, not a one-shot. Each round:

1. Pick an altitude and a slice you have not exhausted (see traversal below).
2. Generate candidate findings on that slice with an independent reasoner working

from raw source (no prior summaries in its context — summaries cause anchoring).

1. Judge each candidate with a separate reasoner, also from raw, prompted to refute.
2. Live-verify survivors against the actual code before they count (see guardrails).
3. Record everything tried and everything found in the ledger.
4. Vary the approach next round — new altitude, new bug-class lens, new slice. Novelty

is mandatory; repeating a round wastes budget.

1. Check the stop condition. Loop until dry, not literally forever.

Multi-altitude traversal (the coverage guarantee)

Different bug classes live at different zoom levels. A single-pass scan implicitly picks one altitude and is structurally blind to the others. Cover all four, in order, and revisit:

• Whole project — architecture, trust boundaries, auth model, data flows across modules.

Catches the broken-object-level-authz / IDOR / missing-authz class that dominates real web audits, plus deserialization sinks, SSRF, and design-level bypasses.

• File by file — each file's responsibilities, its inputs, its exported surface.
• Functionality by functionality — each feature end to end (upload, import, export,

templating, auth, admin actions). Trace source → sink for every bug class, not just the headline one. A mapped-but-untraced entry point is an uncovered entry point.

• Function by function — parsing, memory, encoding, length math, crypto comparisons,

format strings, integer handling. Line-level bugs only surface here.

Track which (altitude × slice) cells you've covered. The point of "start with the whole, then file by file, then functionality, then function" is that you sweep the whole grid, not one band.

Component inventory first — the completeness gate (MANDATORY)

Before round 1, enumerate the entire project as a flat list of components — every top-level module, package, service, transport, and deployable unit — not just the subsystems that look interesting. For a multi-module build, list every module directory (ls modules/, every Maven pom.xml, every top-level source package). This inventory is the denominator for coverage.

Then maintain a coverage matrix: every component maps to a hunt cell — now, or a named, logged later round. The hunt is not "done", and the report must not read as done, until every component is either covered or explicitly listed as omitted with a reason (out of scope, build-time-only tool, generated code, third-party vendored copy). Silent omission is the exact failure this gate prevents: slicing by hot-spots and quietly skipping whole modules (transports, databinding, the newer/less-audited modules) is how a shallow audit masquerades as a complete one — especially on a mature project that has had many issues over the years, where the unexamined module is often where the next bug lives.

Rules:

• The per-round slices must be drawn from the full inventory; you may prioritise, but every

component not yet assigned to a cell is recorded as UNCOVERED in TRIED.md — never absent from it. The ledger's component list must equal the project's component list.

• A component is the unit of accountability. "I audited the interesting parts" is not a complete

assessment. When the codebase is large, scale the number of rounds to cover all of it rather than narrowing the inventory to what is convenient.

• Re-run the enumeration when the target changes (new clone, new release) — modules get added

(e.g. a new protocol bridge, an OpenAPI/REST surface) and a stale inventory silently drops them.

The entrypoint manifest is the coverage SPINE (mechanical, not a hand list). A component list is too coarse — a route can fall between hand-picked cell anchors and be silently skipped (the miss: GET /users/:id/calendar-heatmap was never read because one cell listed six other controllers and another opened the file at the wrong route). Before scheduling cells, deterministically extract every externally-reachable entrypoint — controller routes (method, path, class+method decorators, inherited auth defaults, handler span), framework filesystem routes (e.g. SvelteKit +page.ts / +page.server.ts loads & actions), and statically-enumerable RPC/event handlers — each with a stable entry_id. A cell may claim coverage of an entrypoint only by recording its exact entry_id + handler span + effective audience/auth + primary callee + the boundary-scout check-ids run; opening one line in a controller does not cover the controller, and a wildcard "all routes covered" receipt is forbidden. Round closure fails when manifest_entry_ids − covered − approved_exceptions is non-empty — a deterministic diff, not a model "completeness critic" re-reading its own work. Keep hand-picked non-route anchors (repositories, background workers, parser/process sinks, state transitions) — routes are the spine, not the whole skeleton.

Deterministic front-load — cheap ground truth before the LLM loop (Round 0)

Deterministic tools are fast, hallucination-free, and refusal-free. Run them before the first LLM round and don't spend inference rediscovering what they already know:

• Cross-run Knowledge Base (kb/) — a MONOTONIC-SCRUTINY signal: it can only ever make you hunt MORE.

If this target was hunted before, a durable KB sits beside the ledger ($KB/kb.json). It stores no coverage and no "this is safe" signal; it can only raise scrutiny. Load it into the planner context only, AFTER you have freshly enumerated the whole inventory this run (the completeness gate below) into inv.txt: scripts/raptor-loop-kb load --kb "$KB" --target "" --inventory inv.txt

• Priority, never coverage. priority_order puts confirmed-dirty (a prior confirmed/corrected finding)

first, then prior-rejection components (recheck), then everything else. Every current_state is uncovered and nothing is ever deprioritized — historical work NEVER counts as current coverage and never pushes a component out of scope. Draw this run's slices from the fresh inventory; the KB only changes the order.

• Rejections are recheck ANNOTATIONS, never an exclusion. Each annotations[] entry says "previously

rejected for X — recheck X and ALL delivery vectors (path/query/body/cookie/header/enc)"; a stale one (tree changed since) reads "FULLY OPEN, recheck from scratch." The candidate still runs the full generate → judge → live-verify chain from raw — the annotation only tells you where to look harder.

• Round 0 is never skipped. The KB seeds /sca, inventory enumeration, prior-art recon, and mapping —

it does not replace them. New CVEs, new lockfiles, new advisories, and new modules are seen every run.

• Isolation (MANDATORY). The payload stays in the planner/orchestrator context. Never feed a prior

rejection or summary into the independent generator, judge, or live-verifier — they reason from raw source

• current scope. Injecting history re-creates the anchoring "Generate → judge, both from raw" prevents.
• Known-CVE deps (/sca). SBOM + dependency-CVE audit is deterministic and cheap. Run it

first, log the hits, and exclude those packages from the LLM hunt scope — the model's budget is for the bespoke bugs a scanner can't find, not for re-deriving a public CVE in a pinned dep.

• Native-target reachability ground truth (binary-oracle). For C/C++/Rust/Go targets with a

locally-built debug binary, the binary-oracle is deterministic reachability: it joins the source inventory to the binary via DWARF + nm and marks each function symbol_present / inlined / folded (survived compilation) or absent (compiler/linker removed it). It is auto-detected and on by default in /agentic and /codeql — pass --binary for an explicit build, --binary-auto for a louder auto-detect, --no-binary-oracle to disable, --target-kind library|hybrid|application for library/app targets. An absent verdict hard-suppresses the finding before the LLM ever sees it (logged to suppressions.jsonl); a symbol_present / inlined verdict is exactly what refutes a later "that's dead code" kill (see the reachability guardrail). This is deterministic dead-code ground truth — don't spend inference re-deriving it, and don't reject a native finding on a compiled-away claim the oracle can settle.

• Target's OWN known vulns + upstream fixes (prior-art recon) — MANDATORY, not optional. Pull

the TARGET application's history, not just its dependencies, BEFORE the LLM loop:

• Its CVE/GHSA record — OSV (POST https://api.osv.dev/v1/query {"package":{"name":..,"ecosystem":..}}),

NVD (keywordSearch=), gh api repos///security-advisories. Every past CVE names a vulnerable sink class + file; treat each as a post-fix variant re-audit lead (is the fix complete? does a sibling path / different delivery vector bypass it? is the sink still reachable?). It also calibrates severity — if the vendor/CVE process treated an authenticated/admin-area bug of class X as CVE-worthy before, don't dismiss your class-X finding as "admin-only, informational."

• Upstream open + recently-merged security PRs and recent security commits — gh pr list --state open,

gh search, git log ..HEAD -- , patch-diff ... An open or queued fix is a vendor-acknowledged live bug in the current release: seed it as a known-real finding, and NEVER reject a candidate that an upstream PR is actively fixing (this is exactly how a real finding gets wrongly killed — the vendor was patching it while the audit rejected it).

• Public PoC/exploit search — gh search repos/code , WebSearch exploit/PoC.

This is the standing "search existing PoCs / CVE-breadth" discipline applied to a FROM-SCRATCH AUDIT, not only to known-CVE reproduction. Skipping it means re-deriving — or wrongly rejecting — bugs the vendor already flagged. Log what you checked in TRIED.md as methodology evidence.

• STRIDE template (/threat-model build). One pass over the /understand --map recon that

yields trust boundaries, entry points, and a per-boundary STRIDE classification. Its output is a reusable template that seeds every later round's bug-class lenses — it tells the generators where privilege changes and which STRIDE class to hunt at each boundary. Recon and the threat model are infrastructure for the loop, not outputs — never report them as findings.

• Semgrep anchors seeded from the trust boundaries. Turn each threat-model trust boundary into

a Semgrep pattern and run those rules alongside the generators every round. Semgrep gives fast deterministic anchors at exactly the boundaries the threat model flagged; the LLM reasons about the semantics, data flow, and exploitability pattern-matching can't reach. The union of Semgrep hits and LLM candidates is the candidate pool (high recall, high noise — by design). A Semgrep hit is a lead, not a finding: it enters the same finding contract and the same from-raw judge as any LLM candidate. Keep Semgrep in the generator (recall) seat only — a pattern match never stands in for the judge.

Per-class discovery method (load when a bug-class lens is active)

The altitude traversal says where to look; references/vuln-class-discovery.md says how to find and confirm each vulnerability class, generically. For every bug-class lens a round runs, load that file's matching section and fill its five slots against the target — source class, sink class (by mechanism), violated invariant (the finding's root cause), enumeration strategy (derive the complete sink set from the inventory), confirmation oracle. Stack-agnostic by design; concrete signatures stay in the deterministic layer (Semgrep, /sca).

Generate → judge, both from raw

Separating generation from verification is the single biggest quality lever:

• The judge kills false positives — independent skeptic, prompted to refute. It defaults to

"not a bug" only when the defect itself is uncertain (the code path isn't real, the entry isn't attacker-controlled, the sink isn't dangerous). It does not default to "not a bug" because some unobserved layer might mitigate it — see below.

• The act of re-reading from raw to verify surfaces new findings the generator missed.
• "From raw" is load-bearing. A judge that reads the generator's summary rubber-stamps it.

A judge that reads the source re-examines it. Always feed the judge the code, not the claim.

What counts as a valid refutation (and what doesn't). The judge may only kill or downgrade a finding for a reason it can see in the artifacts:

• VALID: the cited code doesn't do what the claim says; the entry point isn't attacker-reachable;

a mitigating check is present in code you can read; it's designed behavior under the established trust model.

• INVALID: "a well-built server probably enforces this," "the framework likely handles it,"

"presumably there's authz upstream," "the server surely re-hashes/re-validates." Assuming an unseen layer is secure is not refutation — it is the single most common false-negative in this methodology. The whole reason for the test is that the unseen layer might be broken. Don't assume the unseen layer is secure.

• INVALID (reachability / gating): "that component isn't built/loaded," "it needs a non-default

config," "it's behind a flag," "the trigger needs an impractical number of iterations" — asserted without checking. A reachability or gating claim kills a finding, so it carries the finding's own proof burden: verify it against the observable build + default config (the build flag, whether a default deployment exposes the entry point, the real trigger path) before it counts as refutation. A capability that ships and is enabled by default is in scope even when it's packaged as an optional-looking "module" or "plugin." Don't assume the gate is closed. For native (C/C++/Rust/Go) targets, the binary-oracle mechanizes exactly this check: an absent verdict is an observed dead-code reject (the function isn't in the shipped binary), while symbol_present / inlined / folded refutes a "compiled away / dead code" kill — so a compiled-away claim is only a valid refutation when the oracle (or an equivalent DWARF/nm check on the actual build) confirms it, never on assertion.

When the only barrier between a finding and e

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dinosn
• Source: dinosn/raptor-loop-hunt
• License: MIT

Install and usage instructions live in the source repository linked above.