ISA Recovery System

A reverse-engineering pipeline that turns a firmware binary and its (possibly-wrong) disassembly into a working Ghidra processor specification. When you hit a proprietary processor with no documentation and no Ghidra support, this tool recovers the real encoding of each instruction — which bits are the opcode, which are registers, which are immediates — and writes out a SLEIGH spec you can load directly into Ghidra to decompile the firmware.

Under the hood it is an agentic workflow: a fixed pipeline where each step is a large language model prompted for a narrow job. The workflow is orchestrated by deterministic code — not by the LLMs themselves — and every SLEIGH constructor generated at the end is verified by compiling it with Ghidra's sleigh binary before being accepted. Failed compilations are fed back to the model for up to three repair attempts.

How It Works

Objdump
   │
   ▼
Bootstrap ─── deterministic clustering (no LLM)
       │
       ▼
   ┌─ Processing Loop ──────────────────────────┐
   │  Text Interpreter → Bit Interpreter ──┐    │
   │       → Knowledge Manager             │    │
   │            → Supervisor               │    │
   │                 │          split ─────┘    │
   │                 └── next cluster ──────────┤
   └────────────────────────────────────────────┘
       │
       ▼
   Knowledge Base
       │
       ▼
   SLEIGH Generator ─── compile-verify-retry loop
       │
       ▼
   Ghidra .slaspec

Instructions are grouped into clusters by structure (byte size, token pattern, fixed-bit mask). Each cluster is then analyzed by a chain of specialized LLM steps:

• Text Interpreter extracts the text pattern (add {REG1}, {REG2}, {REG3}).
• Bit Interpreter maps each placeholder to a bit range using field-correlation tools; can request a split if a cluster mixes encodings.
• Knowledge Manager integrates per-cluster evidence into a typed knowledge base of registers, instructions, addressing modes, and architecture traits.
• Supervisor is primarily a deterministic gatekeeper (structural checks on match rates, unmapped placeholders, opcode overlap). It only invokes an LLM when a check fails, and it can either accept, re-run a specific agent with feedback, or escalate to the human via the TUI.

When the knowledge base is complete, a separate SLEIGH generator builds the Ghidra spec in two phases: a deterministic skeleton of all constructors marked unimpl, then an LLM fills in the p-code semantics one instruction at a time, compiling each against Ghidra's sleigh binary and retrying on failure.

Designed as a co-pilot for the analyst, not a replacement: the TUI exposes every decision, the supervisor escalates ambiguous clusters to a human, and the full LLM conversation, tool-call, and token-usage history is written to disk.

Tested on LEGv8, MIPS, pi32v2, and x86.

Quick Start

# Docker (recommended)
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
./docker/run.sh integration_tests/mips

# Local
pip install -e ".[all]"
python -m main --config config.yaml

What You Need (and What You Get)

Input: a firmware binary and an objdump disassembly — even one produced against the wrong architecture. The tool does not solve the disassembly problem itself; output quality scales with input disassembly quality.

Output: a Ghidra .slaspec file plus a JSON knowledge base of registers, instruction encodings, addressing modes, and architecture traits.

Documentation

Full documentation — architecture, agent internals, worked examples, configuration reference — lives in the wiki:

pip install -e ".[docs]"
cd wiki && mkdocs serve

Then open http://localhost:8000.

Requirements

• Python >= 3.11
• ANTHROPIC_API_KEY environment variable
• Docker (optional, for run.sh)
• Ghidra (required for the SLEIGH compile-verify step)