retro-kit – reverse engineering di vecchi giochi (Ghidra headless)

Un toolkit per decompilare giochi a 32 bit all'incirca dal 1993–2010 con Ghidra headless:

• DOS LE/LX (DOS/4GW, DOS/32A, PMODE/W, CauseWay, bind DOS/4G; anche OS/2 LX e VxD) compilati con Watcom C/C++ – con un proprio loader LE/LX per Ghidra e specifiche del compilatore Watcom per entrambe le convenzioni di chiamata.
• Win32 PE (tipicamente MSVC): chiamate DirectX attraverso le vtable COM mostrate con i loro nomi dei metodi, import Miles/Smacker/Bink/FMOD/BASS tipizzati, classi C++ dal RTTI MSVC, la versione del compilatore dall'header Rich.

L'output è un workspace con un unico grande file .c che contiene ogni funzione più gli indici (funzioni, call graph, stringhe, fixup/tabelle di puntatori, import) che puoi cercare con grep e suddividere tra persone o agenti AI. I nomi trovati durante l'analisi tornano in Ghidra e l'export viene rigenerato.

Installazione

Prerequisiti: Ghidra 12.x (scompattato), un JDK 21+ (JAVA_HOME), Python 3.10+.

pipx install git+https://github.com/nemo22/retrokit   # or from a checkout: pip install .  (or python -m retrokit)
retrokit doctor                                    # checks Python, Ghidra, Java, loader, cspecs
retrokit install-loader                            # once per Ghidra install (DOS LE/LX only)

Ghidra viene individuato tramite --ghidra DIR, $GHIDRA_INSTALL_DIR, oppure una directory ghidra/ghidra_* accanto al gioco o al kit. install-loader compila il loader con javac rispetto a quella Ghidra (nessun Gradle), lo installa in Ghidra/Extensions e registra le specifiche del compilatore Watcom; eseguilo di nuovo dopo aver aggiornato Ghidra (doctor ti avvisa quando).

Uso

retrokit info GAME.EXE              # format, DOS extender, compiler, calling convention
retrokit analyze GAME.EXE           # full pipeline -> GAME_analysis/  (-o DIR to choose)
retrokit show GAME_analysis FUN_00012345 main
retrokit tables GAME_analysis       # function-pointer and string tables (from fixups)
retrokit names GAME_analysis        # apply notes/names_*.csv, re-export
retrokit reexport GAME_analysis     # re-run the fix-up passes + export without re-importing

analyze rileva il formato, il loader e – per Watcom – la convenzione di chiamata (--cspec watcom|watcomreg la sovrascrive) e li memorizza in GAME_analysis/retrokit.json; i comandi successivi necessitano solo del workspace. Un workspace:

GAME_analysis/
  retrokit.json        how the binary was analysed
  decomp/              <exe>_decompiled.c, functions.csv (addr,name,size,callers,callees,cc,signature),
                       calls.txt, strings.txt, data_symbols.txt, memory_blocks.txt,
                       fixups.txt (source -> target of every pointer: the key to pointer tables
                       and to which function uses which string), imports.txt (PE)
  notes/               findings, names_<topic>.csv proposals
  ghidra_project/      the Ghidra project (open it in the Ghidra GUI too)
  logs/

Agenti AI: retrokit mcp GAME_analysis è un server MCP (stdio, senza pacchetti aggiuntivi) sul workspace: funzioni, codice decompilato, grafo delle chiamate, riferimenti incrociati, stringhe, tabelle di puntatori, disassembly e byte, librerie; registra proposte di nomi e note e può riesportare con i nomi applicati (su richiesta, in background). Claude Code:

claude mcp add retrokit -- retrokit mcp /path/to/GAME_analysis

Configurazione per altri client, ogni strumento e come dovrebbe funzionare un agente: docs/MCP.md; una versione breve per gli agenti in AGENTS.md.

Nomi: scrivi le proposte in notes/names_<topic>.csv (addr,name,confidence,comment, confidence V verificato o G ipotesi); retrokit names WS rinomina funzioni/etichette (V prevale su G, le collisioni ottengono _<addr>) e riesporta.

Cosa fa la pipeline:

• Librerie (entrambi i formati): retrokit libs (anche parte di info e analyze -> notes/libraries.md) riconosce ~20 librerie dell'epoca - Miles/AIL, HMI SOS, DIGPAK, Smacker, Bink, FMOD, BASS, DirectX, zlib, libjpeg, libpng, PKWARE DCL, Lua, ... - da stringhe, import e file di dati, con versione, note sui loro formati e suggerimenti di porting. Il codice delle librerie viene trovato per firma (incluse: run-time Watcom C/C++, librerie matematiche e C++ di Open Watcom, zlib 1.0.4-1.2.3, libjpeg 6b; retrokit sigs build le crea da librerie di tua proprietà, sigs learn da funzioni che hai identificato) - prima le corrispondenze esatte, poi codice simile da altre versioni del compilatore - nominato e tipizzato da retrokit/knowledge/*.h.
• LE/LX: importa con il loader LE e il cspec Watcom, funzioni ai target dei fixup nel codice (i giochi Watcom chiamano gran parte della loro logica tramite tabelle di puntatori), tabelle di salto switch mantenute all'interno delle loro funzioni, flag "no return" errati annullati, stringhe brevi definite e letterali stringa mostrati come "text", conteggi dei parametri dai cleanup ADD ESP,n nei punti di chiamata, prototipi recuperati partendo dai chiamati, esporta.
• PE: importa con il loader PE di Ghidra e l'auto-analisi, poi funzioni ai target delle tabelle di puntatori e dopo il padding finché non ne emergono di nuove, le stesse passate di stringhe / parametri / prototipi, esporta.

Altri comandi: classes (classi C++ MSVC da RTTI), libs (librerie in uso), convert (XMIDI/HMI/HMP -> MIDI, VOC -> WAV, Smacker/Bink/FLIC -> MP4, in base al contenuto), sigs match|build|learn (firme delle librerie, vedi docs/WORKFLOW.md), entries (PE: indirizzi di codice senza una funzione), modules --rules FILE (PE: funzioni → file sorgente originali tramite percorsi assert), strings EXE OUT (inventario delle stringhe PE senza Ghidra), match (trasferisce i nomi a un EXE correlato: sequel, add-on, altra versione), le EXE info|dump|rec|s16|s32 (legge tabelle da un LE a indirizzi Ghidra), rnc (RNC ProPack), flic info|png|video (Autodesk FLI/FLC). retrokit COMMAND --help per le opzioni.

La procedura dettagliata, cosa aspettarsi e le insidie note sono in docs/WORKFLOW.md; il server MCP in docs/MCP.md; i template di attività per agenti AI in docs/AGENT_PROMPTS.md; il lavoro pianificato in docs/ROADMAP.md; manutenzione e rilascio in docs/MAINTAINING.md.

Layout

retrokit/               Python package (CLI: retrokit/cli.py)
  ghidra_scripts/       headless Ghidra scripts used by the pipelines
  tools/                standalone Python tools behind the CLI commands
  le-loader/            LE/LX loader for Ghidra (Java) + Watcom compiler specs (data/languages/)
  sigs/                 library signatures (Open Watcom C run-time)
  knowledge/            libraries.json (library catalog), library prototypes as C headers
scripts/                build_sigs.py: rebuilds the shipped signatures
tests/                  synthetic test programs, scoring against the linker map, baseline
docs/                   WORKFLOW, AGENT_PROMPTS, ROADMAP