feat(artifacts): trace Mach-O dylib resolution in bundles

Add trace_dylib_resolution (CLI trace-dylib-resolution) to the artifact
family. For the active Mach-O, or every executable in the active .app
(the main app, XPC services, extensions, login items, helpers), it
reports which file each dylib load reaches and how.

A pure TypeScript reader decodes FAT and Mach-O load commands:
LC_LOAD/WEAK/REEXPORT/LAZY/UPWARD_DYLIB, including the newer
dylib_use_command encoding with weak, re-export, upward and delayed-init
flags, plus LC_ID_DYLIB, LC_RPATH, LC_DYLD_ENVIRONMENT and code-signature
presence. Malformed tables are reported with the failing command instead
of being guessed.

Resolution follows dyld:
- @executable_path comes from each process root;
- @loader_path comes from the loading image, or from the owner of the
  LC_RPATH entry being expanded;
- @rpath searches the loader's rpaths first, then up the load chain;
- dependencies load dependents-first in load-command order, once per
  process, and a matching install name reuses an already loaded image;
- symlinks are followed inside the analyzed root, and escapes stop.

Every candidate path is reported with its outcome. Each edge resolves to
resolved, conditional (an outside-root candidate such as /usr/lib/swift
precedes), unresolved, or undetermined. Absolute and shared-cache system
paths are never checked against the host. Derived findings cover
unresolved required or weak loads, absent earlier @rpath candidates (with
library validation left unknown), and LC_DYLD_ENVIRONMENT.

verify:macos-bundle now also:
- checks every traced image against otool -l;
- asserts each resolution status on a clang-built fixture that adds a
  missing Overrides rpath, an absolute rpath, and a delay-init library;
- compares the predicted load order of two process roots with what dyld
  loads under DYLD_PRINT_LIBRARIES.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kaoru0822
2026-10-07 10:31:17 +00:00
co-authored by Claude Opus 5.5
parent 55249704c5
commit 11b7f918c2
35 changed files with 2820 additions and 29 deletions
+40
View File
@@ -15,6 +15,7 @@ export const registerArtifactCommands = (
registerExtractionCommand(cli, logger);
registerInterfaceBuilderCommand(cli, logger);
registerAssetCatalogCommand(cli, logger);
registerDylibResolutionCommand(cli, logger);
cli.command(CLI_COMMANDS.inspectKeyedArchive, {
description:
"Inspect a Foundation keyed archive as an object-reference graph",
@@ -58,6 +59,45 @@ export const registerArtifactCommands = (
});
};
const registerDylibResolutionCommand = (
cli: CliInstance,
logger: Logger,
): void => {
cli.command(CLI_COMMANDS.traceDylibResolution, {
description:
"Trace dyld load-path resolution for a Mach-O or every executable in an app bundle",
args: z.object({
path: z.string().describe("Mach-O file or Apple .app bundle path"),
}),
options: z.object({
root: z
.array(z.string())
.optional()
.describe(
"Process root relative to the bundle or the Mach-O's directory (repeatable)",
),
architecture: z
.enum(["arm64", "arm64e", "x86_64"])
.optional()
.describe("Trace only this slice of each root"),
}),
run: ({ args, options }) =>
logCliCommand(logger, CLI_COMMANDS.traceDylibResolution, () =>
runProviderAnalysis(
args.path,
"trace_dylib_resolution",
{
...(options.root === undefined ? {} : { roots: options.root }),
...(options.architecture === undefined
? {}
: { architecture: options.architecture }),
},
logger,
),
),
});
};
const registerAssetCatalogCommand = (
cli: CliInstance,
logger: Logger,