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(process): harden filesystem snapshot identity and cancellation (#956)
morluto93aa9eb5c255
diff --git a/src/application/FilesystemSnapshot.test.ts b/src/application/FilesystemSnapshot.test.tsnew file mode 100644index 000000000..3725fc149--- /dev/null+++ b/src/application/FilesystemSnapshot.test.ts@@ -0,0 +1,122 @@+import { fstatSync } from "node:fs";+import {+ mkdtemp,+ lstat,+ open,+ readdir,+ rm,+ utimes,+ writeFile,+} from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";++import { expect, it } from "vitest";++import { hashFile } from "./FilesystemSnapshot.js";++const countOpenDescriptorsFor = async (path: string): Promise<number> => {+ const directory = process.platform === "linux" ? "/proc/self/fd" : "/dev/fd";+ const expected = await lstat(path);+ const descriptors = await readdir(directory);+ const matches = await Promise.all(+ descriptors.map(async (descriptor) => {+ if (!/^\d+$/u.test(descriptor)) return false;+ try {+ const stats = fstatSync(Number(descriptor));+ return stats.dev === expected.dev && stats.ino === expected.ino;+ } catch (cause: unknown) {+ if (cause instanceof Error && "code" in cause && cause.code === "EBADF")+ return false;+ throw cause;+ }+ }),+ );+ return matches.filter(Boolean).length;+};++it("does not hash a replacement file using the earlier path metadata", async () => {+ const directory = await mkdtemp(join(tmpdir(), "rea-snapshot-identity-"));+ const path = join(directory, "observed-file");+ try {+ await writeFile(path, "captured file\n");+ const expected = await lstat(path);+ await rm(path);+ await writeFile(path, "replacement with a different identity and size\n");++ await expect(hashFile(path, expected, 1_000)).resolves.toBeNull();+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+});++it("rejects a same-size rewrite even when its modification time is restored", async () => {+ const directory = await mkdtemp(join(tmpdir(), "rea-snapshot-ctime-"));+ const path = join(directory, "observed-file");+ try {+ const fixedMtime = new Date("2020-01-02T03:04:05.000Z");+ await writeFile(path, "before\n");+ await utimes(path, fixedMtime, fixedMtime);+ const expected = await lstat(path);+ await writeFile(path, "after!\n");+ await utimes(path, fixedMtime, fixedMtime);+ const rewritten = await lstat(path);++ expect(rewritten).toMatchObject({+ dev: expected.dev,+ ino: expected.ino,+ mode: expected.mode,+ size: expected.size,+ mtimeMs: expected.mtimeMs,+ });+ expect(rewritten.ctimeMs).not.toBe(expected.ctimeMs);++ await expect(hashFile(path, expected, 1_000)).resolves.toBeNull();+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+});++it("rejects cancellation for an empty file before returning its digest", async () => {+ const directory = await mkdtemp(join(tmpdir(), "rea-snapshot-empty-cancel-"));+ const path = join(directory, "observed-file");+ try {+ await writeFile(path, "");+ const expected = await lstat(path);+ const controller = new AbortController();+ controller.abort();++ await expect(+ hashFile(path, expected, 1_000, controller.signal),+ ).rejects.toMatchObject({ name: "AbortError" });+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+});++it.skipIf(process.platform === "win32")(+ "closes the opened file when cancellation arrives during open",+ async () => {+ const directory = await mkdtemp(join(tmpdir(), "rea-snapshot-cancel-"));+ const path = join(directory, "observed-file");+ try {+ await writeFile(path, "captured file\n");+ const expected = await lstat(path);+ const controller = new AbortController();+ const held = await open(path, "r");+ expect(await countOpenDescriptorsFor(path)).toBe(1);+ await held.close();+ expect(await countOpenDescriptorsFor(path)).toBe(0);+ const hashing = hashFile(path, expected, 1_000, controller.signal);+ // hashFile reaches `open` synchronously before its first suspension, so+ // this abort is observed after the descriptor is acquired and is handled+ // by the `finally` close path.+ controller.abort();++ await expect(hashing).rejects.toMatchObject({ name: "AbortError" });+ expect(await countOpenDescriptorsFor(path)).toBe(0);+ } finally {+ await rm(directory, { recursive: true, force: true });+ }+ },+);diff --git a/src/application/FilesystemSnapshot.ts b/src/application/FilesystemSnapshot.tsindex 246497d4a..4fbfe8c94 100644--- a/src/application/FilesystemSnapshot.ts+++ b/src/application/FilesystemSnapshot.ts@@ -19,6 +19,16 @@ const hasSameIdentity = (before.ino === after.ino &&(expected === "directory" ? after.isDirectory() : after.isSymbolicLink());+const hasSameFileState = (before: Stats, after: Stats): boolean =>+ before.dev === after.dev &&+ before.ino === after.ino &&+ before.isFile() &&+ after.isFile() &&+ before.mode === after.mode &&+ before.size === after.size &&+ before.mtimeMs === after.mtimeMs &&+ before.ctimeMs === after.ctimeMs;+const lstatIfPresent = async (path: string): Promise<Stats | undefined> => {try {return await lstat(path);@@ -29,18 +39,26 @@ const lstatIfPresent = async (path: string): Promise<Stats | undefined> => {}};-const hashFile = async (+/** Hash a file only when its opened descriptor still matches the captured path state. */+export const hashFile = async (path: string,+ expected: Stats,maxBytes: number,signal?: AbortSignal,): Promise<string | null> => {+ signal?.throwIfAborted();const handle = await open(path,- fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0),+ fsConstants.O_RDONLY |+ (fsConstants.O_NOFOLLOW ?? 0) |+ (fsConstants.O_NONBLOCK ?? 0),);try {+ signal?.throwIfAborted();const stats = await handle.stat();- if (!stats.isFile() || stats.size > maxBytes) return null;+ signal?.throwIfAborted();+ if (!hasSameFileState(expected, stats) || stats.size > maxBytes)+ return null;const hash = createHash("sha256");const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, maxBytes));let position = 0;@@ -57,8 +75,8 @@ const hashFile = async (position += bytesRead;}const after = await handle.stat();- if (after.size !== stats.size || after.mtimeMs !== stats.mtimeMs)- return null;+ signal?.throwIfAborted();+ if (!hasSameFileState(stats, after)) return null;return hash.digest("hex");} finally {await handle.close();@@ -110,7 +128,7 @@ export const snapshotRoots = async (if (stats.isFile()) {const sha256 =remainingBytes >= stats.size- ? await hashFile(path, remainingBytes, signal)+ ? await hashFile(path, stats, remainingBytes, signal): null;remainingBytes -= sha256 === null ? 0 : stats.size;if (sha256 === null) truncated = true;diff --git a/src/application/ProcessCaptureLifecycle.ts b/src/application/ProcessCaptureLifecycle.tsindex 1ea4b47e9..5810f5461 100644--- a/src/application/ProcessCaptureLifecycle.ts+++ b/src/application/ProcessCaptureLifecycle.ts@@ -449,6 +449,7 @@ export const resolveProcessResult = (export const prepareProcessCapture = async (scenario: ProcessScenario,signal: AbortSignal | undefined,+ captureSnapshot: typeof snapshotRoots = snapshotRoots,host: ProcessPreparationHost = systemProcessPreparationHost,): Promise<{readonly temporaryRoot: string;@@ -456,7 +457,7 @@ export const prepareProcessCapture = async (readonly before: SnapshotResult;}> => {assertNotCancelled(signal);- const before = await snapshotRoots(scenario, signal);+ const before = await captureSnapshot(scenario, signal);const temporaryRoot = await host.createTemporaryRoot();try {const runId = randomUUID();diff --git a/src/application/ProcessHarness.ts b/src/application/ProcessHarness.tsindex 822f8f989..94609cc8e 100644--- a/src/application/ProcessHarness.ts+++ b/src/application/ProcessHarness.ts@@ -233,6 +233,20 @@ const finishProcessRun = async (options: {);};+const normalizeCaptureFailure = (+ cause: unknown,+ signal: AbortSignal | undefined,+): unknown => {+ if (cause instanceof ProcessCaptureError) return cause;+ if (+ signal?.aborted === true &&+ (cause === signal.reason ||+ (cause instanceof Error && cause.name === "AbortError"))+ )+ return processCaptureCancelled();+ return cause;+};+const completeCapture = async (options: {readonly scenario: ProcessScenario;readonly hostPlatform: NodeJS.Platform;@@ -245,6 +259,7 @@ const completeCapture = async (options: {readonly interactions: readonly InteractionEvent[];readonly exit: Awaited<ReturnType<typeof awaitTerminalExit>>;readonly signal?: AbortSignal;+ readonly captureSnapshot: typeof snapshotRoots;readonly initiallyTruncated: boolean;readonly eventJournal: readonly ProcessCaptureEventJournalEntry[];readonly recordEvent: RecordProcessCaptureEvent;@@ -262,7 +277,7 @@ const completeCapture = async (options: {const samplingPartial = (await runtime.stopSampler()).partial;await settleProcessCaptureJournal(options.eventJournal);assertNotCancelled(options.signal);- const after = await snapshotRoots(scenario, options.signal);+ const after = await options.captureSnapshot(scenario, options.signal);options.recordEvent("filesystem_checkpoints", 1);const renderedFrames = await runtime.renderer.frames();const checkpoints: UnverifiedProcessCapture["filesystem_checkpoints"] = [@@ -319,10 +334,12 @@ const runProcessScenario = async (signal?: AbortSignal,hostEnvironment: Readonly<Record<string, string | undefined>> = process.env,hostPlatform: NodeJS.Platform = process.platform,+ captureSnapshot: typeof snapshotRoots = snapshotRoots,): Promise<ProcessCapture> => {const { temporaryRoot, runId, before } = await prepareProcessCapture(scenario,signal,+ captureSnapshot,);const frames: TerminalFrame[] = [];const samples: ProcessSample[] = [];@@ -377,11 +394,12 @@ const runProcessScenario = async (initiallyTruncated: before.truncated,eventJournal,recordEvent,+ captureSnapshot,...(signal === undefined ? {} : { signal }),});} catch (cause: unknown) {runtime?.terminal.kill("SIGKILL");- executionFailure = cause;+ executionFailure = normalizeCaptureFailure(cause, signal);}return finishProcessRun({runtime,@@ -401,6 +419,7 @@ export const captureProcessScenario = async (signal?: AbortSignal,platform: NodeJS.Platform = process.platform,environment: Readonly<Record<string, string | undefined>> = process.env,+ captureSnapshot: typeof snapshotRoots = snapshotRoots,): Promise<Result<ProcessCapture, ProcessCaptureError | AnalysisError>> => {const ownershipReason = processCaptureOwnershipUnavailableReason(platform);if (ownershipReason !== undefined)@@ -419,12 +438,19 @@ export const captureProcessScenario = async (environment,);return ok(- await runProcessScenario(resolvedScenario, signal, environment, platform),+ await runProcessScenario(+ resolvedScenario,+ signal,+ environment,+ platform,+ captureSnapshot,+ ),);} catch (cause: unknown) {+ const failure = normalizeCaptureFailure(cause, signal);return err(- cause instanceof ProcessCaptureError- ? cause+ failure instanceof ProcessCaptureError+ ? failure: new ProcessCaptureError("process capture failed", { cause }),);}diff --git a/tests/boundary/process/filesystemSnapshotFifoRace.test.ts b/tests/boundary/process/filesystemSnapshotFifoRace.test.tsnew file mode 100644index 000000000..14d0f77cb--- /dev/null+++ b/tests/boundary/process/filesystemSnapshotFifoRace.test.ts@@ -0,0 +1,54 @@+import { randomUUID } from "node:crypto";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { fileURLToPath } from "node:url";++import { expect, it } from "vitest";++import {+ ProviderProcessSupervisor,+ spawnOwnedProviderProcess,+} from "../../../src/process/ProviderProcess.js";+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";++it.skipIf(process.platform === "win32")(+ "does not block when an observed regular file is replaced by a FIFO",+ async () => {+ const directory = await createTestTempDirectory("rea-snapshot-fifo-");+ const probe = fileURLToPath(+ new URL(+ "../../fixtures/filesystemSnapshotFifoProbe.mjs",+ import.meta.url,+ ),+ );+ const snapshotModule = fileURLToPath(+ new URL(+ "../../../dist/application/FilesystemSnapshot.js",+ import.meta.url,+ ),+ );+ const launch = await spawnOwnedProviderProcess({+ command: process.execPath,+ arguments: [probe, snapshotModule, directory],+ runId: `rea-snapshot-fifo-${randomUUID()}`,+ cwd: tmpdir(),+ hostEnvironment: process.env,+ });+ const supervisor = new ProviderProcessSupervisor({+ ...launch,+ ownsProcessLifetime: true,+ });++ try {+ const closed = await supervisor.waitForOutputClose(2_000);+ expect(closed).toBe(true);+ expect(supervisor.snapshot().stdout.text.trim()).toBe("rejected");+ } finally {+ const stopped = await supervisor.stop({+ terminationGraceMs: 100,+ killGraceMs: 500,+ });+ expect(stopped.status).not.toBe("incomplete");+ }+ },+);diff --git a/tests/boundary/process/processCaptureLifecycle.test.ts b/tests/boundary/process/processCaptureLifecycle.test.tsindex 6e16c4524..23e1df4d4 100644--- a/tests/boundary/process/processCaptureLifecycle.test.ts+++ b/tests/boundary/process/processCaptureLifecycle.test.ts@@ -1,5 +1,5 @@import { execFile } from "node:child_process";-import { rm, symlink } from "node:fs/promises";+import { rm, symlink, writeFile } from "node:fs/promises";import { dirname, join } from "node:path";import { fileURLToPath } from "node:url";import { promisify } from "node:util";@@ -8,11 +8,15 @@ import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";import { itWithCaptureCapability } from "./processCaptureCapability.js";import { captureProcessScenario } from "../../../src/application/ProcessHarness.js";+import { snapshotRoots } from "../../../src/application/FilesystemSnapshot.js";import { parseProcessScenario } from "../../../src/domain/processCapture.js";const processFixture = fileURLToPath(new URL("../../fixtures/processFidelity.mjs", import.meta.url),);+const snapshotCancellationFixture = fileURLToPath(+ new URL("../../fixtures/processSnapshotCancellation.mjs", import.meta.url),+);const execFileAsync = promisify(execFile);itWithCaptureCapability(@@ -83,6 +87,114 @@ itWithCaptureCapability(},);+itWithCaptureCapability(+ "classifies cancellation raised by the initial filesystem snapshot",+ async () => {+ const root = await createTestTempDirectory("rea-snapshot-initial-cancel-");+ const path = join(root, "input");+ await writeFile(path, "observed\n");+ const controller = new AbortController();+ const { signal } = controller;+ const throwIfAborted = signal.throwIfAborted.bind(signal);+ Object.defineProperty(signal, "throwIfAborted", {+ value: () => {+ controller.abort();+ throwIfAborted();+ },+ });++ const result = await captureProcessScenario(+ parseProcessScenario({+ executable: process.execPath,+ working_directory: root,+ filesystem_observation_paths: [path],+ }),+ signal,+ );++ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("expected initial snapshot cancellation");+ expect(result.error).toMatchObject({+ reason: "cancelled",+ userCategory: "cancelled",+ });+ },+);++itWithCaptureCapability(+ "classifies cancellation raised by the final filesystem snapshot",+ async () => {+ const root = await createTestTempDirectory("rea-snapshot-final-cancel-");+ const controller = new AbortController();+ let initialSnapshotCompleted = false;+ const captureSnapshot: typeof snapshotRoots = async (scenario, signal) => {+ if (initialSnapshotCompleted) controller.abort();+ const snapshot = await snapshotRoots(scenario, signal);+ initialSnapshotCompleted = true;+ return snapshot;+ };+ const resultPromise = captureProcessScenario(+ parseProcessScenario({+ executable: process.execPath,+ arguments: [snapshotCancellationFixture, root],+ working_directory: dirname(snapshotCancellationFixture),+ filesystem_observation_paths: [root],+ settle_ms: 0,+ }),+ controller.signal,+ process.platform,+ process.env,+ captureSnapshot,+ );++ const result = await resultPromise;+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("expected final snapshot cancellation");+ expect(initialSnapshotCompleted).toBe(true);+ expect(result.error).toMatchObject({+ reason: "cancelled",+ userCategory: "cancelled",+ });+ },+);++itWithCaptureCapability(+ "preserves filesystem errors that are not caller cancellation",+ async () => {+ const root = await createTestTempDirectory("rea-snapshot-io-error-");+ const obstruction = join(root, "not-a-directory");+ await writeFile(obstruction, "file");+ const controller = new AbortController();+ const captureSnapshot: typeof snapshotRoots = async (scenario, signal) => {+ try {+ return await snapshotRoots(scenario, signal);+ } catch (cause: unknown) {+ controller.abort();+ throw cause;+ }+ };++ const result = await captureProcessScenario(+ parseProcessScenario({+ executable: process.execPath,+ working_directory: root,+ filesystem_observation_paths: [join(obstruction, "child")],+ }),+ controller.signal,+ process.platform,+ process.env,+ captureSnapshot,+ );++ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("expected filesystem observation failure");+ expect(result.error).toMatchObject({+ reason: "capture_failed",+ cause: { code: "ENOTDIR" },+ });+ },+);+itWithCaptureCapability("captures input, Unicode, and resize across PTY startup",async () => {diff --git a/tests/fixtures/filesystemSnapshotFifoProbe.mjs b/tests/fixtures/filesystemSnapshotFifoProbe.mjsnew file mode 100644index 000000000..de3e466b3--- /dev/null+++ b/tests/fixtures/filesystemSnapshotFifoProbe.mjs@@ -0,0 +1,23 @@+import { execFileSync } from "node:child_process";+import { lstat, unlink, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { pathToFileURL } from "node:url";++const [snapshotModulePath, directory] = process.argv.slice(2);+if (snapshotModulePath === undefined || directory === undefined)+ throw new Error(+ "Filesystem snapshot FIFO probe requires a module path and directory",+ );++const { hashFile } = await import(pathToFileURL(snapshotModulePath));+const path = join(directory, "observed-file");+await writeFile(path, "regular file\n");+const expected = await lstat(path);+await unlink(path);+execFileSync("mkfifo", [path]);+// This invokes the production lstat-to-open hashing seam with a known captured+// regular-file identity. The owner test bounds this child so an O_RDONLY FIFO+// regression cannot hang Vitest.+const digest = await hashFile(path, expected, 1_000);+if (digest !== null) throw new Error("Expected the FIFO to be rejected");+process.stdout.write("rejected\n");diff --git a/tests/fixtures/processSnapshotCancellation.mjs b/tests/fixtures/processSnapshotCancellation.mjsnew file mode 100644index 000000000..6da752d82--- /dev/null+++ b/tests/fixtures/processSnapshotCancellation.mjs@@ -0,0 +1,8 @@+import { writeFile } from "node:fs/promises";+import { join } from "node:path";++const [root] = process.argv.slice(2);+if (root === undefined)+ throw new Error("Snapshot cancellation fixture requires an observation root");++await writeFile(join(root, "created-after-start"), "x");