feat(artifacts): trace Mach-O dylib resolution in bundles

Add trace_dylib_resolution (CLI trace-dylib-resolution) to the artifact
family. For the active Mach-O, or every executable in the active .app
(the main app, XPC services, extensions, login items, helpers), it
reports which file each dylib load reaches and how.

A pure TypeScript reader decodes FAT and Mach-O load commands:
LC_LOAD/WEAK/REEXPORT/LAZY/UPWARD_DYLIB, including the newer
dylib_use_command encoding with weak, re-export, upward and delayed-init
flags, plus LC_ID_DYLIB, LC_RPATH, LC_DYLD_ENVIRONMENT and code-signature
presence. Malformed tables are reported with the failing command instead
of being guessed.

Resolution follows dyld:
- @executable_path comes from each process root;
- @loader_path comes from the loading image, or from the owner of the
  LC_RPATH entry being expanded;
- @rpath searches the loader's rpaths first, then up the load chain;
- dependencies load dependents-first in load-command order, once per
  process, and a matching install name reuses an already loaded image;
- symlinks are followed inside the analyzed root, and escapes stop.

Every candidate path is reported with its outcome. Each edge resolves to
resolved, conditional (an outside-root candidate such as /usr/lib/swift
precedes), unresolved, or undetermined. Absolute and shared-cache system
paths are never checked against the host. Derived findings cover
unresolved required or weak loads, absent earlier @rpath candidates (with
library validation left unknown), and LC_DYLD_ENVIRONMENT.

verify:macos-bundle now also:
- checks every traced image against otool -l;
- asserts each resolution status on a clang-built fixture that adds a
  missing Overrides rpath, an absolute rpath, and a delay-init library;
- compares the predicted load order of two process roots with what dyld
  loads under DYLD_PRINT_LIBRARIES.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kaoru0822
2026-10-07 10:31:17 +00:00
co-authored by Claude Opus 5.5
parent 55249704c5
commit 11b7f918c2
35 changed files with 2820 additions and 29 deletions
+34
View File
@@ -8,6 +8,7 @@ import {
type ExecutionOptions,
} from "../application/AnalysisProvider.js";
import { inspectBundleKeyedArchive } from "./KeyedArchiveReader.js";
import { traceDylibResolution } from "./DylibResolutionReader.js";
import { basename, dirname } from "node:path";
import { inventoryArtifact } from "../application/ArtifactInventory.js";
import { extractArtifact } from "../application/ArtifactExtraction.js";
@@ -153,6 +154,8 @@ class ArtifactClient implements AnalysisClient {
if (operation === "inspect_asset_catalog") {
return await this.inspectAssetCatalog(parameters, options);
}
if (operation === "trace_dylib_resolution")
return await this.traceDylibResolution(parameters, options);
if (operation === "extract_artifact") {
const parsed = artifactExtractionExecutionSchema.parse(parameters);
const result = await extractArtifact(
@@ -234,6 +237,37 @@ class ArtifactClient implements AnalysisClient {
);
}
private async traceDylibResolution(
parameters: Readonly<Record<string, JsonValue>>,
options?: ExecutionOptions,
) {
if (this.target.kind !== "executable" || this.target.format !== "mach-o")
throw new ArtifactReaderFailure(
"unavailable",
"trace_dylib_resolution requires an active Mach-O or .app bundle target",
);
const bundle = this.target.sourcePath?.toLowerCase().endsWith(".app")
? this.target.sourcePath
: undefined;
const result = await traceDylibResolution({
rootPath: bundle ?? dirname(this.target.path),
targetPath: this.target.path,
targetSha256: this.target.sha256,
enumerateRoots: bundle !== undefined,
parameters,
...(options?.signal === undefined ? {} : { signal: options.signal }),
});
return ok(
createAnalysisExecution(result, IDENTITY, {
limitations: result.limitations,
locations: result.images.map(({ path }) => ({
kind: "artifact-path" as const,
path,
})),
}),
);
}
private async inspectArtifact(
parameters: Readonly<Record<string, JsonValue>>,
options?: ExecutionOptions,
+2 -1
View File
@@ -24,7 +24,8 @@ export const artifactCapabilities = (
mutatesArtifact: false,
launchesProcess:
operation !== "decode_interface_builder" &&
operation !== "inspect_keyed_archive",
operation !== "inspect_keyed_archive" &&
operation !== "trace_dylib_resolution",
mayShowUi: false,
mayAccessNetwork: false,
mayWriteFilesystem:
+235
View File
@@ -0,0 +1,235 @@
import { createHash } from "node:crypto";
import { constants } from "node:fs";
import { lstat, open, readlink, realpath } from "node:fs/promises";
import { join, relative, sep } from "node:path";
import {
dylibResolutionInputSchema,
dylibResolutionResultSchema,
traceDylibLoading,
type DylibResolutionResult,
type DylibTreeEntry,
type DylibTreeView,
type MachoImageFacts,
} from "../domain/dylibResolution.js";
import { ArtifactReaderFailure } from "./ArtifactReader.js";
import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js";
import { hasMachoMagic, readMachoImage } from "./MachoLoadCommandReader.js";
const HASH_CHUNK_BYTES = 1024 * 1024;
/** Lazily probed, symlink-preserving view of one analyzed directory. */
class FilesystemTreeView implements DylibTreeView {
readonly #entries = new Map<string, Promise<DylibTreeEntry | undefined>>();
readonly #images = new Map<string, Promise<MachoImageFacts>>();
constructor(
private readonly root: string,
private readonly signal?: AbortSignal,
) {}
entry(path: string): Promise<DylibTreeEntry | undefined> {
const cached = this.#entries.get(path);
if (cached !== undefined) return cached;
const pending = this.#readEntry(path);
this.#entries.set(path, pending);
return pending;
}
image(path: string): Promise<MachoImageFacts> {
const cached = this.#images.get(path);
if (cached !== undefined) return cached;
const pending = readImage(join(this.root, path), this.signal);
this.#images.set(path, pending);
return pending;
}
async #readEntry(path: string): Promise<DylibTreeEntry | undefined> {
cancelled(this.signal);
const absolute = join(this.root, path);
try {
const metadata = await lstat(absolute);
if (metadata.isSymbolicLink())
return { kind: "symlink", target: await readlink(absolute) };
if (metadata.isDirectory()) return { kind: "directory" };
return metadata.isFile() ? { kind: "file" } : undefined;
} catch (cause: unknown) {
if (missing(cause)) return undefined;
throw cause;
}
}
}
/** Resolve dyld load paths for the active Mach-O or every executable in its bundle. */
export const traceDylibResolution = async (options: {
readonly rootPath: string;
readonly targetPath: string;
readonly targetSha256: string;
readonly enumerateRoots: boolean;
readonly parameters: unknown;
readonly signal?: AbortSignal;
}): Promise<DylibResolutionResult> => {
const parsed = dylibResolutionInputSchema.safeParse(options.parameters);
if (!parsed.success)
throw new ArtifactReaderFailure(
"path",
"roots must be normalized paths relative to the analyzed root",
);
const root = await realpath(options.rootPath);
const target = relative(root, await realpath(options.targetPath))
.split(sep)
.join("/");
const view = new FilesystemTreeView(root, options.signal);
try {
const roots =
parsed.data.roots ??
(options.enumerateRoots
? await executableRoots(root, view, options.signal)
: [target]);
await requireMachoRoots(view, roots);
const trace = await traceDylibLoading(view, {
roots,
...(parsed.data.architecture === undefined
? {}
: { architecture: parsed.data.architecture }),
...(options.signal === undefined ? {} : { signal: options.signal }),
});
const digests = new Map<string, string>();
for (const { path } of trace.images)
digests.set(path, await fileSha256(join(root, path), options.signal));
const targetDigest =
digests.get(target) ??
(await fileSha256(join(root, target), options.signal));
if (targetDigest !== options.targetSha256)
throw new ArtifactReaderFailure(
"integrity",
`Active target digest changed: expected ${options.targetSha256}, observed ${targetDigest}`,
);
return dylibResolutionResultSchema.parse({
...trace,
root_path: options.rootPath,
target_sha256: options.targetSha256,
images: trace.images.map((image) => ({
...image,
sha256: digests.get(image.path),
})),
});
} catch (cause: unknown) {
if (options.signal?.aborted === true)
throw new ArtifactReaderFailure(
"cancelled",
"Dylib resolution was cancelled",
{ cause },
);
throw cause;
}
};
/** Every Mach-O in the bundle with an executable slice is its own process root. */
const executableRoots = async (
root: string,
view: FilesystemTreeView,
signal?: AbortSignal,
): Promise<string[]> => {
const roots: string[] = [];
for await (const entry of new DirectoryArtifactReader(root).entries(signal)) {
if (
entry.kind !== "file" ||
!(await startsWithMachoMagic(entry.adapterKey))
)
continue;
const facts = await view.image(entry.path);
if (
facts.status === "parsed" &&
facts.slices.some(({ file_type: type }) => type === "execute")
)
roots.push(entry.path);
}
return roots.sort((left, right) =>
left < right ? -1 : left > right ? 1 : 0,
);
};
const requireMachoRoots = async (
view: FilesystemTreeView,
roots: readonly string[],
): Promise<void> => {
for (const path of roots) {
const entry = await view.entry(path);
if (entry?.kind !== "file")
throw new ArtifactReaderFailure(
"path",
`Root ${path} is not a regular file in the analyzed root`,
);
if ((await view.image(path)).status === "not-mach-o")
throw new ArtifactReaderFailure(
"format",
`Root ${path} is not a Mach-O image`,
);
}
};
const startsWithMachoMagic = async (path: string): Promise<boolean> => {
const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
try {
const buffer = new Uint8Array(4);
const { bytesRead } = await handle.read(buffer, 0, 4, 0);
return hasMachoMagic(buffer.subarray(0, bytesRead));
} finally {
await handle.close();
}
};
const readImage = async (
path: string,
signal?: AbortSignal,
): Promise<MachoImageFacts> => {
cancelled(signal);
const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
try {
const { size } = await handle.stat();
return await readMachoImage(async (offset, length) => {
cancelled(signal);
const buffer = new Uint8Array(
Math.max(0, Math.min(length, size - offset)),
);
const { bytesRead } = await handle.read(buffer, 0, buffer.length, offset);
return buffer.subarray(0, bytesRead);
}, size);
} finally {
await handle.close();
}
};
const fileSha256 = async (
path: string,
signal?: AbortSignal,
): Promise<string> => {
const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
try {
const hash = createHash("sha256");
const buffer = new Uint8Array(HASH_CHUNK_BYTES);
for (;;) {
cancelled(signal);
const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
if (bytesRead === 0) break;
hash.update(buffer.subarray(0, bytesRead));
}
return hash.digest("hex");
} finally {
await handle.close();
}
};
const cancelled = (signal?: AbortSignal): void => {
if (signal?.aborted === true)
throw new ArtifactReaderFailure(
"cancelled",
"Dylib resolution was cancelled",
);
};
const missing = (cause: unknown): boolean =>
cause instanceof Error &&
"code" in cause &&
(cause.code === "ENOENT" || cause.code === "ENOTDIR");
+148
View File
@@ -0,0 +1,148 @@
/** Little-endian Mach-O images and FAT containers built field by field for tests. */
export const LC = {
LOAD_DYLIB: 0xc,
ID_DYLIB: 0xd,
LOAD_WEAK_DYLIB: 0x80000018,
REEXPORT_DYLIB: 0x8000001f,
LAZY_LOAD_DYLIB: 0x20,
LOAD_UPWARD_DYLIB: 0x80000023,
RPATH: 0x8000001c,
DYLD_ENVIRONMENT: 0x27,
CODE_SIGNATURE: 0x1d,
} as const;
export const CPU = {
arm64: { type: 0x0100000c, subtype: 0 },
arm64e: { type: 0x0100000c, subtype: 0x80000002 },
x86_64: { type: 0x01000007, subtype: 3 },
} as const;
export const FILE_TYPE = { execute: 2, dylib: 6, bundle: 8 } as const;
const encoder = new TextEncoder();
/** One load command with a NUL-terminated string at `nameOffset`, padded to 8 bytes. */
const commandWithString = (
command: number,
fields: readonly number[],
text: string,
): Uint8Array => {
const nameOffset = 8 + fields.length * 4 + 4;
const name = encoder.encode(text);
const size = Math.ceil((nameOffset + name.length + 1) / 8) * 8;
const bytes = new Uint8Array(size);
const view = new DataView(bytes.buffer);
view.setUint32(0, command, true);
view.setUint32(4, size, true);
view.setUint32(8, nameOffset, true);
fields.forEach((value, index) => view.setUint32(12 + index * 4, value, true));
bytes.set(name, nameOffset);
return bytes;
};
/** Classic `dylib_command`: timestamp, current and compatibility versions. */
export const dylibCommand = (
command: number,
name: string,
versions: { readonly current?: number; readonly compatibility?: number } = {},
): Uint8Array =>
commandWithString(
command,
[2, versions.current ?? 0x10000, versions.compatibility ?? 0x10000],
name,
);
/** `dylib_use_command`: marker, versions and `DYLIB_USE_*` flags. */
export const dylibUseCommand = (
command: number,
name: string,
flags: number,
): Uint8Array =>
commandWithString(command, [0x1a741800, 0x10000, 0x10000, flags], name);
export const rpathCommand = (path: string): Uint8Array =>
commandWithString(LC.RPATH, [], path);
export const dyldEnvironmentCommand = (value: string): Uint8Array =>
commandWithString(LC.DYLD_ENVIRONMENT, [], value);
export const codeSignatureCommand = (): Uint8Array => {
const bytes = new Uint8Array(16);
const view = new DataView(bytes.buffer);
view.setUint32(0, LC.CODE_SIGNATURE, true);
view.setUint32(4, 16, true);
return bytes;
};
/** A 64-bit (or 32-bit) little-endian Mach-O image made of the given commands. */
export const machoImage = (options: {
readonly cpu?: { readonly type: number; readonly subtype: number };
readonly fileType?: number;
readonly commands?: readonly Uint8Array[];
readonly wide?: boolean;
}): Uint8Array => {
const wide = options.wide ?? true;
const commands = options.commands ?? [];
const headerSize = wide ? 32 : 28;
const commandBytes = commands.reduce((total, item) => total + item.length, 0);
const bytes = new Uint8Array(headerSize + commandBytes + 16);
const view = new DataView(bytes.buffer);
const cpu = options.cpu ?? CPU.arm64;
view.setUint32(0, wide ? 0xfeedfacf : 0xfeedface, true);
view.setUint32(4, cpu.type, true);
view.setUint32(8, cpu.subtype, true);
view.setUint32(12, options.fileType ?? FILE_TYPE.execute, true);
view.setUint32(16, commands.length, true);
view.setUint32(20, commandBytes, true);
let offset = headerSize;
for (const command of commands) {
bytes.set(command, offset);
offset += command.length;
}
return bytes;
};
/** A big-endian FAT container whose slices start on 4 KiB boundaries. */
export const fatImage = (
slices: readonly {
readonly cpu: { readonly type: number; readonly subtype: number };
readonly bytes: Uint8Array;
}[],
wide = false,
): Uint8Array => {
const entrySize = wide ? 32 : 20;
const offsets: number[] = [];
let end = 4096;
for (const slice of slices) {
offsets.push(end);
end += Math.ceil(slice.bytes.length / 4096) * 4096;
}
const bytes = new Uint8Array(end);
const view = new DataView(bytes.buffer);
view.setUint32(0, wide ? 0xcafebabf : 0xcafebabe, false);
view.setUint32(4, slices.length, false);
slices.forEach((slice, index) => {
const base = 8 + index * entrySize;
const offset = offsets[index] ?? 0;
view.setUint32(base, slice.cpu.type, false);
view.setUint32(base + 4, slice.cpu.subtype, false);
if (wide) {
view.setBigUint64(base + 8, BigInt(offset), false);
view.setBigUint64(base + 16, BigInt(slice.bytes.length), false);
view.setUint32(base + 24, 12, false);
} else {
view.setUint32(base + 8, offset, false);
view.setUint32(base + 12, slice.bytes.length, false);
view.setUint32(base + 16, 12, false);
}
bytes.set(slice.bytes, offset);
});
return bytes;
};
/** In-memory `ReadAt` over one buffer. */
export const readerOf =
(bytes: Uint8Array) =>
(offset: number, length: number): Promise<Uint8Array> =>
Promise.resolve(bytes.subarray(offset, offset + length));
@@ -0,0 +1,255 @@
import { describe, expect, it } from "vitest";
import {
CPU,
FILE_TYPE,
LC,
codeSignatureCommand,
dyldEnvironmentCommand,
dylibCommand,
dylibUseCommand,
fatImage,
machoImage,
readerOf,
rpathCommand,
} from "./MachoImage.fixture.js";
import {
MAX_LOAD_COMMAND_BYTES,
hasMachoMagic,
readMachoImage,
} from "./MachoLoadCommandReader.js";
const read = (bytes: Uint8Array) =>
readMachoImage(readerOf(bytes), bytes.length);
describe("Mach-O load command reader", () => {
it("decodes dylib loading commands of a thin image", async () => {
const image = machoImage({
fileType: FILE_TYPE.dylib,
commands: [
dylibCommand(LC.ID_DYLIB, "@rpath/Core.framework/Core"),
dylibCommand(LC.LOAD_DYLIB, "/usr/lib/libSystem.B.dylib", {
current: 0x050f0400,
compatibility: 0x10000,
}),
dylibCommand(LC.LOAD_WEAK_DYLIB, "@rpath/libweak.dylib"),
dylibCommand(LC.REEXPORT_DYLIB, "@loader_path/libre.dylib"),
dylibCommand(LC.LOAD_UPWARD_DYLIB, "@rpath/libup.dylib"),
dylibCommand(LC.LAZY_LOAD_DYLIB, "@rpath/liblazy.dylib"),
rpathCommand("@loader_path/Frameworks"),
rpathCommand("/usr/lib/swift"),
dyldEnvironmentCommand("DYLD_FRAMEWORK_PATH=@executable_path"),
codeSignatureCommand(),
],
});
const facts = await read(image);
expect(facts.status).toBe("parsed");
if (facts.status !== "parsed") return;
expect(facts.slices).toHaveLength(1);
const [slice] = facts.slices;
expect(slice).toMatchObject({
architecture: "arm64",
file_type: "dylib",
install_name: "@rpath/Core.framework/Core",
rpaths: ["@loader_path/Frameworks", "/usr/lib/swift"],
dyld_environment: ["DYLD_FRAMEWORK_PATH=@executable_path"],
code_signature_present: true,
});
expect(
slice?.dependencies.map(
({ command, install_name: name, weak, reexport, upward }) => [
command,
name,
weak,
reexport,
upward,
],
),
).toEqual([
["LC_LOAD_DYLIB", "/usr/lib/libSystem.B.dylib", false, false, false],
["LC_LOAD_WEAK_DYLIB", "@rpath/libweak.dylib", true, false, false],
["LC_REEXPORT_DYLIB", "@loader_path/libre.dylib", false, true, false],
["LC_LOAD_UPWARD_DYLIB", "@rpath/libup.dylib", false, false, true],
["LC_LAZY_LOAD_DYLIB", "@rpath/liblazy.dylib", false, false, false],
]);
expect(slice?.dependencies[0]).toMatchObject({
encoding: "dylib_command",
current_version: "1295.4.0",
compatibility_version: "1.0.0",
});
});
it("decodes dylib_use_command flags", async () => {
const facts = await read(
machoImage({
commands: [
dylibUseCommand(LC.LOAD_DYLIB, "@rpath/libdelay.dylib", 0x8),
dylibUseCommand(LC.LOAD_DYLIB, "@rpath/libweakup.dylib", 0x1 | 0x4),
dylibUseCommand(LC.LOAD_DYLIB, "@rpath/libre.dylib", 0x2),
],
}),
);
if (facts.status !== "parsed") throw new Error(facts.status);
expect(
facts.slices[0]?.dependencies.map(
({ encoding, weak, upward, reexport, delayed_init: delayed }) => ({
encoding,
weak,
upward,
reexport,
delayed,
}),
),
).toEqual([
{
encoding: "dylib_use_command",
weak: false,
upward: false,
reexport: false,
delayed: true,
},
{
encoding: "dylib_use_command",
weak: true,
upward: true,
reexport: false,
delayed: false,
},
{
encoding: "dylib_use_command",
weak: false,
upward: false,
reexport: true,
delayed: false,
},
]);
});
it("reads every slice of FAT and FAT_64 containers", async () => {
for (const wide of [false, true]) {
const facts = await read(
fatImage(
[
{
cpu: CPU.arm64e,
bytes: machoImage({
cpu: CPU.arm64e,
commands: [rpathCommand("@executable_path/a")],
}),
},
{
cpu: CPU.x86_64,
bytes: machoImage({
cpu: CPU.x86_64,
commands: [rpathCommand("@executable_path/b")],
}),
},
],
wide,
),
);
if (facts.status !== "parsed") throw new Error(facts.status);
expect(
facts.slices.map(({ architecture, rpaths }) => [architecture, rpaths]),
).toEqual([
["arm64e", ["@executable_path/a"]],
["x86_64", ["@executable_path/b"]],
]);
}
});
});
describe("Mach-O load command reader inputs", () => {
it("names 32-bit and non-Mach-O inputs without guessing", async () => {
const i386 = await read(
machoImage({ cpu: { type: 7, subtype: 3 }, wide: false }),
);
expect(i386.status === "parsed" && i386.slices[0]?.architecture).toBe(
"i386",
);
// A Java class file shares the FAT magic; its version is not a slice count.
const javaClass = Uint8Array.from([0xca, 0xfe, 0xba, 0xbe, 0, 0, 0, 0x34]);
expect(hasMachoMagic(javaClass)).toBe(true);
expect(await read(javaClass)).toEqual({ status: "not-mach-o" });
expect(await read(new TextEncoder().encode("#!/bin/sh\n"))).toEqual({
status: "not-mach-o",
});
expect(await read(Uint8Array.from([0xcf, 0xfa]))).toEqual({
status: "not-mach-o",
});
});
});
describe("Mach-O load command reader failures", () => {
const withCommandSize = (size: number): Uint8Array => {
const image = machoImage({ commands: [rpathCommand("@loader_path")] });
new DataView(image.buffer).setUint32(32 + 4, size, true);
return image;
};
it("reports malformed command tables with the failing command", async () => {
expect(await read(withCommandSize(0))).toMatchObject({
status: "malformed",
reason: expect.stringContaining("load command 0"),
});
expect(await read(withCommandSize(4096))).toMatchObject({
status: "malformed",
reason: expect.stringContaining("invalid cmdsize"),
});
const extraCommand = machoImage({ commands: [rpathCommand("x")] });
new DataView(extraCommand.buffer).setUint32(16, 2, true);
expect(await read(extraCommand)).toMatchObject({
status: "malformed",
reason: "load command 1 starts beyond sizeofcmds",
});
});
it("rejects strings that are unterminated, misplaced or not UTF-8", async () => {
const unterminated = rpathCommand("abcd");
unterminated.fill(0x41, 12);
expect(await read(machoImage({ commands: [unterminated] }))).toMatchObject({
status: "malformed",
reason: expect.stringContaining("unterminated"),
});
const misplaced = rpathCommand("abcd");
new DataView(misplaced.buffer).setUint32(8, 4, true);
expect(await read(machoImage({ commands: [misplaced] }))).toMatchObject({
status: "malformed",
reason: expect.stringContaining("string offset 4"),
});
const invalid = rpathCommand("ab");
invalid[12] = 0xff;
expect(await read(machoImage({ commands: [invalid] }))).toMatchObject({
status: "malformed",
reason: expect.stringContaining("not UTF-8"),
});
});
it("refuses truncated, oversized, big-endian and out-of-range images", async () => {
const image = machoImage({ commands: [rpathCommand("@loader_path")] });
expect(await read(image.subarray(0, 20))).toMatchObject({
status: "malformed",
reason: "Mach-O header is truncated",
});
const oversized = machoImage({});
new DataView(oversized.buffer).setUint32(
20,
MAX_LOAD_COMMAND_BYTES + 8,
true,
);
expect(await read(oversized)).toMatchObject({ status: "unsupported" });
const beyond = machoImage({ commands: [rpathCommand("x")] });
new DataView(beyond.buffer).setUint32(20, beyond.length, true);
expect(await read(beyond)).toMatchObject({
status: "malformed",
reason: "load commands extend beyond the Mach-O slice",
});
const bigEndian = Uint8Array.from([0xfe, 0xed, 0xfa, 0xcf, 0, 0, 0, 0]);
expect(await read(bigEndian)).toMatchObject({ status: "unsupported" });
const fat = fatImage([{ cpu: CPU.arm64, bytes: machoImage({}) }]);
expect(await read(fat.subarray(0, 4100))).toMatchObject({
status: "malformed",
reason: "FAT architecture 0 extends beyond the file",
});
});
});
+376
View File
@@ -0,0 +1,376 @@
import type {
MachoDependency,
MachoImageFacts,
MachoSlice,
} from "../domain/dylibResolution.js";
/** Read `length` bytes at `offset`; shorter results mean end of file. */
export type ReadAt = (offset: number, length: number) => Promise<Uint8Array>;
/** Load commands larger than this are refused instead of buffered. */
export const MAX_LOAD_COMMAND_BYTES = 16 * 1024 * 1024;
/** Real universal binaries carry a handful of slices; Java class files share the FAT magic. */
const MAX_FAT_ARCHITECTURES = 20;
const MH_MAGIC = 0xfeedface;
const MH_MAGIC_64 = 0xfeedfacf;
const MH_CIGAM = 0xcefaedfe;
const MH_CIGAM_64 = 0xcffaedfe;
const FAT_MAGIC = 0xcafebabe;
const FAT_MAGIC_64 = 0xcafebabf;
const LC_ID_DYLIB = 0xd;
const LC_LOAD_DYLIB = 0xc;
const LC_LOAD_WEAK_DYLIB = 0x80000018;
const LC_REEXPORT_DYLIB = 0x8000001f;
const LC_LAZY_LOAD_DYLIB = 0x20;
const LC_LOAD_UPWARD_DYLIB = 0x80000023;
const LC_RPATH = 0x8000001c;
const LC_DYLD_ENVIRONMENT = 0x27;
const LC_CODE_SIGNATURE = 0x1d;
/** `mach-o/loader.h` `dylib_use_command`: `nameoff == 28` and this marker. */
const DYLIB_USE_MARKER = 0x1a741800;
const DYLIB_USE_WEAK_LINK = 0x1;
const DYLIB_USE_REEXPORT = 0x2;
const DYLIB_USE_UPWARD = 0x4;
const DYLIB_USE_DELAYED_INIT = 0x8;
const DEPENDENCY_COMMANDS: ReadonlyMap<number, MachoDependency["command"]> =
new Map([
[LC_LOAD_DYLIB, "LC_LOAD_DYLIB"],
[LC_LOAD_WEAK_DYLIB, "LC_LOAD_WEAK_DYLIB"],
[LC_REEXPORT_DYLIB, "LC_REEXPORT_DYLIB"],
[LC_LAZY_LOAD_DYLIB, "LC_LAZY_LOAD_DYLIB"],
[LC_LOAD_UPWARD_DYLIB, "LC_LOAD_UPWARD_DYLIB"],
]);
/** Malformed or unsupported structure found while decoding one image. */
class MachoFormatIssue extends Error {
constructor(
readonly status: "malformed" | "unsupported",
message: string,
) {
super(message);
}
}
/** Report whether the first bytes carry a Mach-O or FAT magic number. */
export const hasMachoMagic = (head: Uint8Array): boolean => {
if (head.byteLength < 4) return false;
const magic = new DataView(
head.buffer,
head.byteOffset,
head.byteLength,
).getUint32(0, false);
return [
MH_MAGIC,
MH_MAGIC_64,
MH_CIGAM,
MH_CIGAM_64,
FAT_MAGIC,
FAT_MAGIC_64,
].includes(magic);
};
/** Decode every slice's dylib-loading load commands without reading code. */
export const readMachoImage = async (
readAt: ReadAt,
size: number,
): Promise<MachoImageFacts> => {
try {
const head = await readAt(0, Math.min(size, 8));
if (head.byteLength < 8) return { status: "not-mach-o" };
const view = viewOf(head);
const magic = view.getUint32(0, false);
if (magic === FAT_MAGIC || magic === FAT_MAGIC_64) {
const count = view.getUint32(4, false);
if (count === 0 || count >= MAX_FAT_ARCHITECTURES)
return { status: "not-mach-o" };
return {
status: "parsed",
slices: await readFatSlices(
readAt,
size,
magic === FAT_MAGIC_64,
count,
),
};
}
if (magic === MH_CIGAM || magic === MH_CIGAM_64)
return { status: "parsed", slices: [await readSlice(readAt, 0, size)] };
if (magic === MH_MAGIC || magic === MH_MAGIC_64)
throw new MachoFormatIssue(
"unsupported",
"big-endian Mach-O images are not supported",
);
return { status: "not-mach-o" };
} catch (cause: unknown) {
if (cause instanceof MachoFormatIssue)
return { status: cause.status, reason: cause.message };
throw cause;
}
};
const readFatSlices = async (
readAt: ReadAt,
size: number,
wide: boolean,
count: number,
): Promise<MachoSlice[]> => {
const entrySize = wide ? 32 : 20;
const table = await readExact(readAt, 8, count * entrySize, "FAT table");
const view = viewOf(table);
const slices: MachoSlice[] = [];
for (let index = 0; index < count; index++) {
const base = index * entrySize;
const offset = wide
? safeNumber(view.getBigUint64(base + 8, false))
: view.getUint32(base + 8, false);
const length = wide
? safeNumber(view.getBigUint64(base + 16, false))
: view.getUint32(base + 12, false);
if (offset + length > size)
throw new MachoFormatIssue(
"malformed",
`FAT architecture ${index} extends beyond the file`,
);
slices.push(await readSlice(readAt, offset, length));
}
return slices;
};
const readSlice = async (
readAt: ReadAt,
base: number,
length: number,
): Promise<MachoSlice> => {
const header = viewOf(await readExact(readAt, base, 28, "Mach-O header"));
const magic = header.getUint32(0, true);
if (magic === MH_MAGIC_64 || magic === MH_MAGIC) {
const wide = magic === MH_MAGIC_64;
const headerSize = wide ? 32 : 28;
const commandCount = header.getUint32(16, true);
const commandBytes = header.getUint32(20, true);
if (commandBytes > MAX_LOAD_COMMAND_BYTES)
throw new MachoFormatIssue(
"unsupported",
`load commands occupy ${commandBytes} bytes, above the ${MAX_LOAD_COMMAND_BYTES}-byte limit`,
);
if (headerSize + commandBytes > length)
throw new MachoFormatIssue(
"malformed",
"load commands extend beyond the Mach-O slice",
);
const commands = await readExact(
readAt,
base + headerSize,
commandBytes,
"load commands",
);
return decodeCommands(commands, {
cpuType: header.getUint32(4, true),
cpuSubtype: header.getUint32(8, true),
fileType: header.getUint32(12, true),
commandCount,
});
}
throw new MachoFormatIssue(
magic === swap(MH_MAGIC) || magic === swap(MH_MAGIC_64)
? "unsupported"
: "malformed",
magic === swap(MH_MAGIC) || magic === swap(MH_MAGIC_64)
? "big-endian Mach-O slices are not supported"
: `slice at offset ${base} has no Mach-O header`,
);
};
const decodeCommands = (
bytes: Uint8Array,
header: {
readonly cpuType: number;
readonly cpuSubtype: number;
readonly fileType: number;
readonly commandCount: number;
},
): MachoSlice => {
const view = viewOf(bytes);
const slice: MachoSlice = {
architecture: architectureName(header.cpuType, header.cpuSubtype),
file_type: fileTypeName(header.fileType),
install_name: null,
dependencies: [],
rpaths: [],
dyld_environment: [],
code_signature_present: false,
};
let offset = 0;
for (let index = 0; index < header.commandCount; index++) {
if (offset + 8 > bytes.byteLength)
throw new MachoFormatIssue(
"malformed",
`load command ${index} starts beyond sizeofcmds`,
);
const command = view.getUint32(offset, true);
const size = view.getUint32(offset + 4, true);
if (size < 8 || size % 4 !== 0 || offset + size > bytes.byteLength)
throw new MachoFormatIssue(
"malformed",
`load command ${index} at offset ${offset} has invalid cmdsize ${size}`,
);
const body = bytes.subarray(offset, offset + size);
decodeCommand(command, body, index, slice);
offset += size;
}
return slice;
};
const decodeCommand = (
command: number,
body: Uint8Array,
index: number,
slice: MachoSlice,
): void => {
if (command === LC_ID_DYLIB) {
slice.install_name = commandString(body, 24, index);
return;
}
if (command === LC_RPATH) {
slice.rpaths.push(commandString(body, 12, index));
return;
}
if (command === LC_DYLD_ENVIRONMENT) {
slice.dyld_environment.push(commandString(body, 12, index));
return;
}
if (command === LC_CODE_SIGNATURE) {
slice.code_signature_present = true;
return;
}
const name = DEPENDENCY_COMMANDS.get(command);
if (name !== undefined)
slice.dependencies.push(decodeDependency(name, body, index));
};
const decodeDependency = (
command: MachoDependency["command"],
body: Uint8Array,
index: number,
): MachoDependency => {
if (body.byteLength < 24)
throw new MachoFormatIssue(
"malformed",
`load command ${index} is too short for a dylib command`,
);
const view = viewOf(body);
const nameOffset = view.getUint32(8, true);
const usesFlags =
nameOffset === 28 &&
body.byteLength >= 28 &&
view.getUint32(12, true) === DYLIB_USE_MARKER;
const flags = usesFlags ? view.getUint32(24, true) : 0;
return {
command,
encoding: usesFlags ? "dylib_use_command" : "dylib_command",
install_name: commandString(body, usesFlags ? 28 : 24, index),
weak:
command === "LC_LOAD_WEAK_DYLIB" || (flags & DYLIB_USE_WEAK_LINK) !== 0,
upward:
command === "LC_LOAD_UPWARD_DYLIB" || (flags & DYLIB_USE_UPWARD) !== 0,
reexport:
command === "LC_REEXPORT_DYLIB" || (flags & DYLIB_USE_REEXPORT) !== 0,
delayed_init: (flags & DYLIB_USE_DELAYED_INIT) !== 0,
current_version: version(view.getUint32(16, true)),
compatibility_version: version(view.getUint32(20, true)),
};
};
/** NUL-terminated UTF-8 string at a `lc_str` offset inside one command. */
const commandString = (
body: Uint8Array,
minimumOffset: number,
index: number,
): string => {
const offset = viewOf(body).getUint32(8, true);
if (offset < minimumOffset || offset >= body.byteLength)
throw new MachoFormatIssue(
"malformed",
`load command ${index} has string offset ${offset} outside the command`,
);
const end = body.indexOf(0, offset);
if (end < 0)
throw new MachoFormatIssue(
"malformed",
`load command ${index} has an unterminated string`,
);
try {
return new TextDecoder("utf-8", { fatal: true }).decode(
body.subarray(offset, end),
);
} catch {
throw new MachoFormatIssue(
"malformed",
`load command ${index} has a string that is not UTF-8`,
);
}
};
const readExact = async (
readAt: ReadAt,
offset: number,
length: number,
label: string,
): Promise<Uint8Array> => {
const bytes = await readAt(offset, length);
if (bytes.byteLength < length)
throw new MachoFormatIssue("malformed", `${label} is truncated`);
return bytes;
};
const CPU_ARCH_ABI64 = 0x01000000;
const CPU_ARCH_ABI64_32 = 0x02000000;
const CPU_TYPE_X86 = 7;
const CPU_TYPE_ARM = 12;
const CPU_SUBTYPE_MASK = 0xff000000;
const CPU_SUBTYPE_ARM64E = 2;
const CPU_SUBTYPE_X86_64_H = 8;
const architectureName = (cpuType: number, cpuSubtype: number): string => {
const subtype = cpuSubtype & ~CPU_SUBTYPE_MASK;
if (cpuType === (CPU_TYPE_ARM | CPU_ARCH_ABI64))
return subtype === CPU_SUBTYPE_ARM64E ? "arm64e" : "arm64";
if (cpuType === (CPU_TYPE_ARM | CPU_ARCH_ABI64_32)) return "arm64_32";
if (cpuType === (CPU_TYPE_X86 | CPU_ARCH_ABI64))
return subtype === CPU_SUBTYPE_X86_64_H ? "x86_64h" : "x86_64";
if (cpuType === CPU_TYPE_X86) return "i386";
if (cpuType === CPU_TYPE_ARM) return "arm";
return `cpu-${cpuType.toString(16)}`;
};
const fileTypeName = (fileType: number): MachoSlice["file_type"] =>
fileType === 2
? "execute"
: fileType === 6
? "dylib"
: fileType === 8
? "bundle"
: "other";
const version = (value: number): string =>
`${value >>> 16}.${(value >>> 8) & 0xff}.${value & 0xff}`;
const swap = (value: number): number =>
(((value & 0xff) << 24) |
((value & 0xff00) << 8) |
((value >>> 8) & 0xff00) |
(value >>> 24)) >>>
0;
const safeNumber = (value: bigint): number => {
if (value > BigInt(Number.MAX_SAFE_INTEGER))
throw new MachoFormatIssue("malformed", "FAT offset exceeds safe range");
return Number(value);
};
const viewOf = (bytes: Uint8Array): DataView =>
new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);