Diff gains a type_events axis keyed by (script type, event). The tracker lists each type's original events (vftable list, or the nearest class list up the constructor chain for Piklib 6.1) and where the emulator names them: the type's class, Variable.java or other engine code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
281 lines
16 KiB
Markdown
281 lines
16 KiB
Markdown
# aidem_media_playground
|
||
|
||
**[Atlas API — tracker implementacji emulatora i dowodów](docs/tracker.md)**,
|
||
dostępny pod `/ui/tracker.html`. [Kolejka ekstrakcji silników](docs/batch.md),
|
||
statyczne dowody pluginów: [WORLD](docs/world-analysis.md), [KOLOROWANKA](docs/kolorowanka-pilot.md).
|
||
|
||
```sh
|
||
.venv/bin/python -m ams.serve_tracker --emulator-root /Users/genszu/IdeaProjects/Rex-EMoolator
|
||
```
|
||
|
||
Narzędzie do **analizy różnicowej** silników gier Aidem Media (Piklib / BlooMoo).
|
||
Cel: katalog gier (z ISO/ZIP), wersje silnika z hashami, oraz ekstrakcja i porównywanie
|
||
"powierzchni silnika" — typów, metod, eventów i pól klas `CMC_*` — między wersjami.
|
||
|
||
## Status
|
||
|
||
Pełny łańcuch działa: **binarka → (Ghidra worker) → `snapshot.json` → katalog (DB) → diff → UI**.
|
||
Ekstraktor pokrywa 5 osi (typy / metody / eventy / pola skryptowe / ciała metod) + bonus layout C++,
|
||
zwalidowany na golden pair PIKLIB8 (MSVC6) ↔ bloomoo (MSVC8). Nad tym: FastAPI + katalog (SQLite/Postgres),
|
||
diff z normalizacją ciał i miarą „podobnych wersji", Command Center UI, pipeline akwizycji ISO/ZIP
|
||
i pełny stack `docker compose` z workerem Ghidry. Zobacz **Quickstart** niżej.
|
||
|
||
## Architektura (docelowa)
|
||
|
||
Modularny monolit + worker. Backend Python/FastAPI tylko zleca, wersjonuje i diffuje.
|
||
Cała ekstrakcja żyje w **workerze = Ghidra headless + ten skrypt**, bo wymaga dostępu
|
||
do call-grafu, referencji i vtable. Worker emituje `snapshot.json`, monolit go konsumuje.
|
||
|
||
```
|
||
Front (centrum dowodzenia) ─ FastAPI (katalog/hashe/diff) ─ PostgreSQL
|
||
│ kolejka
|
||
Worker: Ghidra headless + extract_engine_surface.py
|
||
```
|
||
|
||
## Quickstart
|
||
|
||
### 1. Lokalnie, bez Dockera (działa od ręki — golden snapshoty są w repo)
|
||
|
||
```bash
|
||
python -m venv .venv && source .venv/bin/activate
|
||
pip install -e ".[api,dev]"
|
||
|
||
# zasiej katalog dwoma wersjami z golden pair
|
||
python -m ams.api.importer --game "Reksio i UFO" snapshots/PIKLIB8.dll.snapshot.json
|
||
python -m ams.api.importer --game "Reksio i Kapitan Nemo" snapshots/bloomoodll.dll.snapshot.json
|
||
|
||
uvicorn ams.api.app:create_app --factory # → http://127.0.0.1:8000/
|
||
```
|
||
|
||
Diff też z CLI: `python -m ams OLD.json NEW.json --owner CMC_Animo --only dispatch`.
|
||
|
||
### 2. Pełny stack w Dockerze (Ghidra w workerze) — upload ISO/ZIP → snapshot
|
||
|
||
```bash
|
||
docker compose up --build # db(Postgres) + redis + api + worker(Ghidra)
|
||
```
|
||
|
||
Pierwszy build workera **ściąga Ghidrę (~1 GB) + JDK 21** (wolny, ale cache'owany). Potem wgraj grę
|
||
przyciskiem **+ wgraj** w UI (http://localhost:8000) albo z CLI:
|
||
|
||
```bash
|
||
curl -F file=@"/sciezka/do/gra.iso" -F game="Reksio i Czarodzieje" http://localhost:8000/jobs
|
||
curl http://localhost:8000/jobs/1 # status: queued → started → finished
|
||
```
|
||
|
||
Worker rozpakowuje (bsdtar: ISO/ZIP), content-based znajduje DLL silnika, hashuje, odpala
|
||
Ghidra headless + `extract_engine_surface.py` → snapshot → import do Postgresa → UI.
|
||
|
||
### 3. Ghidra w obrazie — wersja / troubleshooting
|
||
|
||
Worker (`docker/worker.Dockerfile`, `eclipse-temurin:21-jdk`) pobiera Ghidrę i ustawia
|
||
`GHIDRA_HOME=/opt/ghidra`. Wersja jest przypięta w `ARG GHIDRA_URL`. Jeśli build padnie na pobieraniu,
|
||
nadpisz URL realnym wydaniem z [releases NSA](https://github.com/NationalSecurityAgency/ghidra/releases)
|
||
(nazwa pliku: `ghidra_<wer>_PUBLIC_<data>.zip`).
|
||
|
||
> **Domyślnie wymaga Ghidry ≤ 11.3.x.** Ekstraktor to skrypt **Pythona (`.py`)**, który Ghidra
|
||
> w headless uruchamia przez wbudowanego **Jythona**. Ghidra **11.4+ / 12.x usunęły Jythona** — tam
|
||
> `.py` headless przez `analyzeHeadless` nie ruszy (`Ghidra was not started with PyGhidra...`):
|
||
> analiza przejdzie, ale post-skrypt nie wyemituje snapshotu. Domyślny `GHIDRA_URL` celuje w 11.2.1.
|
||
|
||
**Wariant Jython (domyślny, ≤ 11.3.x):**
|
||
```bash
|
||
docker compose build worker \
|
||
--build-arg GHIDRA_URL=https://github.com/NationalSecurityAgency/ghidra/releases/download/Ghidra_11.2.1_build/ghidra_11.2.1_PUBLIC_20241105.zip
|
||
docker compose up
|
||
```
|
||
|
||
**Wariant PyGhidra (Ghidra 11.4+ / 12.x):** obraz workera ma już `pyghidra`; ten sam skrypt leci
|
||
przez CPython (`pyghidra.run_script`, bez zmian w kodzie). Zbuduj z nowszą Ghidrą i włącz przełącznik:
|
||
```bash
|
||
docker compose build worker \
|
||
--build-arg GHIDRA_URL=https://github.com/NationalSecurityAgency/ghidra/releases/download/Ghidra_11.4.2_build/ghidra_11.4.2_PUBLIC_20250826.zip
|
||
AMS_USE_PYGHIDRA=1 docker compose up
|
||
```
|
||
Pod spodem worker woła `ams.acquire.ghidra.run_extractor_pyghidra` (uruchamia Ghidrę in-process,
|
||
importuje + analizuje binarkę, odpala nasz GhidraScript z `getScriptArgs()=[out_path]`).
|
||
|
||
### 4. Ekstrakcja ręcznie w GUI Ghidry (alternatywa, bez Dockera)
|
||
|
||
*Script Manager → Manage Script Directories* → wskaż `ghidra_scripts/`, otwórz program (DLL),
|
||
uruchom `extract_engine_surface.py`. Snapshot ląduje w `snapshots/<nazwa>.snapshot.json`,
|
||
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`, 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 |
|
||
|----|-------------------|--------|
|
||
| Typy | `CMC_ObjectsContainer::resolve` (8.x/BlooMoo) lub `CMC_Scene::resolve` (Piklib 6.1/7.1): `operator==("NAME")` → `operator_new(SIZE)` → ctor | ✅ (8.x inline; 6.1 tag-based = nazwy bez ctora) |
|
||
| Metody | `CMC_*_Runner::prepareMthHashSet`: `CInteger(id)` + `CStringHashCode("NAME")` + `CHashtable::put` | ✅ (+ `method_inheritance`) |
|
||
| Eventy | `CMC_*::getBehavioursList`: lista literałów `CXString` | ✅ per klasa (`events`) i per typ (`type_events`: slot `getBehavioursList` z vtable typu, także klasy bez symboli) |
|
||
| 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)` → 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
|
||
|
||
**W GUI Ghidry** (najszybciej do walidacji): skopiuj `ghidra_scripts/extract_engine_surface.py`
|
||
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 \
|
||
-postScript extract_engine_surface.py "$(pwd)/snapshots/PIKLIB8.snapshot.json"
|
||
```
|
||
|
||
## Uruchomienie w kontenerach (docker compose)
|
||
|
||
Pełny stack — modularny monolit + **wydzielony worker Ghidry** — czterema usługami:
|
||
|
||
```
|
||
db (Postgres) ── api (FastAPI + UI) ──┐
|
||
├── redis (kolejka)
|
||
worker (Ghidra headless) ─────────────┘
|
||
```
|
||
|
||
```bash
|
||
docker compose up --build # api na http://localhost:8000
|
||
```
|
||
|
||
`api` i `worker` współdzielą wolumen `uploads`: API streamuje wgrane archiwum na dysk,
|
||
worker czyta je po ścieżce (przez Redisa leci tylko ścieżka, nie bajty). Obraz workera
|
||
**pobiera Ghidrę (~1 GB) przy pierwszym buildzie** — wersję nadpiszesz przez
|
||
`--build-arg GHIDRA_URL=…`. Postgres trzyma katalog trwale (wolumen `pgdata`).
|
||
|
||
Asynchroniczna akwizycja przez API (zlecenie → kolejka → worker → snapshot w bazie):
|
||
|
||
```bash
|
||
curl -F file=@game.iso -F game="Reksio i UFO" http://localhost:8000/jobs # → 202 {id, status:queued}
|
||
curl http://localhost:8000/jobs/1 # poll: queued→started→finished
|
||
```
|
||
Endpointy joba: `POST /jobs` (upload+enqueue), `GET /jobs`, `GET /jobs/{id}` (status, `snapshot_id`, `error`).
|
||
|
||
## Akwizycja — ISO/ZIP → katalog
|
||
|
||
Worker, który domyka łańcuch od *pliku gry* do wpisu w katalogu: rozpakowuje archiwum,
|
||
**sam znajduje DLL silnika** (po markerach w binarce — `CMC_ObjectsContainer` w RTTI —
|
||
więc działa nawet po zmianie nazwy pliku), liczy hashe (sha256 + md5 + opcjonalnie ssdeep),
|
||
odpala Ghidrę headless z ekstraktorem i ląduje snapshotem w bazie.
|
||
|
||
```bash
|
||
pip install -e ".[api,acquire]" # acquire = ppdeep (fuzzy hash, opcjonalny)
|
||
export GHIDRA_HEADLESS=/path/to/ghidra/support/analyzeHeadless # albo GHIDRA_HOME
|
||
|
||
python -m ams.acquire game.iso --game "Reksio i UFO" # ISO/ZIP/katalog/luźny DLL
|
||
python -m ams.acquire dump_dir --game "Reksio i UFO" --sink http --post http://127.0.0.1:8000
|
||
python -m ams.acquire PIKLIB8.dll --identify-only # tylko unpack+identify+hash, bez Ghidry
|
||
```
|
||
|
||
`--sink db` (domyślnie) importuje wprost do bazy, `--sink http` POST-uje na `/snapshots`,
|
||
`--sink none` zostawia sam snapshot. `--identify-only` to suchy bieg do walidacji bez Ghidry.
|
||
Rozpakowywanie stoi na `bsdtar` (libarchive — czyta i ISO9660, i ZIP); ZIP ma fallback na
|
||
czysty Python. Snapshot dostaje doklejony blok `binary.acquisition` (źródło, nazwa DLL) oraz
|
||
`binary.fuzzy/md5/size`.
|
||
|
||
## Diff engine (CLI)
|
||
|
||
```bash
|
||
python -m ams OLD.snapshot.json NEW.snapshot.json [--owner CMC_Animo] \
|
||
[--only types,methods,events,fields,layout,dispatch] [--json]
|
||
```
|
||
Porównuje dwa snapshoty po osiach (added/removed/changed) + wykrywa metody przeniesione
|
||
w hierarchii. Oś `dispatch` (ciała metod, klucz `owner`+`id`) diffuje fingerprint wywołań
|
||
każdej metody — wykrywa **zmiany ciała** między wersjami; jak `struct_layout`, najczystsza
|
||
między wersjami tego samego kompilatora (cross-compiler proste metody i tak się zgadzają,
|
||
np. Animo `SHOW`→`vtbl+0xa0` na MSVC6 i MSVC8).
|
||
|
||
**Normalizacja ciał** (`ams.normalize`): każda zmiana w osi `dispatch` niesie wynik
|
||
`body = {similarity, added, removed}` — podobieństwo 0–100% sekwencji liści (`difflib`,
|
||
po zwinięciu sąsiednich duplikatów = artefaktów codegenu) oraz *które* wywołania doszły/zniknęły.
|
||
Blok dostaje też `summary` (wspólne / identyczne / zmienione / średnie podobieństwo). Na golden
|
||
pair (cross-compiler): 470 wspólnych ciał, 131 identycznych, średnio 66% — a `SHOW/HIDE/PAUSE/
|
||
RESUME` Animo wychodzą 100% mimo MSVC6↔MSVC8. To jest miara „na ile się zmieniło" na poziomie kodu.
|
||
|
||
## Backend (FastAPI + katalog)
|
||
|
||
Modularny monolit nad SQLAlchemy — domyślnie SQLite (zero setupu), gotowy pod Postgres
|
||
przez `DATABASE_URL`. Pełny snapshot trzymany jest w bazie verbatim; diff czyta go z powrotem
|
||
przez `ams.diff`.
|
||
|
||
```bash
|
||
pip install -e ".[api,dev]" # zależności
|
||
python -m ams.api.importer --game "Reksio i UFO" snapshots/PIKLIB8.dll.snapshot.json
|
||
uvicorn ams.api.app:create_app --factory --reload # serwer
|
||
```
|
||
Endpointy: `POST/GET /games`, `POST/GET /snapshots` (import deduplikowany po sha256),
|
||
`GET /diff?old=&new=[&owner=]`, `GET /snapshots/{id}/similar`, `GET /compat?format=md|json`,
|
||
`POST/GET /jobs`, `GET /health`.
|
||
Testy: `pytest` (28, w tym integracyjne na golden pair).
|
||
|
||
### Podobne wersje
|
||
|
||
`GET /snapshots/{id}/similar[?min=N]` rankuje pozostałe wersje w katalogu po **overlapie
|
||
powierzchni** — Jaccard zbiorów tożsamości (te same klucze co diff) per oś, plus pula `overall`.
|
||
Miara jest *cross-compiler*: golden pair PIKLIB8 (MSVC6) ↔ bloomoodll (MSVC8) wychodzi **85%**
|
||
(types 95% / methods 87% / events 77% / fields 90%), tam gdzie fuzzy-hash binarki daje 0.
|
||
Fuzzy (ssdeep) leci jako sygnał poboczny „prawie ten sam plik", gdy snapshot ma `binary.fuzzy`.
|
||
|
||
## Tablica kompatybilności (eksport pod dokumentację)
|
||
|
||
Krosowy widok całego katalogu **grupowany po nazwie biblioteki** (`PIKLIB8.dll`, `bloomoodll.dll`…):
|
||
która gra wiezie którą bibliotekę. Haczyk: ta sama nazwa może wystąpić w kilku grach, a *mimo to*
|
||
nie być tym samym silnikiem. Dlatego w obrębie jednej nazwy klastrujemy **warianty po powierzchni
|
||
silnika** (te same zbiory tożsamości co `diff`/`similarity` — kompilator-agnostyczne), a każdy
|
||
wariant inny niż referencyjny (`A`) dostaje **gwiazdkę** `*` z deltą *czym* się różni. Byte-różnice
|
||
z rekompilacji nie generują gwiazdki — liczy się API skryptowe. Prefiks `<sha8>_` doklejany do
|
||
nazwy pliku przy składowaniu (np. `333ab0c4_PIKLIB8.dll`) jest **obcinany przed grupowaniem**, więc
|
||
wszystkie kopie `PIKLIB8.dll` lądują w jednym wierszu (pełna nazwa pliku zostaje w polu `file` JSON-a).
|
||
|
||
```bash
|
||
# z plików snapshot (bez DB/serwera); Label= ustawia kolumnę-grę
|
||
python -m ams.compat \
|
||
"Reksio i UFO=snapshots/PIKLIB8.dll.snapshot.json" \
|
||
"Reksio i Kapitan Nemo=snapshots/bloomoodll.dll.snapshot.json" \
|
||
--format md -o compat.md # albo --format json
|
||
```
|
||
|
||
Z katalogu (DB) przez API — pobiera gotowy plik (`Content-Disposition: attachment`):
|
||
|
||
```bash
|
||
curl -OJ "http://127.0.0.1:8000/compat?format=md" # → compat.md
|
||
curl -OJ "http://127.0.0.1:8000/compat?format=json" # → compat.json (grupy + warianty + diffy)
|
||
```
|
||
|
||
**JSON niesie pełny baseline.** Każdy wariant ma `api` = *co jest obsługiwane*: lista typów oraz
|
||
`classes` (per klasa jej `methods`/`events`/`fields` z nazwami, id, typami). To punkt odniesienia,
|
||
względem którego czyta się diff — masz i „co było", i „co się zmieniło". Diff rozbieżnego wariantu
|
||
siedzi w `vs_reference` (overlap %, zbiorcze liczby + `detail` z nazwanym rozkładem per klasa, bez cap-a).
|
||
|
||
W UI: przyciski **⬇ md** / **⬇ json** w panelu *Gry / wersje*. Markdown to tylko **podgląd**:
|
||
macierz `biblioteka × gra` (`✓` = obecna; `A`/`B*`/… gdy nazwa ma kilka wariantów) plus sekcja
|
||
*Warianty* — dla każdego wariantu liczba i nazwy klas, a dla rozbieżnych skrócony rozkład zmian
|
||
(`CMC_Animo: −PAUSE ~FPS (type int→float)`). Pełne listy metod bierz z JSON-a (`api` / `vs_reference.detail`).
|
||
|
||
## Front — Command Center
|
||
|
||
Po starcie serwera otwórz **http://127.0.0.1:8000/** (`/` → `/ui/`). Statyczny UI bez build-stepu
|
||
(czysty HTML/CSS/JS w `ams/api/static/`, serwowany przez FastAPI): lista gier/wersji, wybór dwóch
|
||
wersji (A/B), wizualny diff po 4 osiach z filtrem klasy i przeglądarka pojedynczej powierzchni.
|
||
Przycisk **+ wgraj** w panelu gier otwiera upload ISO/ZIP/DLL → `POST /jobs`; status zadania
|
||
(queued→started→finished/failed) jest odpytywany na żywo, a po zakończeniu lista wersji odświeża się sama.
|
||
W przeglądarce pojedynczej wersji widać panel **Podobne wersje** (pasek overlapu + `⇄ diff` ustawiający
|
||
A/B i odpalający porównanie).
|
||
|
||
## Format snapshotu
|
||
|
||
`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. Od wersji 6: `type_events`.
|