# Extract the "engine surface" (types/methods/events/fields) from a Piklib/BlooMoo # engine DLL and emit a snapshot.json for cross-version diffing. # # Runs as a Ghidra **headless** post-script. Compatible with both pyghidra (CPython 3) # and the bundled Jython 2.7, so it avoids f-strings and py3-only APIs. # # Usage (headless): # analyzeHeadless -process PIKLIB8.dll \ # -postScript extract_engine_surface.py /abs/path/out.snapshot.json # # Design note: extraction stands on SEMANTIC ANCHORS (call targets, referenced string # constants, push immediates), never on decompiled-C text. That is what makes the same # script work across MSVC6 (Piklib) and MSVC8 (BlooMoo) despite very different codegen. # # @category AidemMedia from __future__ import print_function import json import hashlib import os import re import tempfile from ghidra.app.decompiler import DecompInterface from ghidra.program.model.pcode import PcodeOp # Names of the helper functions the factory dispatch relies on. These survive demangling # identically on both compilers. OP_NEW = "operator_new" OP_EQ = "operator==" CMC_PREFIX = "CMC_" # How many preceding instructions to inspect when recovering a PUSH argument. LOOKBACK = 8 # --------------------------------------------------------------------------- helpers def find_function_by_qualified(program, class_name, method_name): """Find a function `method_name` whose immediate parent namespace is `class_name`.""" fm = program.getFunctionManager() it = fm.getFunctions(True) while it.hasNext(): f = it.next() if f.getName() != method_name: continue ns = f.getParentNamespace() if ns is not None and ns.getName() == class_name: return f return None def call_target(program, instr): """Resolve the (possibly thunked) function a direct CALL points at, or None.""" fm = program.getFunctionManager() for a in instr.getFlows(): f = fm.getFunctionAt(a) if f is not None: return f return None def resolve_thunk(func): """Follow an incremental-linking (ILT) thunk to the real function. MSVC8 places a `JMP real` stub at the symbol address; the actual body lives elsewhere. Two cases: (a) Ghidra modelled it as a real thunk function, or (b) it didn't, and the stub is just a function whose entire body is one unconditional `JMP real` (the symbol `resolve` sits on the stub, while the body is e.g. FUN_xxxx).""" if func is None: return func if func.isThunk(): return func.getThunkedFunction(True) instr = currentProgram.getListing().getInstructionAt(func.getEntryPoint()) if instr is not None: ft = instr.getFlowType() if ft.isJump() and not ft.isConditional(): flows = instr.getFlows() if len(flows) == 1: target = currentProgram.getFunctionManager().getFunctionAt(flows[0]) if target is not None: return target return func def _read_cstring(program, addr, maxlen=64): """Read a NUL-terminated printable-ASCII string straight from memory. Needed because some type-name literals (e.g. "BOOL", "FONT") are referenced but never defined as Data, so getDataAt() returns nothing for them.""" mem = program.getMemory() chars = [] i = 0 while i < maxlen: try: b = mem.getByte(addr.add(i)) & 0xff except: # noqa: E722 - Java MemoryAccessException isn't a Python Exception under Jython return None if b == 0: return "".join(chars) if chars else None if b < 0x20 or b > 0x7e: return None # not a clean type-name literal chars.append(chr(b)) i += 1 return None # the bound was reached without a terminator def _string_at(program, addr): if addr is None or not addr.isMemoryAddress(): return None # skip stack/register/constant refs (e.g. inline CXString stack buffers) # Registration operands point to literal bytes. Prefer them over an analyzer's # typed string boundary (which can split short/overlapping literals). raw = _read_cstring(program, addr) if raw is not None: return raw d = program.getListing().getDataAt(addr) if d is not None and d.hasStringValue(): return str(d.getValue()) return None def lookback_string(program, recent): """Most recent PUSH that references (or immediately points at) a string constant.""" af = program.getAddressFactory().getDefaultAddressSpace() for instr in reversed(recent): if instr.getMnemonicString() != "PUSH": continue for ref in instr.getReferencesFrom(): s = _string_at(program, ref.getToAddress()) if s is not None: return s sc = instr.getScalar(0) # fallback: treat the immediate as an address if sc is not None: try: s = _string_at(program, af.getAddress(sc.getUnsignedValue())) if s is not None: return s except Exception: pass return None def lookback_scalar(recent): """Most recent PUSH of a plain integer immediate (the operator_new size).""" for instr in reversed(recent): if instr.getMnemonicString() == "PUSH": sc = instr.getScalar(0) if sc is not None and not instr.getReferencesFrom(): return int(sc.getUnsignedValue()) return None # A load from an object field: `[ + 0xNN]` with a general register base (not the stack # pointer/base ESP/EBP). The module-interface dispatch branches fetch their container from a # field of `this` this way, while the direct branches pass `this` straight from a register. # Offset-agnostic, so it survives different compilers/struct layouts. _FIELD_LOAD = re.compile(r"\[E(?:AX|BX|CX|DX|SI|DI) \+ 0x[0-9a-fA-F]+\]") def _branch_uses_field_load(branch): for instr in branch: if _FIELD_LOAD.search(instr.toString()): return True return False def _imm_string(program, instr): """If any operand is an immediate that points at a printable string, return that string. Used for method names: they are loaded as `MOV reg, `, and the immediate is the true string start. Relying on references instead breaks under MSVC6, whose inline strcpy references string+1 (first char handled separately), truncating the name by one char.""" af = program.getAddressFactory().getDefaultAddressSpace() for opi in range(instr.getNumOperands()): sc = instr.getScalar(opi) if sc is None: continue try: s = _string_at(program, af.getAddress(sc.getUnsignedValue())) except: # noqa: E722 continue if s is not None: return s return None # --------------------------------------------------------------------------- extractors def extract_types(program, factory): """Walk CMC_ObjectsContainer::resolve, recovering the type-dispatch ladder. Per branch the engine emits, in order: CALL operator==(typeStr, "NAME") -> script type name CALL operator_new(SIZE) -> object allocation size CALL (...) -> the next call IS the constructor The constructor is detected *structurally* (first CALL after operator_new), not by name: several ctors are unnamed FUN_xxxx (e.g. CMC_Text, CMC_Movie) and name-gating dropped them. """ listing = program.getListing() types = [] recent = [] branch = [] # instructions since the current branch's operator== match pending_name = None pending_size = None armed = False # set by operator_new; the next CALL is the object's constructor it = listing.getInstructions(factory.getBody(), True) while it.hasNext(): instr = it.next() if instr.getMnemonicString() == "CALL": f = call_target(program, instr) tname = f.getName() if f is not None else None if tname == OP_EQ: # Tag-based factory (Piklib 6.1/7.1's CMC_Scene::resolve): a branch is # `operator==(NAME) -> new(SIZE) -> store tag -> jmp`, with the ctor in a # separate tag switch, so no inline ctor ever fires `elif armed`. If we reach # the *next* operator== still armed, record the pending type by name (size known, # ctor not). The inline-ctor factory (8.x) clears `armed` first, so it's untouched. if armed and pending_name is not None: types.append({ "script_name": pending_name, "cpp_class": None, "ctor_addr": None, "object_size": pending_size, "dispatch_addr": None, "via_module_iface": _branch_uses_field_load(branch), }) pending_name = None pending_size = None armed = False s = lookback_string(program, recent) if s is not None: pending_name = s branch = [] elif tname == OP_NEW: pending_size = lookback_scalar(recent) armed = True elif armed: if pending_name is not None and f is not None: ctor = resolve_thunk(f) cls = f.getName() types.append({ "script_name": pending_name, "cpp_class": cls if cls.startswith(CMC_PREFIX) else None, "ctor_addr": "0x%x" % ctor.getEntryPoint().getOffset(), "object_size": pending_size, "dispatch_addr": "0x%x" % instr.getAddress().getOffset(), "via_module_iface": _branch_uses_field_load(branch), }) pending_name = None pending_size = None armed = False recent.append(instr) branch.append(instr) if len(recent) > LOOKBACK: recent.pop(0) return types def _owner_from_runner(runner_name): """CMC_Animo_Runner -> CMC_Animo ; CMC_Runner -> CMC (the base that holds global methods).""" if runner_name.endswith("_Runner"): return runner_name[:-len("_Runner")] return runner_name def _is_method_name(s): return bool(s) and all(c.isalnum() or c == "_" for c in s) def _extract_methods_from(program, runner_func, runner=None): """Walk one CMC_*_Runner::prepareMthHashSet, recovering its directly-registered methods. Per method the engine emits: new CInteger(ID) ; new CStringHashCode("NAME") ; CHashtable::put. The method name is *loaded* (MOV), not pushed, so we track the most recent string literal referenced by any instruction rather than scanning PUSH operands. The leading call to the base class's prepareMthHashSet gives the inheritance link (inherited/global methods). `runner` names a registration reached through a vtable rather than a symbol (see `extract_runner_map`); otherwise the function's namespace is the runner class.""" listing = program.getListing() methods = [] base_runner = None last_string = None last_id = None pending_name = None recent = [] if runner is None: ns = runner_func.getParentNamespace() runner = ns.getName() if ns is not None else "?" owner = _owner_from_runner(runner) it = listing.getInstructions(resolve_thunk(runner_func).getBody(), True) while it.hasNext(): instr = it.next() s = _imm_string(program, instr) if s is not None and _is_method_name(s): last_string = s if instr.getMnemonicString() == "CALL": cf = call_target(program, instr) cname = cf.getName() if cf is not None else None cns = cf.getParentNamespace() if cf is not None else None cns_name = cns.getName() if cns is not None else None if cname == "prepareMthHashSet": if base_runner is None: base_runner = cns_name elif cname == "CInteger": last_id = lookback_scalar(recent) elif cname == "CStringHashCode": pending_name = last_string elif cname == "put" and cns_name == "CHashtable": if pending_name is not None: methods.append({"owner": owner, "runner": runner, "name": pending_name, "id": last_id}) pending_name = None recent.append(instr) if len(recent) > LOOKBACK: recent.pop(0) return methods, runner, base_runner def extract_methods(program, runner_map=None): """Returns (methods, inheritance). `methods` lists each Runner's directly-registered methods; `inheritance` maps each runner to the base runner it chains to, so the consumer can compose the full (incl. global) method set per type. Runners without a symbol are reached through `runner_map` vtables.""" fm = program.getFunctionManager() methods = [] inheritance = [] seen = set() it = fm.getFunctions(True) while it.hasNext(): f = it.next() if f.getName() != "prepareMthHashSet": continue seen.add(resolve_thunk(f).getEntryPoint().getOffset()) own, runner, base = _extract_methods_from(program, f) methods.extend(own) if base is not None: inheritance.append({"runner": runner, "base_runner": base}) for r in (runner_map or {}).get("runners", []): f = _function_at(program, r.get("prepare_addr")) if f is None or resolve_thunk(f).getEntryPoint().getOffset() in seen: continue seen.add(resolve_thunk(f).getEntryPoint().getOffset()) own, runner, base = _extract_methods_from(program, f, r["runner"]) methods.extend(own) if base is not None: inheritance.append({"runner": runner, "base_runner": base}) if not methods: # Piklib 6.1 predates prepareMthHashSet: methods are dispatched by NAME inside # ::run, so recover the names from there instead (no numeric ids). methods = extract_methods_by_name(program) return methods, inheritance def _extract_name_methods_from_run(program, run_func, owner, runner): """Piklib 6.1's `run(CXString name, ...)` is a chain of `CXString(tmp, "name")` then `equalsIgnoreCase(name)`; the literal built right before each compare is a method name.""" listing = program.getListing() methods = [] recent = [] pending = None seen = set() it = listing.getInstructions(resolve_thunk(run_func).getBody(), True) while it.hasNext(): instr = it.next() if instr.getMnemonicString() == "CALL": f = call_target(program, instr) nm = f.getName() if f is not None else None if nm == "CXString": # CXString(tmp, ) builds the literal s = lookback_string(program, recent) if s is not None and _is_method_name(s): pending = s elif nm == "equalsIgnoreCase" and pending is not None: if pending not in seen: seen.add(pending) methods.append({"owner": owner, "runner": runner, "name": pending, "id": None}) pending = None recent.append(instr) if len(recent) > LOOKBACK: recent.pop(0) return methods def extract_methods_by_name(program): """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() with_ids = {} runs = [] it = fm.getFunctions(True) while it.hasNext(): f = it.next() ns = f.getParentNamespace() runner = ns.getName() if ns is not None else "?" if not runner.endswith("_Runner"): continue 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] # run(CXString) names complete getMethodId's: a name it lacks is kept without an id. seen = set((m["runner"], m["name"].upper()) for m in methods) for f, runner in runs: for m in _extract_name_methods_from_run(program, f, _owner_from_runner(runner), runner): if (runner, m["name"].upper()) not in seen: seen.add((runner, m["name"].upper())) methods.append(m) return methods def _method_ids(program, func, owner, runner): """getMethodId's chain: `equalsIgnoreCase(name, "lit")`, then `MOV , id` on a match - a register in optimised builds, a stack local in unoptimised ones (Pinokio).""" 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(1) and instr.getScalar(1) is not None: # No reference check: a stack-local destination carries a stack reference, and # the < 0x10000 bound below already rules out address immediates. 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]+)\]") def _is_generic_name(name): """A compiler-assigned placeholder, not a real symbol.""" return (not name) or name.startswith("FUN_") or name.startswith("thunk_") or name.startswith("LAB_") def _executable(program, addr): """True if `addr` lives in an executable memory block - a sanity gate so a switch shape we don't model (or a table over-read) can never emit a non-code 'case' as a method.""" blk = program.getMemory().getBlock(addr) return blk is not None and blk.isExecute() def _qualified(f): if f is None: return None ns = f.getParentNamespace() nm = f.getName() return (ns.getName() + "::" + nm) if (ns is not None and ns.getName() != "Global") else nm def _call_anchor(program, instr): """A normalisable, compiler-tolerant fingerprint of one CALL inside a switch case. Direct call -> "Namespace::name". On MSVC8 the symbol sits on the ILT *stub* while the body is an unnamed FUN_, so we keep the stub's name and only fall back to the thunk-resolved body when the direct name is itself a placeholder. Indirect virtual call -> "vtbl+0xNN" from the displacement, which abstracts away the register holding `this`.""" cf = call_target(program, instr) if cf is not None: if not _is_generic_name(cf.getName()): return _qualified(cf) resolved = resolve_thunk(cf) if resolved is not None and not _is_generic_name(resolved.getName()): return _qualified(resolved) return _qualified(cf) m = _VTBL_OFF.search(instr.toString()) if m is not None: return "vtbl+" + m.group(1) return None def _walk_calls(program, start_addr, stops, limit=80): """Walk a straight-line block from `start_addr`, returning (anchors, funcs): * `anchors` - ordered CALL fingerprints (see `_call_anchor`), additionally recovering the `MOV reg,[base+0xNN]` / `CALL reg` virtual-call idiom (MSVC8) as `vtbl+0xNN`, so it matches the `CALL [reg+0xNN]` form (MSVC6). * `funcs` - the (anchor, entry) of each *direct* call to a real function, used to detect a thin wrapper case that just forwards to a named/unnamed submethod. Stops at a RET, an unconditional jump, a `stops` address, or after `limit` instructions.""" listing = program.getListing() instr = listing.getInstructionAt(start_addr) anchors = [] funcs = [] regoff = {} # register -> vtable offset most recently loaded into it n = 0 while instr is not None and n < limit: if n > 0 and instr.getAddress() in stops: break n += 1 mn = instr.getMnemonicString() if mn == "MOV" and instr.getNumOperands() >= 2: dst = instr.getDefaultOperandRepresentation(0) m = _MEM_OFF.search(instr.toString()) if m is not None: regoff[dst] = m.group(1) else: regoff.pop(dst, None) elif mn == "CALL": a = _call_anchor(program, instr) if a is None: # CALL reg -> use the offset last loaded into that register op0 = instr.getDefaultOperandRepresentation(0) if op0 in regoff: a = "vtbl+" + regoff[op0] if a is not None: anchors.append(a) cf = call_target(program, instr) if cf is not None: body = resolve_thunk(cf) if body is not None: funcs.append((a, body.getEntryPoint())) ft = instr.getFlowType() if ft.isTerminal() or (ft.isJump() and not ft.isConditional()): break instr = instr.getNext() return anchors, funcs _SWITCH_JMP = re.compile(r"\[(\w+)\*0x4 \+ (0x[0-9a-fA-F]+)\]") _LEA_DISP = re.compile(r"\[\w+ \+ (-?0x[0-9a-fA-F]+)\]") # A two-level switch's byte-index-table load: `byte ptr [ + ]`. The 5+ hex # digits distinguish a table address (0x100xxxxx) from a small struct-field offset. _BYTE_TABLE = re.compile(r"byte ptr \[(\w+) \+ (0x[0-9a-fA-F]{5,})\]") def _lea_disp(instr): """Signed displacement of a `LEA reg,[base + disp]`, parsed from text when getScalar misses.""" m = _LEA_DISP.search(instr.toString()) return int(m.group(1), 16) if m is not None else None def _s32(v): """Interpret a scalar as 32-bit signed. Ghidra's getScalar() hands back the raw unsigned immediate, so e.g. `ADD idx, 0xFFFFFEFF` (really -257, a switch starting at id 257) must be sign-extended or the recovered ids overflow to nonsense.""" v = int(v) & 0xffffffff return v - 0x100000000 if v >= 0x80000000 else v def _parse_switch(program, func): """Recover the dense jump-table switch of a `run` function at the disassembly level (decompiler-independent, so it survives the big inline-heavy runners). Both MSVC6 and MSVC8 emit the same shape: LEA idx,[reg - base] ; CMP idx, range ; JA default ; JMP [idx*4 + TABLE] Returns {table, base, count, default} or None. `id = table_index + base`; `count = range + 1`. `default` is the out-of-range target of the `JA default` bounds check - the jump table also routes its *holes* (ids the runner doesn't implement) there, so cases pointing at it are not real methods and must be dropped.""" listing = program.getListing() space = program.getAddressFactory().getDefaultAddressSpace() instrs = [] it = listing.getInstructions(func.getBody(), True) while it.hasNext(): instrs.append(it.next()) idx_reg = table = jmp_addr = default = None for instr in instrs: ft = instr.getFlowType() if ft.isJump() and ft.isConditional(): # the `JA default` bounds check (last one wins) flows = instr.getFlows() if len(flows) > 0: default = flows[0] if instr.getMnemonicString() == "JMP" and ft.isComputed(): m = _SWITCH_JMP.search(instr.toString()) if m is not None: idx_reg = m.group(1) table = space.getAddress(int(m.group(2), 16)) jmp_addr = instr.getAddress() break if table is None: return None # Two-level switch: the index is itself looked up in a byte table - `MOVZX r, byte[i+bt]` # (MSVC8) or `XOR r,r; MOV rl, byte[i+bt]` (MSVC6). Targets are ptrTable[byteTable[i]]. The # *bounds* register (the `i` indexing the byte table) is what LEA/CMP constrain - which on # MSVC6 differs from the JMP's index register - so recover it from the byte-table load. byte_table = None bounds_reg = idx_reg for instr in instrs: if instr.getAddress().equals(jmp_addr): break mbt = _BYTE_TABLE.search(instr.toString()) if mbt is not None: bounds_reg = mbt.group(1) byte_table = space.getAddress(int(mbt.group(2), 16)) break base, count = _switch_bounds(instrs, jmp_addr, set([bounds_reg])) if count is None: # unoptimised build: the index lives in a stack slot base, count = _switch_bounds(instrs, jmp_addr, _index_aliases(instrs, jmp_addr, bounds_reg)) return {"table": table, "base": base, "count": count, "default": default, "byte_table": byte_table} def _switch_bounds(instrs, jmp_addr, operands): """(base, count) from the arithmetic and the bounds CMP applied to the index `operands`.""" base = 0 count = None for instr in instrs: if instr.getAddress().equals(jmp_addr): break if instr.getNumOperands() == 0 or instr.getDefaultOperandRepresentation(0) not in operands: continue mn = instr.getMnemonicString() s = instr.getScalar(1) if mn == "CMP" and s is not None: count = _s32(s.getValue()) + 1 elif mn == "LEA": # LEA idx,[reg - k] -> id = index + k raw = s.getValue() if s is not None else _lea_disp(instr) if raw is not None: # _s32 also fixes the text path: Ghidra prints a base = -_s32(raw) # big displacement unsigned ("0xfffffeff" = -257) elif mn == "SUB" and s is not None: base = _s32(s.getValue()) elif mn == "ADD" and s is not None: base = -_s32(s.getValue()) elif mn == "DEC": base = 1 return base, count def _index_aliases(instrs, jmp_addr, reg): """Operands that hold the switch index in an unoptimised build, which round-trips it through a stack slot: `SUB ECX,1 ; MOV [EBP-0xc],ECX ; CMP [EBP-0xc],0xc3 ; MOV EDX,[EBP-0xc]`.""" aliases = set([reg]) for _ in range(3): for instr in instrs: if instr.getAddress().equals(jmp_addr): break if instr.getMnemonicString() != "MOV" or instr.getNumOperands() != 2: continue dst, src = instr.getDefaultOperandRepresentation(0), instr.getDefaultOperandRepresentation(1) if dst in aliases and src.startswith("dword ptr ["): aliases.add(src) elif dst in aliases and re.match(r"E[A-Z]{2}$", src): aliases.add(src) elif src in aliases and dst.startswith("dword ptr ["): aliases.add(dst) return aliases 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 `case id:` is the method body - either a tail-call to a named submethod (BlooMoo/MSVC8 keeps show()/load()/... as separate functions) or inline code whose leaves are virtual calls on the wrapped object (Piklib/MSVC6). We fingerprint each case by its ordered CALL anchors, so a later pass can diff method *bodies* by (owner, id). Join names via `methods`. Returns (rows, {runner: run function address}).""" fm = program.getFunctionManager() out = [] seen = set() 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 runner.endswith("_Runner"): runs.append((f, runner)) for r in (runner_map or {}).get("runners", []): f = _function_at(program, r.get("run_addr")) if f is not None: runs.append((f, r["runner"])) run_addrs = {} for f, runner in runs: entry = resolve_thunk(f).getEntryPoint().getOffset() if entry in seen: continue seen.add(entry) run_addrs[runner] = "0x%x" % entry try: 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 def _dispatch_from_run(program, run_func, owner, runner): run_func = resolve_thunk(run_func) sw = _parse_switch(program, run_func) if sw is None: return [] count = sw["count"] if count is None or count < 1 or count > 4096: return [] mem = program.getMemory() space = program.getAddressFactory().getDefaultAddressSpace() ptr = sw["table"] byte_table = sw.get("byte_table") targets = [] for i in range(count): try: # Two-level switch: index the pointer table through the byte index table. slot = (mem.getByte(byte_table.add(i)) & 0xff) if byte_table is not None else i val = mem.getInt(ptr.add(slot * 4)) & 0xffffffff except Exception: break targets.append(space.getAddress(val)) stops = set(t for t in targets if _executable(program, t)) default = sw.get("default") rows = [] for i in range(len(targets)): mid = i + sw["base"] if mid < 0 or mid > 0xffff: continue # nonsensical id -> the switch base wasn't recovered cleanly; don't emit garbage if not _executable(program, targets[i]): continue # target isn't code (unsupported switch shape / over-read) -> skip, never emit garbage if default is not None and targets[i].equals(default): continue # a switch hole (unimplemented id) routed to the base-runner default anchors, funcs = _walk_calls(program, targets[i], stops) # A thin wrapper case forwards to one submethod: the real body (and its leaf anchors) # live in that function. Expanding one level makes MSVC8 (separate show()/load()) line up # with MSVC6 (inline), so `calls` is a compiler-tolerant body fingerprint. if len(anchors) == 1 and len(funcs) == 1 and funcs[0][0] == anchors[0]: impl = funcs[0][0] impl_entry = funcs[0][1] impl_addr = "0x%x" % impl_entry.getOffset() calls, _ = _walk_calls(program, impl_entry, set()) else: impl = None impl_addr = "0x%x" % targets[i].getOffset() # body is inline in the case block calls = anchors rows.append({ "owner": owner, "runner": runner, "id": mid, "case_addr": "0x%x" % targets[i].getOffset(), "impl": impl, "impl_addr": impl_addr, "calls": calls, }) return rows def extract_events(program): """Per CMC_*::getBehavioursList, collect the ordered event-name literals (ONINIT, ONDONE, ...). The function builds a flat CXString[] with each name inlined; there is no base-class call, so each class's list is self-contained (no inheritance chain, unlike methods). Each literal is loaded twice per entry (strlen + memcpy), so consecutive duplicates are collapsed.""" fm = program.getFunctionManager() events = [] it = fm.getFunctions(True) while it.hasNext(): f = it.next() if f.getName() != "getBehavioursList": continue ns = f.getParentNamespace() owner = ns.getName() if ns is not None else "?" for order, name in enumerate(_event_literals(program, f)): events.append({"owner": owner, "name": name, "order": order}) return events def _event_literals(program, func): """Ordered event names a getBehavioursList body builds; each literal is loaded twice per entry (strlen + memcpy), so consecutive duplicates collapse.""" names = [] last = None ins = program.getListing().getInstructions(resolve_thunk(func).getBody(), True) while ins.hasNext(): s = _imm_string(program, ins.next()) if s is not None and _is_method_name(s) and s != last: names.append(s) last = s return names def _is_cmc_ctor(func): ns = func.getParentNamespace() return ns is not None and func.getName() == ns.getName() and func.getName().startswith(CMC_PREFIX) def _this_varnodes(high): """Varnodes that represent the `this` parameter (parameter category index 0).""" out = set() syms = high.getLocalSymbolMap().getSymbols() while syms.hasNext(): s = syms.next() if s.isParameter() and s.getCategoryIndex() == 0: hv = s.getHighVariable() if hv is not None: for vn in hv.getInstances(): out.add(vn) return out def _trace_this_offset(vn, this_vns, depth=0): """If `vn` is `this + constant`, return the constant; else None. Walks the def chain through the address arithmetic the decompiler emits (this abstracts away which register held `this`).""" if vn is None or depth > 12: return None if vn in this_vns: return 0 d = vn.getDef() if d is None: return None op = d.getOpcode() ins = d.getInputs() if op in (PcodeOp.INT_ADD, PcodeOp.PTRADD): a, b = ins[0], ins[1] if b.isConstant(): base = _trace_this_offset(a, this_vns, depth + 1) if base is not None: step = ins[2].getOffset() if (op == PcodeOp.PTRADD and len(ins) > 2) else 1 return base + b.getOffset() * step if a.isConstant(): base = _trace_this_offset(b, this_vns, depth + 1) if base is not None: return base + a.getOffset() elif op == PcodeOp.PTRSUB: b = ins[1] if b.isConstant(): base = _trace_this_offset(ins[0], this_vns, depth + 1) if base is not None: return base + b.getOffset() elif op in (PcodeOp.COPY, PcodeOp.CAST, PcodeOp.INT_ZEXT, PcodeOp.INT_SEXT): return _trace_this_offset(ins[0], this_vns, depth + 1) return None def _is_vtable_value(program, vn): """True if the stored value is a constant pointer to a *vftable* symbol.""" if not vn.isConstant(): return False try: a = program.getAddressFactory().getDefaultAddressSpace().getAddress(vn.getOffset()) except: # noqa: E722 return False sym = program.getSymbolTable().getPrimarySymbol(a) return sym is not None and "vftable" in sym.getName().lower() def _base_ctor(program, ctor): """Direct base class = the first CMC_* constructor this ctor calls (conventionally first).""" listing = program.getListing() it = listing.getInstructions(resolve_thunk(ctor).getBody(), True) while it.hasNext(): instr = it.next() if instr.getMnemonicString() == "CALL": cf = call_target(program, instr) if cf is not None and _is_cmc_ctor(cf) and cf.getName() != ctor.getName(): return cf.getName() return None def _extract_fields_from(program, ifc, ctor): """Recover this-relative STORE offsets from one CMC_* constructor via decompiler P-code.""" res = ifc.decompileFunction(ctor, 60, monitor) if res is None or not res.decompileCompleted(): return [], None high = res.getHighFunction() if high is None: return [], None this_vns = _this_varnodes(high) if not this_vns: return [], None owner = ctor.getParentNamespace().getName() fields = {} ops = high.getPcodeOps() while ops.hasNext(): op = ops.next() if op.getOpcode() != PcodeOp.STORE: continue off = _trace_this_offset(op.getInput(1), this_vns) if off is None or off < 0: continue val = op.getInput(2) rec = {"owner": owner, "offset": off, "size": val.getSize(), "is_vtable": _is_vtable_value(program, val), "confidence": "high"} cur = fields.get(off) if cur is None or rec["size"] > cur["size"]: fields[off] = rec return list(fields.values()), _base_ctor(program, ctor) _PROP_TYPE = [("Bool", "bool"), ("Int", "int"), ("Double", "double"), ("Float", "double"), ("List", "list"), ("Point", "point"), ("Size", "size"), ("Rect", "rect")] def _prop_type(getter): """Map a CMElement::getPropertyValue getter name to the script field type.""" for needle, ty in _PROP_TYPE: if needle in getter: return ty return "string" # plain getPropertyValue def _property_getter(program, addr): """The CMElement::getPropertyValue called at `addr` (any folded alias), or None.""" for _, name in _labels(program, addr): if name.startswith("getProperty"): return name return None def _string_operand(program, instr): """A name literal an instruction pushes or loads into a register. A store into memory is never one: installing a vftable writes an address whose bytes may happen to be printable (BlooMoo read "X5"/"vN" instead of VALUE that way).""" if instr.getMnemonicString() == "MOV" and "[" in instr.getDefaultOperandRepresentation(0): return None s = _imm_string(program, instr) return s if s is not None and _is_method_name(s) else None def _fields_read(program, func): """[(property, value type)] a constructor body reads, in order: the literal pushed or loaded right before each CMElement::getPropertyValue call names the property.""" out = [] last = None ins = program.getListing().getInstructions(resolve_thunk(func).getBody(), True) while ins.hasNext(): instr = ins.next() s = _string_operand(program, instr) if s is not None: last = s if instr.getMnemonicString() == "CALL" and len(instr.getFlows()) == 1 and last is not None: getter = _property_getter(program, instr.getFlows()[0]) if getter is not None: out.append((last, _prop_type(getter))) last = None return out def extract_script_fields(program): """The script-visible named fields each named CMC_* constructor reads (FILENAME, FPS, PRELOAD, VISIBLE, ...), typed by the CMElement getter. Flat list deduped per (owner, name); `type_fields` covers unnamed classes and inheritance per script type.""" fm = program.getFunctionManager() by_key = {} # (owner, name) -> record next_order = {} # owner -> next order index it = fm.getFunctions(True) while it.hasNext(): f = it.next() if not _is_cmc_ctor(f): continue owner = f.getParentNamespace().getName() for name, ty in _fields_read(program, f): key = (owner, name) if key not in by_key: o = next_order.get(owner, 0) by_key[key] = {"owner": owner, "name": name, "type": ty, "order": o} next_order[owner] = o + 1 return sorted(by_key.values(), key=lambda r: (r["owner"], r["order"])) def _constructor_chain(program, ctor, limit=6): """`ctor` and the base constructors it delegates to, most-derived first.""" chain = [] func = ctor while func is not None and len(chain) < limit: chain.append(func) nxt = None it = program.getListing().getInstructions(resolve_thunk(func).getBody(), True) while it.hasNext(): instr = it.next() flows = instr.getFlows() if instr.getMnemonicString() == "CALL" else [] if len(flows) == 1 and _is_base_ctor_call(program, flows[0]): nxt = program.getFunctionManager().getFunctionAt(flows[0]) break func = nxt return chain def extract_type_fields(program, types): """Per script type, the properties its constructor chain reads, base first: reaches unnamed classes (VECTOR's VALUE/SIZE, FILTER's ACTION, PATH's NODES) and inherited ones (INTEGER gets CMC_Variable's TOINI/NETNOTIFY). A property read through several getters lists every value type.""" out = [] seen = set() for t in types: ctor = _function_at(program, t.get("ctor_addr")) if ctor is None or t["script_name"] in seen: continue seen.add(t["script_name"]) records = {} for func in reversed(_constructor_chain(program, ctor)): classes = sorted(ns for ns, name in _labels(program, func.getEntryPoint()) if ns == name) for name, ty in _fields_read(program, func): rec = records.get(name) if rec is None: rec = records[name] = {"type": t["script_name"], "name": name, "value_types": [], "order": len(records), "declared_in": classes[0] if classes else None} if ty not in rec["value_types"]: rec["value_types"].append(ty) out.extend(sorted(records.values(), key=lambda r: r["order"])) return out def extract_struct_layout(program): """Bonus/fuzzy axis: per CMC_* constructor, recover the this-relative C++ field stores (offset, size, is_vtable) and the base-class link. Offsets come from decompiler P-code, so they are normalised across compilers. Returns (layout, field_inheritance).""" fm = program.getFunctionManager() ifc = DecompInterface() ifc.openProgram(program) try: by_key = {} # (owner, offset) -> field record, deduped across overloaded ctors inheritance = {} # class -> base_class it = fm.getFunctions(True) while it.hasNext(): f = it.next() if not _is_cmc_ctor(f): continue own, base = _extract_fields_from(program, ifc, f) for rec in own: key = (rec["owner"], rec["offset"]) cur = by_key.get(key) if cur is None or rec["size"] > cur["size"]: by_key[key] = rec if base is not None and f.getName() not in inheritance: inheritance[f.getName()] = base fields = sorted(by_key.values(), key=lambda r: (r["owner"], r["offset"])) field_inheritance = [{"class": k, "base_class": v} for k, v in inheritance.items()] return fields, field_inheritance finally: ifc.dispose() # --------------------------------------------------------------------------- runner map # CMC_Runner virtuals the script ABI hangs on. Their vtable offsets moved between releases # (prepareMthHashSet is +0x20 in Piklib 7.1, +0x28 from 7.2 on), so they are read off the # labelled base vftable, never hard-coded. _RUNNER_SLOTS = ("prepareMthHashSet", "run", "getParameter", "getParameterBool", "getParameterDouble", "getParameterInteger", "getParameterString") _MAX_VTABLE_SLOTS = 64 # How the demangler spells `??_7@@6B@` differs between Ghidra versions/compilers. _VFTABLE_LABELS = ("vftable", "_vftable_", "`vftable'") # Scratch addresses for emulating CMC_RunnerFactory::getRunner; outside every image. _EMU_STACK = 0x7ff00000 _EMU_RETURN = 0x7fe00000 def _addr(program, value): return program.getAddressFactory().getDefaultAddressSpace().getAddress(value) def _hex(addr): return "0x%x" % addr.getOffset() if addr is not None else None def _function_at(program, hex_addr): if not hex_addr: return None return program.getFunctionManager().getFunctionAt(_addr(program, int(hex_addr, 16))) def _read_ptr(program, addr): try: return _addr(program, program.getMemory().getInt(addr) & 0xffffffff) except: # noqa: E722 - MemoryAccessException / AddressOutOfBounds return None def _labels(program, addr): """(namespace, name) of every label at `addr` and at the body an ILT stub there jumps to. Identical-COMDAT folding gives one body many names (Piklib 8's getType is labelled CMC_DLLExModuleInterface::getModuleInterface too), so the primary symbol is an arbitrary alias: test membership, never trust the primary name alone.""" addrs = [addr] f = program.getFunctionManager().getFunctionAt(addr) body = resolve_thunk(f) if f is not None else None if body is not None and body.getEntryPoint() != addr: addrs.append(body.getEntryPoint()) elif f is None: # an ILT `JMP body` stub the analyzer never made a function instr = program.getListing().getInstructionAt(addr) if instr is not None and instr.getMnemonicString() == "JMP" and len(instr.getFlows()) == 1: addrs.append(instr.getFlows()[0]) out = set() for a in addrs: for s in program.getSymbolTable().getSymbols(a): ns = s.getParentNamespace() out.add((ns.getName() if ns is not None else "", s.getName())) pair = _mangled_pair(s.getName()) if pair is not None: out.add(pair) return out # Folded aliases often stay as raw MSVC labels; class and member are enough to match them. _MANGLED_CTOR = re.compile(r"^\?\?0(\w+)@") _MANGLED_VFTABLE = re.compile(r"^\?\?_7(\w+)@") _MANGLED_MEMBER = re.compile(r"^\?(\w+)@(\w+)@") def _mangled_pair(label): """(class, member) of an undemangled MSVC label, e.g. ?getType@CMC_Object@@QAEHXZ.""" m = _MANGLED_CTOR.match(label) if m: return (m.group(1), m.group(1)) m = _MANGLED_VFTABLE.match(label) if m: return (m.group(1), "vftable") m = _MANGLED_MEMBER.match(label) if m: return (m.group(2), m.group(1)) return None def _vftable_class(program, addr): """The class whose labelled vftable (`??_7@@6B@`) sits at `addr`, or None.""" for ns, name in _labels(program, addr): if name in _VFTABLE_LABELS: return ns return None def _labelled_vftable(program, class_name): st = program.getSymbolTable() for label in _VFTABLE_LABELS: it = st.getSymbols(label) while it.hasNext(): s = it.next() ns = s.getParentNamespace() if ns is not None and ns.getName() == class_name: return s.getAddress() return None def _ensure_function(program, addr): """The function at `addr`, created when auto-analysis missed it: bodies referenced only from a vtable are often left undefined (Piklib 7.2's unnamed runners).""" if addr is None: return None fm = program.getFunctionManager() f = fm.getFunctionAt(addr) if f is None and _executable(program, addr): from ghidra.app.cmd.disassemble import DisassembleCommand from ghidra.app.cmd.function import CreateFunctionCmd tx = program.startTransaction("ams: define vtable target") try: DisassembleCommand(addr, None, True).applyTo(program) CreateFunctionCmd(addr).applyTo(program) finally: program.endTransaction(tx, True) f = fm.getFunctionAt(addr) return f def _runner_slots(program): """{CMC_Runner virtual: vtable offset}. `run(int, ...)` precedes `run(CXString, ...)` in every observed build, so the first labelled slot of a name wins.""" vft = _labelled_vftable(program, "CMC_Runner") slots = {} if vft is None: return slots for i in range(_MAX_VTABLE_SLOTS): target = _read_ptr(program, vft.add(i * 4)) if target is None or not _executable(program, target): break for ns, name in _labels(program, target): if ns == "CMC_Runner" and name in _RUNNER_SLOTS and name not in slots: slots[name] = i * 4 return slots def _vftable_store(program, instr): """The vftable installed by `MOV dword ptr [reg], imm`, or None: a constructor (called or inlined) sets the object's first dword to a non-code table that starts with code.""" if instr.getMnemonicString() != "MOV" or instr.getNumOperands() != 2: return None if not re.match(r"dword ptr \[E[A-Z]{2}\]$", instr.getDefaultOperandRepresentation(0)): return None sc = instr.getScalar(1) if sc is None: return None try: table = _addr(program, sc.getUnsignedValue()) except: # noqa: E722 return None return table if _is_vftable_address(program, table) else None def _last_vftable_store(program, func, depth=0): """The most-derived vftable a constructor installs: base constructors run first, so the last store wins. Descends into callees when the body only delegates.""" found = None callees = [] it = program.getListing().getInstructions(resolve_thunk(func).getBody(), True) while it.hasNext(): instr = it.next() table = _vftable_store(program, instr) if table is not None: found = table elif instr.getMnemonicString() == "CALL": cf = call_target(program, instr) if cf is not None: callees.append(cf) if found is None and depth < 2: for cf in callees: found = _last_vftable_store(program, cf, depth + 1) or found return found def _object_vftable(program, dec, ctor): """The most-derived vftable a constructor installs into `this`: the last P-code STORE of a vftable-shaped constant at this+0. P-code follows `this` through stack spills that a register walk loses (MSVC6 reloads it around inline strlen).""" high = dec.high(resolve_thunk(ctor)) if high is None: return None this_vns = set(vn for vn, role in _storage_roles(program, high, {"ECX": "this"}).items()) found = None ops = high.getPcodeOps() while ops.hasNext(): op = ops.next() if op.getOpcode() != PcodeOp.STORE or _trace_this_offset(op.getInput(1), this_vns) != 0: continue table = _constant_address(program, op.getInput(2)) if table is not None and _is_vftable_address(program, table): found = table return found def _constant_address(program, vn): """The address a P-code value denotes when it is constant: a plain constant, or the decompiler's `PTRSUB(0, addr)` spelling of `&global`.""" vn = _strip(vn) if vn is None: return None if vn.isConstant(): return _addr(program, vn.getOffset()) d = vn.getDef() if d is not None and d.getOpcode() == PcodeOp.PTRSUB and d.getInput(0).isConstant() \ and d.getInput(0).getOffset() == 0 and d.getInput(1).isConstant(): return _addr(program, d.getInput(1).getOffset()) return None def _is_vftable_address(program, table): blk = program.getMemory().getBlock(table) if blk is None or blk.isExecute(): return False first = _read_ptr(program, table) return first is not None and _executable(program, first) def _runner_globals(program, init): """[(global, vftable)] from CMC_RunnerFactory::initialize, which builds every runner as `pRunner = new _Runner`. The vftable installed since the previous global write (inline constructor) or by the last constructor called belongs to the next write; the NULL branch of `new` writes too and is skipped until the constructed store follows.""" out = [] done = set() pending = None calls = [] st = program.getSymbolTable() it = program.getListing().getInstructions(init.getBody(), True) while it.hasNext(): instr = it.next() table = _vftable_store(program, instr) if table is not None: pending = table if instr.getMnemonicString() == "CALL": cf = call_target(program, instr) if cf is not None and cf.getName() != OP_NEW: calls.append(cf) for ref in instr.getReferencesFrom(): if not ref.getReferenceType().isWrite(): continue sym = st.getPrimarySymbol(ref.getToAddress()) name = sym.getName() if sym is not None else "" if not (name.startswith("p") and name.endswith("Runner")) or name in done: continue table = pending for cf in reversed(calls): if table is not None: break table = _last_vftable_store(program, cf) if table is None: continue out.append((name, ref.getToAddress(), table)) done.add(name) pending = None calls = [] return out def _is_cmc_ctor_at(program, addr): for ns, name in _labels(program, addr): if name == ns and name.startswith(CMC_PREFIX): return True return False def _is_base_ctor_call(program, addr): """A CMC_* constructor, or an unlabelled one that chains to it (BlooMoo's FIFO/LIFO share an unexported queue base that calls CMC_Object).""" if _is_cmc_ctor_at(program, addr): return True f = program.getFunctionManager().getFunctionAt(addr) if f is None: return False it = program.getListing().getInstructions(resolve_thunk(f).getBody(), True) while it.hasNext(): instr = it.next() if instr.getMnemonicString() == "CALL": flows = instr.getFlows() return len(flows) == 1 and _is_cmc_ctor_at(program, flows[0]) return False def _ctor_type_id(program, ctor_addr): """The type id a script-type constructor hands to its base. Every CMC_* base constructor takes it as the *last* argument (`CMC_Object(container, element, int)`), which is pushed first - so it is the first plain immediate pushed before the base-constructor call. The SEH frame's `PUSH -1` and pushed addresses are not plain small immediates.""" func = _function_at(program, ctor_addr) if func is None: return None first = None it = program.getListing().getInstructions(resolve_thunk(func).getBody(), True) while it.hasNext(): instr = it.next() mn = instr.getMnemonicString() if mn == "PUSH" and first is None and not instr.getReferencesFrom(): sc = instr.getScalar(0) if sc is not None and 0 <= _s32(sc.getValue()) < 0x10000: first = _s32(sc.getValue()) elif mn == "CALL": flows = instr.getFlows() if len(flows) == 1 and _is_base_ctor_call(program, flows[0]): return first return None def _compared_ids(program, func): """Every small immediate `func` compares against - the case labels of its switch.""" ids = set() it = program.getListing().getInstructions(func.getBody(), True) while it.hasNext(): instr = it.next() if instr.getMnemonicString() in ("CMP", "SUB", "ADD", "LEA") and instr.getNumOperands() == 2: sc = instr.getScalar(1) if sc is not None: v = abs(_s32(sc.getValue())) if v < 0x10000: ids.add(v) return ids def _emulate_get_runner(program, get_runner, runner_globals, extra_ids): """{type id: runner global} by executing CMC_RunnerFactory::getRunner(int) for every id up to the largest one it compares against. Its compiled switch (jump tables, binary search) differs per compiler; running it doesn't care. Each global is seeded with its own address, so the returned pointer names the slot the id selects.""" from ghidra.app.emulator import EmulatorHelper entry = get_runner.getEntryPoint() by_marker = {} emu = EmulatorHelper(program) out = {} try: for name, addr, _ in runner_globals: emu.writeMemoryValue(addr, 4, addr.getOffset()) by_marker[addr.getOffset()] = name emu.setBreakpoint(_addr(program, _EMU_RETURN)) top = max(_compared_ids(program, resolve_thunk(get_runner)) | set(extra_ids) | set([0])) for tid in range(top + 2): emu.writeRegister("ESP", _EMU_STACK) emu.writeMemoryValue(_addr(program, _EMU_STACK), 4, _EMU_RETURN) emu.writeMemoryValue(_addr(program, _EMU_STACK + 4), 4, tid) emu.writeRegister("EAX", 0) emu.writeRegister(emu.getPCRegister(), entry.getOffset()) if not emu.run(monitor): continue name = by_marker.get(int(emu.readRegister("EAX").longValue()) & 0xffffffff) if name is not None: out[tid] = name finally: emu.dispose() return out def _runner_from_global(name): """Runner class for a factory slot whose class has no symbol: BlooMoo's RTTI names the same runners that Piklib exports only as slots (pVectorRunner -> CMC_Vector_Runner).""" 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)], "slots": dict((k, "0x%x" % v) for k, v in _runner_slots(program).items())} def extract_runner_map(program, types): """Which runner executes each script type, from CMC_RunnerFactory (Piklib 7.1+, BlooMoo). The engine dispatches `obj^METHOD` as getRunner(obj.getType())->run(id, ...), so the authoritative link is type id -> runner, not a class name: INTEGER/STRING/BOOL/DOUBLE/ EXPRESSION share one runner, and VECTOR/FILTER/PATH/FIFO/LIFO/MOVIE plus the `@` built-ins (type 0) run on runners that have no symbol at all. Annotates `types` with `type_id`. None when the engine predates the factory (Piklib 6.1).""" init = find_function_by_qualified(program, "CMC_RunnerFactory", "initialize") get_runner = find_function_by_qualified(program, "CMC_RunnerFactory", "getRunner") slots = _runner_slots(program) if init is None or get_runner is None or "prepareMthHashSet" not in slots or "run" not in slots: return None for t in types: t["type_id"] = _ctor_type_id(program, t.get("ctor_addr")) runners = [] key_of = {} globals_ = _runner_globals(program, resolve_thunk(init)) for name, _, table in globals_: cls = _vftable_class(program, table) key = cls if cls and cls != "CMC_Runner" else _runner_from_global(name) key_of[name] = key prepare = _ensure_function(program, _read_ptr(program, table.add(slots["prepareMthHashSet"]))) run_ = _ensure_function(program, _read_ptr(program, table.add(slots["run"]))) runners.append({"runner": key, "global": name, "class": cls, "vftable": _hex(table), "prepare_addr": _hex(prepare.getEntryPoint()) if prepare else None, "run_addr": _hex(run_.getEntryPoint()) if run_ else None}) ids = [t["type_id"] for t in types if t.get("type_id") is not None] by_id = _emulate_get_runner(program, get_runner, globals_, ids) return { "slots": dict((k, "0x%x" % v) for k, v in slots.items()), "runners": runners, "by_type_id": [{"type_id": tid, "runner": key_of[g], "global": g} for tid, g in sorted(by_id.items())], } # --------------------------------------------------------------------------- method facts # Runner getter reading script argument N -> the type the method converts it to. _PARAM_GETTERS = {"getParameter": "any", "getParameterBool": "bool", "getParameterDouble": "double", "getParameterInteger": "int", "getParameterString": "string"} # 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. _RUN_ROLES = {"ECX": "runner", 8: "object", 16: "params"} # A case forwards to a runner member (MSVC8 keeps every method out of line), which may forward again. _HELPER_DEPTH = 2 _DECOMPILE_TIMEOUT = 60 class _Decompiler(object): """HighFunction cache: runner helpers are shared by several cases.""" def __init__(self, program): self.ifc = DecompInterface() self.ifc.openProgram(program) self.cache = {} def high(self, func): key = func.getEntryPoint().getOffset() if key not in self.cache: res = self.ifc.decompileFunction(func, _DECOMPILE_TIMEOUT, monitor) ok = res is not None and res.decompileCompleted() self.cache[key] = res.getHighFunction() if ok else None return self.cache[key] def dispose(self): self.ifc.dispose() class _Facts(object): """What one method body does with its arguments, its object and its result.""" 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() self.type_checks = set() # type ids the body branches on via obj.getType() def as_dict(self): indexes = sorted(i for i in self.params if i is not None) return { "params": [{"index": i, "types": sorted(self.params[i])} for i in indexes], "variadic": None in self.params, "returns": sorted(self.returns), "object_slots": ["0x%x" % off for off in sorted(self.object_slots)], "type_checks": sorted(self.type_checks), } def _strip(vn): """The value behind copies, casts and call side-effect placeholders.""" while vn is not None: d = vn.getDef() if d is None or d.getOpcode() not in (PcodeOp.COPY, PcodeOp.CAST, PcodeOp.INDIRECT): return vn vn = d.getInput(0) return vn def _storage_key(storage): if storage.isRegisterStorage(): return storage.getRegister().getName() if storage.isStackStorage(): return storage.getStackOffset() return None def _storage_roles(program, high, by_storage): """{varnode: role} for the parameters stored where `by_storage` says, plus `this` when the body reads it as an untyped incoming ECX.""" out = {} syms = high.getLocalSymbolMap().getSymbols() while syms.hasNext(): s = syms.next() role = by_storage.get(_storage_key(s.getStorage())) if s.isParameter() else None if role and s.getHighVariable() is not None: for vn in s.getHighVariable().getInstances(): out[vn] = role if by_storage.get("ECX"): ops = high.getPcodeOps() while ops.hasNext(): op = ops.next() for i in range(op.getNumInputs()): vn = op.getInput(i) if vn.isInput() and vn.isRegister(): reg = program.getRegister(vn.getAddress(), vn.getSize()) if reg is not None and reg.getName() == "ECX": out[vn] = by_storage["ECX"] return out def _call_storage(program, op, roles): """storage -> role of a call's arguments: the caller's values (ECX first for __thiscall, then stack slots in order) and, where the call site lost them, the callee's demangled parameter types.""" target = program.getFunctionManager().getFunctionAt(op.getInput(0).getAddress()) out = {} if target is None: return out for p in target.getParameters(): role = _role_of_type(p.getDataType().getName()) key = _storage_key(p.getVariableStorage()) if role and key is not None: out[key] = role slot = 4 for i in range(1, op.getNumInputs()): if i == 1 and target.getCallingConventionName() == "__thiscall": key = "ECX" else: key, slot = slot, slot + 4 role = _role(op.getInput(i), roles) if role is not None: out[key] = role return out def _role_of_type(name): if "CXVector" in name: return "params" if "_Runner" in name: return "runner" if name.startswith(CMC_PREFIX): return "object" return None def _is_runner_member(program, addr): for ns, _ in _labels(program, addr): if ns.endswith("_Runner"): return True return False def _role(vn, roles): vn = _strip(vn) return roles.get(vn) if vn is not None else None def _vcall(op, roles): """(role, offset) of a virtual call `CALLIND [[x] + offset]` on the object `x` holds.""" target = _strip(op.getInput(0)) load = target.getDef() if target is not None else None if load is None or load.getOpcode() != PcodeOp.LOAD: return None ptr = _strip(load.getInput(1)) off = 0 arith = ptr.getDef() if ptr is not None else None if arith is not None and arith.getOpcode() in (PcodeOp.INT_ADD, PcodeOp.PTRSUB) and arith.getInput(1).isConstant(): off = int(arith.getInput(1).getOffset()) ptr = _strip(arith.getInput(0)) vtable = ptr.getDef() if ptr is not None else None if vtable is None or vtable.getOpcode() != PcodeOp.LOAD: return None role = _role(vtable.getInput(1), 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: return name return None def _reachable(starts, allowed): seen = set() order = [] stack = list(starts) while stack: b = stack.pop() if b in seen or not allowed(b): continue seen.add(b) order.append(b) for k in range(b.getOutSize()): stack.append(b.getOut(k)) return order def _case_regions(high, entries): """{case address: blocks reachable from it without entering another case}. Shared epilogues belong to every case that reaches them.""" blocks = high.getBasicBlocks() by_start = {} for i in range(blocks.size()): b = blocks.get(i) by_start[b.getStart().getOffset()] = b heads = dict((a, by_start[a]) for a in entries if a in by_start) head_set = set(heads.values()) out = {} for a, head in heads.items(): out[a] = _reachable([head], lambda b, head=head: b not in head_set or b is head) return out def _passes(op, roles, wanted): """Whether a call hands one of the `wanted` roles to its callee.""" for i in range(1, op.getNumInputs()): if _role(op.getInput(i), roles) in wanted: return True return False def _getter_index(program, op, roles): """Argument index of `runner->getParameter*(params, index)`; None when computed (a loop). The decompiler may or may not pass `this`, or any argument when it misses the callee's signature - then read the pushes: `index` is pushed right before `params`.""" for i in range(1, op.getNumInputs() - 1): if _role(op.getInput(i), roles) == "params": index = _strip(op.getInput(i + 1)) return int(index.getOffset()) if index is not None and index.isConstant() else None return _pushed_constant(program, op.getSeqnum().getTarget(), 1) def _pushed_constant(program, call_addr, arg): """The constant pushed as argument `arg` (0-based) of the CALL at `call_addr`, following `PUSH reg` back to `XOR reg,reg` / `MOV reg,imm` in the same straight line; else None.""" instr = program.getListing().getInstructionAt(call_addr) pushes = [] known = {} trail = [] for _ in range(24): instr = instr.getPrevious() if instr is not None else None if instr is None or instr.getFlowType().isCall() or instr.getFlowType().isJump(): break trail.append(instr) for instr in reversed(trail): # forward: register constants, then the pushes in order mn = instr.getMnemonicString() if mn == "XOR" and instr.getNumOperands() == 2 and \ instr.getDefaultOperandRepresentation(0) == instr.getDefaultOperandRepresentation(1): known[instr.getDefaultOperandRepresentation(0)] = 0 elif mn == "MOV" and instr.getNumOperands() == 2 and instr.getScalar(1) is not None \ and not instr.getReferencesFrom(): known[instr.getDefaultOperandRepresentation(0)] = int(instr.getScalar(1).getValue()) elif mn == "PUSH": sc = instr.getScalar(0) if sc is not None and not instr.getReferencesFrom(): pushes.append(int(sc.getValue())) else: pushes.append(known.get(instr.getDefaultOperandRepresentation(0))) elif instr.getNumOperands() > 0: known.pop(instr.getDefaultOperandRepresentation(0), None) pushes.reverse() # arguments are pushed right to left return pushes[arg] if arg < len(pushes) else None def _type_test(block, type_results): """(opcode, K) when `block` ends branching on obj.getType() ==/!= K, else None.""" ops = list(block.getIterator()) if not ops or ops[-1].getOpcode() != PcodeOp.CBRANCH or block.getOutSize() != 2: return None cond = _strip(ops[-1].getInput(1)) test = cond.getDef() if cond is not None else None if test is None or test.getOpcode() not in (PcodeOp.INT_EQUAL, PcodeOp.INT_NOTEQUAL): return None if not test.getInput(1).isConstant() or _strip(test.getInput(0)) not in type_results: return None return (test.getOpcode(), int(test.getInput(1).getOffset())) def _path_for_type(head, inside, tests, type_id): """Blocks reachable from `head` when obj.getType() == type_id: type branches follow only the side that type takes, every other branch both sides.""" seen = set() stack = [head] while stack: b = stack.pop() if b in seen or b not in inside: continue seen.add(b) test = tests.get(b) if test is None: for k in range(b.getOutSize()): stack.append(b.getOut(k)) continue opcode, k = test holds = (type_id == k) if opcode == PcodeOp.INT_EQUAL else (type_id != k) stack.append(b.getTrueOut() if holds else b.getFalseOut()) return seen def _collect(program, dec, blocks, roles, getters, facts, depth, type_ids): """Accumulate `facts` over `blocks` (head first) and return {type id: does work}: whether the path that type takes reaches a virtual call, a runner helper doing work for it, or a result allocation - an excluded type only reaches the error/skip exit.""" type_results = set() work = {} # block -> [True | {type id: bool} from a helper] for b in blocks: it = b.getIterator() while it.hasNext(): op = it.next() code = op.getOpcode() if code == PcodeOp.CALLIND: vc = _vcall(op, roles) if vc is None: continue role, off = vc if role == "runner" and off in getters: facts.params.setdefault(_getter_index(program, op, roles), set()).add(getters[off]) elif role == "object": facts.object_slots.add(off) work.setdefault(b, []).append(True) elif code == PcodeOp.CALL: target = op.getInput(0).getAddress() 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 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: type_results.add(op.getOutput()) elif helper and body is not None and depth < _HELPER_DEPTH: work.setdefault(b, []).append(_collect_function( program, dec, resolve_thunk(body), _call_storage(program, op, roles), getters, facts, depth + 1, type_ids)) elif this_role == "object" or _passes(op, roles, ("object", "params")): work.setdefault(b, []).append(True) tests = {} for b in blocks: test = _type_test(b, type_results) if test is not None: tests[b] = test facts.type_checks.add(test[1]) inside = set(blocks) applies = {} for type_id in type_ids: path = _path_for_type(blocks[0], inside, tests, type_id) if blocks else set() applies[type_id] = any(w is True or w.get(type_id) for b in path for w in work.get(b, [])) return applies def _collect_function(program, dec, func, by_storage, getters, facts, depth, type_ids): high = dec.high(func) if high is None: return dict((t, True) for t in type_ids) # unknown body: assume it does its job blocks = high.getBasicBlocks() return _collect(program, dec, [blocks.get(i) for i in range(blocks.size())], _storage_roles(program, high, by_storage), getters, facts, depth, type_ids) def annotate_method_facts(program, method_dispatch, run_addrs, runner_map, types): """Per dispatch row: argument types read through CMC_Runner::getParameter*, the result allocator, virtual calls on the object and branches on obj.getType() - the script signature and per-type validity. Read from P-code because MSVC6 inlines bodies into run() while MSVC8 moves them out of line. `run_addrs` maps runner -> run function.""" slots = dict((k, int(v, 16)) for k, v in ((runner_map or {}).get("slots") or {}).items()) 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.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: shared.setdefault(runner_of[t["type_id"]], {})[t["type_id"]] = t["script_name"] 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 and rows else None if high is None: continue 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(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()) if group: # Only an explicit obj.getType() branch can exclude a type. row["per_type"] = dict((group[t], "applies" if ok or not facts.type_checks else "excluded_by_type_check") for t, ok in applies.items()) finally: dec.dispose() def _trivial(program, addr): """A virtual a type leaves as `_purecall`, a bare RET or `return 0`: a no-op for it.""" if addr is None: return True for _, name in _labels(program, addr): if "purecall" in name: return True f = program.getFunctionManager().getFunctionAt(addr) instr = program.getListing().getInstructionAt(resolve_thunk(f).getEntryPoint() if f else addr) for _ in range(3): if instr is None: return False mn = instr.getMnemonicString() if mn == "RET": return True text = instr.toString() if not (mn == "XOR" and text in ("XOR EAX,EAX", "XOR AL,AL")) and \ not (mn == "MOV" and re.match(r"MOV (EAX|AL),0x0$", text)): return False instr = instr.getNext() return False def annotate_type_vftables(program, types, method_dispatch): """Record each type's vftable and demote a shared-runner method to "trivial_virtual" for a type whose vftable leaves every virtual the method calls as a no-op.""" tables = {} dec = _Decompiler(program) try: for t in types: ctor = _function_at(program, t.get("ctor_addr")) table = _object_vftable(program, dec, ctor) if ctor is not None else None t["vftable"] = _hex(table) tables[t["script_name"]] = table finally: dec.dispose() for row in method_dispatch: for name, verdict in (row.get("per_type") or {}).items(): table = tables.get(name) if verdict != "applies" or not row["object_slots"] or table is None: continue targets = [_read_ptr(program, table.add(int(off, 16))) for off in row["object_slots"]] if all(_trivial(program, a) for a in targets): row["per_type"][name] = "trivial_virtual" # --------------------------------------------------------------------------- type events def _virtual_slot(program, member): """vtable offset of virtual `member`, voted by classes that override it in their own namespace. A base body folded with unrelated trivial ones (ICF) carries many labels and shows up in other slots too, so only same-class overrides vote.""" votes = {} it = program.getSymbolTable().getAllSymbols(True) while it.hasNext(): s = it.next() ns = s.getParentNamespace() if "vftable" not in s.getName() or ns is None or not ns.getName().startswith(CMC_PREFIX): continue for i in range(_MAX_VTABLE_SLOTS): target = _read_ptr(program, s.getAddress().add(i * 4)) if target is None or not _executable(program, target): break if (ns.getName(), member) in _labels(program, target): votes[i * 4] = votes.get(i * 4, 0) + 1 return max(votes, key=lambda k: votes[k]) if votes else None def extract_type_events(program, types): """Per script type, the events its own vftable's getBehavioursList returns. Reaches the unnamed classes (FILTER, FIFO/LIFO, MOVIE, ...) and resolves inheritance (INTEGER uses CMC_Variable's list) without guessing. Needs `types[].vftable`; the lists are self-contained (each repeats ONINIT/ONDONE/ONSIGNAL).""" slot = _virtual_slot(program, "getBehavioursList") if slot is None: return [] out = [] seen = set() for t in types: if not t.get("vftable") or t["script_name"] in seen: continue seen.add(t["script_name"]) target = _read_ptr(program, _addr(program, int(t["vftable"], 16)).add(slot)) func = _ensure_function(program, target) if func is None: continue owners = sorted(set(ns for ns, name in _labels(program, target) if name == "getBehavioursList")) for order, name in enumerate(_event_literals(program, func)): out.append({"type": t["script_name"], "name": name, "order": order, "list_addr": _hex(resolve_thunk(func).getEntryPoint()), "list_owner": owners[0] if len(owners) == 1 else None}) return out # --------------------------------------------------------------------------- metadata def detect_engine(factory): """(engine, compiler) from the factory's enclosing namespace. Compiler is heuristic.""" ns = factory.getParentNamespace() parent = ns.getParentNamespace() if ns is not None else None if parent is not None and parent.getName() == "BlooMooDLL": return ("BlooMoo", "MSVC8") return ("Piklib", "MSVC6") def default_out_path(program): """Write into /snapshots/ (derived from this script's own location), falling back to the OS temp dir if the layout is unexpected or unwritable.""" name = program.getName() + ".snapshot.json" try: scripts_dir = os.path.dirname(getSourceFile().getAbsolutePath()) # .../ghidra_scripts out_dir = os.path.join(os.path.dirname(scripts_dir), "snapshots") if not os.path.isdir(out_dir): os.makedirs(out_dir) return os.path.join(out_dir, name) except Exception: return os.path.join(tempfile.gettempdir(), name) def sha256_of(program): try: path = program.getExecutablePath() fh = open(path, "rb") try: return hashlib.sha256(fh.read()).hexdigest() finally: fh.close() except Exception: return None # --------------------------------------------------------------------------- scene modules # A scene module (`SCENE:DLLS=`: World.dll, Matrix.dll, ...) adds script types through # CMC_ExternObject::resolve, which compares TYPE with CXString::equals or operator==. _MODULE_COMPARES = (OP_EQ, "equals", "equalsIgnoreCase") # Engine SDK classes a module links in statically; their runners are not the module's. _SDK_PREFIXES = ("CMC_", "CX") def _is_sdk(func): ns = func.getParentNamespace() return ns is not None and ns.getName().startswith(_SDK_PREFIXES) def _calls(program, func): """Names of the functions `func` calls directly.""" names = set() it = program.getListing().getInstructions(func.getBody(), True) while it.hasNext(): instr = it.next() if instr.getMnemonicString() == "CALL": cf = call_target(program, instr) if cf is not None: names.add(cf.getName()) return names def host_library(program): """The engine DLL a scene module imports (PIKLIB8.DLL, BlooMooDLL.dll, ...), or None.""" for lib in program.getExternalManager().getExternalLibraryNames(): if lib.upper().startswith(("PIKLIB", "BLOOMOO")): return lib return None def extract_module_types(program, factory): """The types one CMC_ExternObject::resolve builds: per branch the TYPE literal, a compare, operator new(SIZE) and the constructor as the next call - the engine's ladder, except that the literal is copied into a CXString inline, more than LOOKBACK instructions before the compare, so the latest literal other than the "TYPE" key names the branch.""" types = [] last = pending = size = None armed = False recent = [] it = program.getListing().getInstructions(factory.getBody(), True) while it.hasNext(): instr = it.next() s = _imm_string(program, instr) if s is not None and s != "TYPE" and _is_method_name(s): last = s if instr.getMnemonicString() == "CALL": f = call_target(program, instr) name = f.getName() if f is not None else None if name in _MODULE_COMPARES: pending = last elif name == OP_NEW: size = lookback_scalar(recent) armed = pending is not None elif armed and f is not None: ctor = resolve_thunk(f) types.append({"script_name": pending, "cpp_class": f.getName() if f.getName().startswith(CMC_PREFIX) else None, "ctor_addr": _hex(ctor.getEntryPoint()), "object_size": size, "dispatch_addr": _hex(instr.getAddress()), "via_module_iface": True}) pending = size = None armed = False recent.append(instr) if len(recent) > LOOKBACK: recent.pop(0) return types def find_module_factories(program): """[(resolve, types)] of a scene module: functions outside the linked-in SDK that compare, allocate and construct a CMC_Object-based type (its constructor hands a type id to the base).""" out = [] it = program.getFunctionManager().getFunctions(True) while it.hasNext(): f = it.next() if f.isThunk() or _is_sdk(f): continue names = _calls(program, f) if OP_NEW not in names or not names.intersection(_MODULE_COMPARES): continue types = [t for t in extract_module_types(program, f) if _ctor_type_id(program, t["ctor_addr"]) is not None] if types: out.append((f, types)) return out def _vtable_functions(program, table): funcs = [] for i in range(_MAX_VTABLE_SLOTS if table is not None else 0): target = _read_ptr(program, table.add(i * 4)) if target is None or not _executable(program, target): break f = _ensure_function(program, target) if f is not None: funcs.append(f) return funcs def _installed_tables(program, funcs, depth=3): """Offsets of every vftable `funcs` and their callees (`depth` levels) install.""" tables = set() seen = set() frontier = list(funcs) for _ in range(depth + 1): nxt = [] for f in frontier: body = resolve_thunk(f) if body.isExternal() or body.getEntryPoint().getOffset() in seen: continue seen.add(body.getEntryPoint().getOffset()) it = program.getListing().getInstructions(body.getBody(), True) while it.hasNext(): instr = it.next() table = _vftable_store(program, instr) if table is not None: tables.add(table.getOffset()) elif instr.getMnemonicString() == "CALL": cf = call_target(program, instr) if cf is not None: nxt.append(cf) frontier = nxt return tables def _module_runner(program, slots, tables): """(vftable, prepare) of the runner among the vftables a type installs: the table whose prepare slot chains to the engine's CMC_Runner::prepareMthHashSet, preferring a module function over a linked-in SDK runner. Analysis often leaves that prepare undefined (referenced from the vtable only), so it is defined here.""" found = [] for off in sorted(tables): table = _addr(program, off) prepare = _ensure_function(program, _read_ptr(program, table.add(slots["prepareMthHashSet"]))) if prepare is not None and not prepare.isThunk() and "prepareMthHashSet" in _calls(program, prepare): found.append((table, prepare)) if len(found) > 1: # a linked-in SDK runner as well; Inertia names its own CMC_Inertia_Runner found = [f for f in found if not _is_sdk(f[1])] or found return found[0] if len(found) == 1 else None def extract_module_runner_map(program, types): """Runner of each module type, in `extract_runner_map`'s shape (marked `module`). The engine asks the object for its runner, so a type's runner is the runner vftable its constructor or one of its virtuals installs (Matrix and Board create it lazily). Annotates `types` with `type_id`. Runner classes have no symbol; they are named after the type (CMC_Matrix_Runner).""" slots = _runner_slots(program) if "prepareMthHashSet" not in slots or "run" not in slots: return None runners = {} by_type_id = [] dec = _Decompiler(program) try: for t in types: t["type_id"] = _ctor_type_id(program, t["ctor_addr"]) ctor = _function_at(program, t["ctor_addr"]) reach = [ctor] + _vtable_functions(program, _object_vftable(program, dec, ctor)) found = _module_runner(program, slots, _installed_tables(program, reach)) if found is None: continue table, prepare = found if table.getOffset() not in runners: cls = _vftable_class(program, table) run_ = _ensure_function(program, _read_ptr(program, table.add(slots["run"]))) runners[table.getOffset()] = { "runner": cls or "CMC_%s_Runner" % t["script_name"].capitalize(), "global": None, "class": cls, "vftable": _hex(table), "prepare_addr": _hex(prepare.getEntryPoint()), "run_addr": _hex(run_.getEntryPoint()) if run_ else None} by_type_id.append({"type_id": t["type_id"], "runner": runners[table.getOffset()]["runner"], "global": None}) finally: dec.dispose() return {"module": True, "slots": dict((k, "0x%x" % v) for k, v in slots.items()), "runners": sorted(runners.values(), key=lambda r: r["runner"]), "by_type_id": by_type_id} def module_surface(program, factories): """Snapshot sections of a scene module. Only the module's own runners and types count: the engine classes it links in statically are the engine's surface, extracted from the engine.""" types = [t for _, found in factories for t in found] runner_map = extract_module_runner_map(program, types) methods, inheritance, dispatch, run_addrs = [], [], [], {} for r in (runner_map or {}).get("runners", []): own, runner, base = _extract_methods_from(program, _function_at(program, r["prepare_addr"]), r["runner"]) methods.extend(own) if base is not None: inheritance.append({"runner": runner, "base_runner": base}) run_func = _function_at(program, r["run_addr"]) if run_func is not None: run_addrs[r["runner"]] = r["run_addr"] dispatch.extend(_dispatch_from_run(program, run_func, _owner_from_runner(r["runner"]), r["runner"])) if runner_map: annotate_method_facts(program, dispatch, run_addrs, runner_map, types) annotate_type_vftables(program, types, dispatch) return {"types": types, "methods": methods, "method_inheritance": inheritance, "events": [], "fields": [], "field_inheritance": [], "struct_layout": [], "method_dispatch": dispatch, "runner_map": runner_map, "type_events": extract_type_events(program, types), "type_fields": extract_type_fields(program, types)} # --------------------------------------------------------------------------- main def find_factory(program): """The type-dispatch factory (the operator==("NAME") -> new -> ctor ladder). Its home class moved across versions: the script factory lived on CMC_Scene in early text-script Piklib (6.1 / 7.1), then was hoisted into CMC_ObjectsContainer from Piklib 8.x onward (and BlooMoo).""" for class_name, method_name in ( ("CMC_ObjectsContainer", "resolve"), # Piklib 8.x / BlooMoo ("CMC_Scene", "resolve"), # Piklib 6.1 / 7.1 ): f = find_function_by_qualified(program, class_name, method_name) if f is not None: return f return None def engine_surface(program, factory): """Snapshot sections of an engine DLL, from its type-dispatch factory.""" types = extract_types(program, factory) 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, methods) if runner_map: annotate_method_facts(program, method_dispatch, run_addrs, runner_map, types) annotate_type_vftables(program, types, method_dispatch) return {"types": types, "methods": methods, "method_inheritance": method_inheritance, "events": events, "fields": fields, "field_inheritance": field_inheritance, "struct_layout": struct_layout, "method_dispatch": method_dispatch, "runner_map": runner_map, "type_events": extract_type_events(program, types), "type_fields": extract_type_fields(program, types)} def run(): program = currentProgram # GhidraScript/pyghidra inject this global, not `program` factory = find_factory(program) if factory is not None: engine, compiler = detect_engine(factory) # namespace lives on the symbol/stub factory = resolve_thunk(factory) # MSVC8 exposes the symbol as a JMP stub surface = engine_surface(program, factory) binary = {"factory_addr": _hex(factory.getEntryPoint())} else: modules = find_module_factories(program) host = host_library(program) if not modules or host is None: print("[!] factory not found (CMC_ObjectsContainer::resolve / CMC_Scene::resolve, nor a" " scene module's CMC_ExternObject::resolve) - is this a Piklib/BlooMoo DLL with" " text-script support? (added in Piklib 6.1)") return engine, compiler = ("BlooMoo", "MSVC8") if host.upper().startswith("BLOOMOO") else ("Piklib", "MSVC6") surface = module_surface(program, modules) binary = {"factory_addr": _hex(modules[0][0].getEntryPoint()), "module_of": host} binary.update({"name": program.getName(), "sha256": sha256_of(program), "engine": engine, "compiler": compiler}) snapshot = {"schema_version": 7, "binary": binary} snapshot.update(surface) args = getScriptArgs() out_path = args[0] if len(args) > 0 else default_out_path(program) fh = open(out_path, "w") try: fh.write(json.dumps(snapshot, indent=2, sort_keys=True)) finally: fh.close() print("[+] %s [%s/%s%s]: %d types, %d methods, %d events (%d per type), %d fields (%d per type, %d layout, %d dispatch, %d runners) -> %s" % ( program.getName(), engine, compiler, " module of " + binary["module_of"] if "module_of" in binary else "", len(snapshot["types"]), len(snapshot["methods"]), len(snapshot["events"]), len(snapshot["type_events"]), len(snapshot["fields"]), len(snapshot["type_fields"]), len(snapshot["struct_layout"]), len(snapshot["method_dispatch"]), len((snapshot["runner_map"] or {}).get("runners", [])), out_path)) run()