Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(apple): trace legacy macOS dylibs with implicit platforms
morluto90062c092228
diff --git a/docs/apple-application-analysis.md b/docs/apple-application-analysis.mdindex 926aae0d4..1ea57eb27 100644--- a/docs/apple-application-analysis.md+++ b/docs/apple-application-analysis.md@@ -216,17 +216,26 @@ parser coverage, such as big-endian images), `architecture-missing`,`outside-target`, `escapes-target`, or `undetermined`. Slices follow dyld'sgraded architectures, so an `x86_64h` process also loads `x86_64`. The edge's `resolution` is one of:-| Status | Meaning |-| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |-| `resolved` | An image inside the analyzed root loads, and no earlier candidate was undeterminable. |-| `conditional` | An image inside the root resolves, but an earlier candidate outside the root (for example `/usr/lib/swift`) would win if it exists on the running system. |-| `unresolved` | Every candidate is definitively absent or unusable inside the root. |-| `undetermined` | No candidate resolves inside the root, and some candidate lies outside it or depends on the environment. |--A `conditional` image is still traced, because it is the image the analyzed-root supplies. Every edge below it has `loader_conditional: true`, and a-request that reuses it by install name is `conditional` too. Findings on those-edges say that they apply only if the conditional image loads.+| Status | Meaning |+| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `resolved` | An image inside the analyzed root loads, and no earlier candidate was undeterminable. |+| `conditional` | An in-root image may load, but an earlier outside candidate, unmodeled environment input, or unknown platform compatibility can change which image dyld loads. |+| `unresolved` | Every candidate is definitively absent or unusable inside the root. |+| `undetermined` | No candidate resolves inside the root, and some candidate lies outside it or depends on the environment. |++A `conditional` image is still traced, because it is an in-root candidate+that may load. Every edge below it has `loader_conditional: true`, and a+request that reuses it by install name is `conditional` too. An in-root dylib+with no platform load command remains unknown unless the root is an executable+with observed macOS platform and the candidate’s CPU type is x86_64, i386, or arm64. In that macOS context,+[Apple's dyld](https://github.com/apple-oss-distributions/dyld/blob/fd8d0c4d52320ebf64db34f3cb280310d905c5ae/mach_o/UnsafeHeader.cpp#L1137-L1145) supplies an implicit macOS platform to legacy dylibs on those CPU+types. The candidate records `platform_basis: "macos-dyld-implicit"`; the+reported slice fields `platform: null` and `platforms: []` remain the parsed+facts. For other process contexts the platform remains unknown, coverage is+partial, and the candidate is not treated as incompatible. If a later known+candidate resolves, it remains the traced image with conditional resolution;+the trace does not claim the unknown candidate's dependency graph. Findings on+conditional edges say that they apply only if the conditional image loads.Absolute install names that name a path beneath the analyzed root are checkedwithin that root, with symlinks and `..` resolved by the same bounded treediff --git a/src/artifacts/apple/MachoLoadCommandReader.test.ts b/src/artifacts/apple/MachoLoadCommandReader.test.tsindex 94dd4891c..c2008e599 100644--- a/src/artifacts/apple/MachoLoadCommandReader.test.ts+++ b/src/artifacts/apple/MachoLoadCommandReader.test.ts@@ -142,6 +142,112 @@ it("uses legacy simulator and device platform facts when resolving dylibs", asyn);});+it.each([false, true] as const)(+ "applies macOS dyld's implicit platform to a platform-less dylib and traces its required child present=%s",+ async (childPresent) => {+ const root = await createTestTempDirectory("rea-dylib-platform-unknown-");+ const executablePath = "Contents/MacOS/probe";+ const dylibPath = "Contents/Frameworks/libA.dylib";+ const fallbackPath = "Contents/Fallbacks/libA.dylib";+ const childPath = "Contents/Frameworks/libMissing.dylib";+ const fallbackChildPath = "Contents/Fallbacks/libFallbackOnly.dylib";+ const executable = machoImage({+ cpu: CPU.arm64,+ commands: [+ buildVersionCommand(1),+ rpathCommand("@executable_path/../Frameworks"),+ rpathCommand("@executable_path/../Fallbacks"),+ dylibCommand(LC.LOAD_DYLIB, "@rpath/libA.dylib"),+ ],+ });+ const dylib = machoImage({+ cpu: CPU.arm64,+ fileType: FILE_TYPE.dylib,+ commands: [+ rpathCommand("@loader_path"),+ dylibCommand(LC.LOAD_DYLIB, "@rpath/libMissing.dylib"),+ ],+ });+ const child = machoImage({+ cpu: CPU.arm64,+ fileType: FILE_TYPE.dylib,+ commands: [buildVersionCommand(1)],+ });+ const fallback = machoImage({+ cpu: CPU.arm64,+ fileType: FILE_TYPE.dylib,+ commands: [+ rpathCommand("@loader_path"),+ dylibCommand(LC.LOAD_DYLIB, "@rpath/libFallbackOnly.dylib"),+ ],+ });+ const fallbackChild = machoImage({+ cpu: CPU.arm64,+ fileType: FILE_TYPE.dylib,+ commands: [buildVersionCommand(1)],+ });+ await mkdir(join(root, "Contents/MacOS"), { recursive: true });+ await mkdir(join(root, "Contents/Frameworks"), { recursive: true });+ await mkdir(join(root, "Contents/Fallbacks"), { recursive: true });+ await writeFile(join(root, executablePath), executable);+ await writeFile(join(root, dylibPath), dylib);+ await writeFile(join(root, fallbackPath), fallback);+ await writeFile(join(root, fallbackChildPath), fallbackChild);+ if (childPresent) await writeFile(join(root, childPath), child);++ const trace = await traceDylibResolution({+ rootPath: root,+ targetPath: join(root, executablePath),+ targetSha256: createHash("sha256").update(executable).digest("hex"),+ enumerateRoots: false,+ parameters: { roots: [executablePath] },+ });++ expect(+ trace.images.find(({ path }) => path === executablePath)?.slices[0],+ ).toMatchObject({ platform: 1, platforms: [1] });+ expect(+ trace.images.find(({ path }) => path === dylibPath)?.slices[0],+ ).toMatchObject({ platform: null, platforms: [] });+ expect(trace.edges[0]).toMatchObject({+ loader: executablePath,+ install_name: "@rpath/libA.dylib",+ candidates: [+ {+ outcome: "resolved",+ resolved_path: dylibPath,+ platform_basis: "macos-dyld-implicit",+ },+ ],+ resolution: { status: "resolved", image: dylibPath },+ });+ expect(trace.edges[1]).toMatchObject({+ loader: dylibPath,+ install_name: "@rpath/libMissing.dylib",+ resolution: childPresent+ ? { status: "resolved", image: childPath }+ : { status: "unresolved", image: null },+ loader_conditional: false,+ });+ expect(trace.images.map(({ path }) => path)).toEqual(+ childPresent+ ? [executablePath, childPath, dylibPath].sort()+ : [executablePath, dylibPath].sort(),+ );+ expect(trace.images.map(({ path }) => path)).not.toContain(fallbackPath);+ expect(trace.images.map(({ path }) => path)).not.toContain(+ fallbackChildPath,+ );+ expect(trace.coverage.status).toBe("complete");+ expect(trace.limitations).toContainEqual(+ expect.stringContaining(dylibPath),+ );+ expect(trace.findings.map(({ kind }) => kind)).toEqual(+ childPresent ? [] : ["required-load-unresolved"],+ );+ },+);+describe("absolute dyld candidate paths at the filesystem reader boundary", () => {it.each(["install-name", "rpath"] as const)("resolves an absolute in-root %s while preserving its source path",diff --git a/src/domain/apple/dylibResolution.test.ts b/src/domain/apple/dylibResolution.test.tsindex dd4c18df2..577ce5d9a 100644--- a/src/domain/apple/dylibResolution.test.ts+++ b/src/domain/apple/dylibResolution.test.ts@@ -441,26 +441,6 @@ describe("dyld resolution outcomes: checking candidate format and compatibility"});});- it("preserves unknown platform compatibility before a later known candidate", async () => {- const trace = await traceDylibLoading(- memoryView({- [MAIN]: executable({- rpaths: ["@executable_path/a", "@executable_path/b"],- dependencies: [dependency("@rpath/lib.dylib")],- }),- "Contents/MacOS/a/lib.dylib": parsed(slice({ platform: null })),- "Contents/MacOS/b/lib.dylib": parsed(slice()),- }),- { roots: [MAIN] },- );- const edge = edgeFor(trace, MAIN, "@rpath/lib.dylib");- expect(edge.candidates.map(({ outcome }) => outcome)).toEqual([- "undetermined",- "resolved",- ]);- expect(edge.resolution.status).toBe("conditional");- });-it("applies dyld Catalyst and zippered platform compatibility", async () => {const catalystProcess = await traceDylibLoading(memoryView({@@ -506,6 +486,104 @@ describe("dyld resolution outcomes: checking candidate format and compatibility"});});+describe("platform-less dylib compatibility", () => {+ it("keeps an unknown candidate unresolved and traces the later known fallback", async () => {+ const trace = await traceDylibLoading(+ memoryView({+ [MAIN]: executable({+ platform: 6,+ platforms: [6],+ rpaths: ["@executable_path/a", "@executable_path/b"],+ dependencies: [dependency("@rpath/lib.dylib")],+ }),+ "Contents/MacOS/a/lib.dylib": parsed(slice({ platform: null })),+ "Contents/MacOS/b/lib.dylib": parsed(+ slice({+ platform: 6,+ platforms: [6],+ dependencies: [dependency("@loader_path/libChild.dylib")],+ }),+ ),+ "Contents/MacOS/b/libChild.dylib": parsed(+ slice({ platform: 6, platforms: [6] }),+ ),+ }),+ { roots: [MAIN] },+ );+ const edge = edgeFor(trace, MAIN, "@rpath/lib.dylib");+ expect(edge.candidates.map(({ outcome }) => outcome)).toEqual([+ "undetermined",+ "resolved",+ ]);+ expect(edge.resolution).toEqual({+ status: "conditional",+ image: "Contents/MacOS/b/lib.dylib",+ });+ expect(edge.candidates[0]).not.toHaveProperty("platform_basis");+ expect(trace.edges.map(({ loader }) => loader)).toContain(+ "Contents/MacOS/b/lib.dylib",+ );+ expect(trace.images.map(({ path }) => path)).toContain(+ "Contents/MacOS/b/libChild.dylib",+ );+ expect(trace.coverage.status).toBe("partial");+ expect(trace.limitations).toContainEqual(+ expect.stringContaining("Contents/MacOS/a/lib.dylib"),+ );+ });++ it("does not infer a platform-less image's platform when process platform is unknown", async () => {+ const trace = await traceDylibLoading(+ memoryView({+ [MAIN]: executable({+ platform: null,+ platforms: [],+ rpaths: ["@executable_path/a"],+ dependencies: [dependency("@rpath/lib.dylib")],+ }),+ "Contents/MacOS/a/lib.dylib": parsed(slice({ platform: null })),+ }),+ { roots: [MAIN] },+ );+ const edge = edgeFor(trace, MAIN, "@rpath/lib.dylib");+ expect(edge.candidates[0]).toMatchObject({+ outcome: "undetermined",+ resolved_path: "Contents/MacOS/a/lib.dylib",+ });+ expect(edge.candidates[0]).not.toHaveProperty("platform_basis");+ expect(edge.resolution).toEqual({ status: "undetermined", image: null });+ expect(trace.coverage.status).toBe("partial");+ });++ it("does not treat a selected dylib root as an executable process context", async () => {+ const library = "Contents/Frameworks/libRoot.dylib";+ const child = "Contents/Frameworks/libChild.dylib";+ const trace = await traceDylibLoading(+ memoryView({+ [library]: parsed(+ slice({+ file_type: "dylib",+ file_type_code: 6,+ platform: 1,+ platforms: [1],+ dependencies: [dependency("@loader_path/libChild.dylib")],+ }),+ ),+ [child]: parsed(slice({ platform: null })),+ }),+ { roots: [library] },+ );+ const edge = edgeFor(trace, library, "@loader_path/libChild.dylib");+ expect(edge.candidates[0]).toMatchObject({+ outcome: "undetermined",+ resolved_path: child,+ });+ expect(edge.candidates[0]).not.toHaveProperty("platform_basis");+ expect(edge.resolution).toEqual({ status: "undetermined", image: null });+ expect(trace.coverage.status).toBe("partial");+ });+});+describe("dyld load order", () => {it("loads each image once per process and reuses matching install names", async () => {const a = "Contents/Frameworks/libA.dylib";diff --git a/src/domain/apple/dylibResolution.ts b/src/domain/apple/dylibResolution.tsindex 1adfdc79f..3fdf5a518 100644--- a/src/domain/apple/dylibResolution.ts+++ b/src/domain/apple/dylibResolution.ts@@ -51,6 +51,13 @@ const dependencyCommandSchema = z.enum(["LC_LOAD_UPWARD_DYLIB",]);+const IMPLICIT_MACOS_PLATFORM = 1;+const MACOS_DYLD_IMPLICIT_PLATFORM_CPU_TYPES = new Set([+ 7, // CPU_TYPE_I386+ 0x01000007, // CPU_TYPE_X86_64+ 0x0100000c, // CPU_TYPE_ARM64, including arm64 subtypes+]);+const dependencySchema = z.strictObject({command: dependencyCommandSchema,encoding: z.enum([@@ -145,6 +152,7 @@ const candidateSchema = z.strictObject({"undetermined",]),resolved_path: z.string().nullable(),+ platform_basis: z.enum(["macos-dyld-implicit"]).optional(),});const edgeSchema = z.strictObject({@@ -227,7 +235,7 @@ interface LoadedImage {readonly slice: MachoSlice;/** Images from the process root to this image; the rpath stack, outermost first. */readonly chain: readonly string[];- /** Some edge on the chain was conditional: an unknown earlier candidate may load instead. */+ /** Some edge on the chain has unresolved candidate or platform facts. */readonly conditional: boolean;}@@ -240,6 +248,8 @@ interface ProcessContext {>;readonly searchOverrides: readonly DyldSearchOverride[];readonly environmentRoots: Set<string>;+ readonly unknownPlatformCandidates: Set<string>;+ readonly implicitMacOSPlatformCandidates: Set<string>;readonly platforms: readonly number[];readonly executable: string | null;readonly loaded: Map<string, LoadedImage>;@@ -346,47 +356,75 @@ const evaluateCandidate = async (// also admits main executables and bundles for different operations.else if (slice.file_type_code !== 6) outcome = "not-loadable";else {- const platformResult = platformLoadability(- context.platforms,- slice.platforms,- slice.file_type_code,- context.processIdentity.architecture,- );+ const platformResult = platformLoadability(context, slice);outcome =- platformResult === "compatible"+ platformResult.outcome === "compatible"? "resolved"- : platformResult === "incompatible"+ : platformResult.outcome === "incompatible"? "platform-mismatch": "undetermined";+ if (outcome === "undetermined")+ context.unknownPlatformCandidates.add(lookup.path);+ if (platformResult.basis !== undefined) {+ context.implicitMacOSPlatformCandidates.add(lookup.path);+ return {+ ...base,+ outcome,+ resolved_path: lookup.path,+ platform_basis: platformResult.basis,+ };+ }}}return { ...base, outcome, resolved_path: lookup.path };};type PlatformLoadability = "compatible" | "incompatible" | "unknown";+type PlatformLoadabilityResult = {+ readonly outcome: PlatformLoadability;+ readonly basis?: Candidate["platform_basis"];+};/** Apply dyld's documented cross-platform load cases and retain uncertain host cases. */const platformLoadability = (- processPlatforms: readonly number[],- imagePlatforms: readonly number[],- fileType: number,- architecture: string,-): PlatformLoadability => {- if (processPlatforms.length === 0 || imagePlatforms.length === 0)- return "unknown";+ context: Pick<ProcessContext, "platforms" | "executable">,+ image: MachoSlice,+): PlatformLoadabilityResult => {+ const { platforms: processPlatforms } = context;+ const { file_type_code: fileType, platforms: imagePlatforms } = image;+ let effectiveImagePlatforms = imagePlatforms;+ let basis: Candidate["platform_basis"];+ if (imagePlatforms.length === 0) {+ // macOS dyld supplies an implicit macOS platform to old dylibs on these+ // CPU types. Keep the parsed platform facts untouched; this is only the+ // compatibility interpretation used for an explicitly macOS process.+ if (+ context.executable !== null &&+ processPlatforms.length === 1 &&+ processPlatforms[0] === IMPLICIT_MACOS_PLATFORM &&+ MACOS_DYLD_IMPLICIT_PLATFORM_CPU_TYPES.has(image.cpu_type)+ ) {+ effectiveImagePlatforms = [IMPLICIT_MACOS_PLATFORM];+ basis = "macos-dyld-implicit";+ } else return { outcome: "unknown" };+ }+ if (processPlatforms.length === 0) return { outcome: "unknown" };const outcomes = processPlatforms.map((processPlatform) =>imageLoadabilityForPlatform(processPlatform,- imagePlatforms,+ effectiveImagePlatforms,fileType,- architecture,+ image.architecture,),);if (outcomes.every((outcome) => outcome === "compatible"))- return "compatible";+ return { outcome: "compatible", ...(basis === undefined ? {} : { basis }) };if (outcomes.every((outcome) => outcome === "incompatible"))- return "incompatible";- return "unknown";+ return {+ outcome: "incompatible",+ ...(basis === undefined ? {} : { basis }),+ };+ return { outcome: "unknown", ...(basis === undefined ? {} : { basis }) };};const imageLoadabilityForPlatform = (@@ -572,7 +610,7 @@ const traceProcess = async (context.loaded.set(image, {slice,chain: [...current.chain, image],- // dyld may load an unknown earlier candidate instead of this fallback.+ // A modeled earlier search uncertainty can make this image conditional.conditional:current.conditional || edge.resolution.status === "conditional",});@@ -589,6 +627,69 @@ const traceProcess = async (return edges;};+const projectTraceResult = (input: {+ readonly images: ReadonlyMap<string, MachoImageFacts>;+ readonly roots: DylibTrace["roots"];+ readonly rootSlices: readonly TracedRootSlice[];+ readonly edges: readonly Edge[];+ readonly withoutArchitecture: readonly string[];+ readonly environmentRoots: ReadonlySet<string>;+ readonly unknownPlatformCandidates: ReadonlySet<string>;+ readonly implicitMacOSPlatformCandidates: ReadonlySet<string>;+}): DylibTrace => {+ const reported = [...input.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: input.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: [...input.edges],+ findings: deriveFindings(input.edges, input.rootSlices),+ coverage: {+ status:+ unparsed.length === 0 &&+ input.withoutArchitecture.length === 0 &&+ input.environmentRoots.size === 0 &&+ input.unknownPlatformCandidates.size === 0+ ? "complete"+ : "partial",+ unparsed_images: unparsed,+ roots_without_architecture: [...input.withoutArchitecture],+ },+ limitations: [+ ...DYLIB_RESOLUTION_LIMITATIONS,+ ...(input.environmentRoots.size === 0+ ? []+ : [+ `Roots ${[...input.environmentRoots].join(", ")} request applicable image-selection inputs through LC_DYLD_ENVIRONMENT that are not modeled; affected dependencies or inserted images remain uncertain.`,+ ]),+ ...(input.unknownPlatformCandidates.size === 0+ ? []+ : [+ `In-root dylib candidates ${[...input.unknownPlatformCandidates].sort(compare).join(", ")} have unknown platform compatibility and are not treated as incompatible. Their dependent graphs may be incomplete.`,+ ]),+ ...(input.implicitMacOSPlatformCandidates.size === 0+ ? []+ : [+ `In-root dylib candidates ${[...input.implicitMacOSPlatformCandidates].sort(compare).join(", ")} have no observed platform load command; macOS compatibility was derived from dyld's implicit-platform rule for an executable root with explicit macOS platform and a supported CPU type. Reported platform facts remain unchanged.`,+ ]),+ ],+ };+};+/** Trace dyld load paths from each process root through the analyzed root. */export const traceDylibLoading = async (view: DylibTreeView,@@ -608,6 +709,8 @@ export const traceDylibLoading = async (const edges: Edge[] = [];const withoutArchitecture: string[] = [];const environmentRoots = new Set<string>();+ const unknownPlatformCandidates = new Set<string>();+ const implicitMacOSPlatformCandidates = new Set<string>();for (const root of request.roots) {const facts = await view.image(root);images.set(root, facts);@@ -647,6 +750,8 @@ export const traceDylibLoading = async (},searchOverrides,environmentRoots,+ unknownPlatformCandidates,+ implicitMacOSPlatformCandidates,platforms: slice.platforms,executable,loaded: new Map(),@@ -659,46 +764,16 @@ export const traceDylibLoading = async ();}}- 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 {+ return projectTraceResult({+ images,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) : [],- })),+ rootSlices,edges,- findings: deriveFindings(edges, rootSlices),- coverage: {- status:- unparsed.length === 0 &&- withoutArchitecture.length === 0 &&- environmentRoots.size === 0- ? "complete"- : "partial",- unparsed_images: unparsed,- roots_without_architecture: withoutArchitecture,- },- limitations: [- ...DYLIB_RESOLUTION_LIMITATIONS,- ...(environmentRoots.size === 0- ? []- : [- `Roots ${[...environmentRoots].join(", ")} request applicable image-selection inputs through LC_DYLD_ENVIRONMENT that are not modeled; affected dependencies or inserted images remain uncertain.`,- ]),- ],- };+ withoutArchitecture,+ environmentRoots,+ unknownPlatformCandidates,+ implicitMacOSPlatformCandidates,+ });};const withoutDependencies = (