import { z } from "zod"; import { compatibleSlice, directoryOf, expandPrefix, joinPath, resolveTreePath, type Expansion, } from "./dyldPaths.js"; import { digestSchema } from "./digests.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(), }); 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; export type MachoSlice = z.infer; /** 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; image(path: string): Promise; } 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", "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", "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, 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; type Candidate = z.infer; type Edge = z.infer; type Finding = z.infer; /** Result before the adapter adds file digests and the analyzed root. */ export type DylibTrace = Omit< DylibResolutionResult, "root_path" | "target_sha256" | "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; readonly byInstallName: Map; readonly images: Map; } 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 => { const base = { path: template.expansion.path, source: template.source, rpath: template.rpath, rpath_owner: template.rpathOwner, }; if (template.expansion.scope === "outside") return { ...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 => { 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, }; // 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 => { 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") 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 => { 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 signal?: AbortSignal; }, ): Promise => { const images = new Map(); 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, }, 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, }; }; const withoutDependencies = ( slice: MachoSlice, ): Omit => ({ 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 deriveFindings = ( edges: readonly Edge[], roots: DylibTrace["roots"], images: ReadonlyMap, ): Finding[] => { const findings: Finding[] = []; edges.forEach((edge, index) => { if (edge.resolution.status === "unresolved") findings.push({ kind: edge.weak ? "weak-load-unresolved" : "required-load-unresolved", edge_index: index, image: edge.loader, basis: "derived", explanation: edge.weak ? `No candidate for weak dependency ${edge.install_name} exists in the analyzed root; dyld continues without it.` : `No candidate for ${edge.install_name} exists in the analyzed root; dyld would fail to launch ${edge.root} (${edge.architecture}) unless the image is supplied elsewhere.`, }); const resolvedAt = edge.candidates.findIndex( ({ outcome }) => outcome === "resolved", ); const earlier = edge.candidates .slice(0, Math.max(resolvedAt, 0)) .filter( ({ source, outcome }) => source === "rpath" && outcome === "absent", ) .map(({ path }) => path); if (resolvedAt > 0 && earlier.length > 0) findings.push({ kind: "earlier-rpath-candidate-absent", edge_index: index, image: edge.loader, basis: "derived", explanation: `dyld searches ${earlier.join(", ")} before ${edge.resolution.image ?? edge.install_name}. A Mach-O placed at an earlier path would load first unless code-signing library validation rejects it; library validation is not evaluated here (see inspect_signature).`, }); }); for (const { image, architecture } of roots) { const facts = images.get(image); const environment = facts?.status === "parsed" ? (facts.slices.find((slice) => slice.architecture === architecture) ?.dyld_environment ?? []) : []; if (environment.length > 0) findings.push({ kind: "dyld-environment-present", edge_index: null, image, basis: "derived", explanation: `${image} (${architecture}) sets dyld environment variables through LC_DYLD_ENVIRONMENT (${environment.join(", ")}); search paths they add are not modeled.`, }); } return findings; }; const DYLIB_RESOLUTION_LIMITATIONS = [ "Slices are matched by dyld's graded architectures (an x86_64h process also loads x86_64). arm64e processes that disable pointer authentication can also load arm64 slices; that fallback is not modeled.", "Absolute install names and rpaths are outside the analyzed root and are not evaluated, including /System and /usr/lib libraries that the dyld shared cache usually provides.", "Leaf and relative install names depend on dyld fallback paths, DYLD_* variables, and the working directory; they are undetermined.", "Load order follows dyld's dependents-first traversal in load-command order. An image reached through several chains is resolved once per process, with the rpath stack of the first chain; a later request whose install name matches an already loaded image reuses it.", "@loader_path uses each image's symlink-resolved path within the analyzed root.", "Code-signing checks that can reject a found image, such as library validation and the hardened runtime, are not evaluated.", ]; const compare = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0;