---

## Cos'è

L'analisi automatica di IDA Pro è a thread singolo. Su una DLL il2cpp da 34 MB ci vogliono *minuti*. spectrIDA divide il binario in N frammenti, li esegue in parallelo tramite idalib, li unisce in un unico `.i64`, e poi lascia che un modello 8B messo a punto **dia un nome a ogni funzione** — tutto da un'unica interfaccia terminale con tema cyberpunk e la giusta dose di sarcasmo.

Questo è il Capitolo 1, e regge da solo: pura velocità, nessuna IA richiesta se non la si vuole.

Il Capitolo 2 trasforma l'output in qualcosa che sopravvive alla sessione — un grafo Neo4j in cui un client MCP (Claude, [pi](https://pi.dev), qualunque cosa parli MCP) può realmente vivere, invece di dover copiare e incollare l'output del decompilatore in una finestra di chat una funzione alla volta:```
Binary  ─▶  Parallel IDA Analysis  ─▶  Demangle  ─▶  AI Naming  ─▶  Neo4j Graph  ─▶  MCP Server  ─▶  Claude
              (N idalib shards)       (free, real)   (stripped     (persists,        (search/chain/
                                                       leftovers     forever,          rename, live)
                                                       only)         across sessions)

Requisiti: **IDA Pro 9.x** with idalib · **Python 3.10+** · **Ollama**```bash
# install Ollama (Windows)
winget install Ollama.Ollama

# pull the model (8.7 GB — go get coffee)
ollama pull hf.co/gdfhhjk/spectrida-re-gguf:latest

# first run — detects your IDA install and sets everything up
spectrida onboard

# or just try the demo right now
spectrida --demo

---

## Tasti TUI

| Tasto | Azione |
|-------|--------|
| `N` | Assegna nome alla funzione selezionata — AI trasmette il risultato in tempo reale |
| `R` | Rinomina — precompilato con il suggerimento dell'AI |
| `D` | Attiva/disattiva pseudocodice decompilato (Hex-Rays) |
| `C` | Catena di chiamate — chiamanti e chiamati |
| `B` | Assegna nome in batch a tutte le funzioni `sub_*` nell'elenco corrente |
| `O` | Panoramica — riepilogo AI dell'intero binario |
| `/` | Ricerca fuzzy |
| `?` | Aiuto |
| `Q` | Esci |

---

## API programmatica

Niente TUI necessario — guida spectrIDA da script, Claude Code, notebook, qualsiasi cosa:```python
import asyncio
from spectrida.api import open_i64

async def main():
    async with open_i64("GameAssembly.i64") as db:

        # list all 153k functions
        funcs = await db.list_functions()

        # name one function — returns name + reasoning + confidence
        result = await db.name_function(0x10001000)
        print(result["new_name"])     # init_atexit_handler
        print(result["reasoning"])    # allocates array of 3 fn ptrs, calls _atexit...

        # batch name everything (with live progress)
        async def on_progress(done, total, r):
            print(f"  {done}/{total}  {r['old_name']} -> {r['new_name']}")

        await db.batch_name(limit=500, rename=True, progress_cb=on_progress)

        # ask what the binary does
        overview = await db.overview()
        print(overview)

        # export to IDA script
        await db.export("names.idc", fmt="idc", named_only=True)

asyncio.run(main())

Override delle variabili d'ambiente: `SPECTRIDA_IDALIB` · `SPECTRIDA_MODEL` · `SPECTRIDA_WORKERS` · `SPECTRIDA_OLLAMA_URL`

---

## Aggiungere un nuovo formato binario

Il supporto dei formati è un sistema a plugin, non un ammasso di rami if/elif — PE, NSO e ELF sono tutti semplicemente file sotto `spectrida/analysis/formats/`, scoperti automaticamente. Esegui `spectrida formats` per vedere cosa è attualmente registrato.```bash
$ spectrida formats
ELF        spectrida.analysis.formats.elf.ELFHandler
NSO        spectrida.analysis.formats.nso.NSOHandler
PE         spectrida.analysis.formats.pe.PEHandler
generic    spectrida.analysis.formats.generic.GenericHandler

@staticmethod
def sniff(header: bytes, path: str) -> bool:
    return header[:4] == b"MYF0"          # however you recognize the format

def prepare(self, path: str, workdir: str) -> PreparedImage:
    # Format idalib already loads natively (ELF, PE, Mach-O)? Just parse
    # the section/segment table — return the original path unchanged.
    return PreparedImage(
        binary_path=path,
        image_base=0,
        sections=[Section(name=".text", va=0x1000, raw_off=0x400,
                           raw_size=0x2000, vsize=0x2000, is_code=True)],
        arch=None,        # set "x86_64"/"arm64" only if IDA can't detect it itself
    )

# Only needed if idalib has NO native loader for this format (NSO is the
# example): do any manual idaapi/ida_segment setup here, called right
# after idapro.open_database() succeeds, before analysis starts.
# def post_open(self) -> None: ...

Questo è l'intero contratto:

| Metodo | Obbligatorio? | Cosa fa |
|---|---|---|
| `sniff(header, path)` | sì | Controllo magic-byte/estensione — questo handler possiede il file? |
| `prepare(path, workdir)` | sì | Restituisce un `PreparedImage`: il file che idalib dovrebbe aprire + la sua tabella delle sezioni |
| `post_open()` | no (default no-op) | Configurazione manuale dei segmenti per formati senza loader IDA nativo (vedi `nso.py`) |
| `make_shard_binary(image, dst, va_start, va_end)` | no (default funziona) | Esegui l'override solo se azzerare i byte delle sezioni fuori shard è sbagliato per il tuo formato (vedi `nso.py` — non azzerare mai un file compresso) |
| `code_range(image)` | no (default funziona) | Esegui l'override solo se 'min/max delle sezioni `is_code`' non è la risposta giusta |
| `read_bytes(image, va_start, va_end)` | no (default funziona) | Esegui l'override se `prepare()` contiene già i byte rilevanti in memoria (NSO) invece che su disco |
| `global_entry_points(image, text_start, text_end)` | no (default: None) | Esegui l'override solo se una scansione locale per shard perderebbe i punti di ingresso reali — NSO ne ha bisogno perché le funzioni foglia AArch64 sono rilevabili solo tramite destinazioni BL viste altrove nel binario, non tramite una scansione locale del prologo |

Guarda `formats/pe.py` per l'handler più semplice possibile (puro parsing dell'intestazione, nessun override) e
`formats/nso.py` per il caso completo (include decompressione + configurazione manuale dei segmenti + tutti gli override).

Anche i pacchetti di terze parti possono registrare un handler, senza toccare affatto il codice sorgente di spectrIDA, tramite il gruppo di entry-point `spectrida.formats`:```toml
# in a separate package's pyproject.toml
[project.entry-points."spectrida.formats"]
myformat = "spectrida_myformat_plugin:HANDLER"

Questo è tutto. Registra automaticamente il server con Claude Code e pi (includendo `mcp` + `neo4j` se una semplice `pip install spectrida` li ha saltati), scrive la loro configurazione e ti dice quale riavvio gli devi.

**Cosa ottiene effettivamente Claude, una volta che Neo4j è in esecuzione (config `[graph]` di `spectrida`, o basta puntarlo a un'istanza locale):**

- `search_functions` / `get_function` / `get_callees` / `get_callers` / `trace_chain` — letture rapide e memorizzate nella cache del grafo. `get_function` restituisce pseudocodice **e** disassemblato (limiti esatti delle istruzioni e operandi — il livello che lo pseudocodice non può darti, che conta nel momento in cui passi da "cosa fa questo" a "dove esattamente dovrei patchare questo") più chiamanti/chiamati inline, così Claude decide se approfondire la catena guardando se un chiamato è ancora `sub_*` proprio lì nella risposta — nessun viaggio aggiuntivo solo per scoprire che non c'è nient'altro da vedere.
- `get_full_pseudocode` / `rename_function` — letture/scritture live e autorevoli direttamente nel `.i64` quando lo snippet memorizzato non è sufficiente o un nome è finalmente stato scoperto.
- `analyze_binary` — dagli un binario che non ha mai visto (PE o NSO, parallelizzato in ogni caso) ed esegue l'intera pipeline — analizza → demangla (Itanium *e* MSVC) → assegna nomi AI ai resti realmente spogliati → inserisce tutto nel grafo — come un job in background che interroghi, così un'esecuzione di diversi minuti non blocca mai la conversazione.
- `doctor` / `start_all` — verifica o avvia llama-server + Neo4j senza uscire dalla chat. Se llama-server stesso non è installato da nessuna parte, `start_all` lo recupera tramite winget (Windows) o brew (macOS) prima — nessun download/configurazione separata di llama.cpp necessaria.

Non è magia — una funzione che è ancora `sub_140001234` perché nessuno ci ha ancora guardato è ancora `sub_140001234`. Ma il grafo ricorda tutto ciò che il modello *ha* scoperto, per sempre, tra sessioni, e Claude può percorrerlo come un collega che ha già letto il codebase invece di fissare una funzione alla volta.

**In arrivo:**

- **Assegnazione nomi con contesto profondo** — segui alberi di chiamate a N livelli di profondità, fornisci la catena completa al modello. Una funzione a 3 salti da `encrypt_block` dovrebbe sapere che è nel percorso crittografico.
- **Deoffuscamento** — rilevamento di pattern TigressVM e tracciamento degli handler
- **Patching reale** — il disassemblato è ora nel grafo, quindi un agente *può* pianificare una patch a livello di byte; trasformare "ecco l'istruzione esatta da cambiare" in "ed ecco la scrittura" è il prossimo passo.

---

## Capitolo 3 — il fantasma cammina attraverso i muri

I capitoli 1 e 2 leggono il binario e lo ricordano. Ma leggere una funzione ti dice cosa *è*, mai cosa *fa* quando premi il grilletto. Il capitolo 3 — [**phantomrt**](https://pypi.org/project/phantomrt/) — preme il grilletto.```bash
pip install "spectrida[atlas]"

**E, nello spirito dell'incubo NSO di cui sopra:** la prima vera caccia ai bug onestamente non ha trovato *niente* — e il motivo è stato più interessante di quanto sarebbe stato un crash. Puntato su un FreeType genuinamente vecchio e vulnerabile, il fuzzing cieco ha ottenuto zero. Il fuzzing guidato dalla copertura ha poi riportato un trionfale **64.000 edge** coperti — il che era una bugia, perché il binario era PIE e ASLR stava silenziosamente ri-randomizzando gli indirizzi a ogni esecuzione, quindi la "nuova copertura" era per lo più il loader che mescolava le carte. Disabilita ASLR, il numero onesto scende a *reali* 727 edge, e si stabilizza lì — perché ogni seed era un font TrueType, quindi il fuzzer era intrappolato in un parser e non poteva mutare strutturalmente per entrare nel codice CFF/Type1/BDF dove i bug vivono realmente. La soluzione non è stata un mutatore più intelligente, ma semi migliori: l'agente ha recuperato veri campioni OpenType/Type1/BDF, la copertura è saltata da 727 a 4.013 prima di una singola iterazione di fuzz, e ha esplorato correttamente. Ancora nessun crash nel budget — che è l'onesto stato di un'esecuzione di 3 minuti su un core rispetto a un lavoro che richiede normalmente ore. Il meccanismo è reale. Ha catturato il suo *stesso* numero falso invece di segnalarlo. Questo è il punto.

**Dichiarazione onesta del fantasma:** phantomrt è `0.1.0`. Alpha. È un solido strato dinamico, non un oracolo magico di bug — ha trovato bug piantati in un target giocattolo all'istante, e su target reali ti dice onestamente quando è bloccato (`needs_state`), quando un crash è solo un *candidato* (vai a verificare che il puntatore sia effettivamente controllato dall'input), e quando ha solo bisogno di più tempo e semi migliori. I binari Switch non girano live — Frida ha bisogno di qualcosa che possa lanciare — quindi lì, l'emulazione è l'unica porta e dirà `needs_state` spesso. Questo è onesto, non rotto.

È il pesante extra intenzionale (`torch`, `unicorn`, `frida`) — il base `pip install spectrida` non ne tira nessuno. Il codice sorgente vive in [`phantomrt/`](https://github.com/ggfuchsi-oss/spectrida-reverse_engineering_stack/blob/HEAD/phantomrt/); il suo README in stile fantasma è [proprio lì](https://github.com/ggfuchsi-oss/spectrida-reverse_engineering_stack/blob/HEAD/phantomrt/README.md).

*Il fantasma statico nomina le tue funzioni. Questo le fa confessare.* 👻

---

## License

MIT. Fai quello che vuoi. Se funziona, figo.
Se non funziona, dai la colpa alla quantizzazione GGUF.

Costruito con rancore, caffè e una RTX 4070.
Il modello ha 199 download con zero marketing. Ognuno aggiunge lo 0,01% alla velocità di sviluppo.
(Non è vero. Ma ci si avvicina.) 👻