From f8178a08f304bfa9d8e5d94992c0cb3e7a42458d Mon Sep 17 00:00:00 2001 From: Patryk Gensch <43010113+patryk025@users.noreply.github.com> Date: Sat, 24 Oct 2026 19:01:41 +0200 Subject: [PATCH] docs: runner_map and method facts; tools/ghidra_probe.py for fast iteration Co-Authored-By: Claude Opus 5.5 --- README.md | 14 +++++++-- docs/tracker.md | 3 +- tools/ghidra_probe.py | 72 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 85 insertions(+), 4 deletions(-) create mode 100644 tools/ghidra_probe.py diff --git a/README.md b/README.md index d0e0acf..ba6cc68 100644 --- a/README.md +++ b/README.md @@ -104,8 +104,9 @@ potem zaimportuj go przez `python -m ams.api.importer …`. ## Zasada ekstrakcji Ekstrakcja stoi na **kotwicach semantycznych** (cele wywołań, referowane literały -stringów, immediaty `PUSH`), a **nie** na tekście dekompilatu. Dzięki temu jeden skrypt -działa na MSVC6 (Piklib) i MSVC8 (BlooMoo) mimo różnego kodu wynikowego. +stringów, immediaty `PUSH`, sloty vtable), a **nie** na tekście dekompilatu. Dzięki temu jeden +skrypt działa na MSVC6 (Piklib) i MSVC8 (BlooMoo) mimo różnego kodu wynikowego. Nazwy funkcji +bywają aliasami (ICF skleja identyczne ciała), więc liczy się adres i każda etykieta pod nim. | Co | Kotwica w Ghidrze | Status | |----|-------------------|--------| @@ -114,7 +115,9 @@ działa na MSVC6 (Piklib) i MSVC8 (BlooMoo) mimo różnego kodu wynikowego. | Eventy | `CMC_*::getBehavioursList`: lista literałów `CXString` | ✅ (lista per klasa, bez dziedziczenia) | | Pola (skryptowe) | ctory `CMC_*`: literały czytane przez `CMElement::getPropertyValue` → nazwa + typ pola (FPS, PRELOAD, VISIBLE…) | ✅ (+ `field_inheritance`) | | Layout C++ (bonus) | ctory `CMC_*`: store'y `this+offset` przez P-code (rozmyte, `is_vtable`) | ✅ pod `struct_layout` | -| Ciała metod | `CMC_*_Runner::run`: `switch(id)` (vtable slot 17) → per case kotwice CALL (`Klasa::metoda` / `vtbl+0xNN`), rozwinięcie wrapperów | ✅ pod `method_dispatch` (id→`impl_addr`+`calls`) | +| Ciała metod | `CMC_*_Runner::run`: `switch(id)` → per case kotwice CALL (`Klasa::metoda` / `vtbl+0xNN`), rozwinięcie wrapperów | ✅ pod `method_dispatch` (id→`impl_addr`+`calls`) | +| Typ → runner | 7.1+/BlooMoo: emulacja `CMC_RunnerFactory::getRunner(typeId)`, `typeId` z konstruktora typu, vtable runnerów z `RunnerFactory::initialize` (także runnery bez symboli: VECTOR, FILTER, PATH, FIFO/LIFO, MOVIE, instrukcje `@`). 6.1: konstruktor klasy tworzący runner | ✅ pod `runner_map` | +| Sygnatury, ważność per typ | P-code case'ów i pomocników: `CMC_Runner::getParameter*` (typy argumentów), `CMC_VariableFactory::alloc*` (wynik), wirtualne obiektu, gałęzie na `obj.getType()` | ✅ w `method_dispatch` (`params`/`returns`/`per_type`) | ## Uruchomienie ekstraktora @@ -122,6 +125,9 @@ działa na MSVC6 (Piklib) i MSVC8 (BlooMoo) mimo różnego kodu wynikowego. do swojego katalogu skryptów (Script Manager → *Manage Script Directories*), otwórz program, uruchom skrypt. Wynik trafi do `.snapshot.json` w katalogu roboczym Ghidry. +**Szybka pętla** (projekt przeanalizowany raz, kolejne uruchomienia w sekundach): +`tools/ghidra_probe.py --project DIR DLL --extract out.json` albo `--snippet probe.py`. + **Headless** (tryb docelowy): ```bash analyzeHeadless -process PIKLIB8.dll \ @@ -270,3 +276,5 @@ A/B i odpalający porównanie). `schema_version`, `binary{name,sha256,engine,compiler,factory_addr}`, oraz listy `types` / `methods` / `events` / `fields`. Diff = operacje na zbiorach dwóch snapshotów. +Od wersji 5: `runner_map` (`by_type_id` / `by_class`, sloty `CMC_Runner`), `types[].type_id` +i `vftable`, a w `method_dispatch` fakty z ciała metody. diff --git a/docs/tracker.md b/docs/tracker.md index 838ae48..8217d12 100644 --- a/docs/tracker.md +++ b/docs/tracker.md @@ -37,7 +37,8 @@ Atlas odczytuje snapshoty z dysku przy każdym pobraniu katalogu. Command Center - **Zaimplementowana / przegląd ASM / test zachowania**: aktualne deklaracje przeglądu obejmują wszystkie obserwowane warianty danej pary typ/metoda. - **Nieustalone w oryginale**: brak obserwacji, nigdy dowód nieobecności. -Licznik to pary typ/metoda, z rozwinięciem rozpoznanego dziedziczenia. Nie jest liczbą unikalnych ciał Java ani procentem zgodności całego silnika. Zakres `*` pokazuje metody bazowe/globalne; nazwy klas bez dopasowania fabryki są wnioskowane (mogą obejmować klasy bazowe i singletony). Typy bez rozpoznanych metod pozostają widoczne. +Licznik to pary typ/metoda. Nie jest liczbą unikalnych ciał Java ani procentem zgodności całego silnika. Metody bazowe `CMC_Runner` (SEND, CLONE, …) są w zakresie `*` raz; typy wskazują go polem `inherits`. Zakres `@` to instrukcje `@IF`/`@LOOP`/… (runner typu 0), porównywane z `CodeParser.dispatchSpecialCall`. Typy bez rozpoznanych metod pozostają widoczne. +Typ → runner pochodzi z `runner_map` snapshotu (fabryka w 7.1+, konstruktory klas w 6.1); bez niego z nazwy klasy, oznaczone jako wnioskowane. Metoda wspólnego runnera, którą oryginał pomija dla danego typu warunkiem `obj.getType()`, nie jest temu typowi przypisana; pusta implementacja wirtualna jest oznaczona jako brak efektu. Sygnatury (typy argumentów i wyniku) są odczytane z ciała metody i mogą być sumą wariantów (`int/string`). Alias `BOOL` jest łączony z `BOOLEAN`, `INT` z `INTEGER`; nazwy metod są normalizowane do uppercase. ID metody pozostaje lokalne dla konkretnej klasy i binarki. Relacje dziedziczenia pochodzą wyłącznie ze snapshotu, nie są zgadywane z innej wersji. Adapter rozpoznaje bieżący wzorzec rejestracji Java; nie jest ogólnym parserem języka Java. Komentarze i literały nie tworzą fałszywych wpisów, nawiasy są dopasowywane leksykalnie. Własne dispatchery `GROUP` / `INSTANCE` są oznaczone do przeglądu. Celowe no-op nie są automatycznie stubami. diff --git a/tools/ghidra_probe.py b/tools/ghidra_probe.py new file mode 100644 index 0000000..362d11b --- /dev/null +++ b/tools/ghidra_probe.py @@ -0,0 +1,72 @@ +"""Re-run the extractor, or any snippet, against a kept and already analysed Ghidra project. + +Auto-analysis dominates a batch attempt (~40 s per DLL). Iterating on +ghidra_scripts/extract_engine_surface.py against a project analysed once takes seconds: + + .venv-ghidra/bin/python tools/ghidra_probe.py --project /tmp/probe DLL --extract out.json + .venv-ghidra/bin/python tools/ghidra_probe.py --project /tmp/probe DLL --snippet probe.py [args...] + +A snippet runs with `program`, `flat` (FlatProgramAPI), `extractor` (the extractor's globals, +loaded without running it) and `ARGS` in scope. The DLL is only read; the project directory +is scratch state and can be deleted at any time. +""" +from __future__ import annotations + +import argparse +import os +import re +import time +from pathlib import Path + +EXTRACTOR = Path(__file__).resolve().parents[1] / "ghidra_scripts/extract_engine_surface.py" + + +def extractor_globals(program, monitor, script_args=()): + """The extractor's module namespace bound to `program`, without its trailing run().""" + source = EXTRACTOR.read_text(encoding="utf-8").rsplit("\nrun()", 1)[0] + scope = {"currentProgram": program, "monitor": monitor, "getScriptArgs": lambda: list(script_args), + "getSourceFile": None, "__name__": "extract_engine_surface"} + exec(compile(source, str(EXTRACTOR), "exec"), scope) + return scope + + +def main(argv=None): + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument("dll", type=Path) + parser.add_argument("--project", type=Path, required=True, help="kept Ghidra project directory") + parser.add_argument("--ghidra-home", default=os.environ.get("GHIDRA_INSTALL_DIR") or os.environ.get("GHIDRA_HOME")) + action = parser.add_mutually_exclusive_group(required=True) + action.add_argument("--extract", type=Path, metavar="OUT", help="write a snapshot like the batch does") + action.add_argument("--snippet", type=Path, metavar="PY", help="run a Python snippet against the program") + parser.add_argument("args", nargs="*", help="snippet arguments (ARGS)") + args = parser.parse_args(argv) + if not args.ghidra_home: + parser.error("set --ghidra-home or GHIDRA_INSTALL_DIR") + os.environ["GHIDRA_INSTALL_DIR"] = args.ghidra_home + args.project.mkdir(parents=True, exist_ok=True) + + import pyghidra + from pyghidra.launcher import HeadlessPyGhidraLauncher + launcher = HeadlessPyGhidraLauncher(verbose=False) + launcher.vm_args.extend(["-Duser.home=" + str(args.project / "runtime-home"), "-Xmx4G"]) + launcher.start() + from ghidra.util.task import ConsoleTaskMonitor + + # Ghidra domain-file names reject some Polish letters; only the project-internal name changes. + name = re.sub(r"[^A-Za-z0-9_.-]", "_", args.dll.name) + with pyghidra.open_program(str(args.dll), project_location=str(args.project), project_name="probe", + program_name=name, analyze=True) as flat: + program = flat.getCurrentProgram() + started = time.monotonic() + if args.extract: + scope = extractor_globals(program, ConsoleTaskMonitor(), [str(args.extract.resolve())]) + scope["run"]() + else: + scope = {"program": program, "flat": flat, "ARGS": args.args, + "extractor": extractor_globals(program, ConsoleTaskMonitor())} + exec(compile(args.snippet.read_text(encoding="utf-8"), str(args.snippet), "exec"), scope) + print("[probe] %.1fs" % (time.monotonic() - started)) + + +if __name__ == "__main__": + main()