Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
feat(artifacts): add approved native DMG traversal
morluto24d000a76e3f
diff --git a/src/application/ArtifactInventory.ts b/src/application/ArtifactInventory.tsindex 2147a5282..32a66ad9f 100644--- a/src/application/ArtifactInventory.ts+++ b/src/application/ArtifactInventory.ts@@ -17,6 +17,7 @@ import {import { DirectoryArtifactReader } from "../artifacts/DirectoryArtifactReader.js";import { ZipArtifactReader } from "../artifacts/ZipArtifactReader.js";import { MachOSliceArtifactReader } from "../artifacts/MachOSliceArtifactReader.js";+import { NativeDmgArtifactReader } from "../artifacts/NativeDmgArtifactReader.js";import { streamChunkToBuffer } from "../artifacts/StreamBytes.js";import {artifactInventoryResultSchema,@@ -49,6 +50,17 @@ interface InventoryPageInput {readonly edgeLimit: number;}+/** Per-request authority combined with operator-owned native mount policy. */+export interface ArtifactNativeMountPolicy {+ readonly nativeMountApproved: boolean;+ readonly nativeMountEnabled: boolean;+}++const NATIVE_MOUNT_DISABLED: ArtifactNativeMountPolicy = {+ nativeMountApproved: false,+ nativeMountEnabled: false,+};+/** Immutable inventory produced by one complete artifact scan. */export interface ArtifactInventorySnapshot {readonly manifest: ArtifactInventoryResult["manifest"];@@ -68,8 +80,14 @@ export const inventoryArtifact = async (limits: ArtifactLimits,page: InventoryPageInput,signal?: AbortSignal,+ nativeMount: ArtifactNativeMountPolicy = NATIVE_MOUNT_DISABLED,): Promise<ArtifactInventoryResult> => {- const snapshot = await scanArtifactInventory(inputPath, limits, signal);+ const snapshot = await scanArtifactInventory(+ inputPath,+ limits,+ signal,+ nativeMount,+ );return paginateArtifactInventory(snapshot, page);};@@ -78,6 +96,7 @@ export const scanArtifactInventory = async (inputPath: string,limits: ArtifactLimits,signal?: AbortSignal,+ nativeMount: ArtifactNativeMountPolicy = NATIVE_MOUNT_DISABLED,): Promise<ArtifactInventorySnapshot> => {abortIfNeeded(signal);const path = await realpath(inputPath);@@ -86,7 +105,7 @@ export const scanArtifactInventory = async (const rootDigest = metadata.isDirectory()? null: await hashReadable(createReadStream(path), limits.maxTotalBytes, signal);- const reader = await createReader(path, rootFormat);+ const reader = await createReader(path, rootFormat, nativeMount, signal);try {const { nodes, occurrences } = await scanReader(reader, limits, signal);@@ -202,6 +221,8 @@ const inventoryLimitations = (const createReader = async (path: string,format: ArtifactNode["format"],+ nativeMount: ArtifactNativeMountPolicy,+ signal?: AbortSignal,): Promise<ArtifactReader | undefined> => {switch (format) {case "directory":@@ -216,6 +237,14 @@ const createReader = async (return process.platform === "darwin"? new MachOSliceArtifactReader(path): undefined;+ case "dmg":+ if (!nativeMount.nativeMountApproved) return undefined;+ if (!nativeMount.nativeMountEnabled)+ throw new ArtifactReaderFailure(+ "unavailable",+ "Native DMG mounting is disabled by operator policy",+ );+ return NativeDmgArtifactReader.create(path, signal);default:return undefined;}@@ -235,75 +264,102 @@ const scanReader = async (const occurrenceByPath = new Map<string, MutableOccurrence>();const registry = new ArtifactPathRegistry();let totalBytes = 0;- for await (const entry of reader.entries(signal)) {- if (occurrences.length >= limits.maxEntries)- throw new ArtifactReaderFailure("limit", "Artifact entry limit exceeded");- const logicalPath = normalizeArtifactPath(entry.path, limits);- registry.add(logicalPath, entry.kind);- preflightEntry(entry, limits);- const parent = nearestParent(logicalPath, occurrenceByPath);- const occurrence = createOccurrence(- entry,- logicalPath,- parent?.occurrence_id ?? null,- );- if ((entry.kind === "file" || entry.kind === "slice") && !entry.encrypted) {- const remainingBytes = limits.maxTotalBytes - totalBytes;- if (remainingBytes <= 0)- throw new ArtifactReaderFailure(- "limit",- "Artifact total byte limit exceeded",- );- if (entry.declaredSize !== null && entry.declaredSize > remainingBytes)+ const visit = async (+ currentReader: ArtifactReader,+ prefix: string,+ ): Promise<void> => {+ for await (const entry of currentReader.entries(signal)) {+ if (occurrences.length >= limits.maxEntries)throw new ArtifactReaderFailure("limit",- "Declared artifact bytes exceed remaining cumulative limit",+ "Artifact entry limit exceeded",);- const digest = await hashReadable(- await reader.open(entry, signal),- Math.min(limits.maxEntryBytes, remainingBytes),- signal,+ const logicalPath = normalizeArtifactPath(+ prefix.length === 0 ? entry.path : `${prefix}/${entry.path}`,+ limits,+ );+ const expandableAsar =+ entry.kind === "file" &&+ logicalPath.toLowerCase().endsWith(".asar") &&+ entry.adapterKey.startsWith("/");+ registry.add(logicalPath, expandableAsar ? "directory" : entry.kind);+ preflightEntry(entry, limits);+ const parent = nearestParent(logicalPath, occurrenceByPath);+ const occurrence = createOccurrence(+ entry,+ logicalPath,+ parent?.occurrence_id ?? null,);- totalBytes += digest.bytes;if (- entry.declaredSha256 !== null &&- entry.declaredSha256 !== digest.sha256- )- throw new ArtifactReaderFailure(- "integrity",- `Artifact integrity metadata disagrees with content: ${logicalPath}`,- undefined,- {- logicalPath,- declaredSha256: entry.declaredSha256,- calculatedSha256: digest.sha256,- unpacked: entry.unpacked,- },+ (entry.kind === "file" || entry.kind === "slice") &&+ !entry.encrypted+ ) {+ const remainingBytes = limits.maxTotalBytes - totalBytes;+ if (remainingBytes <= 0)+ throw new ArtifactReaderFailure(+ "limit",+ "Artifact total byte limit exceeded",+ );+ if (entry.declaredSize !== null && entry.declaredSize > remainingBytes)+ throw new ArtifactReaderFailure(+ "limit",+ "Declared artifact bytes exceed remaining cumulative limit",+ );+ const digest = await hashReadable(+ await currentReader.open(entry, signal),+ Math.min(limits.maxEntryBytes, remainingBytes),+ signal,);- if (totalBytes > limits.maxTotalBytes)- throw new ArtifactReaderFailure(- "limit",- "Artifact total byte limit exceeded",- );- const classified =- entry.kind === "slice"- ? ({ kind: "universal-slice", format: "mach-o" } as const)- : classifyArtifactContent(logicalPath, digest.prefix);- const node = createArtifactNode({- sha256: digest.sha256,- size: digest.bytes,- kind: classified.kind,- format: classified.format,- executable: entry.executable,- contentState: "embedded",- });- nodes.set(node.artifact_id, node);- occurrence.artifact_id = node.artifact_id;- occurrence.hash_status = "verified";+ totalBytes += digest.bytes;+ if (+ entry.declaredSha256 !== null &&+ entry.declaredSha256 !== digest.sha256+ )+ throw new ArtifactReaderFailure(+ "integrity",+ `Artifact integrity metadata disagrees with content: ${logicalPath}`,+ undefined,+ {+ logicalPath,+ declaredSha256: entry.declaredSha256,+ calculatedSha256: digest.sha256,+ unpacked: entry.unpacked,+ },+ );+ if (totalBytes > limits.maxTotalBytes)+ throw new ArtifactReaderFailure(+ "limit",+ "Artifact total byte limit exceeded",+ );+ const classified =+ entry.kind === "slice"+ ? ({ kind: "universal-slice", format: "mach-o" } as const)+ : classifyArtifactContent(logicalPath, digest.prefix);+ const node = createArtifactNode({+ sha256: digest.sha256,+ size: digest.bytes,+ kind: classified.kind,+ format: classified.format,+ executable: entry.executable,+ contentState: "embedded",+ });+ nodes.set(node.artifact_id, node);+ occurrence.artifact_id = node.artifact_id;+ occurrence.hash_status = "verified";+ }+ occurrences.push(occurrence);+ occurrenceByPath.set(logicalPath, occurrence);+ if (expandableAsar) {+ const nested = new AsarArtifactReader(entry.adapterKey);+ try {+ await visit(nested, logicalPath);+ } finally {+ await nested.close();+ }+ }}- occurrences.push(occurrence);- occurrenceByPath.set(logicalPath, occurrence);- }+ };+ await visit(reader, "");return { nodes, occurrences };};diff --git a/src/application/runtime.ts b/src/application/runtime.tsindex dcef83779..9dafb2330 100644--- a/src/application/runtime.ts+++ b/src/application/runtime.ts@@ -17,7 +17,7 @@ export const createBinarySession = (): BinarySession => {return new BinarySession(new CompositeProvider([- new ArtifactProvider(),+ new ArtifactProvider(config.artifactNativeMountEnabled),new NativeMacOSProvider(),new HopperProvider(config, logger),]),diff --git a/src/artifacts/ArtifactProvider.ts b/src/artifacts/ArtifactProvider.tsindex 02a42f5ea..c9d7cc76b 100644--- a/src/artifacts/ArtifactProvider.ts+++ b/src/artifacts/ArtifactProvider.ts@@ -35,6 +35,8 @@ const IDENTITY: ProviderIdentity = Object.freeze({/** Read-only inventory and exclusively owned extraction provider. */export class ArtifactProvider implements AnalysisProvider {+ constructor(private readonly nativeMountEnabled = false) {}+readonly #capabilities: readonly CapabilityDescriptor[] = Object.freeze(ARTIFACT_TOOL_CONTRACTS.map((contract) =>Object.freeze({@@ -61,8 +63,8 @@ export class ArtifactProvider implements AnalysisProvider {timeoutMs: 120_000,}),limitations: Object.freeze([- "DMG and PKG child inventory requires a future native read-only adapter.",- "Nested containers are recorded but not recursively expanded implicitly.",+ "DMG child inventory is macOS-only and requires per-call approval plus operator policy; PKG remains root-hash-only.",+ "ASAR files discovered in filesystem-backed inventories are expanded without bulk extraction; other nested containers remain recorded only.",]),}),),@@ -77,12 +79,15 @@ export class ArtifactProvider implements AnalysisProvider {}createClient(target: BinaryTarget): AnalysisClient {- return new ArtifactClient(target);+ return new ArtifactClient(target, this.nativeMountEnabled);}}class ArtifactClient implements AnalysisClient {- constructor(private readonly target: BinaryTarget) {}+ constructor(+ private readonly target: BinaryTarget,+ private readonly nativeMountEnabled: boolean,+ ) {}async execute(operation: AnalysisOperation,@@ -144,6 +149,10 @@ class ArtifactClient implements AnalysisClient {edgeLimit: parsed.edge_limit,},options?.signal,+ {+ nativeMountApproved: parsed.native_mount_approved === true,+ nativeMountEnabled: this.nativeMountEnabled,+ },);return ok(createAnalysisExecution(result, IDENTITY, {diff --git a/src/artifacts/NativeDmgArtifactReader.ts b/src/artifacts/NativeDmgArtifactReader.tsnew file mode 100644index 000000000..03b23c8be--- /dev/null+++ b/src/artifacts/NativeDmgArtifactReader.ts@@ -0,0 +1,227 @@+import { execFile } from "node:child_process";+import { mkdtemp, rm } from "node:fs/promises";+import { tmpdir } from "node:os";+import { basename, join } from "node:path";+import type { Readable } from "node:stream";+import { promisify } from "node:util";++import { parse } from "plist";+import { z } from "zod";++import type { ArtifactCommand } from "../domain/artifactGraph.js";+import {+ ArtifactReaderFailure,+ type ArtifactEntry,+ type ArtifactReader,+} from "./ArtifactReader.js";+import { DirectoryArtifactReader } from "./DirectoryArtifactReader.js";++const execFileAsync = promisify(execFile);+const attachOutputSchema = z.object({+ "system-entities": z.array(+ z.object({+ "dev-entry": z.string().startsWith("/dev/"),+ "mount-point": z.string().optional(),+ }),+ ),+});++/** Narrow host seam for tested, shell-free hdiutil lifecycle operations. */+export interface NativeDmgHost {+ run(+ arguments_: readonly string[],+ signal?: AbortSignal,+ ): Promise<{ readonly stdout: string; readonly exitCode: number }>;+}++const systemHost: NativeDmgHost = {+ async run(arguments_, signal) {+ try {+ const { stdout } = await execFileAsync(+ "/usr/bin/hdiutil",+ [...arguments_],+ {+ encoding: "utf8",+ timeout: 120_000,+ ...(signal === undefined ? {} : { signal }),+ },+ );+ return { stdout, exitCode: 0 };+ } catch (cause: unknown) {+ if (cause instanceof Error && cause.name === "AbortError")+ throw new ArtifactReaderFailure("cancelled", "DMG operation cancelled");+ throw new ArtifactReaderFailure("format", "hdiutil rejected the DMG", {+ cause,+ });+ }+ },+};++/** Read-only macOS DMG adapter that owns attachment and reverse-order detach. */+export class NativeDmgArtifactReader implements ArtifactReader {+ readonly format = "file" as const;+ readonly #provenance: ArtifactCommand[] = [];+ #directory: DirectoryArtifactReader | undefined;+ #devices: string[] = [];+ #mountRoot: string | undefined;++ private constructor(+ private readonly path: string,+ private readonly host: NativeDmgHost,+ ) {}++ /** Verify and attach one image beneath an exclusively owned temporary root. */+ static async create(+ path: string,+ signal?: AbortSignal,+ host: NativeDmgHost = systemHost,+ ): Promise<NativeDmgArtifactReader> {+ if (process.platform !== "darwin")+ throw new ArtifactReaderFailure(+ "unavailable",+ "Native DMG traversal is available only on macOS",+ );+ const reader = new NativeDmgArtifactReader(path, host);+ await reader.attach(signal);+ return reader;+ }++ async *entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry> {+ if (this.#directory === undefined)+ throw new ArtifactReaderFailure("unavailable", "DMG is not attached");+ const prefix = basename(this.path);+ for await (const entry of this.#directory.entries(signal))+ yield { ...entry, path: `${prefix}/${entry.path}` };+ }++ open(entry: ArtifactEntry, signal?: AbortSignal): Promise<Readable> {+ if (this.#directory === undefined)+ return Promise.reject(+ new ArtifactReaderFailure("unavailable", "DMG is not attached"),+ );+ return this.#directory.open(entry, signal);+ }++ provenance(): readonly ArtifactCommand[] {+ return this.#provenance;+ }++ async close(): Promise<void> {+ let detachFailure: unknown;+ for (const device of [...this.#devices].reverse()) {+ try {+ await runChecked(this.host, ["detach", device]);+ this.#provenance.push(command(["detach", device], ["mount"]));+ } catch (cause: unknown) {+ detachFailure ??= cause;+ }+ }+ this.#devices = [];+ if (this.#mountRoot !== undefined)+ await rm(this.#mountRoot, { recursive: true, force: true }).catch(+ (cause: unknown) => {+ detachFailure ??= cause;+ },+ );+ if (detachFailure !== undefined)+ throw new ArtifactReaderFailure(+ "unavailable",+ "DMG detach or mount-root cleanup failed",+ { cause: detachFailure },+ );+ }++ async attach(signal?: AbortSignal): Promise<void> {+ await runChecked(this.host, ["verify", this.path], signal);+ this.#provenance.push(command(["verify", this.path], ["read"]));+ this.#mountRoot = await mkdtemp(join(tmpdir(), "rea-dmg-"));+ try {+ const attached = await runChecked(+ this.host,+ [+ "attach",+ "-readonly",+ "-nobrowse",+ "-plist",+ "-mountroot",+ this.#mountRoot,+ this.path,+ ],+ signal,+ );+ const parsed = attachOutputSchema.parse(parse(attached.stdout));+ this.#devices = parsed["system-entities"].map(+ (entity) => entity["dev-entry"],+ );+ if (this.#devices.length === 0)+ throw new ArtifactReaderFailure(+ "format",+ "hdiutil returned no attached devices",+ );+ for (const entity of parsed["system-entities"])+ if (+ entity["mount-point"] !== undefined &&+ !entity["mount-point"].startsWith(`${this.#mountRoot}/`)+ )+ throw new ArtifactReaderFailure(+ "path",+ "hdiutil mounted outside the owned root",+ );+ this.#provenance.push(+ command(+ [+ "attach",+ "-readonly",+ "-nobrowse",+ "-plist",+ "-mountroot",+ this.#mountRoot,+ this.path,+ ],+ ["read", "mount"],+ ),+ );+ this.#directory = new DirectoryArtifactReader(this.#mountRoot);+ } catch (cause: unknown) {+ let cleanupFailure: unknown;+ try {+ await this.close();+ } catch (cleanupCause: unknown) {+ cleanupFailure = cleanupCause;+ }+ if (cleanupFailure !== undefined)+ throw new ArtifactReaderFailure(+ "unavailable",+ "DMG attach failed and cleanup could not detach every device",+ { cause: new AggregateError([cause, cleanupFailure]) },+ );+ throw cause;+ }+ }+}++const runChecked = async (+ host: NativeDmgHost,+ arguments_: readonly string[],+ signal?: AbortSignal,+): Promise<{ readonly stdout: string; readonly exitCode: 0 }> => {+ const result = await host.run(arguments_, signal);+ if (result.exitCode !== 0)+ throw new ArtifactReaderFailure(+ "unavailable",+ `hdiutil ${arguments_[0] ?? "operation"} failed with a non-zero exit code`,+ );+ return { stdout: result.stdout, exitCode: 0 };+};++const command = (+ arguments_: readonly string[],+ effects: ArtifactCommand["effects"],+): ArtifactCommand => ({+ tool: "/usr/bin/hdiutil",+ arguments: [...arguments_],+ tool_version: null,+ executable_sha256: null,+ exit_code: 0,+ effects,+});diff --git a/src/config.ts b/src/config.tsindex 62e952170..6554bbcf0 100644--- a/src/config.ts+++ b/src/config.ts@@ -21,6 +21,7 @@ export interface AppConfig {readonly hopperLoaderArgs: readonly string[];readonly logLevel: LogLevel;readonly processExecutionPolicy: ProcessExecutionPolicy;+ readonly artifactNativeMountEnabled: boolean;readonly evidenceFilePolicy: EvidenceFilePolicy;readonly referenceSourcePolicy: ReferenceSourcePolicy;}@@ -34,6 +35,7 @@ const environmentSchema = z.object({.enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"]).default("info"),REA_PROCESS_CAPTURE_ENABLED: z.enum(["true", "false"]).default("false"),+ REA_ARTIFACT_NATIVE_MOUNT_ENABLED: z.enum(["true", "false"]).default("false"),REA_PROCESS_ALLOW_EXTERNAL_NETWORK: z.enum(["true", "false"]).default("false"),@@ -151,6 +153,8 @@ export const parseConfig = (allowExternalNetwork:parsedEnvironment.data.REA_PROCESS_ALLOW_EXTERNAL_NETWORK === "true",},+ artifactNativeMountEnabled:+ parsedEnvironment.data.REA_ARTIFACT_NATIVE_MOUNT_ENABLED === "true",evidenceFilePolicy: {roots: evidenceRoots.value,maxBytes: 64 * 1024 * 1024,diff --git a/src/contracts/artifactToolContracts.ts b/src/contracts/artifactToolContracts.tsindex c42af930d..bfe9694df 100644--- a/src/contracts/artifactToolContracts.ts+++ b/src/contracts/artifactToolContracts.ts@@ -34,6 +34,7 @@ const traversalLimitsInput = {/** Exact caller boundary for deterministic artifact inventory. */export const artifactInventoryInputSchema = z.object({+ native_mount_approved: z.boolean().default(false),...pageInput,...traversalLimitsInput,});diff --git a/tests/config.test.ts b/tests/config.test.tsindex ab86eadce..4c2322e7a 100644--- a/tests/config.test.ts+++ b/tests/config.test.ts@@ -47,6 +47,7 @@ describe("runtime configuration", () => {hopperTargetKind: "database",hopperLoaderArgs: ["-l", "FAT", "--aarch64", "-l", "Mach-O"],logLevel: "info",+ artifactNativeMountEnabled: false,processExecutionPolicy: {enabled: false,executableRoots: [],diff --git a/tests/nativeDmgArtifactReader.test.ts b/tests/nativeDmgArtifactReader.test.tsnew file mode 100644index 000000000..f5cae14b2--- /dev/null+++ b/tests/nativeDmgArtifactReader.test.ts@@ -0,0 +1,80 @@+import { mkdir, writeFile } from "node:fs/promises";+import { join } from "node:path";++import { build } from "plist";+import { describe, expect, it } from "vitest";++import {+ NativeDmgArtifactReader,+ type NativeDmgHost,+} from "../src/artifacts/NativeDmgArtifactReader.js";++describe("native DMG artifact reader", () => {+ it("uses plist attachment metadata and detaches returned devices", async () => {+ if (process.platform !== "darwin") return;+ const calls: string[][] = [];+ const host: NativeDmgHost = {+ async run(arguments_) {+ const args = [...arguments_];+ calls.push(args);+ if (args[0] !== "attach") return { stdout: "", exitCode: 0 };+ const mountRoot = args[args.indexOf("-mountroot") + 1];+ if (mountRoot === undefined) throw new Error("missing mount root");+ const mountPoint = join(mountRoot, "Fixture");+ await mkdir(mountPoint);+ await writeFile(join(mountPoint, "hello.txt"), "hello");+ return {+ stdout: build({+ "system-entities": [+ { "dev-entry": "/dev/disk-fixture", "mount-point": mountPoint },+ ],+ }),+ exitCode: 0,+ };+ },+ };+ const reader = await NativeDmgArtifactReader.create(+ "/tmp/image.dmg",+ undefined,+ host,+ );+ const entries = [];+ for await (const entry of reader.entries()) entries.push(entry.path);+ expect(entries).toContain("image.dmg/Fixture/hello.txt");+ await reader.close();+ expect(calls).toContainEqual(["verify", "/tmp/image.dmg"]);+ expect(calls).toContainEqual(["detach", "/dev/disk-fixture"]);+ });++ it("rejects non-zero results and surfaces detach failure during attach cleanup", async () => {+ if (process.platform !== "darwin") return;+ await expect(+ NativeDmgArtifactReader.create("/tmp/image.dmg", undefined, {+ run: () => Promise.resolve({ stdout: "", exitCode: 1 }),+ }),+ ).rejects.toThrow("non-zero exit code");++ const host: NativeDmgHost = {+ run(arguments_) {+ if (arguments_[0] === "detach")+ return Promise.reject(new Error("detach failed"));+ if (arguments_[0] !== "attach")+ return Promise.resolve({ stdout: "", exitCode: 0 });+ return Promise.resolve({+ stdout: build({+ "system-entities": [+ {+ "dev-entry": "/dev/disk-fixture",+ "mount-point": "/tmp/not-owned",+ },+ ],+ }),+ exitCode: 0,+ });+ },+ };+ await expect(+ NativeDmgArtifactReader.create("/tmp/image.dmg", undefined, host),+ ).rejects.toThrow("cleanup could not detach every device");+ });+});