Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

22.7 KB
Raw Blame
interface ParsedSection {
  readonly segment: string;
  readonly name: string;
  readonly address: string | null;
  readonly size: number | null;
  readonly file_offset: number | null;
  readonly alignment: number | null;
  readonly flags: string[];
}

interface ParsedSegment {
  readonly name: string;
  readonly vm_address: string | null;
  readonly vm_size: number | null;
  readonly file_offset: number | null;
  readonly file_size: number | null;
  readonly maximum_permissions: ReturnType<typeof permissions>;
  readonly initial_permissions: ReturnType<typeof permissions>;
  readonly sections: ParsedSection[];
}

interface ParsedLoadCommands {
  readonly cpuType: number | null;
  readonly commands: Array<{
    index: number;
    kind: string;
    fields: Record<string, string | number | null>;
  }>;
  readonly segments: ParsedSegment[];
  readonly dependencies: Array<{
    path: string;
    kind: string;
    current_version: string | null;
    compatibility_version: string | null;
  }>;
  readonly entrypoints: Array<{ file_offset: number }>;
  readonly builds: Array<{
    platform: string | null;
    minimum_os: string | null;
    sdk: string | null;
    tools: Array<{ name: string; version: string }>;
  }>;
  uuid: string | null;
  readonly flags: Set<string>;
  readonly omittedDependencyCommands: string[];
}

const DYLIB_COMMANDS = new Set([
  "LC_ID_DYLIB",
  "LC_LOAD_DYLIB",
  "LC_LOAD_WEAK_DYLIB",
  "LC_REEXPORT_DYLIB",
  "LC_LAZY_LOAD_DYLIB",
  "LC_LOAD_UPWARD_DYLIB",
]);
/**
 * Dependency commands whose install name is not in the otool command text.
 * `LC_LAZY_LOAD_DYLIB_INFO` stores it in a linkedit payload.
 */
const PAYLOAD_DEPENDENCY_COMMANDS = new Set(["LC_LAZY_LOAD_DYLIB_INFO"]);

const DYLIB_FIELDS = [
  "cmd",
  "cmdsize",
  "name",
  "current version",
  "compatibility version",
];
// otool prints options for dylib_use_command and a timestamp for dylib_command.
const DYLIB_ENCODING_FIELDS = ["time stamp", "options"];
const EMPTY_VALUE_FIELDS = new Set(["options", "segname", "sectname"]);

/**
 * Non-verbose otool prints LC_BUILD_VERSION platform and tool codes as
 * numbers. Name the codes declared in the SDK's <mach-o/loader.h>, without
 * the PLATFORM_/TOOL_ prefix, so build metadata uses the same symbolic style
 * as LC_VERSION_MIN_* platforms. Unknown codes keep their printed value.
 */
const BUILD_PLATFORM_NAMES: ReadonlyMap<string, string> = 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 BUILD_TOOL_NAMES: ReadonlyMap<string, string> = 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 buildCodeName = (
  names: ReadonlyMap<string, string>,
  value: string | null,
): string | null => (value === null ? null : (names.get(value) ?? value));

/**
 * otool emits LF, but a capture replayed from another host or toolchain can
 * carry CRLF. The section/command boundaries below match a bare `\n`, so a
 * stray `\r` would swallow the terminator and silently empty `sections` while
 * leaking section fields into the command. Normalizing once at the boundary
 * keeps every parser below working on one line ending.
 */
const normalizeLineEndings = (output: string): string =>
  output.replaceAll("\r\n", "\n");

/** Parse stable fields from `otool -l`, preserving unknown command fields. */
export const parseOtoolLoadCommands = (raw: string) => {
  const output = normalizeLineEndings(raw);
  const header = parseHeader(output);
  if (header === undefined)
    throw new TypeError("otool output is missing the Mach header");
  const state = createLoadCommandState(header.flags, header.cpuType);
  for (const block of output.split(/(?=^Load command \d+$)/mu))
    parseLoadCommand(block, state);
  validateLoadCommandFraming(header, state.commands);
  return {
    wordSize: WORD_SIZES.get(header.magic ?? "") ?? null,
    endian: header.cpuType === null ? null : cpuEndian(header.cpuType),
    fileType: header.fileType,
    flags: [...state.flags].sort(),
    uuid: state.uuid,
    commands: state.commands,
    segments: state.segments,
    dependencies: state.dependencies,
    omittedDependencyCommands: state.omittedDependencyCommands,
    entrypoints: state.entrypoints,
    builds: state.builds,
  };
};

/** otool prints the selected slice's magic in host order, symbolic with -v. */
const WORD_SIZES: ReadonlyMap<string, 32 | 64> = new Map<string, 32 | 64>([
  ["0xfeedface", 32],
  ["0xfeedfacf", 64],
  ["MH_MAGIC", 32],
  ["MH_MAGIC_64", 64],
]);

/** Mach-O byte order by CPU family, ignoring the ABI bits; others stay unknown. */
const cpuEndian = (cpuType: number): "little" | "big" | null => {
  const family = cpuType & 0x00ffffff;
  if (family === 7 || family === 12) return "little";
  return family === 18 ? "big" : null;
};

const parseHeader = (
  output: string,
):
  | {
      magic: string | null;
      cpuType: number | null;
      fileType: string | null;
      flags: string[];
      commandCount: number;
      commandBytes: number;
    }
  | undefined => {
  const lines = output.split(/\r?\n/u).map((line) => line.trim());
  const columnsLine = lines.findIndex((line) => /(?:^|\s)magic\s/u.test(line));
  if (columnsLine < 0) return undefined;
  const columns = lines[columnsLine]?.split(/\s+/u);
  const dataLine = lines.slice(columnsLine + 1).find((line) => line.length > 0);
  const values = dataLine?.split(/\s+/u);
  if (columns === undefined || values === undefined) return undefined;
  const commandCount = headerValue(columns, values, "ncmds");
  const commandBytes = headerValue(columns, values, "sizeofcmds");
  if (commandCount === null || commandBytes === null)
    throw new TypeError("otool Mach header is missing valid command framing");
  const fileTypeIndex = columns.indexOf("filetype");
  const flagsIndex = columns.indexOf("flags");
  const complete = values.length >= columns.length;
  const fileTypeValueIndex =
    flagsIndex >= 0 && fileTypeIndex > flagsIndex
      ? values.length - (columns.length - fileTypeIndex)
      : fileTypeIndex;
  const flagsEnd =
    flagsIndex >= 0 ? values.length - (columns.length - flagsIndex - 1) : 0;
  const magicIndex = columns.indexOf("magic");
  return {
    magic: magicIndex < 0 ? null : (values[magicIndex] ?? null),
    cpuType: headerValue(columns, values, "cputype"),
    commandCount,
    commandBytes,
    fileType:
      complete && fileTypeValueIndex >= 0 && fileTypeValueIndex < values.length
        ? (values[fileTypeValueIndex] ?? null)
        : null,
    flags:
      !complete || flagsIndex < 0 || flagsIndex >= flagsEnd
        ? []
        : values
            .slice(flagsIndex, flagsEnd)
            .filter((value) => value.length > 0),
  };
};

const headerValue = (
  columns: readonly string[],
  values: readonly string[],
  name: string,
): number | null => {
  const index = columns.indexOf(name);
  if (index < 0) return null;
  const flagsIndex = columns.indexOf("flags");
  const valueIndex =
    flagsIndex >= 0 && index > flagsIndex
      ? values.length - (columns.length - index)
      : index;
  const value = values[valueIndex];
  return value === undefined ? null : numeric(value);
};

const validateLoadCommandFraming = (
  header: { readonly commandCount: number; readonly commandBytes: number },
  commands: readonly {
    readonly index: number;
    readonly fields: Readonly<Record<string, string | number | null>>;
  }[],
): void => {
  if (commands.length !== header.commandCount)
    throw new TypeError(
      "otool load-command count does not match the Mach header",
    );
  let totalBytes = 0;
  for (const [expectedIndex, command] of commands.entries()) {
    const size = numberField(command.fields, "cmdsize");
    if (command.index !== expectedIndex || size === null || size < 8)
      throw new TypeError("otool load-command sequence or size is invalid");
    totalBytes += size;
    if (!Number.isSafeInteger(totalBytes))
      throw new TypeError("otool load-command byte count is unsafe");
  }
  if (totalBytes !== header.commandBytes)
    throw new TypeError(
      "otool load-command sizes do not match the Mach header",
    );
};

const createLoadCommandState = (
  headerFlags: readonly string[] | undefined,
  cpuType: number | null,
): ParsedLoadCommands => ({
  cpuType,
  commands: [],
  segments: [],
  dependencies: [],
  entrypoints: [],
  builds: [],
  uuid: null,
  flags: new Set(headerFlags ?? []),
  omittedDependencyCommands: [],
});

const parseLoadCommand = (block: string, state: ParsedLoadCommands): void => {
  const indexText = /^Load command (\d+)/u.exec(block)?.[1];
  if (indexText === undefined) return;
  const index = Number(indexText);
  if (!Number.isSafeInteger(index))
    throw new TypeError("otool load-command index is unsafe");
  const header = block.split(/\n\s*Section\n/u)[0] ?? block;
  const parsed = parseFields(header);
  const fields = parsed.values;
  const kind = stringField(fields, "cmd");
  if (kind === null) throw new TypeError("otool load command is missing cmd");
  for (const key of scalarFields(kind)) requireUniqueField(parsed, key);
  if (DYLIB_COMMANDS.has(kind)) validateDylibCommandLines(parsed);
  if (kind === "LC_LINKER_OPTION") validateLinkerOptionLines(parsed);
  state.commands.push({
    index,
    kind,
    fields,
  });
  collectUuid(kind, fields, state);
  collectEntrypoint(kind, fields, state);
  collectBuild(kind, block, fields, state);
  collectDependency(kind, fields, state);
  if (PAYLOAD_DEPENDENCY_COMMANDS.has(kind))
    state.omittedDependencyCommands.push(kind);
  collectSegment(kind, block, fields, state);
};

const validateDylibCommandLines = (parsed: ParsedFields): void => {
  const encodingFields = DYLIB_ENCODING_FIELDS.filter((key) =>
    parsed.rows.some((field) => field?.[0] === key),
  );
  if (encodingFields.length !== 1)
    throw new TypeError(
      "otool dylib command must contain timestamp or options",
    );
  for (const key of encodingFields) requireUniqueField(parsed, key);
  const allowed = new Set([...DYLIB_FIELDS, ...DYLIB_ENCODING_FIELDS]);
  for (const field of parsed.rows) {
    const key = field?.[0];
    if (key === undefined || !allowed.has(key))
      throw new TypeError(
        "otool dylib command contains ambiguous multiline text",
      );
  }
};

/** Each declared option appears once, in order, as `string #1..count`. */
const validateLinkerOptionLines = (parsed: ParsedFields): void => {
  const count = numberField(parsed.values, "count");
  const labels = parsed.rows
    .map((field) => field?.[0])
    .filter((key) => key !== "cmd" && key !== "cmdsize" && key !== "count");
  if (
    count === null ||
    labels.length !== count ||
    labels.some((key, index) => key !== `string #${String(index + 1)}`)
  )
    throw new TypeError("otool linker-option strings do not match count");
};

const scalarFields = (kind: string): readonly string[] => {
  const common = ["cmd", "cmdsize"];
  if (DYLIB_COMMANDS.has(kind)) return DYLIB_FIELDS;
  if (kind === "LC_LINKER_OPTION") return [...common, "count"];
  if (kind === "LC_LOAD_DYLINKER" || kind === "LC_ID_DYLINKER")
    return [...common, "name"];
  if (kind === "LC_UUID") return [...common, "uuid"];
  if (kind === "LC_MAIN") return [...common, "entryoff"];
  if (kind === "LC_BUILD_VERSION")
    return [...common, "platform", "minos", "sdk", "ntools"];
  if (kind.startsWith("LC_VERSION_MIN_")) return [...common, "version", "sdk"];
  if (kind === "LC_SEGMENT" || kind === "LC_SEGMENT_64")
    return [
      ...common,
      "segname",
      "vmaddr",
      "vmsize",
      "fileoff",
      "filesize",
      "maxprot",
      "initprot",
      "nsects",
      "flags",
    ];
  return common;
};

const collectUuid = (
  kind: string,
  fields: Readonly<Record<string, string | number | null>>,
  state: ParsedLoadCommands,
): void => {
  if (kind === "LC_UUID")
    state.uuid = stringField(fields, "uuid") ?? state.uuid;
};

const collectEntrypoint = (
  kind: string,
  fields: Readonly<Record<string, string | number | null>>,
  state: ParsedLoadCommands,
): void => {
  if (kind !== "LC_MAIN") return;
  const entry = numberField(fields, "entryoff");
  if (entry !== null) state.entrypoints.push({ file_offset: entry });
};

const collectBuild = (
  kind: string,
  block: string,
  fields: Readonly<Record<string, string | number | null>>,
  state: ParsedLoadCommands,
): void => {
  if (kind === "LC_BUILD_VERSION") {
    const tools = parseBuildTools(block);
    if (numberField(fields, "ntools") !== tools.length)
      throw new TypeError("otool build-tool count does not match ntools");
    state.builds.push({
      platform: buildCodeName(
        BUILD_PLATFORM_NAMES,
        stringField(fields, "platform"),
      ),
      minimum_os: stringField(fields, "minos"),
      sdk: stringField(fields, "sdk"),
      tools,
    });
    return;
  }
  if (kind.startsWith("LC_VERSION_MIN_")) {
    const platform = kind.slice("LC_VERSION_MIN_".length) || null;
    state.builds.push({
      platform: legacySimulatorPlatform(platform, state.cpuType),
      minimum_os: stringField(fields, "version"),
      sdk: stringField(fields, "sdk"),
      tools: [],
    });
  }
};

// Apple dyld interprets legacy iOS/tvOS/watchOS minimum-version commands on
// Intel slices as simulator platforms. Newer commands encode this directly.
const legacySimulatorPlatform = (
  platform: string | null,
  cpuType: number | null,
): string | null => {
  if (![7, 0x01000007].includes(cpuType ?? -1)) return platform;
  return (
    (
      {
        IPHONEOS: "IOSSIMULATOR",
        TVOS: "TVOSSIMULATOR",
        WATCHOS: "WATCHOSSIMULATOR",
      } as const
    )[platform as "IPHONEOS" | "TVOS" | "WATCHOS"] ?? platform
  );
};

const collectDependency = (
  kind: string,
  fields: Readonly<Record<string, string | number | null>>,
  state: ParsedLoadCommands,
): void => {
  // LC_ID_DYLIB names this image itself; it stays a raw load command only.
  if (!DYLIB_COMMANDS.has(kind) || kind === "LC_ID_DYLIB") return;
  state.dependencies.push({
    path: stripOffsetSuffix(stringField(fields, "name")),
    kind,
    current_version: stringField(fields, "current version"),
    compatibility_version: stringField(fields, "compatibility version"),
  });
};

const collectSegment = (
  kind: string,
  block: string,
  fields: Readonly<Record<string, string | number | null>>,
  state: ParsedLoadCommands,
): void => {
  if (kind !== "LC_SEGMENT" && kind !== "LC_SEGMENT_64") return;
  const segment = parseSegment(block, fields);
  if (numberField(fields, "nsects") !== segment.sections.length)
    throw new TypeError(
      "otool segment section count does not match its sections",
    );
  state.segments.push(segment);
};

interface ParsedFields {
  readonly values: Record<string, string | number | null>;
  readonly rows: readonly (readonly [string, string] | undefined)[];
}

/**
 * A key otool prints more than once, such as each LC_BUILD_VERSION tool, is
 * labeled `key #n` in print order so no row overwrites another. Linker-option
 * strings keep otool's own `string #n` label at every count.
 */
const parseFields = (block: string): ParsedFields => {
  const rows: Array<readonly [string, string] | undefined> = [];
  for (const rawLine of block.split(/\r?\n/u).slice(1))
    if (rawLine.trim().length > 0) rows.push(parseField(rawLine));
  const occurrences = new Map<string, number>();
  for (const field of rows)
    if (field !== undefined)
      occurrences.set(field[0], (occurrences.get(field[0]) ?? 0) + 1);
  const fields: Record<string, string | number | null> = {};
  const ordinals = new Map<string, number>();
  for (const field of rows) {
    if (field === undefined) continue;
    const [key, value] = field;
    const ordinal = (ordinals.get(key) ?? 0) + 1;
    ordinals.set(key, ordinal);
    const label =
      (occurrences.get(key) ?? 0) > 1 ? `${key} #${String(ordinal)}` : key;
    fields[label] = TEXT_FIELDS.test(key) ? value : (numeric(value) ?? value);
  }
  return { values: fields, rows };
};

/** Names and linker options are text even when they look numeric. */
const TEXT_FIELDS = /^(?:segname|sectname|string #\d+)$/u;

/**
 * otool prints load-command strings as `<key> %s (offset %u)`: exactly one
 * separator space on each side of the recorded string, whose own leading and
 * trailing whitespace belongs to the Mach-O value.
 */
const OFFSET_STRING_FIELD = /^(name|path) (.* \(offset \d+\))$/u;

const parseField = (rawLine: string): readonly [string, string] | undefined => {
  const offsetString = OFFSET_STRING_FIELD.exec(rawLine.trimStart());
  if (offsetString?.[1] !== undefined && offsetString[2] !== undefined)
    return [offsetString[1], offsetString[2]];
  // otool prints each linker option as `string #n <option>`; keep the option
  // exactly, including surrounding spaces, under otool's ordinal label.
  const option = /^\s*(string #[1-9]\d*)(?: (.*))?$/u.exec(rawLine);
  if (option?.[1] !== undefined) return [option[1], option[2] ?? ""];
  const line = rawLine.trim();
  // These are the compound field labels used by otool. Keeping this list
  // explicit prevents a one-word field value such as `sectname version` from
  // being consumed as an invented `sectname version` key.
  const match =
    /^(time stamp|current version|compatibility version|\S+)(?:\s+(.+))?$/u.exec(
      line,
    );
  return match?.[1] === undefined
    ? undefined
    : [match[1], match[2]?.trim() ?? ""];
};

const requireUniqueField = (parsed: ParsedFields, key: string): void => {
  const matches = parsed.rows.filter((field) => field?.[0] === key);
  const field = matches[0];
  if (matches.length !== 1 || field === undefined)
    throw new TypeError(`otool field ${key} is missing or repeated`);
  // Only options and fixed-width Mach-O names may legitimately be empty.
  if (field[1] === "" && !EMPTY_VALUE_FIELDS.has(key))
    throw new TypeError(`otool field ${key} has no value`);
};

const parseSegment = (
  block: string,
  fields: Readonly<Record<string, string | number | null>>,
): ParsedSegment => ({
  name: machoName(fields, "segname"),
  vm_address: hexField(fields, "vmaddr"),
  vm_size: numberField(fields, "vmsize"),
  file_offset: numberField(fields, "fileoff"),
  file_size: numberField(fields, "filesize"),
  maximum_permissions: permissions(stringField(fields, "maxprot")),
  initial_permissions: permissions(stringField(fields, "initprot")),
  sections: parseSections(block),
});

const parseSections = (block: string): ParsedSection[] =>
  block
    .split(/(?=\n\s*Section\n)/u)
    .slice(1)
    .map((sectionBlock) => {
      const parsed = parseFields(`Section${sectionBlock}`);
      const fields = parsed.values;
      for (const key of [
        "sectname",
        "segname",
        "addr",
        "size",
        "offset",
        "align",
        "flags",
      ])
        requireUniqueField(parsed, key);
      return {
        segment: machoName(fields, "segname"),
        name: machoName(fields, "sectname"),
        address: hexField(fields, "addr"),
        size: numberField(fields, "size"),
        file_offset: numberField(fields, "offset"),
        alignment: sectionAlignment(stringField(fields, "align")),
        flags: (stringField(fields, "flags") ?? "")
          .split(/\s+/u)
          .filter((flag) => flag.length > 0),
      };
    });

const parseBuildTools = (
  block: string,
): Array<{ name: string; version: string }> => {
  const tools: Array<{ name: string; version: string }> = [];
  const lines = block.split(/\r?\n/u).map((line) => line.trim());
  for (let index = 0; index < lines.length - 1; index += 1) {
    const tool = /^tool\s+(.+)$/u.exec(lines[index] ?? "")?.[1];
    const version = /^version\s+(.+)$/u.exec(lines[index + 1] ?? "")?.[1];
    if (tool !== undefined && version !== undefined)
      tools.push({ name: BUILD_TOOL_NAMES.get(tool) ?? tool, version });
  }
  return tools;
};

const permissions = (raw: string | null) => {
  if (raw === null)
    return { read: null, write: null, execute: null, raw: null };
  const numericValue = numeric(raw);
  if (numericValue !== null)
    return {
      read: (numericValue & 1) !== 0,
      write: (numericValue & 2) !== 0,
      execute: (numericValue & 4) !== 0,
      raw,
    };
  if (/^[r-][w-][x-]$/u.test(raw))
    return {
      read: raw[0] === "r",
      write: raw[1] === "w",
      execute: raw[2] === "x",
      raw,
    };
  return { read: null, write: null, execute: null, raw };
};

/** A whole decimal or hexadecimal integer literal, with no surrounding text. */
const NUMERIC_PATTERN = /^(?:0x[a-fA-F0-9]+|\d+)$/u;

const numeric = (value: string): number | null => {
  if (!NUMERIC_PATTERN.test(value)) return null;
  const parsed = Number.parseInt(value, value.startsWith("0x") ? 16 : 10);
  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : null;
};

/**
 * A Mach-O segment or section name exactly as observed. Object files place
 * every section in one unnamed segment, so the empty name is a source value.
 */
const machoName = (
  fields: Readonly<Record<string, string | number | null>>,
  key: "segname" | "sectname",
): string => {
  const name = stringField(fields, key);
  if (name === null) throw new TypeError(`otool field ${key} is missing`);
  return name;
};

const stringField = (
  fields: Readonly<Record<string, string | number | null>>,
  name: string,
): string | null => {
  const value = fields[name];
  return typeof value === "string"
    ? value
    : value === undefined || value === null
      ? null
      : String(value);
};

const numberField = (
  fields: Readonly<Record<string, string | number | null>>,
  name: string,
): number | null => {
  const value = fields[name];
  return typeof value === "number"
    ? value
    : typeof value === "string"
      ? numeric(value)
      : null;
};

const hexField = (
  fields: Readonly<Record<string, string | number | null>>,
  name: string,
): string | null => {
  const value = stringField(fields, name);
  if (value === null || !NUMERIC_PATTERN.test(value)) return null;
  return `0x${BigInt(value).toString(16)}`;
};

const stripOffsetSuffix = (value: string | null): string =>
  value?.replace(/ \(offset \d+\)$/u, "") ?? "unknown";

const sectionAlignment = (raw: string | null): number | null => {
  if (raw === null) return null;
  const exponent = numeric(/^2\^(\d+)(?:\s+\(\d+\))?$/u.exec(raw)?.[1] ?? raw);
  return exponent === null || exponent > 52 ? null : 2 ** exponent;
};