fix(artifacts): follow dyld slice grading and report unparsed images

Address review findings in trace_dylib_resolution:
- Choose child slices by dyld's graded architectures, so an x86_64h
  process loads a generic x86_64 slice instead of reporting
  architecture-missing.
- Read FAT containers with the byte-swapped FAT_CIGAM and FAT_CIGAM_64
  magics, which target opening already accepts.
- Report string-bearing load commands too short to hold their string
  offset as malformed instead of failing with a RangeError.
- Keep recognized but unsupported images as an `unsupported` candidate
  outcome. It is undeterminable like an outside-root path, not
  malformed.
- List Mach-O files that do not parse during root enumeration as
  unparsed images, so coverage is partial rather than silently complete.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kaoru0822
2026-10-07 11:07:31 +00:00
co-authored by Claude Opus 5.5
parent 63800ff5a2
commit a0ec3e2016
13 changed files with 245 additions and 63 deletions
+24 -11
View File
@@ -81,14 +81,16 @@ export const traceDylibResolution = async (options: {
.join("/");
const view = new FilesystemTreeView(root, options.signal);
try {
const roots =
parsed.data.roots ??
(options.enumerateRoots
? await executableRoots(root, view, options.signal)
: [target]);
const { roots, unclassified } =
parsed.data.roots !== undefined
? { roots: parsed.data.roots, unclassified: [] }
: options.enumerateRoots
? await executableRoots(root, view, options.signal)
: { roots: [target], unclassified: [] };
await requireMachoRoots(view, roots);
const trace = await traceDylibLoading(view, {
roots,
unclassified,
...(parsed.data.architecture === undefined
? {}
: { architecture: parsed.data.architecture }),
@@ -125,13 +127,18 @@ export const traceDylibResolution = async (options: {
}
};
/** Every Mach-O in the bundle with an executable slice is its own process root. */
/**
* Every Mach-O in the bundle with an executable slice is its own process root.
* Mach-O files that do not parse are returned separately: whether they are
* executables is unknown, so they make coverage partial instead of vanishing.
*/
const executableRoots = async (
root: string,
view: FilesystemTreeView,
signal?: AbortSignal,
): Promise<string[]> => {
): Promise<{ readonly roots: string[]; readonly unclassified: string[] }> => {
const roots: string[] = [];
const unclassified: string[] = [];
for await (const entry of new DirectoryArtifactReader(root).entries(signal)) {
if (
entry.kind !== "file" ||
@@ -139,17 +146,23 @@ const executableRoots = async (
)
continue;
const facts = await view.image(entry.path);
if (
if (facts.status === "malformed" || facts.status === "unsupported")
unclassified.push(entry.path);
else 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,
);
return {
roots: roots.sort(compare),
unclassified: unclassified.sort(compare),
};
};
const compare = (left: string, right: string): number =>
left < right ? -1 : left > right ? 1 : 0;
const requireMachoRoots = async (
view: FilesystemTreeView,
roots: readonly string[],
+15 -11
View File
@@ -103,13 +103,17 @@ export const machoImage = (options: {
return bytes;
};
/** A big-endian FAT container whose slices start on 4 KiB boundaries. */
/**
* A FAT container whose slices start on 4 KiB boundaries. Headers are
* big-endian unless `littleEndian` selects the swapped FAT_CIGAM magics.
*/
export const fatImage = (
slices: readonly {
readonly cpu: { readonly type: number; readonly subtype: number };
readonly bytes: Uint8Array;
}[],
wide = false,
littleEndian = false,
): Uint8Array => {
const entrySize = wide ? 32 : 20;
const offsets: number[] = [];
@@ -120,21 +124,21 @@ export const fatImage = (
}
const bytes = new Uint8Array(end);
const view = new DataView(bytes.buffer);
view.setUint32(0, wide ? 0xcafebabf : 0xcafebabe, false);
view.setUint32(4, slices.length, false);
view.setUint32(0, wide ? 0xcafebabf : 0xcafebabe, littleEndian);
view.setUint32(4, slices.length, littleEndian);
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);
view.setUint32(base, slice.cpu.type, littleEndian);
view.setUint32(base + 4, slice.cpu.subtype, littleEndian);
if (wide) {
view.setBigUint64(base + 8, BigInt(offset), false);
view.setBigUint64(base + 16, BigInt(slice.bytes.length), false);
view.setUint32(base + 24, 12, false);
view.setBigUint64(base + 8, BigInt(offset), littleEndian);
view.setBigUint64(base + 16, BigInt(slice.bytes.length), littleEndian);
view.setUint32(base + 24, 12, littleEndian);
} else {
view.setUint32(base + 8, offset, false);
view.setUint32(base + 12, slice.bytes.length, false);
view.setUint32(base + 16, 12, false);
view.setUint32(base + 8, offset, littleEndian);
view.setUint32(base + 12, slice.bytes.length, littleEndian);
view.setUint32(base + 16, 12, littleEndian);
}
bytes.set(slice.bytes, offset);
});
+19 -2
View File
@@ -125,8 +125,13 @@ describe("Mach-O load command reader", () => {
]);
});
it("reads every slice of FAT and FAT_64 containers", async () => {
for (const wide of [false, true]) {
it("reads every slice of FAT and FAT_64 containers in either byte order", async () => {
for (const [wide, littleEndian] of [
[false, false],
[true, false],
[false, true],
[true, true],
] as const) {
const facts = await read(
fatImage(
[
@@ -146,6 +151,7 @@ describe("Mach-O load command reader", () => {
},
],
wide,
littleEndian,
),
);
if (facts.status !== "parsed") throw new Error(facts.status);
@@ -204,6 +210,17 @@ describe("Mach-O load command reader failures", () => {
});
});
it("rejects string commands too short to hold their string offset", async () => {
const short = new Uint8Array(8);
const view = new DataView(short.buffer);
view.setUint32(0, LC.RPATH, true);
view.setUint32(4, 8, true);
expect(await read(machoImage({ commands: [short] }))).toMatchObject({
status: "malformed",
reason: "load command 0 is too short to hold a string offset",
});
});
it("rejects strings that are unterminated, misplaced or not UTF-8", async () => {
const unterminated = rpathCommand("abcd");
unterminated.fill(0x41, 12);
+30 -15
View File
@@ -18,6 +18,8 @@ const MH_CIGAM = 0xcefaedfe;
const MH_CIGAM_64 = 0xcffaedfe;
const FAT_MAGIC = 0xcafebabe;
const FAT_MAGIC_64 = 0xcafebabf;
const FAT_CIGAM = 0xbebafeca;
const FAT_CIGAM_64 = 0xbfbafeca;
const LC_ID_DYLIB = 0xd;
const LC_LOAD_DYLIB = 0xc;
@@ -70,6 +72,8 @@ export const hasMachoMagic = (head: Uint8Array): boolean => {
MH_CIGAM_64,
FAT_MAGIC,
FAT_MAGIC_64,
FAT_CIGAM,
FAT_CIGAM_64,
].includes(magic);
};
@@ -83,18 +87,19 @@ export const readMachoImage = async (
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 ([FAT_MAGIC, FAT_MAGIC_64, FAT_CIGAM, FAT_CIGAM_64].includes(magic)) {
// FAT headers are big-endian; the swapped magics store them little-endian.
const littleEndian = magic === FAT_CIGAM || magic === FAT_CIGAM_64;
const count = view.getUint32(4, littleEndian);
if (count === 0 || count >= MAX_FAT_ARCHITECTURES)
return { status: "not-mach-o" };
return {
status: "parsed",
slices: await readFatSlices(
readAt,
size,
magic === FAT_MAGIC_64,
slices: await readFatSlices(readAt, size, {
wide: magic === FAT_MAGIC_64 || magic === FAT_CIGAM_64,
littleEndian,
count,
),
}),
};
}
if (magic === MH_CIGAM || magic === MH_CIGAM_64)
@@ -115,21 +120,26 @@ export const readMachoImage = async (
const readFatSlices = async (
readAt: ReadAt,
size: number,
wide: boolean,
count: number,
table: {
readonly wide: boolean;
readonly littleEndian: boolean;
readonly count: number;
},
): Promise<MachoSlice[]> => {
const { wide, littleEndian, count } = table;
const entrySize = wide ? 32 : 20;
const table = await readExact(readAt, 8, count * entrySize, "FAT table");
const view = viewOf(table);
const view = viewOf(
await readExact(readAt, 8, count * entrySize, "FAT 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);
? safeNumber(view.getBigUint64(base + 8, littleEndian))
: view.getUint32(base + 8, littleEndian);
const length = wide
? safeNumber(view.getBigUint64(base + 16, false))
: view.getUint32(base + 12, false);
? safeNumber(view.getBigUint64(base + 16, littleEndian))
: view.getUint32(base + 12, littleEndian);
if (offset + length > size)
throw new MachoFormatIssue(
"malformed",
@@ -291,6 +301,11 @@ const commandString = (
minimumOffset: number,
index: number,
): string => {
if (body.byteLength < 12)
throw new MachoFormatIssue(
"malformed",
`load command ${index} is too short to hold a string offset`,
);
const offset = viewOf(body).getUint32(8, true);
if (offset < minimumOffset || offset >= body.byteLength)
throw new MachoFormatIssue(