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(firmware): recover after workspace removal failures (#1616)
Ysopwnable043fd2579d71
diff --git a/src/domain/firmware/firmwareAnalysis.ts b/src/domain/firmware/firmwareAnalysis.tsindex a7cdb3550..0ebbdc2e9 100644--- a/src/domain/firmware/firmwareAnalysis.ts+++ b/src/domain/firmware/firmwareAnalysis.ts@@ -99,6 +99,8 @@ const chunk = z.strictObject({export interface FirmwarePartialObservation {readonly kind: "firmware";readonly result: JsonValue;+ /** Completed producer data, artifact identity and analysis metadata. */+ readonly provenance?: JsonValue;}/** Portable results retain reported boundaries, unknowns and extraction lineage. */diff --git a/src/firmware/FirmwareProvider.test.ts b/src/firmware/FirmwareProvider.test.tsdeleted file mode 100644index 0f3bb0b61..000000000--- a/src/firmware/FirmwareProvider.test.ts+++ /dev/null@@ -1,98 +0,0 @@-import { describe, expect, it, vi } from "vitest";--import { projectAnalysisError } from "../domain/analysisErrorProjection.js";-import { ProviderAdapterError } from "../domain/providerAdapterError.js";-import { ProviderCleanupError } from "../domain/providerCleanupError.js";-import { err, ok } from "../domain/result.js";-import { firmwareRequestSchema } from "../domain/firmware/firmwareAnalysis.js";-import { finishFirmwareWorkspace } from "./FirmwareProvider.js";--const request = firmwareRequestSchema.parse({- operation: "extract_firmware",- input: {- path: "/tmp/firmware.bin",- output_directory: "/tmp/extracted",- },-});--const execution = ok({- result: { files: ["kept"] },- rawResult: null,- provider: { id: "unblob", name: "unblob", version: "1" },- limitations: [],- locations: [],- subject: null,-});--describe("firmware workspace cleanup", () => {- it("returns the completed extraction beside a cleanup failure and does not delete the leaked root", async () => {- const close = vi.fn(async () => {- throw new Error("cleanup failed");- });- const finished = await finishFirmwareWorkspace(- { path: "/tmp/runtime", close },- execution,- "unblob",- request,- );- expect(close).toHaveBeenCalledOnce();- if (finished.ok || !(finished.error instanceof ProviderAdapterError))- throw new Error("Expected cleanup failure");- expect(finished.error.cleanupResources).toEqual([- "/tmp/runtime",- "/tmp/extracted",- ]);- expect(finished.error.partialObservation).toEqual({- kind: "firmware",- result: { files: ["kept"] },- });- expect(finished.error.diagnostics).toEqual({ reason: "cleanup failed" });- expect(projectAnalysisError(finished.error).details).toMatchObject({- partial_observation: {- kind: "firmware",- result: { files: ["kept"] },- },- });- });-- it("does not replay a cleanup failure for a later workspace", async () => {- const failed = await finishFirmwareWorkspace(- {- path: "/tmp/runtime",- close: async () => {- throw new Error("cleanup failed");- },- },- execution,- "unblob",- request,- );- expect(failed.ok).toBe(false);- const next = await finishFirmwareWorkspace(- { path: "/tmp/next", close: async () => undefined },- execution,- "unblob",- request,- );- expect(next).toBe(execution);- });-- it("leaves an uncertain workspace recorded and does not remove it", async () => {- const close = vi.fn(async () => undefined);- const cleanup = new ProviderCleanupError(- "unblob",- ["/tmp/runtime"],- { reason: "ownership uncertain" },- { operation: "extract_firmware" },- );- const outcome = err(cleanup);- const finished = await finishFirmwareWorkspace(- { path: "/tmp/runtime", close },- outcome,- "unblob",- request,- );- expect(close).not.toHaveBeenCalled();- expect(finished).toBe(outcome);- });-});diff --git a/src/firmware/FirmwareProvider.ts b/src/firmware/FirmwareProvider.tsindex 8be790140..6f21f2288 100644--- a/src/firmware/FirmwareProvider.ts+++ b/src/firmware/FirmwareProvider.ts@@ -3,13 +3,16 @@ import { z } from "zod";import type { FirmwareAnalysisPort } from "../application/firmware/FirmwareAnalysisPort.js";import {createAnalysisExecution,+ type AnalysisExecution,type ExecutionOptions,} from "../application/AnalysisProvider.js";import {firmwareResultSchemas,type FirmwareRequest,+ type FirmwarePartialObservation,} from "../domain/firmware/firmwareAnalysis.js";import { AnalysisError } from "../domain/analysisErrorBase.js";+import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";import {AnalysisCancelledError,AnalysisInputError,@@ -18,6 +21,7 @@ import {} from "../domain/analysisErrorCore.js";import { ProviderAdapterError } from "../domain/providerAdapterError.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";+import { jsonValueSchema } from "../domain/jsonValue.js";import { err, ok } from "../domain/result.js";import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";import type { ProviderProcessSupervisor } from "../process/ProviderProcess.js";@@ -42,6 +46,37 @@ import {} from "./FirmwareReports.js";type Outcome = Awaited<ReturnType<FirmwareAnalysisPort["execute"]>>;+interface PendingFirmwareCleanup {+ supervisor?: ProviderProcessSupervisor;+ readonly root: PrivateRuntimeRoot;+ readonly engine: string;+ readonly operation: string;+}++interface FirmwareCleanupAttempt {+ readonly failure: ProviderCleanupError | undefined;+ readonly processUnverified: boolean;+}++const combineCleanupFailures = (+ failures: readonly ProviderCleanupError[],+): ProviderCleanupError | undefined => {+ if (failures.length < 2) return failures[0];+ return new ProviderCleanupError(+ "firmware",+ failures.flatMap((failure) => [...failure.cleanupResources]),+ {+ reason: "Multiple owned firmware resources could not be cleaned",+ failures: failures.map((failure) => ({+ engine: failure.providerId,+ operation: failure.operation,+ resources: [...failure.cleanupResources],+ reason: failure.diagnostics?.reason ?? failure.message,+ })),+ },+ { operation: "close_firmware", cause: new AggregateError(failures) },+ );+};const waitForPredecessor = (predecessor: Promise<void>,operation: string,@@ -67,14 +102,7 @@ const limitations = [export class FirmwareProvider implements FirmwareAnalysisPort {#tail: Promise<void> = Promise.resolve();#closed = false;- #pendingCleanup:- | {- supervisor?: ProviderProcessSupervisor;- root: PrivateRuntimeRoot;- engine: string;- operation: string;- }- | undefined;+ readonly #pendingCleanup = new Map<string, PendingFirmwareCleanup>();constructor(readonly environment: Readonly<Record<string, string | undefined>@@ -107,53 +135,71 @@ export class FirmwareProvider implements FirmwareAnalysisPort {try {if (this.#closed)return err(new AnalysisCancelledError(request.operation));- try {- await this.#retryCleanup();- } catch (cause: unknown) {- return err(- cause instanceof AnalysisError- ? cause- : new ProviderCleanupError("firmware", [], {- reason: cause instanceof Error ? cause.message : String(cause),- }),- );- }+ const cleanup = await this.#retryCleanup();+ if (cleanup.processUnverified && cleanup.failure !== undefined)+ return err(cleanup.failure);return await this.#execute(request, options);} finally {release();}}- /** Retry identity-bound cleanup before relinquishing private workspaces. */+ /** Retry every retained owner, reporting failures without discarding other roots. */async close(): Promise<void> {this.#closed = true;await this.#tail;- await this.#retryCleanup();+ const cleanup = await this.#retryCleanup();+ if (cleanup.failure !== undefined) throw cleanup.failure;}- async #retryCleanup(): Promise<void> {- const pending = this.#pendingCleanup;- if (pending === undefined) return;- const stopped = await pending.supervisor?.stop();- if (stopped?.status === "incomplete")- throw new ProviderCleanupError(- pending.engine,- [pending.root.path],- { reason: stopped.reason },- { operation: pending.operation },- );- delete pending.supervisor;- try {- await pending.root.close();- } catch (cause: unknown) {- throw new ProviderCleanupError(- pending.engine,- [pending.root.path],- { reason: cause instanceof Error ? cause.message : String(cause) },- { operation: pending.operation, cause },- );+ async #retryCleanup(): Promise<FirmwareCleanupAttempt> {+ const failures: ProviderCleanupError[] = [];+ let processUnverified = false;+ for (const [path, pending] of this.#pendingCleanup) {+ try {+ const stopped = await pending.supervisor?.stop();+ if (stopped?.status === "incomplete") {+ processUnverified = true;+ failures.push(+ new ProviderCleanupError(+ pending.engine,+ [path],+ { reason: stopped.reason },+ { operation: pending.operation },+ ),+ );+ continue;+ }+ delete pending.supervisor;+ } catch (cause: unknown) {+ processUnverified = true;+ failures.push(+ new ProviderCleanupError(+ pending.engine,+ [path],+ { reason: cause instanceof Error ? cause.message : String(cause) },+ { operation: pending.operation, cause },+ ),+ );+ continue;+ }+ try {+ await pending.root.close();+ this.#pendingCleanup.delete(path);+ } catch (cause: unknown) {+ // A verified stopped process cannot use this root. Keep ownership for+ // later removal without blocking a new operation's disjoint workspace.+ failures.push(+ new ProviderCleanupError(+ pending.engine,+ [path],+ { reason: cause instanceof Error ? cause.message : String(cause) },+ { operation: pending.operation, cause },+ ),+ );+ }}- this.#pendingCleanup = undefined;+ return { failure: combineCleanupFailures(failures), processUnverified };}async #execute(@@ -192,12 +238,12 @@ export class FirmwareProvider implements FirmwareAnalysisPort {environment: this.environment,signal,retainCleanup: (supervisor) => {- this.#pendingCleanup = {+ this.#pendingCleanup.set(ownedRoot.path, {supervisor,root: ownedRoot,engine: engineName,operation: request.operation,- };+ });},...(this.launcher === undefined ? {} : { launcher: this.launcher }),...(outputBudget === undefined@@ -386,12 +432,17 @@ export class FirmwareProvider implements FirmwareAnalysisPort {engineName,request,);- if (!finished.ok && finished.error.cleanupIncomplete && root !== undefined)- this.#pendingCleanup ??= {+ if (+ !finished.ok &&+ finished.error.cleanupIncomplete &&+ root !== undefined &&+ !this.#pendingCleanup.has(root.path)+ )+ this.#pendingCleanup.set(root.path, {root,engine: engineName,operation: request.operation,- };+ });return finished;}}@@ -429,32 +480,53 @@ export const finishFirmwareWorkspace = async (try {await root?.close();} catch (cause: unknown) {+ const cleanup = new ProviderCleanupError(+ engineName,+ [+ root?.path ?? "unknown",+ ...(outcome.ok && request.operation === "extract_firmware"+ ? [request.input.output_directory]+ : []),+ ],+ { reason: cause instanceof Error ? cause.message : String(cause) },+ {+ cause,+ operation: request.operation,+ ...(outcome.ok+ ? {+ partialObservation: completedFirmwareObservation(outcome.value),+ }+ : outcome.error.partialObservation === undefined+ ? {}+ : { partialObservation: outcome.error.partialObservation }),+ },+ );return err(- new ProviderCleanupError(- engineName,- [- root?.path ?? "unknown",- ...(outcome.ok && request.operation === "extract_firmware"- ? [request.input.output_directory]- : []),- ],- { reason: cause instanceof Error ? cause.message : String(cause) },- {- cause,- operation: request.operation,- ...(outcome.ok- ? {- partialObservation: {- kind: "firmware",- result: outcome.value.result,- },- }- : outcome.error.partialObservation === undefined- ? {}- : { partialObservation: outcome.error.partialObservation }),- },- ),+ outcome.ok+ ? cleanup+ : analysisErrorWithCleanupFailure(+ outcome.error,+ cleanup,+ request.operation,+ ),);}return outcome;};++const completedFirmwareObservation = (+ execution: AnalysisExecution,+): FirmwarePartialObservation => ({+ kind: "firmware",+ result: execution.result,+ provenance: jsonValueSchema.parse({+ raw_result: execution.rawResult,+ provider: execution.provider,+ subject: execution.subject,+ locations: execution.locations,+ limitations: execution.limitations,+ ...(execution.analysisProfile === undefined+ ? {}+ : { analysis_profile: execution.analysisProfile }),+ }),+});diff --git a/tests/boundary/firmware/firmwareIntegration.test.ts b/tests/boundary/firmware/firmwareIntegration.test.tsindex 163ee00e1..4cce5a73d 100644--- a/tests/boundary/firmware/firmwareIntegration.test.ts+++ b/tests/boundary/firmware/firmwareIntegration.test.ts@@ -324,7 +324,7 @@ it("cancels a waiting request promptly while keeping later launches behind the aawait assertFirmwareCleanup(fixture.launches);});-it("retains an uncertain worker and prevents another launch", async () => {+it("retains an uncertain worker's workspace and blocks later launches", async () => {const fixture = await firmwareFixture("cleanup-failure");const first = await fixture.service.execute("inspect_firmware_regions", {path: fixture.path,@@ -335,14 +335,22 @@ it("retains an uncertain worker and prevents another launch", async () => {});const workspace = fixture.launches[0]?.cwd;expect(workspace).toBeDefined();- if (workspace === undefined) return;+ if (workspace === undefined) throw new Error("Expected retained workspace");await access(workspace);+ const originalLaunches = [...fixture.launches];const next = await fixture.service.execute("inspect_firmware_regions", {path: fixture.path,});expect(next).toMatchObject({ ok: false, error: { cleanupIncomplete: true } });- expect(fixture.launches).toHaveLength(1);+ expect(fixture.launches).toEqual(originalLaunches);await access(workspace);+ fixture.restoreCleanup();+ const resumed = await fixture.service.execute("inspect_firmware_regions", {+ path: fixture.path,+ });+ if (!resumed.ok) throw resumed.error;+ expect(resumed.value.subject?.local_path).toBe(fixture.path);+ await assertFirmwareCleanup(fixture.launches);});it("accepts another build on the verified release line and reports it", async () => {diff --git a/tests/boundary/firmware/firmwareWorkspaceRecovery.test.ts b/tests/boundary/firmware/firmwareWorkspaceRecovery.test.tsnew file mode 100644index 000000000..686928a12--- /dev/null+++ b/tests/boundary/firmware/firmwareWorkspaceRecovery.test.ts@@ -0,0 +1,164 @@+import { access, chmod, readFile } from "node:fs/promises";+import { join } from "node:path";+import { createHash } from "node:crypto";+import { expect, it } from "vitest";+import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";++import { toolContract } from "../../../src/contracts/toolContracts.js";+import { firmwareResultSchemas } from "../../../src/domain/firmware/firmwareAnalysis.js";+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";+import { ToolResultDelivery } from "../../../src/server/toolResult.js";+import {+ assertFirmwareCleanup,+ firmwareFixture,+} from "../../fixtures/firmware/provider.js";++it.skipIf(process.platform !== "linux" || process.getuid?.() === 0)(+ "retains completed extractions and retries all workspaces without blocking stopped-worker operations",+ async () => {+ const fixture = await firmwareFixture("workspace-cleanup-failure");+ const sourceBytes = await readFile(fixture.path);+ const sourceSha256 = createHash("sha256").update(sourceBytes).digest("hex");+ const workspaces = new Set<string>();+ try {+ for (const output of [+ fixture.output,+ join(fixture.root, "second-output"),+ ]) {+ const extracted = await fixture.service.execute("extract_firmware", {+ path: fixture.path,+ output_directory: output,+ range: { offset: 2, length: 4 },+ });+ const workspace = fixture.launches.at(-1)?.cwd;+ if (workspace === undefined)+ throw new Error("Expected owned workspace");+ expect(workspaces.has(workspace)).toBe(false);+ workspaces.add(workspace);+ if (extracted.ok) throw new Error("Expected workspace removal failure");+ expect(extracted.error.cleanupIncomplete).toBe(true);+ const partial = extracted.error.partialObservation;+ if (+ partial === undefined ||+ !("kind" in partial) ||+ partial.kind !== "firmware"+ )+ throw new Error("Expected completed firmware observation");+ expect(partial.provenance).toMatchObject({+ subject: {+ format: "file",+ path: fixture.path,+ sha256: sourceSha256,+ },+ provider: { id: "unblob", version: "26.6.4" },+ raw_result: {+ report: expect.any(Array),+ execution: { exit_code: 0 },+ },+ locations: [{ kind: "file-offset-range", start: 2, end: 6 }],+ });+ const result = firmwareResultSchemas.extract_firmware.parse(+ partial.result,+ );+ expect(result.selection).toEqual({+ offset: 2,+ length: 4,+ sha256: createHash("sha256")+ .update(sourceBytes.subarray(2, 6))+ .digest("hex"),+ });+ const file = result.files[0];+ if (file === undefined)+ throw new Error("Expected published extracted file");+ expect(await readFile(file.path, "utf8")).toBe("firmware=true\n");+ expect(extracted.error.cleanupResources).toContain(workspace);+ await access(workspace);+ const delivered = new ToolResultDelivery(+ STDIO_DEFAULT_MAX_BUFFER_SIZE,+ ).toCallToolResult(extracted, toolContract("extract_firmware"));+ expect(delivered.isError).toBe(true);+ expect(delivered.structuredContent).toMatchObject({+ error: {+ details: {+ partial_observation: {+ kind: "firmware",+ result,+ provenance: partial.provenance,+ },+ },+ },+ });++ const inspected = await fixture.service.execute(+ "inspect_firmware_regions",+ {+ path: fixture.path,+ },+ );+ if (!inspected.ok) throw inspected.error;+ expect(inspected.value.subject?.local_path).toBe(fixture.path);+ expect(+ firmwareResultSchemas.inspect_firmware_regions.parse(+ inspected.value.normalized_result,+ ).regions[0]?.signature,+ ).toBe("gzip");+ }+ await expect(fixture.close()).rejects.toMatchObject({+ cleanupResources: expect.arrayContaining([...workspaces]),+ });+ for (const workspace of workspaces) await access(workspace);+ } finally {+ for (const workspace of workspaces)+ await chmod(join(workspace, "cleanup-blocked"), 0o700);+ await fixture.close();+ }+ await assertFirmwareCleanup(fixture.launches);+ expect(await readFile(fixture.path)).toEqual(sourceBytes);+ for (const output of [fixture.output, join(fixture.root, "second-output")])+ expect(await readFile(join(output, "rootfs/config"), "utf8")).toBe(+ "firmware=true\n",+ );+ },+);++it.skipIf(process.platform !== "linux" || process.getuid?.() === 0)(+ "preserves the report failure alongside a workspace removal failure",+ async () => {+ const fixture = await firmwareFixture(+ "workspace-cleanup-failure-malformed",+ );+ let workspace: string | undefined;+ try {+ const failed = await fixture.service.execute("extract_firmware", {+ path: fixture.path,+ output_directory: fixture.output,+ });+ workspace = fixture.launches.at(-1)?.cwd;+ if (failed.ok || workspace === undefined)+ throw new Error("Expected both report and cleanup failures");+ expect(projectAnalysisError(failed.error)).toMatchObject({+ code: "cleanup_incomplete",+ details: {+ diagnostics: {+ primary_error: { code: "unreadable_output" },+ cleanup_error: {+ code: "cleanup_incomplete",+ details: {+ diagnostics: { reason: expect.stringContaining("EACCES") },+ },+ },+ },+ resources: expect.arrayContaining([workspace]),+ },+ });+ await expect(access(fixture.output)).rejects.toMatchObject({+ code: "ENOENT",+ });+ } finally {+ if (workspace !== undefined)+ await chmod(join(workspace, "cleanup-blocked"), 0o700);+ await fixture.close();+ }+ await assertFirmwareCleanup(fixture.launches);+ },+);diff --git a/tests/fixtures/firmware/producer.mjs b/tests/fixtures/firmware/producer.mjsindex 3c079c831..6654c4941 100644--- a/tests/fixtures/firmware/producer.mjs+++ b/tests/fixtures/firmware/producer.mjs@@ -1,5 +1,5 @@import { createHash } from "node:crypto";-import { mkdir, readFile, writeFile, symlink } from "node:fs/promises";+import { chmod, mkdir, readFile, writeFile, symlink } from "node:fs/promises";import { join } from "node:path";const args = process.argv.slice(2);const mode = process.env.REA_FIRMWARE_FIXTURE_MODE;@@ -125,8 +125,19 @@ if (args.includes("--version")) {];await writeFile(reportPath,- mode === "malformed" ? "[" : JSON.stringify(records),+ mode === "malformed" || mode === "workspace-cleanup-failure-malformed"+ ? "["+ : JSON.stringify(records),);if (mode === "dependency") process.exitCode = 1;+ if (+ mode === "workspace-cleanup-failure" ||+ mode === "workspace-cleanup-failure-malformed"+ ) {+ const blocked = join(process.cwd(), "cleanup-blocked");+ await mkdir(blocked);+ await writeFile(join(blocked, "retained"), "owned workspace bytes");+ await chmod(blocked, 0);+ }}}diff --git a/tests/fixtures/firmware/provider.ts b/tests/fixtures/firmware/provider.tsindex b6e32b9da..5b73226c5 100644--- a/tests/fixtures/firmware/provider.ts+++ b/tests/fixtures/firmware/provider.ts@@ -5,6 +5,7 @@ import { expect, onTestFinished } from "vitest";import { createFirmwareAnalysisProvider } from "../../../src/composition/firmware.js";import { FirmwareAnalysisService } from "../../../src/application/firmware/FirmwareAnalysisService.js";import { spawnOwnedProviderProcess } from "../../../src/process/ProviderProcess.js";+import { cleanupOwnedProcessGroup } from "../../../src/process/ProcessOwnership.js";import { createTestTempDirectory } from "../temporaryDirectory.js";/** Exercise real subprocess ownership with synthetic pinned producer representations. */@@ -18,6 +19,7 @@ export const firmwareFixture = async (mode = "normal", banner?: string) => {pid: number | undefined;args: readonly string[];}[] = [];+ let cleanupUnverified = mode === "cleanup-failure";const provider = createFirmwareAnalysisProvider({...process.env,@@ -54,21 +56,29 @@ export const firmwareFixture = async (mode = "normal", banner?: string) => {args: options.arguments,});if (mode === "cleanup-failure") {- onTestFinished(async () => {- if (options.cwd !== undefined)- await rm(options.cwd, { recursive: true, force: true });- });return {...spawned,- cleanup: async () => ({- cleaned: false,- reason: "injected ownership failure",- }),+ cleanup: () =>+ cleanupUnverified+ ? Promise.resolve({+ cleaned: false,+ reason: "injected ownership failure",+ })+ : cleanupOwnedProcessGroup(spawned.ownership),};}return spawned;},);+ const close = async () => {+ if (provider.close === undefined)+ throw new Error("Expected firmware provider cleanup capability");+ await provider.close();+ };+ onTestFinished(async () => {+ cleanupUnverified = false;+ await close();+ });return {provider,service: new FirmwareAnalysisService(provider),@@ -76,6 +86,10 @@ export const firmwareFixture = async (mode = "normal", banner?: string) => {output: join(root, "output"),root,launches,+ close,+ restoreCleanup: () => {+ cleanupUnverified = false;+ },};};