feat(apple): inspect dyld shared caches and resolve system paths
macOS 11 and later ship system libraries only inside the dyld shared cache. trace_dylib_resolution therefore left every /usr/lib and /System load undetermined, and REA had no way to see what a cache contains. inspect_dyld_shared_cache (CLI inspect-dyld-shared-cache) reads a cache file set selected by path, without an open target. Its pure TypeScript reader parses modern and legacy dyld_cache_header layouts and reports: - UUID, architecture, platform, OS version, Mac Catalyst alternate, cache type, shared region, max slide; - every VM mapping; - each subcache by file suffix, checked by UUID. A missing or mismatched subcache makes coverage partial; - the complete image list. For each requested install path it reads that image's load commands through the cache mappings with the existing Mach-O reader. trace_dylib_resolution accepts an optional shared_cache. Absolute candidates found in a cache that serves the process's CPU family resolve with the new outcome and status `shared-cache`. That status also takes precedence over later in-bundle fallbacks such as a back-deployed libswiftCore. The result names the cache UUID and OS version it used. verify:dyld-shared-cache checks every image in the host cache (3,649 on macOS 26.6), with dependencies and their re-export, weak, upward and delay-init attributes, against `dyld_info -all_dyld_cache -linked_dylibs`. It also checks CLI/MCP parity, and that each shared-cache edge in the fixture trace is a library dyld actually loads. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
co-authored by
Claude Opus 5.5
parent
a0ec3e2016
commit
ade11fa02d
@@ -0,0 +1,462 @@
|
||||
import { open, type FileHandle } from "node:fs/promises";
|
||||
|
||||
import type { MachoImageFacts } from "../domain/dylibResolution.js";
|
||||
import type {
|
||||
DyldCacheMapping,
|
||||
DyldCacheSubcache,
|
||||
DyldSharedCacheHeader,
|
||||
} from "../domain/dyldSharedCache.js";
|
||||
import { ArtifactReaderFailure } from "./ArtifactReader.js";
|
||||
import { readMachoImage } from "./MachoLoadCommandReader.js";
|
||||
|
||||
const MAGIC_PREFIX = "dyld_v1";
|
||||
/** Header fields are valid only below `mappingOffset`; real headers are under 1 KiB. */
|
||||
const MAX_HEADER_BYTES = 64 * 1024;
|
||||
const MAX_IMAGES = 200_000;
|
||||
const MAX_MAPPINGS = 64;
|
||||
const MAX_SUBCACHES = 256;
|
||||
const MAX_PATH_BYTES = 4096;
|
||||
const BLOCK_BYTES = 64 * 1024;
|
||||
|
||||
/** Byte offsets of `dyld_cache_header` fields in Apple's open-source dyld. */
|
||||
const FIELD = {
|
||||
mappingOffset: 0x10,
|
||||
mappingCount: 0x14,
|
||||
imagesOffsetOld: 0x18,
|
||||
imagesCountOld: 0x1c,
|
||||
uuid: 0x58,
|
||||
cacheType: 0x68,
|
||||
platform: 0xd8,
|
||||
formatBits: 0xdc,
|
||||
sharedRegionStart: 0xe0,
|
||||
sharedRegionSize: 0xe8,
|
||||
maxSlide: 0xf0,
|
||||
osVersion: 0x16c,
|
||||
altPlatform: 0x170,
|
||||
altOsVersion: 0x174,
|
||||
subCacheArrayOffset: 0x188,
|
||||
subCacheArrayCount: 0x18c,
|
||||
symbolFileUuid: 0x190,
|
||||
imagesOffset: 0x1c0,
|
||||
imagesCount: 0x1c4,
|
||||
cacheSubType: 0x1c8,
|
||||
} as const;
|
||||
|
||||
const hex = (value: bigint | number): string => `0x${value.toString(16)}`;
|
||||
|
||||
const uuidText = (bytes: Buffer): string => {
|
||||
const text = bytes.toString("hex").toUpperCase();
|
||||
return `${text.slice(0, 8)}-${text.slice(8, 12)}-${text.slice(12, 16)}-${text.slice(16, 20)}-${text.slice(20)}`;
|
||||
};
|
||||
|
||||
const safeNumber = (value: bigint, label: string): number => {
|
||||
if (value > BigInt(Number.MAX_SAFE_INTEGER))
|
||||
throw new ArtifactReaderFailure(
|
||||
"format",
|
||||
`dyld cache ${label} exceeds the safe range`,
|
||||
);
|
||||
return Number(value);
|
||||
};
|
||||
|
||||
/** Block-cached positional reads over one cache file. */
|
||||
class CacheFile {
|
||||
readonly #blocks = new Map<number, Buffer>();
|
||||
|
||||
private constructor(
|
||||
readonly suffix: string,
|
||||
readonly handle: FileHandle,
|
||||
readonly size: number,
|
||||
) {}
|
||||
|
||||
static async open(path: string, suffix: string): Promise<CacheFile> {
|
||||
const handle = await open(path, "r");
|
||||
try {
|
||||
return new CacheFile(suffix, handle, (await handle.stat()).size);
|
||||
} catch (cause: unknown) {
|
||||
await handle.close();
|
||||
throw cause;
|
||||
}
|
||||
}
|
||||
|
||||
async read(offset: number, length: number): Promise<Buffer> {
|
||||
if (offset < 0 || offset + length > this.size)
|
||||
throw new ArtifactReaderFailure(
|
||||
"format",
|
||||
`dyld cache read at ${hex(offset)} extends beyond ${this.suffix === "" ? "the main file" : `subcache ${this.suffix}`}`,
|
||||
);
|
||||
if (length > BLOCK_BYTES) {
|
||||
const bytes = Buffer.alloc(length);
|
||||
await this.handle.read(bytes, 0, length, offset);
|
||||
return bytes;
|
||||
}
|
||||
const chunks: Buffer[] = [];
|
||||
for (let position = offset; position < offset + length;) {
|
||||
const index = Math.floor(position / BLOCK_BYTES);
|
||||
let block = this.#blocks.get(index);
|
||||
if (block === undefined) {
|
||||
const start = index * BLOCK_BYTES;
|
||||
block = Buffer.alloc(Math.min(BLOCK_BYTES, this.size - start));
|
||||
await this.handle.read(block, 0, block.length, start);
|
||||
this.#blocks.set(index, block);
|
||||
}
|
||||
const from = position - index * BLOCK_BYTES;
|
||||
const take = Math.min(block.length - from, offset + length - position);
|
||||
chunks.push(block.subarray(from, from + take));
|
||||
position += take;
|
||||
}
|
||||
return chunks.length === 1
|
||||
? (chunks[0] ?? Buffer.alloc(0))
|
||||
: Buffer.concat(chunks);
|
||||
}
|
||||
|
||||
async cString(offset: number): Promise<string> {
|
||||
const bytes = await this.read(
|
||||
offset,
|
||||
Math.min(MAX_PATH_BYTES, this.size - offset),
|
||||
);
|
||||
const end = bytes.indexOf(0);
|
||||
if (end < 0)
|
||||
throw new ArtifactReaderFailure(
|
||||
"format",
|
||||
`dyld cache string at ${hex(offset)} is unterminated`,
|
||||
);
|
||||
return bytes.toString("utf8", 0, end);
|
||||
}
|
||||
}
|
||||
|
||||
interface ParsedHeader {
|
||||
readonly magic: string;
|
||||
readonly uuid: string;
|
||||
readonly mappings: readonly {
|
||||
readonly address: bigint;
|
||||
readonly size: bigint;
|
||||
readonly fileOffset: bigint;
|
||||
readonly maxProt: number;
|
||||
readonly initProt: number;
|
||||
}[];
|
||||
readonly header: Buffer;
|
||||
readonly length: number;
|
||||
}
|
||||
|
||||
const has = (parsed: ParsedHeader, offset: number, width: number): boolean =>
|
||||
parsed.length >= offset + width;
|
||||
|
||||
const readHeader = async (file: CacheFile): Promise<ParsedHeader> => {
|
||||
if (file.size < 0x20)
|
||||
throw new ArtifactReaderFailure(
|
||||
"format",
|
||||
"File is too short to be a dyld shared cache",
|
||||
);
|
||||
const prefix = await file.read(0, 0x20);
|
||||
const magic = prefix.toString("latin1", 0, 16).replace(/\0+$/u, "");
|
||||
if (!magic.startsWith(MAGIC_PREFIX))
|
||||
throw new ArtifactReaderFailure(
|
||||
"format",
|
||||
"File is not a dyld shared cache",
|
||||
);
|
||||
const mappingOffset = prefix.readUInt32LE(FIELD.mappingOffset);
|
||||
const mappingCount = prefix.readUInt32LE(FIELD.mappingCount);
|
||||
if (
|
||||
mappingOffset < 0x20 ||
|
||||
mappingOffset > MAX_HEADER_BYTES ||
|
||||
mappingCount > MAX_MAPPINGS
|
||||
)
|
||||
throw new ArtifactReaderFailure(
|
||||
"format",
|
||||
"dyld cache header has an invalid mapping table",
|
||||
);
|
||||
const header = await file.read(0, mappingOffset);
|
||||
const table = await file.read(mappingOffset, mappingCount * 32);
|
||||
const mappings = Array.from({ length: mappingCount }, (_, index) => ({
|
||||
address: table.readBigUInt64LE(index * 32),
|
||||
size: table.readBigUInt64LE(index * 32 + 8),
|
||||
fileOffset: table.readBigUInt64LE(index * 32 + 16),
|
||||
maxProt: table.readUInt32LE(index * 32 + 24),
|
||||
initProt: table.readUInt32LE(index * 32 + 28),
|
||||
}));
|
||||
const parsed = { magic, uuid: "", mappings, header, length: mappingOffset };
|
||||
return {
|
||||
...parsed,
|
||||
uuid: has(parsed, FIELD.uuid, 16)
|
||||
? uuidText(header.subarray(FIELD.uuid, FIELD.uuid + 16))
|
||||
: "",
|
||||
};
|
||||
};
|
||||
|
||||
const PLATFORMS: Readonly<Record<number, string>> = {
|
||||
1: "macos",
|
||||
2: "ios",
|
||||
3: "tvos",
|
||||
4: "watchos",
|
||||
5: "bridgeos",
|
||||
6: "maccatalyst",
|
||||
7: "ios-simulator",
|
||||
8: "tvos-simulator",
|
||||
9: "watchos-simulator",
|
||||
10: "driverkit",
|
||||
11: "visionos",
|
||||
12: "visionos-simulator",
|
||||
};
|
||||
|
||||
const version = (value: number): string | null =>
|
||||
value === 0
|
||||
? null
|
||||
: `${value >>> 16}.${(value >>> 8) & 0xff}.${value & 0xff}`;
|
||||
|
||||
/** A main dyld shared cache file and the subcaches it names. */
|
||||
export class DyldSharedCache {
|
||||
readonly #byPath: ReadonlyMap<
|
||||
string,
|
||||
{ readonly path: string; readonly address: number }
|
||||
>;
|
||||
|
||||
private constructor(
|
||||
readonly header: DyldSharedCacheHeader,
|
||||
readonly images: readonly {
|
||||
readonly path: string;
|
||||
readonly address: number;
|
||||
}[],
|
||||
private readonly files: readonly CacheFile[],
|
||||
private readonly regions: readonly {
|
||||
readonly file: CacheFile;
|
||||
readonly address: number;
|
||||
readonly size: number;
|
||||
readonly fileOffset: number;
|
||||
}[],
|
||||
) {
|
||||
this.#byPath = new Map(images.map((image) => [image.path, image]));
|
||||
}
|
||||
|
||||
/** Open the main cache file and every subcache beside it. */
|
||||
static async open(
|
||||
path: string,
|
||||
signal?: AbortSignal,
|
||||
): Promise<DyldSharedCache> {
|
||||
const main = await CacheFile.open(path, "");
|
||||
const files = [main];
|
||||
try {
|
||||
const parsed = await readHeader(main);
|
||||
const subcaches = await DyldSharedCache.#subcacheEntries(main, parsed);
|
||||
const statuses: DyldCacheSubcache[] = [];
|
||||
const parsedFiles = [{ file: main, parsed }];
|
||||
for (const entry of subcaches) {
|
||||
signal?.throwIfAborted();
|
||||
let file: CacheFile;
|
||||
try {
|
||||
file = await CacheFile.open(`${path}${entry.suffix}`, entry.suffix);
|
||||
} catch (cause: unknown) {
|
||||
if (
|
||||
cause instanceof Error &&
|
||||
"code" in cause &&
|
||||
cause.code === "ENOENT"
|
||||
) {
|
||||
statuses.push({ ...entry, status: "missing", observed_uuid: null });
|
||||
continue;
|
||||
}
|
||||
throw cause;
|
||||
}
|
||||
files.push(file);
|
||||
const subParsed = await readHeader(file);
|
||||
const matches = subParsed.uuid === entry.uuid;
|
||||
statuses.push({
|
||||
...entry,
|
||||
status: matches ? "present" : "uuid-mismatch",
|
||||
observed_uuid: subParsed.uuid,
|
||||
});
|
||||
if (matches) parsedFiles.push({ file, parsed: subParsed });
|
||||
}
|
||||
const header = DyldSharedCache.#summary(parsed, parsedFiles, statuses);
|
||||
const images = await DyldSharedCache.#images(main, parsed, signal);
|
||||
const regions = parsedFiles.flatMap(({ file, parsed: item }) =>
|
||||
item.mappings.map((mapping) => ({
|
||||
file,
|
||||
address: safeNumber(mapping.address, "mapping address"),
|
||||
size: safeNumber(mapping.size, "mapping size"),
|
||||
fileOffset: safeNumber(mapping.fileOffset, "mapping file offset"),
|
||||
})),
|
||||
);
|
||||
return new DyldSharedCache(header, images, files, regions);
|
||||
} catch (cause: unknown) {
|
||||
await Promise.allSettled(files.map(({ handle }) => handle.close()));
|
||||
throw cause;
|
||||
}
|
||||
}
|
||||
|
||||
static async #subcacheEntries(
|
||||
main: CacheFile,
|
||||
parsed: ParsedHeader,
|
||||
): Promise<
|
||||
{
|
||||
readonly suffix: string;
|
||||
readonly uuid: string;
|
||||
readonly vm_offset: string;
|
||||
}[]
|
||||
> {
|
||||
if (!has(parsed, FIELD.subCacheArrayCount, 4)) return [];
|
||||
const offset = parsed.header.readUInt32LE(FIELD.subCacheArrayOffset);
|
||||
const count = parsed.header.readUInt32LE(FIELD.subCacheArrayCount);
|
||||
if (count === 0) return [];
|
||||
if (count > MAX_SUBCACHES)
|
||||
throw new ArtifactReaderFailure(
|
||||
"format",
|
||||
"dyld cache lists too many subcaches",
|
||||
);
|
||||
// Headers that include cacheSubType use entries with an explicit file suffix.
|
||||
const named = has(parsed, FIELD.cacheSubType, 4);
|
||||
const size = named ? 56 : 24;
|
||||
const table = await main.read(offset, count * size);
|
||||
return Array.from({ length: count }, (_, index) => {
|
||||
const base = index * size;
|
||||
const suffix = named
|
||||
? table.toString("latin1", base + 24, base + 56).replace(/\0.*$/su, "")
|
||||
: `.${index + 1}`;
|
||||
if (!/^\.[A-Za-z0-9.]+$/u.test(suffix))
|
||||
throw new ArtifactReaderFailure(
|
||||
"format",
|
||||
"dyld subcache has an unsafe file suffix",
|
||||
);
|
||||
return {
|
||||
suffix,
|
||||
uuid: uuidText(table.subarray(base, base + 16)),
|
||||
vm_offset: hex(table.readBigUInt64LE(base + 16)),
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
static #summary(
|
||||
parsed: ParsedHeader,
|
||||
files: readonly {
|
||||
readonly file: CacheFile;
|
||||
readonly parsed: ParsedHeader;
|
||||
}[],
|
||||
subcaches: readonly DyldCacheSubcache[],
|
||||
): DyldSharedCacheHeader {
|
||||
const header = parsed.header;
|
||||
const u32 = (offset: number): number | null =>
|
||||
has(parsed, offset, 4) ? header.readUInt32LE(offset) : null;
|
||||
const u64 = (offset: number): string | null =>
|
||||
has(parsed, offset, 8) ? hex(header.readBigUInt64LE(offset)) : null;
|
||||
const platform = u32(FIELD.platform);
|
||||
const altPlatform = u32(FIELD.altPlatform);
|
||||
const cacheType = has(parsed, FIELD.cacheType, 8)
|
||||
? Number(header.readBigUInt64LE(FIELD.cacheType))
|
||||
: null;
|
||||
const symbols = has(parsed, FIELD.symbolFileUuid, 16)
|
||||
? header.subarray(FIELD.symbolFileUuid, FIELD.symbolFileUuid + 16)
|
||||
: undefined;
|
||||
const mappings: DyldCacheMapping[] = files.flatMap(
|
||||
({ file, parsed: item }) =>
|
||||
item.mappings.map((mapping) => ({
|
||||
file: file.suffix,
|
||||
address: hex(mapping.address),
|
||||
size: hex(mapping.size),
|
||||
file_offset: hex(mapping.fileOffset),
|
||||
max_protection: mapping.maxProt,
|
||||
initial_protection: mapping.initProt,
|
||||
})),
|
||||
);
|
||||
return {
|
||||
magic: parsed.magic,
|
||||
architecture: parsed.magic.slice(MAGIC_PREFIX.length).trim(),
|
||||
uuid: parsed.uuid,
|
||||
platform:
|
||||
platform === null
|
||||
? null
|
||||
: { id: platform, name: PLATFORMS[platform] ?? null },
|
||||
os_version: version(u32(FIELD.osVersion) ?? 0),
|
||||
alt_platform:
|
||||
altPlatform === null || altPlatform === 0
|
||||
? null
|
||||
: { id: altPlatform, name: PLATFORMS[altPlatform] ?? null },
|
||||
alt_os_version: version(u32(FIELD.altOsVersion) ?? 0),
|
||||
cache_type:
|
||||
cacheType === 0
|
||||
? "development"
|
||||
: cacheType === 1
|
||||
? "production"
|
||||
: cacheType === 2
|
||||
? "multi-cache"
|
||||
: null,
|
||||
shared_region:
|
||||
u64(FIELD.sharedRegionStart) === null
|
||||
? null
|
||||
: {
|
||||
start: u64(FIELD.sharedRegionStart) ?? "0x0",
|
||||
size: u64(FIELD.sharedRegionSize) ?? "0x0",
|
||||
},
|
||||
max_slide: u64(FIELD.maxSlide),
|
||||
mappings,
|
||||
subcaches: [...subcaches],
|
||||
symbols_file_uuid:
|
||||
symbols === undefined || symbols.every((byte) => byte === 0)
|
||||
? null
|
||||
: uuidText(symbols),
|
||||
};
|
||||
}
|
||||
|
||||
static async #images(
|
||||
main: CacheFile,
|
||||
parsed: ParsedHeader,
|
||||
signal?: AbortSignal,
|
||||
): Promise<{ readonly path: string; readonly address: number }[]> {
|
||||
const modern = has(parsed, FIELD.imagesCount, 4);
|
||||
const offset = parsed.header.readUInt32LE(
|
||||
modern ? FIELD.imagesOffset : FIELD.imagesOffsetOld,
|
||||
);
|
||||
const count = parsed.header.readUInt32LE(
|
||||
modern ? FIELD.imagesCount : FIELD.imagesCountOld,
|
||||
);
|
||||
if (count > MAX_IMAGES)
|
||||
throw new ArtifactReaderFailure(
|
||||
"limit",
|
||||
`dyld cache lists more than ${MAX_IMAGES} images`,
|
||||
);
|
||||
const table = await main.read(offset, count * 32);
|
||||
const images: { path: string; address: number }[] = [];
|
||||
for (let index = 0; index < count; index++) {
|
||||
if (index % 512 === 0) signal?.throwIfAborted();
|
||||
images.push({
|
||||
address: safeNumber(table.readBigUInt64LE(index * 32), "image address"),
|
||||
path: await main.cString(table.readUInt32LE(index * 32 + 24)),
|
||||
});
|
||||
}
|
||||
return images;
|
||||
}
|
||||
|
||||
/** Locate an image by its exact install path. */
|
||||
find(
|
||||
path: string,
|
||||
): { readonly path: string; readonly address: number } | undefined {
|
||||
return this.#byPath.get(path);
|
||||
}
|
||||
|
||||
/** Parse one cached image's load commands through the cache's VM mappings. */
|
||||
async imageFacts(
|
||||
path: string,
|
||||
): Promise<
|
||||
{ readonly file: string; readonly facts: MachoImageFacts } | undefined
|
||||
> {
|
||||
const image = this.find(path);
|
||||
if (image === undefined) return undefined;
|
||||
const region = this.regions.find(
|
||||
({ address, size }) =>
|
||||
image.address >= address && image.address < address + size,
|
||||
);
|
||||
if (region === undefined) return undefined;
|
||||
const base = region.fileOffset + (image.address - region.address);
|
||||
const available = region.size - (image.address - region.address);
|
||||
const facts = await readMachoImage(
|
||||
async (offset, length) =>
|
||||
region.file.read(
|
||||
base + offset,
|
||||
Math.max(0, Math.min(length, available - offset)),
|
||||
),
|
||||
available,
|
||||
);
|
||||
return { file: region.file.suffix, facts };
|
||||
}
|
||||
|
||||
async close(): Promise<void> {
|
||||
await Promise.allSettled(this.files.map(({ handle }) => handle.close()));
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user