From 11f4b6fc37ce70dc4ddabed94c5e37beb65d1377 Mon Sep 17 00:00:00 2001 From: Patryk Gensch <43010113+patryk025@users.noreply.github.com> Date: Sat, 24 Oct 2026 18:59:58 +0200 Subject: [PATCH] feat: map Piklib 6.1 types through constructor-created runners Piklib 6.1 predates CMC_RunnerFactory; each class constructor creates its own runner. The extractor records class -> runner from those call sites (runner_map.by_class) and the tracker walks the snapshot's constructor chain from a type's class to the nearest one creating a runner, so 6.1 variable and condition types no longer fall into pseudo-types either. Co-Authored-By: Claude Opus 5.5 --- ams/api/static/tracker.js | 2 +- ams/tracker.py | 24 +++++++++++++++++ ghidra_scripts/extract_engine_surface.py | 34 +++++++++++++++++++++--- tests/test_tracker.py | 15 +++++++++++ 4 files changed, 71 insertions(+), 4 deletions(-) diff --git a/ams/api/static/tracker.js b/ams/api/static/tracker.js index 831b7f5..452b9bf 100644 --- a/ams/api/static/tracker.js +++ b/ams/api/static/tracker.js @@ -1,5 +1,5 @@ 'use strict'; -const MAPPING={explicit:'Jawne (klasa C++ z fabryki)',runner_factory:'CMC_RunnerFactory (typ → runner)',inferred:'Wywnioskowane z nazwy'}; +const MAPPING={explicit:'Jawne (klasa C++ z fabryki)',runner_factory:'CMC_RunnerFactory (typ → runner)',class_constructor:'Runner tworzony w konstruktorze klasy',inferred:'Wywnioskowane z nazwy'}; const $ = id => document.getElementById(id); const labels = {missing:'Brak rejestracji',registered:'Zarejestrowana',stub_candidate:'Podejrzenie stubu',partial:'Częściowa',implemented:'Zaimplementowana',unverified:'Niezweryfikowana',asm_reviewed:'Przegląd ASM',runtime_tested:'Test zachowania',stale:'Dowód wymaga aktualizacji'}; let data, selected = null; diff --git a/ams/tracker.py b/ams/tracker.py index dd9db82..ef74574 100644 --- a/ams/tracker.py +++ b/ams/tracker.py @@ -182,6 +182,23 @@ BASE_SCOPE = "*" BUILTIN_SCOPE, BUILTIN_TYPE_ID = "@", 0 +def _constructor_runner(name, cpp_class, class_runner, bases, known_classes): + """Runner owner for engines whose class constructors create their runner (Piklib 6.1): + the nearest class up this snapshot's constructor chain that creates one.""" + if not class_runner: + return None + if not cpp_class: + candidates = [c for c in known_classes if owner_name(c) == name] + cpp_class = candidates[0] if len(candidates) == 1 else None + seen = set() + while cpp_class and cpp_class not in seen: + if cpp_class in class_runner: + return class_runner[cpp_class] + seen.add(cpp_class) + cpp_class = bases.get(cpp_class) + return None + + def script_owners(snap: Snapshot, owners) -> dict[str, tuple[str, str]]: """Script scope -> (method owner, provenance) for one binary. @@ -190,6 +207,9 @@ def script_owners(snap: Snapshot, owners) -> dict[str, tuple[str, str]]: 6.1, plugins, older extractions) the C++ class or its name is the best available guess.""" runner_map = snap.raw.get("runner_map") or {} by_type_id = {e["type_id"]: e["runner"].removesuffix("_Runner") for e in runner_map.get("by_type_id", [])} + class_runner = {e["class"]: e["runner"].removesuffix("_Runner") for e in runner_map.get("by_class", [])} + bases = {e["class"]: e["base_class"] for e in snap.field_inheritance} + known_classes = set(class_runner) | set(bases) | set(bases.values()) mappings = {} if BUILTIN_TYPE_ID in by_type_id: mappings[BUILTIN_SCOPE] = (by_type_id[BUILTIN_TYPE_ID], "runner_factory") @@ -198,6 +218,10 @@ def script_owners(snap: Snapshot, owners) -> dict[str, tuple[str, str]]: if t.get("type_id") in by_type_id: mappings[name] = (by_type_id[t["type_id"]], "runner_factory") continue + runner_owner = _constructor_runner(name, t.get("cpp_class"), class_runner, bases, known_classes) + if runner_owner: + mappings[name] = (runner_owner, "class_constructor") + continue owner, mapping = t.get("cpp_class"), "explicit" # Known extractor failure: unrelated factory entries all mapped to Behaviour. if owner == "CMC_Behaviour" and name != "BEHAVIOUR": diff --git a/ghidra_scripts/extract_engine_surface.py b/ghidra_scripts/extract_engine_surface.py index 9fe145d..078122b 100644 --- a/ghidra_scripts/extract_engine_surface.py +++ b/ghidra_scripts/extract_engine_surface.py @@ -1263,6 +1263,34 @@ def _runner_from_global(name): return "CMC_%s_Runner" % name[1:-len("Runner")] +def extract_class_runners(program): + """{"by_class": [{class, runner}]} for engines without CMC_RunnerFactory (Piklib 6.1), + where every class constructor creates its own runner: CMC_Variable's constructor makes + CMC_Variable_Runner and CMC_Integer inherits it through that base constructor.""" + fm = program.getFunctionManager() + refs = program.getReferenceManager() + pairs = set() + it = fm.getFunctions(True) + while it.hasNext(): + f = it.next() + ns = f.getParentNamespace() + runner = ns.getName() if ns is not None else "" + if f.getName() != runner or not runner.endswith("_Runner") or runner == "CMC_Runner": + continue + for ref in refs.getReferencesTo(f.getEntryPoint()): + if not ref.getReferenceType().isCall(): + continue + caller = fm.getFunctionContaining(ref.getFromAddress()) + if caller is None: + continue + for cls, name in _labels(program, caller.getEntryPoint()): + if cls == name and cls.startswith(CMC_PREFIX) and not cls.endswith("_Runner"): + pairs.add((cls, runner)) + if not pairs: + return None + return {"by_class": [{"class": c, "runner": r} for c, r in sorted(pairs)]} + + def extract_runner_map(program, types): """Which runner executes each script type, from CMC_RunnerFactory (Piklib 7.1+, BlooMoo). @@ -1804,13 +1832,13 @@ def run(): engine, compiler = detect_engine(factory) # namespace lives on the symbol/stub factory = resolve_thunk(factory) # MSVC8 exposes the symbol as a JMP stub types = extract_types(program, factory) - runner_map = extract_runner_map(program, types) + runner_map = extract_runner_map(program, types) or extract_class_runners(program) methods, method_inheritance = extract_methods(program, runner_map) events = extract_events(program) fields = extract_script_fields(program) struct_layout, field_inheritance = extract_struct_layout(program) method_dispatch, run_addrs = extract_method_dispatch(program, runner_map) - if runner_map: + if runner_map and "by_type_id" in runner_map: annotate_method_facts(program, method_dispatch, run_addrs, runner_map, types) annotate_type_vftables(program, types, method_dispatch) @@ -1845,7 +1873,7 @@ def run(): print("[+] %s [%s/%s]: %d types, %d methods, %d events, %d fields (%d layout, %d dispatch, %d runners) -> %s" % ( program.getName(), engine, compiler, len(types), len(methods), len(events), len(fields), len(struct_layout), len(method_dispatch), - len(runner_map["runners"]) if runner_map else 0, out_path)) + len((runner_map or {}).get("runners", [])), out_path)) run() diff --git a/tests/test_tracker.py b/tests/test_tracker.py index 84dc4b7..2a63b46 100644 --- a/tests/test_tracker.py +++ b/tests/test_tracker.py @@ -262,3 +262,18 @@ def test_shared_runner_methods_follow_per_type_verdicts(tmp_path): assert row(result, "STRING", "ADD")["signatures"] == ["(int) → copy"] assert any("bez efektu" in n for n in row(result, "INTEGER", "ADD")["notes"]) assert row(result, "INTEGER", "ADD")["original"][0]["per_type"] == "trivial_virtual" + + +def test_class_constructor_runners_map_piklib61_types(tmp_path): + snap = Snapshot({"binary": {"name": "p61.dll", "sha256": SHA}, + "types": [{"script_name": "INTEGER", "cpp_class": None}, {"script_name": "CONDITION", "cpp_class": None}], + "methods": [{"owner": "CMC_Variable", "runner": "CMC_Variable_Runner", "name": "inc", "id": None}, + {"owner": "CMC_BasicCondition", "runner": "CMC_BasicCondition_Runner", "name": "check", "id": None}], + "field_inheritance": [{"class": "CMC_Integer", "base_class": "CMC_Variable"}, + {"class": "CMC_Condition", "base_class": "CMC_BasicCondition"}], + "runner_map": {"by_class": [{"class": "CMC_Variable", "runner": "CMC_Variable_Runner"}, + {"class": "CMC_BasicCondition", "runner": "CMC_BasicCondition_Runner"}]}}) + result = build_tracker([snap], emulator(tmp_path)) + assert row(result, "INTEGER", "INC")["original"][0]["mapping"] == "class_constructor" + assert row(result, "CONDITION", "CHECK")["original"] + assert not {"VARIABLE", "BASICCONDITION"} & {t["name"] for t in result["types"]}