raptor Agent工作流

Prerequisites

• Claude Code with an active subscription (Max, Pro, Team, or Enterprise) or an Anthropic API key. This is the orchestration layer -- RAPTOR runs inside a Claude Code session.
• Python 3.10+ and Node.js 18+.
• Semgrep (pip install semgrep) for static analysis. CodeQL is optional but recommended.

For the analysis dispatch layer (the LLM that analyses individual findings), Claude Code itself handles everything by default -- no extra API keys needed. If you want multi-model analysis (e.g. Claude + GPT + Gemini), you will need API keys for each provider. See Using a different LLM below.

Install Python dependencies

pip install -r requirements.txt

Install Semgrep (required for scanning)

pip install semgrep

Option 1: Install manually

```bash

Install Claude Code (if you don't already have it)

npm install -g @anthropic-ai/claude-code

Quick Start

Option 2: Run in a container (recommended)

Using containers is a common security practice to restrict agents from accessing areas of your filesystem you don't want them to, as well as limiting the blast radius of any malicious code that may execute (e.g via supply-chain attack). The image is large (around 6 GB). It starts from the Microsoft Python 3.12 devcontainer and adds static analysis, fuzzing, and browser automation tooling.

You can pull down a pre-built image:

docker pull danielcuthbert/raptor:latest

or build it locally using the included Dockerfile:

docker build -f .devcontainer/Dockerfile -t raptor:latest .

The image expects the RAPTOR framework (this repo) to be mounted into /workspaces/raptor on startup. You can optionally mount a target folder for local analysis.

To start the container:

docker run -it \
  -v "$(pwd):/workspaces/raptor" \
  raptor:latest

To mount a target folder as well:

docker run -it \
  -v "$(pwd):/workspaces/raptor" \
  -v "/path/to/target-folder:/workspaces/target" \
  raptor:latest

Add --privileged if you need the rr deterministic debugger.

VS Code devcontainers are also supported. To mount a target folder, add it to the mounts section of .devcontainer/devcontainer.json:

"mounts": [
  // ...existing entries...
  "source=/path/to/target-folder,target=/workspaces/target,type=bind,consistency=cached"
]

Then open the repo in VS Code — it will prompt you to reopen in the container:

cd /path/to/raptor
code .

Either way, once you're inside the container, run raptor to get started.

---

How the pipeline works

Start by creating a project so all your runs land in one place:

/project create myapp --target /path/to/code   # create a project first
/project use myapp                             # set it as active
/understand --map                              # map the attack surface
/agentic --threat-model --validate             # map, model, scan, validate
/project findings                              # review everything in one place

For a compiled artefact, the equivalent starting point is:

/binary investigate /path/to/binary            # build the evidence-backed binary map
/binary graph <run-dir> --edges --json         # query the persisted graph
/binary trace-parser <run-dir>                 # collect runtime parser evidence
/binary harness <run-dir>                      # draft a harness only when the boundary is explicit

/understand builds a context map of entry points, trust boundaries, and sinks before a line of scanning happens. /agentic then runs Semgrep and CodeQL, deduplicates findings, and dispatches each one for validation using the exploitation-validator methodology:

With --threat-model, RAPTOR runs the map first, creates threat-model.json and THREAT_MODEL.md if the project does not already have them, then feeds a compact version into /understand, autonomous analysis, and /validate. Existing project threat models are preserved unless you pass --threat-model-refresh; stale fallback maps are refused unless you explicitly pass --threat-model-use-stale. It also turns mapped unchecked flows into candidate SARIF so scanner misses do not kill the run. It is operator-owned context, not magic proof: findings still need code evidence or oracle-backed confirmation. See docs/threat-model.md.

• Stage A: is the pattern actually a vulnerability, or is the tool pattern-matching noise?
• Stage B: what does an attacker need to reach it, and what gets in the way?
• Stage C: does the code path actually exist? can it be reached from outside?
• Stage D: final call -- is this test code, does it need unrealistic preconditions, is the model hedging?
• Stage E: binary exploit feasibility (when a compiled artefact is available)
• Stage F: self-review -- did any earlier stage hedge or contradict itself?

Findings that clear validation get exploit PoCs and patches generated. A cross-finding analysis runs at the end to find shared root causes and attack chains.

/validate runs this same pipeline as a standalone step if you already have findings from a previous scan.

For a compiled artefact, /binary <path> now runs an evidence-first investigation rather than dumping a pile of raw reverse-engineering artefacts on the operator. Underneath it still builds the SHA-256-bound manifest, evidence ledger, context map, checklist and SQLite graph from file metadata, imports and radare2 xrefs. Mach-O apps also get slice inventory, bundle metadata and Objective-C / Swift class selectors; high-value pseudocode is persisted rather than disappearing inside the run. PE DLL exports, Windows driver dispatchers and Linux kernel-module ioctl handlers are handled as their own ingress candidates too, with PE architecture read from the COFF header rather than guessed. The investigation layer then queries that graph, ranks external ingress before generic sink leads, discovers declared helper/sibling binaries, and writes a compact report split into facts, structural inferences and unproven hypotheses. Frida observations, fuzz crash witnesses, explicit Z3 checks and binary diffs can then add stronger evidence later. RAPTOR also keeps the internal call graph needed to recover bounded ingress-to-parser candidates, so an app callback can be narrowed to the internal function that actually calls XML_Parse, d2i_X509, jpeg_read_header or another real parser surface without pretending that is taint proof. /binary trace-parser <run-dir> is the explicit dynamic follow-on: it runs the narrow Frida parser trace, then refreshes the same context map, handoff, graph and investigation report in place. /binary investigate --active maps first and only launches a real fuzz campaign when a concrete harness boundary exists; app, DLL and driver targets get a harness or snapshot step instead. /binary harness writes an evidence-backed harness spec for the chosen ingress and only emits candidate source when the ABI or IOCTL contract is explicit. It does not blag its way from “memcpy exists” to “this is exploitable”: imports, selectors and call edges stay candidates until something mechanical proves more. See docs/binary-analysis.md.

---

Z3 SMT integration

RAPTOR has a two-layer Z3 integration (pip install z3-solver). It is optional. Everything works without it, but the results are better with it.

Dataflow pre-screening (CodeQL)

When CodeQL produces a path result, the path constraints are checked for satisfiability before any LLM call is made. Paths that are provably unreachable get dropped immediately. For paths that are reachable, Z3 produces concrete candidate inputs that go into the analysis prompt, so the LLM has something specific to reason about rather than abstract patterns.

One-gadget constraint analysis (binary feasibility)

During binary exploit feasibility assessment, Z3 checks whether a one-gadget's register and memory constraints are satisfiable against the concrete crash state. Gadgets are ranked by actual reachability rather than heuristics, so you spend time on gadgets that can actually work.

Z3 is pre-installed in the devcontainer. For manual installs: pip install z3-solver.

---

Running offline and in air-gapped pipelines

RAPTOR's custom rules under engine/semgrep/rules/ are fully local and run without network access.

For registry packs (p/security-audit, p/owasp-top-ten, etc.), the cache directory ships empty. A cache tool (engine/semgrep/tools/cache-packs.py) handles population:

```bash

the repo. (Alternatively, symlink bin/raptor into a directory already on PATH.)

export PATH="$PATH:$PWD/bin"