import { decodeStrictUtf8 } from "../domain/strictUtf8.js"; import { legacyMachoPlatform } from "../domain/apple/machoPlatform.js"; import { LC, machoLoadCommandName, } from "../domain/apple/machoLoadCommandCodes.js"; import type { MachoCommandNames } from "../domain/apple/machoCommandNames.js"; const PLATFORM_NAMES = new Map([ [1, "MACOS"], [2, "IOS"], [3, "TVOS"], [4, "WATCHOS"], [5, "BRIDGEOS"], [6, "MACCATALYST"], [7, "IOSSIMULATOR"], [8, "TVOSSIMULATOR"], [9, "WATCHOSSIMULATOR"], [10, "DRIVERKIT"], [11, "VISIONOS"], [12, "VISIONOSSIMULATOR"], [13, "FIRMWARE"], [14, "SEPOS"], [15, "MACOS_EXCLAVECORE"], [16, "MACOS_EXCLAVEKIT"], [17, "IOS_EXCLAVECORE"], [18, "IOS_EXCLAVEKIT"], [19, "TVOS_EXCLAVECORE"], [20, "TVOS_EXCLAVEKIT"], [21, "WATCHOS_EXCLAVECORE"], [22, "WATCHOS_EXCLAVEKIT"], [23, "VISIONOS_EXCLAVECORE"], [24, "VISIONOS_EXCLAVEKIT"], ]); const TOOL_NAMES = new Map([ [1, "CLANG"], [2, "SWIFT"], [3, "LD"], [4, "LLD"], [1024, "METAL"], [1025, "AIRLLD"], [1026, "AIRNT"], [1027, "AIRNT_PLUGIN"], [1028, "AIRPACK"], [1031, "GPUARCHIVER"], [1032, "METAL_FRAMEWORK"], ]); const DYLIBS = new Set([ "LC_LOAD_DYLIB", "LC_LOAD_WEAK_DYLIB", "LC_REEXPORT_DYLIB", "LC_LAZY_LOAD_DYLIB", "LC_LOAD_UPWARD_DYLIB", "LC_LOADFVMLIB", "LC_PREBOUND_DYLIB", ]); // Fixed-VM and prebound library commands carry fields after the name that this // projection does not decode. const UNDECODED_STRING_COMMANDS = new Set([ LC.LOADFVMLIB, LC.IDFVMLIB, LC.FVMFILE, LC.PREBOUND_DYLIB, ]); const STRING_FIELDS = new Map([ [LC.LOADFVMLIB, "name"], [LC.IDFVMLIB, "name"], [LC.FVMFILE, "name"], [LC.PREBOUND_DYLIB, "name"], [LC.LOAD_DYLIB, "name"], [LC.ID_DYLIB, "name"], [LC.LOAD_WEAK_DYLIB, "name"], [LC.REEXPORT_DYLIB, "name"], [LC.LAZY_LOAD_DYLIB, "name"], [LC.LOAD_UPWARD_DYLIB, "name"], [LC.LOAD_DYLINKER, "name"], [LC.ID_DYLINKER, "name"], [LC.SUB_FRAMEWORK, "umbrella"], [LC.SUB_UMBRELLA, "sub_umbrella"], [LC.SUB_CLIENT, "client"], [LC.SUB_LIBRARY, "sub_library"], [LC.RPATH, "path"], [LC.DYLD_ENVIRONMENT, "name"], [LC.TARGET_TRIPLE, "triple"], ]); const bytesText = (input: Uint8Array, fixed: boolean) => { const end = fixed ? input.indexOf(0) : -1; const bytes = end < 0 ? input : input.subarray(0, end); try { return { text: decodeStrictUtf8(bytes, "preserve"), bytesHex: null, }; } catch { return { text: null, bytesHex: Buffer.from(bytes).toString("hex") }; } }; const numberOrNull = (value: bigint): number | null => value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : null; const rawNumber = (value: bigint, width: number): number | string => numberOrNull(value) ?? `0x${value.toString(16).padStart(width, "0")}`; const address = (value: bigint) => `0x${value.toString(16)}`; const version = (value: number, includePatch = false) => { const major = value >>> 16; const minor = (value >>> 8) & 0xff; const patch = value & 0xff; return `${major}.${minor}${includePatch || patch !== 0 ? `.${patch}` : ""}`; }; const permissions = (value: number) => ({ read: (value & 1) !== 0, write: (value & 2) !== 0, execute: (value & 4) !== 0, raw: String(value), }); const uuidText = (bytes: Uint8Array) => { const hex = Buffer.from(bytes).toString("hex").toUpperCase(); return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`; }; type Section = { segment: string | null; segment_bytes_hex?: string; name: string | null; name_bytes_hex?: string; address: string; size: number | null; size_hex?: string; file_offset: number; alignment: number | null; alignment_exponent?: number; flags: string[]; }; type Segment = { name: string | null; name_bytes_hex?: string; vm_address: string; vm_size: number | null; vm_size_hex?: string; file_offset: number | null; file_offset_hex?: string; file_size: number | null; file_size_hex?: string; maximum_permissions: ReturnType; initial_permissions: ReturnType; sections: Section[]; }; type Dependency = { path: string | null; path_bytes_hex?: string; kind: string; current_version: string | null; compatibility_version: string | null; }; export interface BinaryMachoProjection { readonly wordSize: 32 | 64; readonly endian: "little" | "big"; readonly fileType: string; readonly flags: string[]; readonly commands: { index: number; kind: string; fields: Record; }[]; readonly segments: Segment[]; readonly dependencies: Dependency[]; readonly entrypoints: { file_offset: number }[]; readonly builds: { platform: string | null; minimum_os: string | null; sdk: string | null; tools: { name: string; version: string }[]; }[]; readonly commandLimitations: string[]; readonly segmentLimitations: string[]; readonly dependencyLimitations: string[]; readonly entrypointLimitations: string[]; readonly buildLimitations: string[]; } /** Project only observed binary fields; unmodeled command payloads are explicit. */ export const projectMachoBinary = ( binary: MachoCommandNames, ): BinaryMachoProjection => { const commands: BinaryMachoProjection["commands"] = []; const segments: Segment[] = []; const dependencies: Dependency[] = []; const entrypoints: BinaryMachoProjection["entrypoints"] = []; const builds: BinaryMachoProjection["builds"] = []; const commandLimitations = new Set(); const segmentLimitations = new Set(); const dependencyLimitations = new Set(); const entrypointLimitations = new Set(); const buildLimitations = new Set(); const wordWidth = binary.header.wide ? 16 : 8; const textFact = ( bytes: Uint8Array, fixed: boolean, limitations: Set, ) => { const fact = bytesText(bytes, fixed); if (fact.text === null) limitations.add( "A Mach-O name is not valid UTF-8; its exact bytes are retained as hexadecimal and its text is unknown.", ); return fact; }; for (const row of binary.commands) { const kind = machoLoadCommandName(row.command) ?? `LC_UNKNOWN_0x${row.command.toString(16)}`; const fields: Record = { cmd: kind, cmdsize: row.size, ...row.fixedFields, }; let decoded = row.fixedFields !== undefined; if ( row.segment !== undefined && row.segmentName !== undefined && row.sections !== undefined ) { decoded = true; const name = textFact(row.segmentName, true, segmentLimitations); if (name.text === null) commandLimitations.add( "A Mach-O name is not valid UTF-8; its exact bytes are retained as hexadecimal and its text is unknown.", ); const repeated = (key: string, index: number, count: number) => count > 1 ? `${key} #${index + 1}` : key; fields[repeated("segname", 0, row.sections.length + 1)] = name.text; fields[`${repeated("segname", 0, row.sections.length + 1)}_storage_hex`] = Buffer.from(row.segmentName).toString("hex"); if (name.bytesHex !== null) fields[`${repeated("segname", 0, row.sections.length + 1)}_bytes_hex`] = name.bytesHex; fields.vmaddr = rawNumber(row.segment.address, wordWidth); fields.vmsize = rawNumber(row.segment.memorySize, wordWidth); fields.fileoff = rawNumber(row.segment.fileOffset, wordWidth); fields.filesize = rawNumber(row.segment.fileSize, wordWidth); fields.maxprot = row.segment.maxProtection; fields.initprot = row.segment.protection; fields.nsects = row.sections.length; fields[repeated("flags", 0, row.sections.length + 1)] = row.segment.flags; const vmSize = numberOrNull(row.segment.memorySize); const fileOffset = numberOrNull(row.segment.fileOffset); const fileSize = numberOrNull(row.segment.fileSize); if (vmSize === null || fileOffset === null || fileSize === null) segmentLimitations.add( "A segment size or file offset exceeds the safe integer range; its exact hexadecimal value remains in the load command.", ); const sections = row.sections.map((section, index): Section => { const sectionName = textFact(section.name, true, segmentLimitations); const sectionOwner = textFact( section.segmentName, true, segmentLimitations, ); const size = numberOrNull(section.size); const sectionNameKey = repeated( "sectname", index, row.sections!.length, ); const segmentNameKey = repeated( "segname", index + 1, row.sections!.length + 1, ); fields[sectionNameKey] = sectionName.text; fields[segmentNameKey] = sectionOwner.text; fields[`${sectionNameKey}_storage_hex`] = Buffer.from( section.name, ).toString("hex"); fields[`${segmentNameKey}_storage_hex`] = Buffer.from( section.segmentName, ).toString("hex"); if (sectionName.bytesHex !== null) fields[`${sectionNameKey}_bytes_hex`] = sectionName.bytesHex; if (sectionOwner.bytesHex !== null) fields[`${segmentNameKey}_bytes_hex`] = sectionOwner.bytesHex; if (sectionName.text === null || sectionOwner.text === null) commandLimitations.add( "A Mach-O name is not valid UTF-8; its exact bytes are retained as hexadecimal and its text is unknown.", ); const count = row.sections!.length; fields[repeated("addr", index, count)] = rawNumber( section.address, wordWidth, ); fields[repeated("size", index, count)] = rawNumber( section.size, wordWidth, ); fields[repeated("offset", index, count)] = section.fileOffset; fields[repeated("align", index, count)] = section.alignmentExponent; fields[repeated("reloff", index, count)] = section.relocationOffset; fields[repeated("nreloc", index, count)] = section.relocationCount; fields[repeated("flags", index + 1, count + 1)] = section.flags; fields[repeated("reserved1", index, count)] = section.reserved1; fields[repeated("reserved2", index, count)] = section.reserved2; if (section.reserved3 !== undefined) fields[repeated("reserved3", index, count)] = section.reserved3; const alignment = section.alignmentExponent > 52 ? null : 2 ** section.alignmentExponent; if (size === null || alignment === null) segmentLimitations.add( "A section size or alignment exceeds the safe integer range and is unknown in the segment view.", ); return { segment: sectionOwner.text, ...(sectionOwner.bytesHex === null ? {} : { segment_bytes_hex: sectionOwner.bytesHex }), name: sectionName.text, ...(sectionName.bytesHex === null ? {} : { name_bytes_hex: sectionName.bytesHex }), address: address(section.address), size, ...(size === null ? { size_hex: address(section.size) } : {}), file_offset: section.fileOffset, alignment, ...(alignment === null ? { alignment_exponent: section.alignmentExponent } : {}), flags: [`0x${section.flags.toString(16)}`], }; }); segments.push({ name: name.text, ...(name.bytesHex === null ? {} : { name_bytes_hex: name.bytesHex }), vm_address: address(row.segment.address), vm_size: vmSize, ...(vmSize === null ? { vm_size_hex: address(row.segment.memorySize) } : {}), file_offset: fileOffset, ...(fileOffset === null ? { file_offset_hex: address(row.segment.fileOffset) } : {}), file_size: fileSize, ...(fileSize === null ? { file_size_hex: address(row.segment.fileSize) } : {}), maximum_permissions: permissions(row.segment.maxProtection), initial_permissions: permissions(row.segment.protection), sections, }); } if (row.commandString !== undefined) { decoded = !UNDECODED_STRING_COMMANDS.has(row.command); const name = textFact(row.commandString, false, commandLimitations); const field = STRING_FIELDS.get(row.command) ?? "name"; fields[field] = name.text === null ? null : `${name.text} (offset ${String(row.commandStringOffset)})`; if (name.bytesHex !== null) fields[`${field}_bytes_hex`] = name.bytesHex; if (row.dylib !== undefined) { fields["current version"] = version(row.dylib.currentVersion, true); fields["compatibility version"] = version( row.dylib.compatibilityVersion, true, ); if (row.dylib.encoding.kind === "timestamp") fields["time stamp"] = row.dylib.encoding.timestamp; else fields.options = row.dylib.encoding.flags; } if (DYLIBS.has(kind)) { if (name.text === null) dependencyLimitations.add( "A dependency path is not valid UTF-8; its exact bytes are retained as hexadecimal and its text is unknown.", ); dependencies.push({ path: name.text, ...(name.bytesHex === null ? {} : { path_bytes_hex: name.bytesHex }), kind, current_version: row.dylib === undefined ? null : version(row.dylib.currentVersion, true), compatibility_version: row.dylib === undefined ? null : version(row.dylib.compatibilityVersion, true), }); } } if (row.fvmlib !== undefined) { decoded = true; fields["minor version"] = row.fvmlib.minorVersion; fields["header addr"] = row.fvmlib.headerAddress; } if (row.fvmfile !== undefined) { decoded = true; fields["header addr"] = row.fvmfile.headerAddress; } if (row.prebound !== undefined) { decoded = true; fields.nmodules = row.prebound.moduleCount; fields.linked_modules_offset = row.prebound.linkedModulesOffset; fields.linked_modules_bytes_hex = Buffer.from( row.prebound.linkedModules, ).toString("hex"); } if (row.uuid !== undefined) { decoded = true; fields.uuid = uuidText(row.uuid); } if (row.entrypoint !== undefined) { decoded = true; fields.entryoff = rawNumber(row.entrypoint.offset, 16); fields.stacksize = rawNumber(row.entrypoint.stackSize, 16); const offset = numberOrNull(row.entrypoint.offset); if (offset === null) entrypointLimitations.add( "An entrypoint offset exceeds the safe integer range; its exact value remains in the load command.", ); else entrypoints.push({ file_offset: offset }); } if (row.build !== undefined) { decoded = true; fields.platform = row.build.platform; fields.minos = version(row.build.minimumOs); fields.sdk = version(row.build.sdk); fields.ntools = row.build.tools.length; const tools = row.build.tools.map((tool, index) => { const suffix = row.build!.tools.length > 1 ? ` #${index + 1}` : ""; fields[`tool${suffix}`] = tool.tool; fields[`version${suffix}`] = version(tool.version); return { name: TOOL_NAMES.get(tool.tool) ?? String(tool.tool), version: version(tool.version), }; }); builds.push({ platform: PLATFORM_NAMES.get(row.build.platform) ?? String(row.build.platform), minimum_os: version(row.build.minimumOs), sdk: version(row.build.sdk), tools, }); } if (row.legacyBuild !== undefined) { decoded = true; fields.version = version(row.legacyBuild.version); fields.sdk = version(row.legacyBuild.sdk); const platform = row.legacyBuild.platform; const effective = legacyMachoPlatform(platform, binary.header.cpuType); builds.push({ platform: effective === platform ? (["MACOSX", "IPHONEOS", "TVOS", "WATCHOS"][platform - 1] ?? null) : (PLATFORM_NAMES.get(effective) ?? String(effective)), minimum_os: version(row.legacyBuild.version), sdk: version(row.legacyBuild.sdk), tools: [], }); } if (row.linkerOptions !== undefined) { decoded = true; fields.count = row.linkerOptions.length; row.linkerOptions.forEach((option, index) => { const fact = textFact(option, false, commandLimitations); const label = `string #${index + 1}`; fields[label] = fact.text; if (fact.bytesHex !== null) fields[`${label}_bytes_hex`] = fact.bytesHex; }); } if (row.note !== undefined) { decoded = true; const owner = textFact(row.note.owner, true, commandLimitations); fields.data_owner = owner.text; fields.data_owner_storage_hex = Buffer.from(row.note.owner).toString( "hex", ); if (owner.bytesHex !== null) fields.data_owner_bytes_hex = owner.bytesHex; fields.offset = rawNumber(row.note.offset, 16); fields.size = rawNumber(row.note.size, 16); } if (row.fileset !== undefined) { decoded = true; const id = textFact(row.fileset.entryId, false, commandLimitations); fields.vmaddr = rawNumber(row.fileset.address, 16); fields.fileoff = rawNumber(row.fileset.fileOffset, 16); fields.entry_id = id.text; if (id.bytesHex !== null) fields.entry_id_bytes_hex = id.bytesHex; fields.reserved = row.fileset.reserved; } if ( !row.fullyDecoded || !decoded || machoLoadCommandName(row.command) === undefined ) { fields.command_code = row.command; fields.command_offset = (binary.header.wide ? 32 : 28) + row.offset; fields.command_sha256 = row.rawSha256; commandLimitations.add( "Some load-command payload fields are not decoded; command codes, positions and sizes remain observed, but the payload bytes are not retained. A whole-command SHA-256 is included when it fit the read allowance.", ); if (machoLoadCommandName(row.command) === undefined) { dependencyLimitations.add( "An unknown load command may contain dependency facts that were not decoded.", ); entrypointLimitations.add( "An unknown load command may contain entrypoint facts that were not decoded.", ); buildLimitations.add( "An unknown load command may contain build facts that were not decoded.", ); } if (kind === "LC_THREAD" || kind === "LC_UNIXTHREAD") entrypointLimitations.add("Thread-state entrypoints are not decoded."); if (kind.startsWith("LC_VERSION_MIN_") || kind === "LC_BUILD_VERSION") buildLimitations.add(`The ${kind} payload is not decoded.`); } if (kind === "LC_LAZY_LOAD_DYLIB_INFO") dependencyLimitations.add( "The linkedit dependency payload is not decoded.", ); commands.push({ index: row.index, kind, fields }); } return { wordSize: binary.header.wide ? 64 : 32, endian: binary.header.littleEndian ? "little" : "big", fileType: String(binary.header.fileType), flags: [`0x${binary.header.flags.toString(16).padStart(8, "0")}`], commands, segments, dependencies, entrypoints, builds, commandLimitations: [...commandLimitations], segmentLimitations: [...segmentLimitations], dependencyLimitations: [...dependencyLimitations], entrypointLimitations: [...entrypointLimitations], buildLimitations: [...buildLimitations], }; };