nemo22/retrokitBoîte à outils Headless-Ghidra pour le reverse engineering de jeux DOS 32 bits et Win32 (1993-2010) : chargeur LE/LX propre, conventions d'appel Watcom, signatures de bibliothèques, serveur MCP
Une boîte à outils pour décompiler des jeux 32 bits d'environ 1993–2010 avec Ghidra headless :
La sortie est un espace de travail avec un grand fichier .c contenant chaque fonction plus des index
(fonctions, graphe d'appels, chaînes, fixups/tables de pointeurs, imports) que vous pouvez grep et répartir
entre personnes ou agents IA. Les noms trouvés pendant l'analyse sont réinjectés dans Ghidra et l'export
est régénéré.
Prérequis : Ghidra 12.x
(décompressé), 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 est trouvé via --ghidra DIR, $GHIDRA_INSTALL_DIR, ou un répertoire ghidra/ghidra_* à côté
du jeu ou du kit. install-loader compile le loader avec javac contre ce Ghidra
(sans Gradle), l'installe dans Ghidra/Extensions et enregistre les spécifications du compilateur Watcom ; exécutez-le
à nouveau après avoir mis à jour Ghidra (doctor vous indique quand).
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 détecte le format, le loader et – pour Watcom – la convention d'appel
(--cspec watcom|watcomreg la remplace) et les stocke dans GAME_analysis/retrokit.json ;
les commandes suivantes n'ont besoin que du 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/
Agents IA : retrokit mcp GAME_analysis est un serveur MCP (stdio, sans paquets supplémentaires) sur
l'espace de travail : fonctions, code décompilé, graphe d'appels, références croisées, chaînes,
tables de pointeurs, désassemblage et octets, bibliothèques ; il enregistre les propositions de noms et les notes et peut
réexporter avec les noms appliqués (sur demande, en arrière-plan). Claude Code :
claude mcp add retrokit -- retrokit mcp /path/to/GAME_analysis
Configuration pour les autres clients, chaque outil et comment un agent doit fonctionner : docs/MCP.md ; une version courte pour les agents dans AGENTS.md.
Noms : écrire les propositions dans notes/names_<topic>.csv (addr,name,confidence,comment, confiance
V vérifié ou G supposé) ; retrokit names WS renomme les fonctions/labels (V l'emporte sur G,
les collisions reçoivent _<addr>) et réexporte.
Ce que fait le pipeline :
retrokit libs (également partie de info et analyze ->
notes/libraries.md) reconnaît ~20 bibliothèques de l'époque - Miles/AIL, HMI SOS, DIGPAK,
Smacker, Bink, FMOD, BASS, DirectX, zlib, libjpeg, libpng, PKWARE DCL, Lua, ... - à partir
des chaînes, des imports et des fichiers de données, avec la version, des notes sur leurs formats et des indices de portage.
Le code des bibliothèques est trouvé par signature (fournies : run-time Watcom C/C++, bibliothèques math et C++
d'Open Watcom, zlib 1.0.4-1.2.3, libjpeg 6b ; retrokit sigs build les crée à partir des
bibliothèques que vous possédez, sigs learn à partir des fonctions que vous avez identifiées) - correspondances exactes d'abord, puis
code similaire d'autres versions de compilateur - nommées, et typées à partir de retrokit/knowledge/*.h.switch
conservées à l'intérieur de leurs fonctions, faux indicateurs "no return" annulés, chaînes courtes définies et littéraux de chaîne affichés comme "text", nombres de paramètres à partir des nettoyages ADD ESP,n aux sites d'appel,
prototypes récupérés en commençant par les appelés, export.Autres commandes : classes (classes C++ MSVC à partir des RTTI), libs (bibliothèques utilisées), convert (XMIDI/HMI/HMP -> MIDI, VOC -> WAV,
Smacker/Bink/FLIC -> MP4, par contenu), sigs match|build|learn (signatures de bibliothèques, voir
docs/WORKFLOW.md),
entries (PE : adresses de code sans fonction), modules --rules FILE
(PE : fonctions → fichiers source d'origine via les chemins d'assertion), strings EXE OUT (inventaire des chaînes PE
sans Ghidra), match (transférer les noms vers un EXE apparenté : suite, add-on, autre version),
le EXE info|dump|rec|s16|s32 (lire les tables d'un LE aux adresses Ghidra), rnc (RNC ProPack),
flic info|png|video (Autodesk FLI/FLC). retrokit COMMAND --help pour les options.
La procédure détaillée, ce à quoi s'attendre et les pièges connus se trouvent dans docs/WORKFLOW.md ; le
serveur MCP dans docs/MCP.md ; les modèles de tâches pour les agents IA dans docs/AGENT_PROMPTS.md ; le travail
prévu dans docs/ROADMAP.md ; la maintenance et la publication dans docs/MAINTAINING.md.
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