From 835cd4f7293db13bf91e88a9687ee04554beb2dd Mon Sep 17 00:00:00 2001 From: Patryk Gensch <43010113+patryk025@users.noreply.github.com> Date: Sat, 24 Oct 2026 20:34:33 +0200 Subject: [PATCH] feat: Piklib 6.1 method ids, name dispatch and signatures Later 6.1 builds give every runner getMethodId(CXString); its equalsIgnoreCase chain now yields name -> id, so their run(int) switch rows join to names. Runners without a switch (earliest 6.1) get rows from run(CXString) by name, joined by name in the tracker. Method facts run for 6.1 too, with its ABI: run(int, CXVector*), methods as runner members taking only the params, and new CMC_ as the result. Co-Authored-By: Claude Opus 5.5 --- ams/tracker.py | 6 +- ghidra_scripts/extract_engine_surface.py | 139 ++++++++++++++++++++--- tests/test_tracker.py | 14 +++ 3 files changed, 142 insertions(+), 17 deletions(-) diff --git a/ams/tracker.py b/ams/tracker.py index 81beef0..bbdd335 100644 --- a/ams/tracker.py +++ b/ams/tracker.py @@ -431,6 +431,9 @@ def build_tracker(snapshots: list[Snapshot], emulator: dict, reviews: list[dict] id_names[(m["owner"], m["id"])].add(m["name"].upper()) name_ids[(m["owner"], m["name"].upper())].add(m["id"]) dispatch = {(d["owner"], d.get("id")): d for d in snap.method_dispatch if d.get("id") is not None} + # Earliest Piklib 6.1 dispatches by name and has no method ids. + dispatch_by_name = {(d["owner"], d["name"]): d for d in snap.method_dispatch + if d.get("id") is None and d.get("name")} parents = defaultdict(list) for edge in snap.method_inheritance: parents[edge["runner"].removesuffix("_Runner")].append(edge["base_runner"].removesuffix("_Runner")) @@ -472,7 +475,8 @@ def build_tracker(snapshots: list[Snapshot], emulator: dict, reviews: list[dict] type_row(name).setdefault("inherits", []).append(BASE_SCOPE) return for m in owners[current]: - d = dispatch.get((current, m.get("id")), {}) if m.get("id") is not None else {} + d = (dispatch.get((current, m.get("id")), {}) if m.get("id") is not None + else dispatch_by_name.get((current, m["name"].upper()), {})) verdict = {canonical(k): v for k, v in (d.get("per_type") or {}).items()}.get(name) if verdict == "excluded_by_type_check": excluded[(name, m["name"].upper())].add(bid) diff --git a/ghidra_scripts/extract_engine_surface.py b/ghidra_scripts/extract_engine_surface.py index 5466d7b..b1c8fb6 100644 --- a/ghidra_scripts/extract_engine_surface.py +++ b/ghidra_scripts/extract_engine_surface.py @@ -385,22 +385,62 @@ def _extract_name_methods_from_run(program, run_func, owner, runner): def extract_methods_by_name(program): - """Name-dispatched method recovery for engines without prepareMthHashSet (Piklib 6.1).""" + """Name-dispatched method recovery for engines without prepareMthHashSet (Piklib 6.1). + Later 6.1 builds give every runner a `getMethodId(CXString)` (name -> id); the earliest + only compare names inside `run(CXString)`, so those methods have no id.""" fm = program.getFunctionManager() - methods = [] + with_ids = {} + runs = [] it = fm.getFunctions(True) while it.hasNext(): f = it.next() - if f.getName() != "run": - continue ns = f.getParentNamespace() runner = ns.getName() if ns is not None else "?" if not runner.endswith("_Runner"): continue - methods.extend(_extract_name_methods_from_run(program, f, _owner_from_runner(runner), runner)) + if f.getName() == "getMethodId": + with_ids.setdefault(runner, []).extend(_method_ids(program, f, _owner_from_runner(runner), runner)) + elif f.getName() == "run": + runs.append((f, runner)) + methods = [m for rows in with_ids.values() for m in rows] + seen = set() + for f, runner in runs: + if runner in with_ids: + continue + for m in _extract_name_methods_from_run(program, f, _owner_from_runner(runner), runner): + if (runner, m["name"]) not in seen: + seen.add((runner, m["name"])) + methods.append(m) return methods +def _method_ids(program, func, owner, runner): + """getMethodId's chain: `equalsIgnoreCase(name, "lit")`, then `MOV reg, id` on a match.""" + out = [] + seen = set() + pending = None + armed = None + it = program.getListing().getInstructions(resolve_thunk(func).getBody(), True) + while it.hasNext(): + instr = it.next() + s = _string_operand(program, instr) + if s is not None: + pending, armed = s, None + mn = instr.getMnemonicString() + flows = instr.getFlows() if mn == "CALL" else [] + if len(flows) == 1 and any(n == "equalsIgnoreCase" for _, n in _labels(program, flows[0])): + armed, pending = pending, None + elif armed is not None and mn == "MOV" and instr.getNumOperands() == 2 \ + and "[" not in instr.getDefaultOperandRepresentation(0) \ + and instr.getScalar(1) is not None and not instr.getReferencesFrom(): + value = _s32(instr.getScalar(1).getValue()) + if 0 <= value < 0x10000 and armed not in seen: + seen.add(armed) + out.append({"owner": owner, "runner": runner, "name": armed, "id": value}) + armed = None + return out + + _VTBL_OFF = re.compile(r"\[\w+ \+ (0x[0-9a-fA-F]+)\]") _MEM_OFF = re.compile(r"\[\w+ \+ (0x[0-9a-fA-F]+)\]") @@ -590,7 +630,39 @@ def _parse_switch(program, func): "byte_table": byte_table} -def extract_method_dispatch(program, runner_map=None): +def _name_dispatch_from_run(program, run_func, owner, runner, ids): + """Piklib 6.1 `run(CXString name, CXVector*)`: each `equalsIgnoreCase(name, "lit")` match + calls the method's runner member. Rows carry the name (`dispatch: name`) and the id + getMethodId gives, when the build has one.""" + rows = [] + pending = None + armed = None + it = program.getListing().getInstructions(resolve_thunk(run_func).getBody(), True) + while it.hasNext(): + instr = it.next() + s = _string_operand(program, instr) + if s is not None: + pending = s + flows = instr.getFlows() if instr.getMnemonicString() == "CALL" else [] + if len(flows) != 1: + continue + labels = _labels(program, flows[0]) + if any(n == "equalsIgnoreCase" for _, n in labels): + armed, pending = pending, None + elif armed is not None and _is_runner_member(program, flows[0]) and \ + not any(n == "run" for _, n in labels): + impl = resolve_thunk(program.getFunctionManager().getFunctionAt(flows[0])) + if impl is not None: + rows.append({"owner": owner, "runner": runner, "id": ids.get((runner, armed.upper())), + "name": armed.upper(), "dispatch": "name", + "case_addr": "0x%x" % instr.getAddress().getOffset(), + "impl": _qualified(impl), "impl_addr": _hex(impl.getEntryPoint()), + "calls": _walk_calls(program, impl.getEntryPoint(), set())[0]}) + armed = None + return rows + + +def extract_method_dispatch(program, runner_map=None, methods=None): """For each CMC_*_Runner::run, recover how method ids map to their implementation. `run(int id, ...)` is a `switch(id)` (overridden per runner) whose every @@ -627,6 +699,15 @@ def extract_method_dispatch(program, runner_map=None): out.extend(_dispatch_from_run(program, f, _owner_from_runner(runner), runner)) except Exception as e: # one malformed runner shouldn't sink the whole axis print("[!] method_dispatch %s: %s" % (runner, e)) + # Runners without a switch (earliest Piklib 6.1) dispatch by comparing names. + with_rows = set(r["runner"] for r in out) + ids = dict(((m["runner"], m["name"].upper()), m.get("id")) for m in methods or []) + for f, runner in runs: + if runner not in with_rows: + rows = _name_dispatch_from_run(program, f, _owner_from_runner(runner), runner, ids) + if rows: + out.extend(rows) + with_rows.add(runner) return out, run_addrs @@ -1360,7 +1441,8 @@ def extract_class_runners(program): pairs.add((cls, runner)) if not pairs: return None - return {"by_class": [{"class": c, "runner": r} for c, r in sorted(pairs)]} + return {"by_class": [{"class": c, "runner": r} for c, r in sorted(pairs)], + "slots": dict((k, "0x%x" % v) for k, v in _runner_slots(program).items())} def extract_runner_map(program, types): @@ -1408,6 +1490,12 @@ _PARAM_GETTERS = {"getParameter": "any", "getParameterBool": "bool", "getParamet # CMC_VariableFactory call building the result -> result type ("copy": same type as the object). _RESULT_ALLOCATORS = {"allocBool": "bool", "allocDouble": "double", "allocInteger": "int", "allocString": "string", "copyVariable": "copy"} +# Piklib 6.1 has no CMC_VariableFactory: a method builds its result with `new CMC_`. +_RESULT_CTORS = {"CMC_Bool": "bool", "CMC_Double": "double", "CMC_Integer": "int", "CMC_String": "string"} +# Piklib 6.1 keeps one runner per object: run(int id, CXVector* params), and each method is a +# runner member taking only the params. +_RUN61_ROLES = {"ECX": "runner", 8: "params"} +_NAMED_IMPL_ROLES = {"ECX": "runner", 4: "params"} # __thiscall run(int id, CMC_Object* obj, container, CXVector* params): storage -> role. # Keyed by storage, not parameter index: an optimised body without a signature drops an # unused `this` and renumbers what is left. @@ -1440,7 +1528,8 @@ class _Decompiler(object): class _Facts(object): """What one method body does with its arguments, its object and its result.""" - def __init__(self): + def __init__(self, result_ctors=False): + self.result_ctors = result_ctors # count `new CMC_` as the result (Piklib 6.1) self.params = {} # argument index (None: read in a loop) -> set of types self.returns = set() self.object_slots = set() @@ -1565,6 +1654,13 @@ def _vcall(op, roles): return (role, off) if role is not None else None +def _variable_ctor(labels): + for cls, ty in _RESULT_CTORS.items(): + if (cls, cls) in labels: + return ty + return None + + def _member(labels, cls, names): for ns, name in labels: if ns == cls and name in names: @@ -1715,10 +1811,11 @@ def _collect(program, dec, blocks, roles, getters, facts, depth, type_ids): labels = _labels(program, target) this_role = _role(op.getInput(1), roles) if op.getNumInputs() > 1 else None alloc = _member(labels, "CMC_VariableFactory", _RESULT_ALLOCATORS) + built = _variable_ctor(labels) if facts.result_ctors else None helper = this_role == "runner" or (op.getNumInputs() == 1 and _is_runner_member(program, target)) body = program.getFunctionManager().getFunctionAt(target) - if alloc: - facts.returns.add(_RESULT_ALLOCATORS[alloc]) + if alloc or built: + facts.returns.add(_RESULT_ALLOCATORS[alloc] if alloc else built) work.setdefault(b, []).append(True) elif this_role == "object" and _member(labels, "CMC_Object", ("getType",)): if op.getOutput() is not None: @@ -1761,10 +1858,12 @@ def annotate_method_facts(program, method_dispatch, run_addrs, runner_map, types getters = dict((slots[name], ty) for name, ty in _PARAM_GETTERS.items() if name in slots) if not getters: return + legacy = "by_type_id" not in runner_map # Piklib 6.1: no factory, runner per object + run_roles = _RUN61_ROLES if legacy else _RUN_ROLES by_runner = {} for row in method_dispatch: by_runner.setdefault(row["runner"], []).append(row) - runner_of = dict((e["type_id"], e["runner"]) for e in runner_map["by_type_id"]) + runner_of = dict((e["type_id"], e["runner"]) for e in runner_map.get("by_type_id", [])) shared = {} # runner -> {type id: script name}, for runners several types dispatch to for t in types: if t.get("type_id") in runner_of: @@ -1772,17 +1871,25 @@ def annotate_method_facts(program, method_dispatch, run_addrs, runner_map, types dec = _Decompiler(program) try: for runner, rows in by_runner.items(): + for row in [r for r in rows if r.get("dispatch") == "name"]: + impl = _function_at(program, row.get("impl_addr")) + if impl is not None: + facts = _Facts(legacy) + _collect_function(program, dec, resolve_thunk(impl), _NAMED_IMPL_ROLES, getters, + facts, 1, []) + row.update(facts.as_dict()) + rows = [r for r in rows if r.get("dispatch") != "name"] run_func = _function_at(program, run_addrs.get(runner)) - high = dec.high(run_func) if run_func is not None else None + high = dec.high(run_func) if run_func is not None and rows else None if high is None: continue - roles = _storage_roles(program, high, _RUN_ROLES) + roles = _storage_roles(program, high, run_roles) regions = _case_regions(high, set(int(r["case_addr"], 16) for r in rows)) for row in rows: region = regions.get(int(row["case_addr"], 16)) if region is None: continue - facts = _Facts() + facts = _Facts(legacy) group = shared.get(runner, {}) if len(shared.get(runner, {})) > 1 else {} applies = _collect(program, dec, region, roles, getters, facts, 0, sorted(group)) row.update(facts.as_dict()) @@ -1957,8 +2064,8 @@ def run(): 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 and "by_type_id" in runner_map: + method_dispatch, run_addrs = extract_method_dispatch(program, runner_map, methods) + if runner_map: annotate_method_facts(program, method_dispatch, run_addrs, runner_map, types) annotate_type_vftables(program, types, method_dispatch) type_events = extract_type_events(program, types) diff --git a/tests/test_tracker.py b/tests/test_tracker.py index 28b3154..83553e5 100644 --- a/tests/test_tracker.py +++ b/tests/test_tracker.py @@ -354,3 +354,17 @@ def test_fields_per_type_and_emulator_property_literals(tmp_path): integer = {f["name"]: f for f in typ(result, "INTEGER")["fields"]} # class chain, base first assert [f["name"] for f in typ(result, "INTEGER")["fields"]] == ["TOINI", "VALUE"] assert integer["TOINI"]["status"] == "read_base" and integer["VALUE"]["value_types"] == ["int"] + + +def test_name_dispatch_rows_join_methods_without_ids(tmp_path): + snap = Snapshot({"binary": {"name": "p61.dll", "sha256": SHA}, + "types": [{"script_name": "ANIMO", "cpp_class": None}], + "methods": [{"owner": "CMC_Animo", "runner": "CMC_Animo_Runner", "name": "setPosition", "id": None}], + "method_dispatch": [{"owner": "CMC_Animo", "runner": "CMC_Animo_Runner", "id": None, "name": "SETPOSITION", + "dispatch": "name", "impl_addr": "0x10027ff0", "params": [ + {"index": 0, "types": ["int"]}, {"index": 1, "types": ["int"]}], + "variadic": False, "returns": []}]}) + result = build_tracker([snap], emulator(tmp_path)) + entry = row(result, "ANIMO", "SETPOSITION") + assert entry["original"][0]["impl_addr"] == "0x10027ff0" + assert entry["signatures"] == ["(int, int) → —"]