auto-re-agent

auto-re-agent is an open-source AI reverse-engineering agent that uses Ghidra and LLMs—including Claude, Codex, and OpenAI-compatible models—to reconstruct and validate C/C++ functions from compiled binaries. It combines independent reverser/checker models, agentic evidence gathering, candidate build and test gates, structural verification, and parity analysis in one autonomous workflow.

Original pre-0.2 demo: YouTube

What it does

re-agent reverse --class CTrain
    │
    ├── Configuration (YAML + supported environment overrides + CLI flags)
    ├── Function selection (dependency-order | easiest-first | high-impact)
    ├── Source and binary context
    │   ├── decompile, xrefs, structs, enums, vtables, globals, and strings
    │   └── normalized high P-code, CFG, assembly, and nearby project source
    ├── Reverser → checker → fix loop (bounded rounds and investigations)
    ├── Conservative structural verifier
    ├── Candidate overlay
    │   └── configured build, test, and runtime gates
    ├── Candidate parity gate (GREEN | YELLOW | RED)
    └── Reports, per-call logs, round checkpoints, session history, and knowledge graph

The tool generates candidate C/C++ implementations; it does not patch the original source tree automatically. A successful reversal can require four independent conditions:

1. the LLM checker returns PASS;
2. the objective verifier finds no strong structural mismatch;
3. candidate validation satisfies the configured acceptance policy;
4. parity is not blocked by the configured RED/YELLOW policy.

This is conservative verification, not a proof of semantic equivalence.

New in 0.3.0

Build, test, runtime, differential and semantic-rule failures now return to the repair loop. Class validation can compose accepted functions in an isolated scratch project (copy_project: true, cumulative_validation: true).

• re-agent doctor --address ADDR checks setup before model calls.
• re-agent benchmark --manifest cases.json --output result.json compares JSON harnesses.
• backend.type: ghidra-json reads structured exports directly using backend.export_dir and an optional backend.address_map; it requires no bridge executable.
• project_profile.compilation_database enables optional Clang AST indexing.
• orchestrator.max_llm_calls_per_function bounds all reverser/checker calls together.
• Sessions retain round diagnostics and archive completed state when fingerprinted inputs change.

See migration and configuration, release validation, the GTA differential adapters, and the changelog.

Requirements

• Python 3.10+
• Git, for the current source installation
• Ghidra plus a configured ghidra-ai-bridge
• At least one LLM setup:
  • Claude API: ANTHROPIC_API_KEY
  • OpenAI-compatible API: OPENAI_API_KEY
  • Claude CLI: an authenticated local claude command
  • Codex CLI: an authenticated local codex command

Installation

Install the agent and its Ghidra query bridge from PyPI:

python3 -m pip install --upgrade "auto-re-agent[ghidra-bridge]>=0.3.0"

For headless Ghidra exports, install the bridge with its PyGhidra extra:

python3 -m pip install --upgrade "auto-re-agent[headless]>=0.3.0"

To install the latest development versions directly from GitHub instead:

python3 -m pip install --upgrade \
  "ghidra-ai-bridge @ git+https://github.com/Dryxio/ghidra-ai-bridge.git@main" \
  "auto-re-agent @ git+https://github.com/Dryxio/auto-re-agent.git@main"

Set up Ghidra evidence

Run these commands from the project you want to reverse:

# Create ghidra-bridge.yaml, then edit its Ghidra project/program paths
ghidra-bridge init

# Requires the bridge headless extra and a local Ghidra installation
ghidra-bridge export all

# Optional but recommended when reversed source/hook patterns are available
ghidra-bridge build-map

# Confirm that exports and configuration are visible
ghidra-bridge info

See the bridge documentation for its Ghidra, export, and source-map configuration.

Quick start

Create a configuration in the target project:

# Recommended portable default
re-agent init --profile generic-cpp

# Other available profiles
# re-agent init --profile windows-x64
# re-agent init --profile gta-reversed
# re-agent init --profile openrct2

Running re-agent init without --profile preserves the original GTA-reversed defaults. Prefer an explicit profile for new projects.

Then edit re-agent.yaml. At minimum, select an LLM, point the backend at the installed bridge executable, set the source paths, and configure validation.

llm:
  provider: claude-cli
  model: sonnet

# Optional: use a different provider/model for checking.
agents:
  checker:
    provider: codex
    model: gpt-5.4

backend:
  type: ghidra-bridge
  cli_path: ghidra-bridge

project_profile:
  name: generic-cpp
  language_standard: C++20
  source_root: src
  hooks_csv: null

orchestrator:
  max_review_rounds: 4
  investigation_enabled: true
  max_investigations: 8
  selection_strategy: dependency-order
  max_attempts_per_function: 3

validation:
  enabled: true
  copy_project: true
  project_root: .
  build_commands:
    - cmake -S . -B build
    - cmake --build build
  test_commands:
    - ctest --test-dir build --output-on-failure
  require_build: true
  require_tests: true
  require_verified: true
  # This explicitly attests that the project-owned shell commands above are
  # meaningful validation gates. Leave false for untrusted commands.
  trust_configured_commands: true
  keep_project_copy: false
  parity_fail_on_red: true
  parity_fail_on_yellow: false

Validation is deliberately strict: with the generated defaults, no configured commands produce UNKNOWN, and require_verified: true rejects that result. For exploration without build validation, explicitly set validation.enabled: false; such results are not build-verified.

Start with one function before launching a class run:

re-agent reverse --address 0x401000
re-agent reverse --class CTrain --max-functions 10
re-agent status

LLM providers

Claude API

llm:
  provider: claude
  model: claude-sonnet-4-5-20250929

Set ANTHROPIC_API_KEY or RE_AGENT_LLM_API_KEY.

Claude CLI

Authenticate the local Claude Code CLI first, then configure:

llm:
  provider: claude-cli
  model: sonnet
  cli_path: claude
  effort: high
  max_budget_usd: 1.0

Claude CLI supports real session resume and reports usage/cost metadata. A stale CLI login can still require re-authentication even when its auth-status command reports a session.

OpenAI-compatible APIs

llm:
  provider: openai # or openai-compat
  model: your-model
  base_url: https://your-endpoint.example/v1 # optional

Set OPENAI_API_KEY or RE_AGENT_LLM_API_KEY.

Codex CLI

llm:
  provider: codex
  model: gpt-5.4

Codex uses the authenticated local codex exec command. CLI-provider max_tokens values are planning allowances, not hard output limits.

Omit agents.reverser or agents.checker to reuse the top-level llm configuration for that role. A role block is a complete role configuration, not a field-by-field merge with llm.

Evidence and investigation

When supported by the backend, the reverser preloads a bounded evidence bundle and can request additional read-only operations:

• decompile, xrefs_from, and xrefs_to
• struct and enum
• vtable, global, and strings
• context, normalized pcode, and cfg

Evidence bundle data is also ingested into reports/re-agent/knowledge-graph.json, connecting functions, calls, globals, and strings. Unsupported bridge capabilities degrade gracefully.

Candidate validation

Generated code is written to an overlay. With copy_project: true, the project is copied to a temporary directory, the candidate replaces the matching body there, and commands run from that copy. .git, .venv, build, reports, and Python cache files are not copied. Internal symlinks are remapped into the copy; external or broken links are rejected. Temporary project copies are deleted unless keep_project_copy: true.

Commands may use:

• {candidate_file}, {overlay_root}, and {source_file} placeholders;
• RE_AGENT_CANDIDATE_FILE, RE_AGENT_OVERLAY_ROOT, and RE_AGENT_SOURCE_FILE environment variables.

Configured build/test/runtime commands are arbitrary project-owned shell commands. The agent cannot prove from their text that they actually validate a candidate, so they only become acceptance evidence when trust_configured_commands: true is set explicitly.

If multiple C++ definitions match an overloaded method and the source cannot be disambiguated, the overlay is rejected instead of replacing an arbitrary body.

Verification and parity

The objective verifier runs on each review round. It compares generated code with available decompile, assembly, CFG, and normalized high P-code evidence. It returns FAIL only for strong mismatches; insufficient evidence returns UNKNOWN.

The reversal pipeline runs the 11 built-in heuristic parity signals and configured semantic rules against the generated candidate body on every round. RED is blocking by default; YELLOW can be made blocking with `vali