Sistema di Recupero ISA

Una pipeline di reverse-engineering che trasforma un binario di firmware e il suo disassembly (possibilmente errato) in una specifica funzionante del processore per Ghidra. Quando ti imbatti in un processore proprietario senza documentazione e senza supporto in Ghidra, questo strumento recupera la codifica reale di ogni istruzione — quali bit sono l'opcode, quali sono i registri, quali sono gli immediati — e scrive una specifica SLEIGH che puoi caricare direttamente in Ghidra per decompilare il firmware.

Sotto il cofano è un workflow agente: una pipeline fissa in cui ogni passaggio è un modello linguistico di grandi dimensioni a cui viene chiesto un compito circoscritto. Il workflow è orchestrato da codice deterministico — non dai LLM stessi — e ogni costruttore SLEIGH generato alla fine viene verificato compilandolo con il binario sleigh di Ghidra prima di essere accettato. Le compilazioni fallite vengono restituite al modello per un massimo di tre tentativi di riparazione.

Come Funziona

Objdump
   │
   ▼
Bootstrap ─── clustering deterministico (senza LLM)
       │
       ▼
   ┌─ Ciclo di Elaborazione ────────────────────┐
   │  Text Interpreter → Bit Interpreter ──┐    │
   │       → Knowledge Manager             │    │
   │            → Supervisor               │    │
   │                 │          split ─────┘    │
   │                 └── prossimo cluster ──────┤
   └────────────────────────────────────────────┘
       │
       ▼
   Knowledge Base
       │
       ▼
   SLEIGH Generator ─── ciclo compila-verifica-riprova
       │
       ▼
   Ghidra .slaspec

Le istruzioni sono raggruppate in cluster in base alla struttura (dimensione in byte, pattern di token, maschera di bit fissi). Ogni cluster viene poi analizzato da una catena di passaggi LLM specializzati:

• Text Interpreter estrae il pattern testuale (add {REG1}, {REG2}, {REG3}).
• Bit Interpreter mappa ogni segnaposto a un intervallo di bit usando strumenti di correlazione dei campi; può richiedere una suddivisione se un cluster mescola codifiche diverse.
• Knowledge Manager integra le prove per singolo cluster in una knowledge base tipizzata di registri, istruzioni, modalità di indirizzamento e tratti architetturali.
• Supervisor è principalmente un gatekeeper deterministico (controlli strutturali sui tassi di corrispondenza, segnaposto non mappati, sovrapposizione di opcode). Invoca un LLM solo quando un controllo fallisce e può accettare, rilanciare un agente specifico con feedback, o escalare al fattore umano tramite la TUI.

Quando la knowledge base è completa, un generatore SLEIGH separato costruisce la specifica Ghidra in due fasi: uno scheletro deterministico di tutti i costruttori marcati unimpl, poi un LLM riempie la semantica p-code un'istruzione alla volta, compilando ciascuna contro il binario sleigh di Ghidra e riprovando in caso di errore.

Progettato come co-pilota per l'analista, non un sostituto: la TUI espone ogni decisione, il supervisor scala i cluster ambigui a un essere umano e l'intera cronologia delle conversazioni LLM, delle chiamate agli strumenti e dell'uso dei token viene scritta su disco.

Testato su LEGv8, MIPS, pi32v2 e x86.

Avvio Rapido

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

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

Cosa Ti Serve (e Cosa Ottieni)

Input: un binario di firmware e un disassembly objdump — anche uno prodotto contro l'architettura sbagliata. Lo strumento non risolve da solo il problema del disassembly; la qualità dell'output scala con la qualità del disassembly in ingresso.

Output: un file Ghidra .slaspec più una knowledge base JSON di registri, codifiche di istruzioni, modalità di indirizzamento e tratti architetturali.

Documentazione

La documentazione completa — architettura, internals degli agenti, esempi pratici, riferimento di configurazione — vive nella wiki:

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

Poi apri http://localhost:8000.

Requisiti

• Python >= 3.11
• Variabile d'ambiente ANTHROPIC_API_KEY
• Docker (opzionale, per run.sh)
• Ghidra (richiesto per il passaggio di compilazione-verifica SLEIGH)