docs: runner_map and method facts; tools/ghidra_probe.py for fast iteration

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Patryk Gensch
2026-10-24 19:01:41 +02:00
co-authored by Claude Opus 5.5
parent 11f4b6fc37
commit f8178a08f3
3 changed files with 85 additions and 4 deletions
+11 -3
View File
@@ -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::getProperty<T>Value` → 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 `<NazwaProgramu>.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 <projDir> <projName> -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.
+2 -1
View File
@@ -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.
+72
View File
@@ -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()