Files
Aidem-Media-DLL-Analysis/ghidra_scripts/extract_engine_surface.py
T
Patryk GenschandClaude Opus 5.5 cb03de47ac feat(extractor): events per script type through the type's vftable
type_events reads getBehavioursList from each type's own vftable, so
unnamed classes (FILTER, FIFO/LIFO, MOVIE) get their events and
INTEGER/STRING/... resolve to CMC_Variable's list without guessing. The
slot is voted by same-class overrides because the folded base body
carries unrelated labels. Type vftables are recorded for every engine.
Schema 6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-24 19:49:26 +02:00

1936 lines
79 KiB
Python

# 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 <projDir> <projName> -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: `[<reg> + 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, <strptr>`, 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 <ctor>(...) -> 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
# <Runner>::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, <strptr>) 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)."""
fm = program.getFunctionManager()
methods = []
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))
return methods
_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 [<boundsreg> + <tableaddr>]`. 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 = 0
count = None
for instr in instrs:
if instr.getAddress().equals(jmp_addr):
break
if instr.getNumOperands() == 0 or instr.getDefaultOperandRepresentation(0) != bounds_reg:
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 {"table": table, "base": base, "count": count, "default": default,
"byte_table": byte_table}
def extract_method_dispatch(program, runner_map=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))
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::getProperty<T>Value getter name to the script field type."""
for needle, ty in _PROP_TYPE:
if needle in getter:
return ty
return "string" # plain getPropertyValue
def extract_script_fields(program):
"""The script-visible named fields each type exposes (FILENAME, FPS, PRELOAD, VISIBLE, ...).
The CMC_* constructor reads them from the element: it builds the property-name literal and
calls CMElement::getProperty<T>Value(...). We anchor on that getter call, take the preceding
string literal as the field name, and derive the field type from the getter. Returns a flat
list deduped per (owner, name)."""
fm = program.getFunctionManager()
listing = program.getListing()
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()
last_string = None
ins = listing.getInstructions(resolve_thunk(f).getBody(), True)
while ins.hasNext():
instr = ins.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
if cname is not None and cname.startswith("getProperty") and last_string is not None:
key = (owner, last_string)
if key not in by_key:
o = next_order.get(owner, 0)
by_key[key] = {"owner": owner, "name": last_string,
"type": _prop_type(cname), "order": o}
next_order[owner] = o + 1
last_string = None
return sorted(by_key.values(), key=lambda r: (r["owner"], r["order"]))
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<class>@@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<class>@@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
`p<X>Runner = new <X>_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)]}
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"}
# __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):
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 _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)
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])
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
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"])
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():
run_func = _function_at(program, run_addrs.get(runner))
high = dec.high(run_func) if run_func is not None 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()
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 <repo>/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
# --------------------------------------------------------------------------- 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 run():
program = currentProgram # GhidraScript/pyghidra inject this global, not `program`
factory = find_factory(program)
if factory is None:
print("[!] factory not found (CMC_ObjectsContainer::resolve / CMC_Scene::resolve)"
" - is this a Piklib/BlooMoo DLL with text-script support? (added in Piklib 6.1)")
return
engine, compiler = detect_engine(factory) # namespace lives on the symbol/stub
factory = resolve_thunk(factory) # MSVC8 exposes the symbol as a JMP stub
types = extract_types(program, factory)
runner_map = extract_runner_map(program, types) or extract_class_runners(program)
methods, method_inheritance = extract_methods(program, runner_map)
events = extract_events(program)
fields = extract_script_fields(program)
struct_layout, field_inheritance = extract_struct_layout(program)
method_dispatch, run_addrs = extract_method_dispatch(program, runner_map)
if runner_map and "by_type_id" in runner_map:
annotate_method_facts(program, method_dispatch, run_addrs, runner_map, types)
annotate_type_vftables(program, types, method_dispatch)
type_events = extract_type_events(program, types)
snapshot = {
"schema_version": 6,
"binary": {
"name": program.getName(),
"sha256": sha256_of(program),
"engine": engine,
"compiler": compiler,
"factory_addr": "0x%x" % factory.getEntryPoint().getOffset(),
},
"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": type_events,
}
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]: %d types, %d methods, %d events (%d per type), %d fields (%d layout, %d dispatch, %d runners) -> %s" % (
program.getName(), engine, compiler, len(types), len(methods),
len(events), len(type_events), len(fields), len(struct_layout), len(method_dispatch),
len((runner_map or {}).get("runners", [])), out_path))
run()