Files
Aidem-Media-DLL-Analysis/docs/tracker.md
T

6.0 KiB

Atlas API — tracker silników i bibliotek

Atlas łączy snapshoty oryginalnych DLL z rejestracjami MethodSpec w Rex-EMoolator. Nie uruchamia emulatora ani binarek. Nie utożsamia wykrycia metody z poprawną implementacją.

Uruchomienie

Z katalogu tego repozytorium, z zainstalowanymi zależnościami .[api]:

.venv/bin/python -m ams.serve_tracker \
  --emulator-root /ścieżka/do/Rex-EMoolator

Otwórz http://127.0.0.1:8766/ui/tracker.html. Command Center ma odnośnik do Atlasu. GET /tracker oraz GET /tracker?download=1 udostępniają te same dane jako JSON. Snapshoty z bazy i jawnie wskazanego katalogu są łączone i deduplikowane po SHA DLL. Bez SHA używany jest identyfikator snapshotu, jawnie niebędący tożsamością binarki. Katalog snapshotów jest przeszukiwany rekurencyjnie. Wyniki batcha mają pierwszeństwo przed starszymi snapshotami tego samego SHA; konflikt jest widoczny w uwagach, a dane nie są automatycznie scalane. Launcher domyślnie wczytuje data/binary-inventory.json, aby pokazać pokrycie zbioru DLL. Filtr rodziny i wariantu ogranicza dowody oryginału; nadal pokazuje sumę metod API z oznaczeniem „nieustalone” dla braku obserwacji w wybranym zakresie.

Eksport bez serwera:

.venv/bin/python -m ams.tracker snapshots/batch/*.snapshot.json snapshots/*.snapshot.json \
  --emulator-root /ścieżka/do/Rex-EMoolator \
  --reviews tracker-reviews.json --out /tmp/tracker.json

Atlas odczytuje snapshoty z dysku przy każdym pobraniu katalogu. Command Center, diff i eksport zgodności korzystają z bazy SQLite; nowe wyniki można do niej dodać poleceniem .venv/bin/python -m ams.api.importer snapshots/batch/*.snapshot.json.

Interpretacja

  • Zarejestrowana: znaleziono wpis MethodSpec, bez oceny poprawności.
  • Podejrzenie stubu: heurystyka wykryła wyjątek lub komunikat o braku implementacji. Może dotyczyć tylko gałęzi; wymaga przeglądu.
  • Brak rejestracji: adapter nie znalazł wpisu; dynamiczny dispatcher może obsługiwać metodę inaczej.
  • 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. 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.

Dowody poprawności

tracker-reviews.json jest wersjonowanym rejestrem przeglądów; początkowo pustym. Ekstrakcja rejestracji silników, WORLD i KOLOROWANKA nie wypełnia go automatycznie. Każdy wpis wymaga pól tekstowych:

Pole Znaczenie
type, method Para API
binary_sha256, rva Dokładna binarka i adres względny, np. 0xc950
emulator_commit, body_sha256, source_tree_sha256 Rewizja i hashe z eksportu trackera
kind asm lub runtime
verdict matches, partial, differs
reviewer, date Autor i data przeglądu
notes, evidence Zakres porównania i odnośnik do trwałego dowodu/testu

matches oznacza świadomą ocenę całej metody dla wskazanego wariantu; dla sprawdzenia pojedynczego przypadku użyj partial. Sam adres lub dekompilat nie wystarcza do takiej oceny. Zmiana commita lub dowolnego źródła Java w core/src unieważnia przegląd konserwatywnie (także zmiana helpera). Można zachować historyczne wpisy dla starszych rewizji. Sprzeczne, zduplikowane przeglądy tej samej pary i rewizji są odrzucane. Adresy impl_addr, case_addr, registration_addr w snapshotach są VA, nie RVA. Należy odjąć potwierdzoną bazę obrazu przed zapisaniem rva.

Kolejka dalszej analizy

.venv/bin/python -m ams.inventory /ścieżka/do/_dll_repository \
  /ścieżka/do/World.dll /ścieżka/do/Kolorowanka.dll \
  --snapshots snapshots --out /tmp/binary-inventory.json

Manifest zachowuje wszystkie ścieżki identycznych DLL i proponuje pliki wynikowe po pełnym SHA. Nie uruchamia analiz. Klasyfikacja nazw wymaga przeglądu przy przemianowanych DLL. Starsze Pikliby są wyłączone z zakresu, Sekai oznaczone jako zależność natywna.

Kolejka wszystkich unikalnych silników: batch.md. Statyczne dowody pluginów: WORLD i KOLOROWANKA.

Pozostałe etapy: uogólnienie ekstrakcji pluginów na kolejne warianty; uzupełnienie niepełnych mapowań klas, dziedziczenia, pól i zdarzeń; rozstrzygnięcie podwójnej rejestracji WORLD.SETPOSITION; analiza natywnego Sekai; porównanie zachowania i rejestracja przeglądów. Historyczny snapshot 7.1 bez SHA pozostaje oznaczony jako nieustalony; nowe ekstrakcje mają pełną tożsamość DLL. Istniejący ogólny pipeline acquire(directory) nadal wybiera jeden silnik — do masowej analizy służy ams.acquire.batch.