ISA Recovery System

Un pipeline de rétro-ingénierie qui transforme un binaire de firmware et son désassemblage (éventuellement erroné) en une spécification de processeur Ghidra fonctionnelle. Lorsque vous rencontrez un processeur propriétaire sans documentation ni prise en charge Ghidra, cet outil retrouve le codage réel de chaque instruction — quels bits sont l'opcode, lesquels sont les registres, lesquels sont les valeurs immédiates — et génère une spécification SLEIGH que vous pouvez charger directement dans Ghidra pour décompiler le firmware.

Sous le capot, il s'agit d'un workflow agentique : un pipeline fixe où chaque étape est un grand modèle de langage sollicité pour une tâche précise. Le workflow est orchestré par du code déterministe — et non par les LLM eux-mêmes — et chaque constructeur SLEIGH généré à la fin est vérifié en le compilant avec le binaire sleigh de Ghidra avant d'être accepté. Les compilations échouées sont renvoyées au modèle pour jusqu'à trois tentatives de réparation.

Comment ça fonctionne

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

Les instructions sont regroupées en clusters selon leur structure (taille en octets, motif de jetons, masque de bits fixes). Chaque cluster est ensuite analysé par une chaîne d'étapes LLM spécialisées :

• Text Interpreter extrait le motif textuel (add {REG1}, {REG2}, {REG3}).
• Bit Interpreter fait correspondre chaque espace réservé à une plage de bits à l'aide d'outils de corrélation de champs ; il peut demander une scission si un cluster mélange des codages.
• Knowledge Manager intègre les preuves par cluster dans une base de connaissances typée des registres, instructions, modes d'adressage et caractéristiques d'architecture.
• Supervisor est avant tout un gardien déterministe (vérifications structurelles des taux de correspondance, des espaces réservés non mappés, du chevauchement des opcodes). Il n'invoque un LLM que lorsqu'une vérification échoue, et il peut soit accepter, relancer un agent spécifique avec des commentaires, soit escalader vers l'humain via la TUI.

Lorsque la base de connaissances est complète, un générateur SLEIGH séparé construit la spécification Ghidra en deux phases : un squelette déterministe de tous les constructeurs marqués unimpl, puis un LLM comble la sémantique p-code instruction par instruction, en compilant chacune avec le binaire sleigh de Ghidra et en réessayant en cas d'échec.

Conçu comme un copilote pour l'analyste, pas un remplaçant : la TUI expose chaque décision, le superviseur fait remonter les clusters ambigus à un humain, et l'historique complet des conversations LLM, des appels d'outils et de l'utilisation des jetons est écrit sur le disque.

Testé sur LEGv8, MIPS, pi32v2 et x86.

Démarrage rapide

# 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

Ce dont vous avez besoin (et ce que vous obtenez)

Entrée : un binaire de firmware et un désassemblage objdump — même un produit contre la mauvaise architecture. L'outil ne résout pas lui-même le problème du désassemblage ; la qualité de la sortie dépend de la qualité du désassemblage d'entrée.

Sortie : un fichier .slaspec Ghidra ainsi qu'une base de connaissances JSON des registres, des codages d'instructions, des modes d'adressage et des caractéristiques d'architecture.

Documentation

La documentation complète — architecture, internes des agents, exemples concrets, référence de configuration — se trouve dans le wiki :

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

Ouvrez ensuite http://localhost:8000.

Prérequis

• Python >= 3.11
• La variable d'environnement ANTHROPIC_API_KEY
• Docker (facultatif, pour run.sh)
• Ghidra (requis pour l'étape de compilation-vérification SLEIGH)