Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(process): harden filesystem snapshot identity and cancellation (#956)

morluto93aa9eb5c255
diff --git a/src/application/FilesystemSnapshot.test.ts b/src/application/FilesystemSnapshot.test.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.mjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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");