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>
534 lines
16 KiB
TypeScript
534 lines
16 KiB
TypeScript
import { z } from "zod";
|
|
|
|
import {
|
|
cacheServes,
|
|
compatibleSlice,
|
|
directoryOf,
|
|
expandPrefix,
|
|
joinPath,
|
|
resolveTreePath,
|
|
type Expansion,
|
|
} from "./dyldPaths.js";
|
|
import { digestSchema } from "./digests.js";
|
|
import {
|
|
DYLIB_RESOLUTION_LIMITATIONS,
|
|
deriveFindings,
|
|
sharedCacheLimitations,
|
|
} from "./dylibResolutionFindings.js";
|
|
|
|
/** Normalized path below the analyzed root: no `.`/`..` or empty segments. */
|
|
const ROOT_RELATIVE_PATH =
|
|
/^(?!\/)(?!(?:.*\/)?\.{1,2}(?:\/|$))(?!.*\/\/)(?!.*\/$)[^\\\0]+$/u;
|
|
const rootRelativePathSchema = z.string().min(1).regex(ROOT_RELATIVE_PATH);
|
|
|
|
/** Caller selection of process roots and one CPU slice. */
|
|
export const dylibResolutionInputSchema = z.strictObject({
|
|
roots: z.array(rootRelativePathSchema).min(1).optional(),
|
|
architecture: z.enum(["arm64", "arm64e", "x86_64"]).optional(),
|
|
/** Main dyld shared cache file whose image list answers system install paths. */
|
|
shared_cache: z.string().min(1).optional(),
|
|
});
|
|
|
|
const dependencyCommandSchema = z.enum([
|
|
"LC_LOAD_DYLIB",
|
|
"LC_LOAD_WEAK_DYLIB",
|
|
"LC_REEXPORT_DYLIB",
|
|
"LC_LAZY_LOAD_DYLIB",
|
|
"LC_LOAD_UPWARD_DYLIB",
|
|
]);
|
|
|
|
const dependencySchema = z.strictObject({
|
|
command: dependencyCommandSchema,
|
|
encoding: z.enum(["dylib_command", "dylib_use_command"]),
|
|
install_name: z.string(),
|
|
weak: z.boolean(),
|
|
upward: z.boolean(),
|
|
reexport: z.boolean(),
|
|
delayed_init: z.boolean(),
|
|
current_version: z.string(),
|
|
compatibility_version: z.string(),
|
|
});
|
|
|
|
/** Observed dylib-loading facts of one Mach-O slice. */
|
|
export const machoSliceSchema = z.strictObject({
|
|
architecture: z.string().min(1),
|
|
file_type: z.enum(["execute", "dylib", "bundle", "other"]),
|
|
install_name: z.string().nullable(),
|
|
dependencies: z.array(dependencySchema),
|
|
rpaths: z.array(z.string()),
|
|
dyld_environment: z.array(z.string()),
|
|
code_signature_present: z.boolean(),
|
|
});
|
|
|
|
export type MachoDependency = z.infer<typeof dependencySchema>;
|
|
export type MachoSlice = z.infer<typeof machoSliceSchema>;
|
|
|
|
/** Header parse of one file; malformed and unsupported images keep their reason. */
|
|
export type MachoImageFacts =
|
|
| { readonly status: "parsed"; readonly slices: readonly MachoSlice[] }
|
|
| {
|
|
readonly status: "malformed" | "unsupported";
|
|
readonly reason: string;
|
|
}
|
|
| { readonly status: "not-mach-o" };
|
|
|
|
/** One observed path below the analyzed root. Symlink targets are not followed by the view. */
|
|
export type DylibTreeEntry =
|
|
| { readonly kind: "file" | "directory" }
|
|
| { readonly kind: "symlink"; readonly target: string };
|
|
|
|
/** Read-only, lazily probed view of the analyzed root. Paths are root-relative. */
|
|
export interface DylibTreeView {
|
|
entry(path: string): Promise<DylibTreeEntry | undefined>;
|
|
image(path: string): Promise<MachoImageFacts>;
|
|
}
|
|
|
|
/** Image list of one caller-supplied dyld shared cache. */
|
|
export interface DylibSharedCacheView {
|
|
readonly architecture: string;
|
|
has(path: string): boolean;
|
|
}
|
|
|
|
const candidateSchema = z.strictObject({
|
|
path: z.string(),
|
|
source: z.enum([
|
|
"literal",
|
|
"executable_path",
|
|
"loader_path",
|
|
"rpath",
|
|
"already-loaded",
|
|
]),
|
|
rpath: z.string().nullable(),
|
|
rpath_owner: z.string().nullable(),
|
|
outcome: z.enum([
|
|
"resolved",
|
|
"absent",
|
|
"not-mach-o",
|
|
"malformed",
|
|
"unsupported",
|
|
"architecture-missing",
|
|
"outside-target",
|
|
"shared-cache",
|
|
"escapes-target",
|
|
"undetermined",
|
|
]),
|
|
resolved_path: z.string().nullable(),
|
|
});
|
|
|
|
const edgeSchema = z.strictObject({
|
|
root: z.string(),
|
|
architecture: z.string(),
|
|
loader: z.string(),
|
|
via: z.array(z.string()),
|
|
...dependencySchema.shape,
|
|
candidates: z.array(candidateSchema),
|
|
resolution: z.strictObject({
|
|
status: z.enum([
|
|
"resolved",
|
|
"conditional",
|
|
"shared-cache",
|
|
"unresolved",
|
|
"undetermined",
|
|
]),
|
|
image: z.string().nullable(),
|
|
}),
|
|
install_name_matches: z.boolean().nullable(),
|
|
});
|
|
|
|
const findingSchema = z.strictObject({
|
|
kind: z.enum([
|
|
"required-load-unresolved",
|
|
"weak-load-unresolved",
|
|
"earlier-rpath-candidate-absent",
|
|
"dyld-environment-present",
|
|
]),
|
|
edge_index: z.number().int().nonnegative().nullable(),
|
|
image: z.string().nullable(),
|
|
basis: z.literal("derived"),
|
|
explanation: z.string().min(1),
|
|
});
|
|
|
|
const imageSchema = z.strictObject({
|
|
path: z.string(),
|
|
sha256: digestSchema,
|
|
parse_status: z.enum(["parsed", "malformed", "unsupported"]),
|
|
reason: z.string().nullable(),
|
|
slices: z.array(machoSliceSchema.omit({ dependencies: true })),
|
|
});
|
|
|
|
/** Static dyld load-path resolution for every selected process root. */
|
|
export const dylibResolutionResultSchema = z.strictObject({
|
|
root_path: z.string(),
|
|
target_sha256: digestSchema,
|
|
shared_cache: z
|
|
.strictObject({
|
|
path: z.string(),
|
|
uuid: z.string(),
|
|
architecture: z.string(),
|
|
os_version: z.string().nullable(),
|
|
})
|
|
.nullable(),
|
|
roots: z.array(
|
|
z.strictObject({ image: z.string(), architecture: z.string() }),
|
|
),
|
|
images: z.array(imageSchema),
|
|
edges: z.array(edgeSchema),
|
|
findings: z.array(findingSchema),
|
|
coverage: z.strictObject({
|
|
status: z.enum(["complete", "partial"]),
|
|
unparsed_images: z.array(z.string()),
|
|
roots_without_architecture: z.array(z.string()),
|
|
}),
|
|
limitations: z.array(z.string().min(1)),
|
|
});
|
|
|
|
export type DylibResolutionResult = z.infer<typeof dylibResolutionResultSchema>;
|
|
type Candidate = z.infer<typeof candidateSchema>;
|
|
export type DylibEdge = z.infer<typeof edgeSchema>;
|
|
export type DylibFinding = z.infer<typeof findingSchema>;
|
|
type Edge = DylibEdge;
|
|
|
|
/** Result before the adapter adds file digests and the analyzed root. */
|
|
export type DylibTrace = Omit<
|
|
DylibResolutionResult,
|
|
"root_path" | "target_sha256" | "shared_cache" | "images"
|
|
> & {
|
|
readonly images: readonly (Omit<
|
|
DylibResolutionResult["images"][number],
|
|
"sha256"
|
|
> & { readonly sha256?: never })[];
|
|
};
|
|
|
|
interface LoadedImage {
|
|
readonly slice: MachoSlice;
|
|
/** Images from the process root to this image; the rpath stack, outermost first. */
|
|
readonly chain: readonly string[];
|
|
}
|
|
|
|
interface ProcessContext {
|
|
readonly view: DylibTreeView;
|
|
readonly root: string;
|
|
readonly architecture: string;
|
|
readonly executable: string | null;
|
|
readonly loaded: Map<string, LoadedImage>;
|
|
readonly byInstallName: Map<string, string>;
|
|
readonly images: Map<string, MachoImageFacts>;
|
|
/** The supplied cache, when it serves this process's architecture. */
|
|
readonly sharedCache: DylibSharedCacheView | undefined;
|
|
}
|
|
|
|
interface CandidateTemplate {
|
|
readonly expansion: Expansion;
|
|
readonly source: Candidate["source"];
|
|
readonly rpath: string | null;
|
|
readonly rpathOwner: string | null;
|
|
}
|
|
|
|
const candidateTemplates = (
|
|
dependency: MachoDependency,
|
|
loader: string,
|
|
context: ProcessContext,
|
|
): CandidateTemplate[] => {
|
|
const name = dependency.install_name;
|
|
if (!name.startsWith("@rpath/")) {
|
|
const source = name.startsWith("@executable_path")
|
|
? "executable_path"
|
|
: name.startsWith("@loader_path")
|
|
? "loader_path"
|
|
: "literal";
|
|
return [
|
|
{
|
|
expansion: expandPrefix(name, {
|
|
ownerDirectory: directoryOf(loader),
|
|
executable: context.executable,
|
|
}),
|
|
source,
|
|
rpath: null,
|
|
rpathOwner: null,
|
|
},
|
|
];
|
|
}
|
|
const rest = name.slice("@rpath/".length);
|
|
const owners = [...(context.loaded.get(loader)?.chain ?? [loader])].reverse();
|
|
return owners.flatMap((owner) =>
|
|
(context.loaded.get(owner)?.slice.rpaths ?? []).map((rpath) => {
|
|
const base = expandPrefix(rpath, {
|
|
ownerDirectory: directoryOf(owner),
|
|
executable: context.executable,
|
|
});
|
|
const expansion: Expansion = {
|
|
scope: base.scope,
|
|
path:
|
|
base.scope === "outside"
|
|
? `${base.path.replace(/\/+$/u, "")}/${rest}`
|
|
: joinPath(base.path, rest),
|
|
};
|
|
return { expansion, source: "rpath" as const, rpath, rpathOwner: owner };
|
|
}),
|
|
);
|
|
};
|
|
|
|
const evaluateCandidate = async (
|
|
template: CandidateTemplate,
|
|
context: ProcessContext,
|
|
): Promise<Candidate> => {
|
|
const base = {
|
|
path: template.expansion.path,
|
|
source: template.source,
|
|
rpath: template.rpath,
|
|
rpath_owner: template.rpathOwner,
|
|
};
|
|
if (template.expansion.scope === "outside")
|
|
return context.sharedCache?.has(template.expansion.path) === true
|
|
? {
|
|
...base,
|
|
outcome: "shared-cache",
|
|
resolved_path: template.expansion.path,
|
|
}
|
|
: { ...base, outcome: "outside-target", resolved_path: null };
|
|
if (template.expansion.scope === "undetermined")
|
|
return { ...base, outcome: "undetermined", resolved_path: null };
|
|
const lookup = await resolveTreePath(context.view, template.expansion.path);
|
|
if (lookup.kind === "escapes")
|
|
return { ...base, outcome: "escapes-target", resolved_path: null };
|
|
if (lookup.kind !== "file")
|
|
return { ...base, outcome: "absent", resolved_path: null };
|
|
const facts = await imageFacts(context, lookup.path);
|
|
const outcome: Candidate["outcome"] =
|
|
facts.status !== "parsed"
|
|
? facts.status
|
|
: compatibleSlice(facts.slices, context.architecture) === undefined
|
|
? "architecture-missing"
|
|
: "resolved";
|
|
return { ...base, outcome, resolved_path: lookup.path };
|
|
};
|
|
|
|
const imageFacts = async (
|
|
context: ProcessContext,
|
|
path: string,
|
|
): Promise<MachoImageFacts> => {
|
|
const known = context.images.get(path);
|
|
if (known !== undefined) return known;
|
|
const facts = await context.view.image(path);
|
|
context.images.set(path, facts);
|
|
return facts;
|
|
};
|
|
|
|
const resolution = (candidates: readonly Candidate[]): Edge["resolution"] => {
|
|
let external = false;
|
|
for (const candidate of candidates) {
|
|
if (candidate.outcome === "resolved")
|
|
return {
|
|
status: external ? "conditional" : "resolved",
|
|
image: candidate.resolved_path,
|
|
};
|
|
if (candidate.outcome === "shared-cache")
|
|
return { status: "shared-cache", image: candidate.resolved_path };
|
|
// dyld might load these; REA cannot decide them from the analyzed root.
|
|
if (
|
|
candidate.outcome === "outside-target" ||
|
|
candidate.outcome === "escapes-target" ||
|
|
candidate.outcome === "unsupported" ||
|
|
candidate.outcome === "undetermined"
|
|
)
|
|
external = true;
|
|
}
|
|
return { status: external ? "undetermined" : "unresolved", image: null };
|
|
};
|
|
|
|
const resolveDependency = async (
|
|
dependency: MachoDependency,
|
|
loader: string,
|
|
context: ProcessContext,
|
|
): Promise<Edge> => {
|
|
const chain = context.loaded.get(loader)?.chain ?? [loader];
|
|
const loaded = context.byInstallName.get(dependency.install_name);
|
|
const candidates: Candidate[] = [];
|
|
if (loaded !== undefined)
|
|
candidates.push({
|
|
path: dependency.install_name,
|
|
source: "already-loaded",
|
|
rpath: null,
|
|
rpath_owner: null,
|
|
outcome: "resolved",
|
|
resolved_path: loaded,
|
|
});
|
|
else
|
|
for (const template of candidateTemplates(dependency, loader, context)) {
|
|
const candidate = await evaluateCandidate(template, context);
|
|
candidates.push(candidate);
|
|
// dyld stops at the first loadable candidate.
|
|
if (
|
|
candidate.outcome === "resolved" ||
|
|
candidate.outcome === "shared-cache"
|
|
)
|
|
break;
|
|
}
|
|
const resolved = resolution(candidates);
|
|
const image =
|
|
resolved.image === null ? undefined : context.images.get(resolved.image);
|
|
const slice =
|
|
image?.status === "parsed"
|
|
? compatibleSlice(image.slices, context.architecture)
|
|
: undefined;
|
|
return {
|
|
root: context.root,
|
|
architecture: context.architecture,
|
|
loader,
|
|
via: [...chain],
|
|
...dependency,
|
|
candidates,
|
|
resolution: resolved,
|
|
install_name_matches:
|
|
slice === undefined || slice.install_name === null
|
|
? null
|
|
: slice.install_name === dependency.install_name,
|
|
};
|
|
};
|
|
|
|
/**
|
|
* Follow dyld4's dependents-first order: resolve every dependency of one
|
|
* image, then recurse into the images it newly loaded, in load-command order.
|
|
*/
|
|
const traceProcess = async (
|
|
context: ProcessContext,
|
|
rootSlice: MachoSlice,
|
|
signal?: AbortSignal,
|
|
): Promise<Edge[]> => {
|
|
const edges: Edge[] = [];
|
|
context.loaded.set(context.root, { slice: rootSlice, chain: [context.root] });
|
|
if (rootSlice.install_name !== null)
|
|
context.byInstallName.set(rootSlice.install_name, context.root);
|
|
const pending = [context.root];
|
|
while (pending.length > 0) {
|
|
signal?.throwIfAborted();
|
|
const loader = pending.pop() ?? "";
|
|
const current = context.loaded.get(loader);
|
|
if (current === undefined) continue;
|
|
const created: string[] = [];
|
|
for (const dependency of current.slice.dependencies) {
|
|
const edge = await resolveDependency(dependency, loader, context);
|
|
edges.push(edge);
|
|
const image = edge.resolution.image;
|
|
if (image === null || context.loaded.has(image)) continue;
|
|
const facts = context.images.get(image);
|
|
const slice =
|
|
facts?.status === "parsed"
|
|
? compatibleSlice(facts.slices, context.architecture)
|
|
: undefined;
|
|
if (slice === undefined) continue;
|
|
context.loaded.set(image, { slice, chain: [...current.chain, image] });
|
|
if (
|
|
slice.install_name !== null &&
|
|
!context.byInstallName.has(slice.install_name)
|
|
)
|
|
context.byInstallName.set(slice.install_name, image);
|
|
created.push(image);
|
|
}
|
|
pending.push(...created.reverse());
|
|
}
|
|
return edges;
|
|
};
|
|
|
|
/** Trace dyld load paths from each process root through the analyzed root. */
|
|
export const traceDylibLoading = async (
|
|
view: DylibTreeView,
|
|
request: {
|
|
readonly roots: readonly string[];
|
|
/** Mach-O files whose root role could not be classified because they did not parse. */
|
|
readonly unclassified?: readonly string[];
|
|
readonly architecture?: string;
|
|
readonly sharedCache?: DylibSharedCacheView;
|
|
readonly signal?: AbortSignal;
|
|
},
|
|
): Promise<DylibTrace> => {
|
|
const images = new Map<string, MachoImageFacts>();
|
|
for (const path of request.unclassified ?? [])
|
|
images.set(path, await view.image(path));
|
|
const roots: DylibTrace["roots"][number][] = [];
|
|
const edges: Edge[] = [];
|
|
const withoutArchitecture: string[] = [];
|
|
for (const root of request.roots) {
|
|
const facts = await view.image(root);
|
|
images.set(root, facts);
|
|
if (facts.status !== "parsed") continue;
|
|
const slices = facts.slices.filter(
|
|
({ architecture }) =>
|
|
request.architecture === undefined ||
|
|
architecture === request.architecture,
|
|
);
|
|
if (slices.length === 0) withoutArchitecture.push(root);
|
|
for (const slice of slices) {
|
|
roots.push({ image: root, architecture: slice.architecture });
|
|
edges.push(
|
|
...(await traceProcess(
|
|
{
|
|
view,
|
|
root,
|
|
architecture: slice.architecture,
|
|
executable: slice.file_type === "execute" ? root : null,
|
|
loaded: new Map(),
|
|
byInstallName: new Map(),
|
|
images,
|
|
sharedCache:
|
|
request.sharedCache !== undefined &&
|
|
cacheServes(request.sharedCache.architecture, slice.architecture)
|
|
? request.sharedCache
|
|
: undefined,
|
|
},
|
|
slice,
|
|
request.signal,
|
|
)),
|
|
);
|
|
}
|
|
}
|
|
const reported = [...images.entries()]
|
|
.filter(([, facts]) => facts.status !== "not-mach-o")
|
|
.sort(([left], [right]) => compare(left, right));
|
|
const unparsed = reported
|
|
.filter(([, facts]) => facts.status !== "parsed")
|
|
.map(([path]) => path);
|
|
return {
|
|
roots,
|
|
images: reported.map(([path, facts]) => ({
|
|
path,
|
|
parse_status:
|
|
facts.status === "not-mach-o" ? "unsupported" : facts.status,
|
|
reason:
|
|
facts.status === "parsed" || facts.status === "not-mach-o"
|
|
? null
|
|
: facts.reason,
|
|
slices:
|
|
facts.status === "parsed" ? facts.slices.map(withoutDependencies) : [],
|
|
})),
|
|
edges,
|
|
findings: deriveFindings(edges, roots, images),
|
|
coverage: {
|
|
status:
|
|
unparsed.length === 0 && withoutArchitecture.length === 0
|
|
? "complete"
|
|
: "partial",
|
|
unparsed_images: unparsed,
|
|
roots_without_architecture: withoutArchitecture,
|
|
},
|
|
limitations: [
|
|
...DYLIB_RESOLUTION_LIMITATIONS,
|
|
...sharedCacheLimitations(request.sharedCache, roots),
|
|
],
|
|
};
|
|
};
|
|
|
|
const withoutDependencies = (
|
|
slice: MachoSlice,
|
|
): Omit<MachoSlice, "dependencies"> => ({
|
|
architecture: slice.architecture,
|
|
file_type: slice.file_type,
|
|
install_name: slice.install_name,
|
|
rpaths: slice.rpaths,
|
|
dyld_environment: slice.dyld_environment,
|
|
code_signature_present: slice.code_signature_present,
|
|
});
|
|
|
|
const compare = (left: string, right: string): number =>
|
|
left < right ? -1 : left > right ? 1 : 0;
|