ipeddle 0.1.0__py3-none-any.whl

ipeddle/macho.py

@@ -0,0 +1,281 @@
+"""A small, dependency-free Mach-O reader (enough for ``ipeddle inspect``)."""
+
+from __future__ import annotations
+
+import struct
+from dataclasses import dataclass, field
+
+MH_MAGIC_64 = 0xFEEDFACF
+FAT_MAGIC = 0xCAFEBABE
+FAT_MAGIC_64 = 0xCAFEBABF
+
+CPU_TYPE_ARM64 = 0x0100000C
+CPU_TYPE_X86_64 = 0x01000007
+CPU_SUBTYPE_ARM64E = 2
+
+LC_REQ_DYLD = 0x80000000
+LC_SEGMENT_64 = 0x19
+LC_LOAD_DYLIB = 0xC
+LC_LOAD_WEAK_DYLIB = 0x18 | LC_REQ_DYLD
+LC_REEXPORT_DYLIB = 0x1F | LC_REQ_DYLD
+LC_LAZY_LOAD_DYLIB = 0x20
+LC_LOAD_UPWARD_DYLIB = 0x23 | LC_REQ_DYLD
+LC_ID_DYLIB = 0xD
+LC_RPATH = 0x1C | LC_REQ_DYLD
+LC_ENCRYPTION_INFO_64 = 0x2C
+LC_VERSION_MIN_IPHONEOS = 0x25
+LC_BUILD_VERSION = 0x32
+LC_DYLD_INFO = 0x22
+LC_DYLD_INFO_ONLY = 0x22 | LC_REQ_DYLD
+LC_DYLD_CHAINED_FIXUPS = 0x34 | LC_REQ_DYLD
+LC_CODE_SIGNATURE = 0x1D
+LC_MAIN = 0x28 | LC_REQ_DYLD
+
+DYLIB_CMDS = {LC_LOAD_DYLIB: "load", LC_LOAD_WEAK_DYLIB: "weak", LC_REEXPORT_DYLIB: "reexport",
+              LC_LAZY_LOAD_DYLIB: "lazy", LC_LOAD_UPWARD_DYLIB: "upward"}
+
+PLATFORMS = {1: "macOS", 2: "iOS", 3: "tvOS", 4: "watchOS", 5: "bridgeOS", 6: "Mac Catalyst",
+             7: "iOS Simulator", 8: "tvOS Simulator", 9: "watchOS Simulator", 10: "DriverKit",
+             11: "visionOS", 12: "visionOS Simulator"}
+
+BIND_SPECIAL_SELF = 0
+BIND_SPECIAL_MAIN = -1
+BIND_SPECIAL_FLAT = -2
+BIND_SPECIAL_WEAK = -3
+
+
+class MachOError(Exception):
+    pass
+
+
+@dataclass
+class Dylib:
+    path: str
+    kind: str
+
+
+@dataclass
+class Import:
+    name: str
+    ordinal: int        # 1-based library ordinal, or a BIND_SPECIAL_* value
+    weak: bool = False
+
+
+@dataclass
+class Slice:
+    cputype: int
+    cpusubtype: int
+    filetype: int
+    platform: str | None = None
+    minos: str | None = None
+    sdk: str | None = None
+    dylibs: list[Dylib] = field(default_factory=list)
+    rpaths: list[str] = field(default_factory=list)
+    imports: list[Import] = field(default_factory=list)
+    encrypted: bool = False
+    signed: bool = False
+    has_main: bool = False
+
+    @property
+    def arch(self) -> str:
+        if self.cputype == CPU_TYPE_ARM64:
+            return "arm64e" if (self.cpusubtype & 0xFF) == CPU_SUBTYPE_ARM64E else "arm64"
+        if self.cputype == CPU_TYPE_X86_64:
+            return "x86_64"
+        return hex(self.cputype)
+
+    def library_for(self, imp: Import) -> str:
+        if imp.ordinal == BIND_SPECIAL_FLAT:
+            return "<flat lookup>"
+        if imp.ordinal == BIND_SPECIAL_SELF:
+            return "<self>"
+        if imp.ordinal == BIND_SPECIAL_MAIN:
+            return "<main executable>"
+        if imp.ordinal == BIND_SPECIAL_WEAK:
+            return "<weak lookup>"
+        if 1 <= imp.ordinal <= len(self.dylibs):
+            return self.dylibs[imp.ordinal - 1].path
+        return f"<bad ordinal {imp.ordinal}>"
+
+
+def _ver(v: int) -> str:
+    major, minor, patch = v >> 16, (v >> 8) & 0xFF, v & 0xFF
+    return f"{major}.{minor}" + (f".{patch}" if patch else "")
+
+
+def _cstr(buf: bytes, off: int) -> str:
+    end = buf.find(b"\0", off)
+    return buf[off:end if end >= 0 else len(buf)].decode("utf-8", "replace")
+
+
+def _uleb(buf: bytes, i: int) -> tuple[int, int]:
+    result = shift = 0
+    while True:
+        b = buf[i]
+        i += 1
+        result |= (b & 0x7F) << shift
+        shift += 7
+        if not b & 0x80:
+            return result, i
+
+
+def _sleb(buf: bytes, i: int) -> tuple[int, int]:
+    result = shift = 0
+    while True:
+        b = buf[i]
+        i += 1
+        result |= (b & 0x7F) << shift
+        shift += 7
+        if not b & 0x80:
+            if b & 0x40:
+                result -= 1 << shift
+            return result, i
+
+
+def parse_slice(data: bytes, base: int = 0) -> Slice:
+    magic, cputype, cpusub, filetype, ncmds, sizeofcmds, _flags, _res = struct.unpack_from("<IiiIIIII", data, base)
+    if magic != MH_MAGIC_64:
+        raise MachOError("not a 64-bit little-endian Mach-O")
+    sl = Slice(cputype & 0xFFFFFFFF, cpusub & 0xFFFFFFFF, filetype)
+    off = base + 32
+    end = off + sizeofcmds
+    chained = None
+    dyld_info = None
+    for _ in range(ncmds):
+        if off + 8 > end:
+            raise MachOError("load commands overrun their declared size")
+        cmd, cmdsize = struct.unpack_from("<II", data, off)
+        if cmdsize < 8:
+            raise MachOError("corrupt load command")
+        if cmd in DYLIB_CMDS:
+            name_off = struct.unpack_from("<I", data, off + 8)[0]
+            sl.dylibs.append(Dylib(_cstr(data, off + name_off), DYLIB_CMDS[cmd]))
+        elif cmd == LC_RPATH:
+            sl.rpaths.append(_cstr(data, off + struct.unpack_from("<I", data, off + 8)[0]))
+        elif cmd == LC_BUILD_VERSION:
+            plat, minos, sdk = struct.unpack_from("<III", data, off + 8)
+            sl.platform, sl.minos, sl.sdk = PLATFORMS.get(plat, str(plat)), _ver(minos), _ver(sdk)
+        elif cmd == LC_VERSION_MIN_IPHONEOS:
+            v, sdk = struct.unpack_from("<II", data, off + 8)
+            sl.platform, sl.minos, sl.sdk = "iOS", _ver(v), _ver(sdk)
+        elif cmd == LC_ENCRYPTION_INFO_64:
+            sl.encrypted = struct.unpack_from("<I", data, off + 16)[0] != 0
+        elif cmd == LC_CODE_SIGNATURE:
+            sl.signed = True
+        elif cmd == LC_MAIN:
+            sl.has_main = True
+        elif cmd == LC_DYLD_CHAINED_FIXUPS:
+            chained = struct.unpack_from("<II", data, off + 8)
+        elif cmd in (LC_DYLD_INFO, LC_DYLD_INFO_ONLY):
+            dyld_info = struct.unpack_from("<10I", data, off + 8)
+        off += cmdsize
+    if chained:
+        sl.imports = _chained_imports(data, base + chained[0], chained[1])
+    elif dyld_info:
+        imports = {}
+        for o, s in ((dyld_info[2], dyld_info[3]), (dyld_info[4], dyld_info[5]), (dyld_info[6], dyld_info[7])):
+            if s:
+                for imp in _bind_opcodes(data, base + o, s):
+                    imports.setdefault((imp.name, imp.ordinal), imp)
+        sl.imports = list(imports.values())
+    return sl
+
+
+def _chained_imports(data: bytes, off: int, size: int) -> list[Import]:
+    (_ver, _starts, imports_off, symbols_off, count, fmt, sym_fmt) = struct.unpack_from("<7I", data, off)
+    if sym_fmt != 0:
+        raise MachOError("compressed chained-fixup symbol tables are not supported")
+    out = []
+    p = off + imports_off
+    syms = off + symbols_off
+    for _ in range(count):
+        if fmt == 1:      # DYLD_CHAINED_IMPORT
+            v = struct.unpack_from("<I", data, p)[0]
+            p += 4
+            lib, weak, name_off = v & 0xFF, (v >> 8) & 1, v >> 9
+            if lib > 0xF0:
+                lib -= 0x100
+        elif fmt == 2:    # DYLD_CHAINED_IMPORT_ADDEND
+            v = struct.unpack_from("<I", data, p)[0]
+            p += 8
+            lib, weak, name_off = v & 0xFF, (v >> 8) & 1, v >> 9
+            if lib > 0xF0:
+                lib -= 0x100
+        elif fmt == 3:    # DYLD_CHAINED_IMPORT_ADDEND64
+            v = struct.unpack_from("<Q", data, p)[0]
+            p += 16
+            lib, weak, name_off = v & 0xFFFF, (v >> 16) & 1, v >> 32
+            if lib > 0xFFF0:
+                lib -= 0x10000
+        else:
+            raise MachOError(f"unknown chained import format {fmt}")
+        out.append(Import(_cstr(data, syms + name_off), lib, bool(weak)))
+    return out
+
+
+def _bind_opcodes(data: bytes, off: int, size: int) -> list[Import]:
+    out = []
+    i, end = off, off + size
+    ordinal, name, weak = 0, "", False
+    while i < end:
+        b = data[i]
+        i += 1
+        op, imm = b & 0xF0, b & 0x0F
+        if op == 0x00:          # DONE (lazy streams continue)
+            continue
+        elif op == 0x10:        # SET_DYLIB_ORDINAL_IMM
+            ordinal = imm
+        elif op == 0x20:        # SET_DYLIB_ORDINAL_ULEB
+            ordinal, i = _uleb(data, i)
+        elif op == 0x30:        # SET_DYLIB_SPECIAL_IMM
+            ordinal = (imm | 0xF0) - 0x100 if imm else 0
+        elif op == 0x40:        # SET_SYMBOL_TRAILING_FLAGS_IMM
+            j = data.index(b"\0", i)
+            name = data[i:j].decode("utf-8", "replace")
+            weak = bool(imm & 0x1)
+            i = j + 1
+        elif op == 0x50:        # SET_TYPE_IMM
+            pass
+        elif op == 0x60:        # SET_ADDEND_SLEB
+            _, i = _sleb(data, i)
+        elif op == 0x70:        # SET_SEGMENT_AND_OFFSET_ULEB
+            _, i = _uleb(data, i)
+        elif op == 0x80:        # ADD_ADDR_ULEB
+            _, i = _uleb(data, i)
+        elif op in (0x90, 0xB0):  # DO_BIND, DO_BIND_ADD_ADDR_IMM_SCALED
+            out.append(Import(name, ordinal, weak))
+        elif op == 0xA0:        # DO_BIND_ADD_ADDR_ULEB
+            out.append(Import(name, ordinal, weak))
+            _, i = _uleb(data, i)
+        elif op == 0xC0:        # DO_BIND_ULEB_TIMES_SKIPPING_ULEB
+            out.append(Import(name, ordinal, weak))
+            _, i = _uleb(data, i)
+            _, i = _uleb(data, i)
+        else:
+            break
+    return out
+
+
+def parse(data: bytes) -> list[Slice]:
+    if len(data) < 32:
+        raise MachOError("file too small to be Mach-O")
+    magic_be = struct.unpack_from(">I", data, 0)[0]
+    if magic_be in (FAT_MAGIC, FAT_MAGIC_64):
+        n = struct.unpack_from(">I", data, 4)[0]
+        slices = []
+        for k in range(n):
+            if magic_be == FAT_MAGIC:
+                _ct, _cs, offset, _size, _align = struct.unpack_from(">IIIII", data, 8 + k * 20)
+            else:
+                _ct, _cs, offset, _size, _align, _r = struct.unpack_from(">IIQQII", data, 8 + k * 32)
+            slices.append(parse_slice(data, offset))
+        return slices
+    return [parse_slice(data, 0)]
+
+
+def is_macho(data: bytes) -> bool:
+    if len(data) < 4:
+        return False
+    le = struct.unpack_from("<I", data, 0)[0]
+    be = struct.unpack_from(">I", data, 0)[0]
+    return le == MH_MAGIC_64 or be in (FAT_MAGIC, FAT_MAGIC_64)

ipeddle/mangling.py

@@ -0,0 +1,136 @@
+"""Tiny helpers over Swift mangled names.
+
+We never need a full demangler: ipeddle only has to answer "which module owns
+this symbol?" so it can decide which library a symbol must be bound to.
+"""
+
+from __future__ import annotations
+
+import re
+
+_PREFIXES = ("_$s", "$s", "_$S", "$S")
+
+# Kind letters that may follow a nominal type in a mangled context.
+_KIND_CHARS = set("VCOPaN")
+
+
+def is_swift_symbol(name: str) -> bool:
+    return name.startswith(_PREFIXES)
+
+
+def _strip_prefix(name: str) -> str | None:
+    for p in _PREFIXES:
+        if name.startswith(p):
+            return name[len(p):]
+    return None
+
+
+def _read_ident(s: str, i: int) -> tuple[str, int] | None:
+    """Read a ``<decimal length><identifier>`` token at ``s[i:]``.
+
+    Word-substituted identifiers (introduced by ``0``) are not decoded and
+    return ``None``.
+    """
+    m = re.match(r"[1-9][0-9]*", s[i:])
+    if not m:
+        return None
+    n = int(m.group(0))
+    start = i + len(m.group(0))
+    ident = s[start:start + n]
+    if len(ident) != n or not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", ident):
+        return None
+    return ident, start + n
+
+
+def literal_identifiers(name: str) -> list[str]:
+    """All literal ``<len><ident>`` tokens, in order (best effort)."""
+    s = _strip_prefix(name)
+    if s is None:
+        return []
+    out = []
+    i = 0
+    while i < len(s):
+        if s[i].isdigit() and s[i] != "0" and (i == 0 or not s[i - 1].isdigit()):
+            tok = _read_ident(s, i)
+            if tok:
+                out.append(tok[0])
+                i = tok[1]
+                continue
+        i += 1
+    return out
+
+
+def owner_module(name: str, known: set[str] | frozenset[str] | None = None) -> str | None:
+    """Like :func:`_owner_module`; with ``known`` (the module names that exist
+    in the SDK), an answer that is not a module falls back to the first
+    module named literally in the mangling.  That covers witness tables of
+    standard types (``$sSi7SwiftUI...WP``) and associated type descriptors
+    (``$s4Body7SwiftUI4ViewPTl``)."""
+    guess = _owner_module(name)
+    if known is None or guess in known:
+        return guess
+    for ident in literal_identifiers(name):
+        if ident in known:
+            return ident
+    return None
+
+
+def _owner_module(name: str) -> str | None:
+    """Return the module that *defines* the entity a Swift symbol refers to.
+
+    Rules (enough for linking decisions):
+    * ``$s<len>Module...``                        -> Module
+    * ``$s<context><len>ModuleE...`` (extension)  -> Module of the extension
+    * ``$sSo<len>Type<kind><len>ModuleE...``      -> Module (extension on an
+      imported Objective-C/C type)
+    * ``$sS<x><len>ModuleE...``                   -> Module (extension on a
+      standard library type, e.g. ``SS`` = String)
+    Anything else returns ``None``.
+    """
+    s = _strip_prefix(name)
+    if s is None or not s:
+        return None
+    i = 0
+    first: str | None = None
+    if s.startswith(("So", "SC")):
+        tok = _read_ident(s, 2)
+        if tok is None:
+            return None
+        i = tok[1]
+        while i < len(s) and s[i] in _KIND_CHARS:
+            i += 1
+    elif len(s) >= 2 and s[0] == "S" and s[1].isalpha():
+        i = 2
+    else:
+        tok = _read_ident(s, 0)
+        if tok is None:
+            return None
+        first, i = tok
+    # Walk the remaining context chain looking for an extension marker.
+    steps = 0
+    while i < len(s) and steps < 8:
+        steps += 1
+        tok = _read_ident(s, i)
+        if tok is None:
+            break
+        ident, j = tok
+        if j < len(s) and s[j] == "E":
+            return ident
+        if first is None:
+            # Context started with a substitution and the next identifier is
+            # not an extension module: we cannot tell the owner reliably.
+            return None
+        i = j
+        while i < len(s) and s[i] in _KIND_CHARS:
+            i += 1
+    return first
+
+
+def mentions_module(name: str, module: str) -> bool:
+    """True if the literal ``<len><module>`` token occurs in the mangling."""
+    s = _strip_prefix(name) or name
+    tok = f"{len(module)}{module}"
+    for m in re.finditer(re.escape(tok), s):
+        if m.start() == 0 or not s[m.start() - 1].isdigit():
+            return True
+    return False