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): keep a missing producer report distinct after exit 0 (#6008)
Kaoru0822c8d3f8f8ec4e
diff --git a/docs/firmware-analysis.md b/docs/firmware-analysis.mdindex b0f92c14d..7cbbc2692 100644--- a/docs/firmware-analysis.md+++ b/docs/firmware-analysis.md@@ -183,6 +183,9 @@ tree semantics, vulnerability scanning, emulation or hardware runtime capture.120 CPU seconds and zero core-dump allowance through `prlimit`.- JSON reports: at most **8 MiB** and valid UTF-8; malformed encoding andoversized reports fail without repairing or truncating producer data.+ Exit status 0 is not an empty result: a missing, empty, malformed or+ oversized report fails with `unreadable_output`, its `report_state`, the+ command, exit status and captured output. REA does not retry automatically.Diagnostic output is bounded with exact captured byte counts.- Default staging budget: **256 MiB** and **10,000 entries**, configurable using`max_output_bytes` / `max_output_files` (CLI `--max-output-bytes` /diff --git a/src/firmware/FirmwareCommand.ts b/src/firmware/FirmwareCommand.tsindex 1b4362c47..b677f7953 100644--- a/src/firmware/FirmwareCommand.ts+++ b/src/firmware/FirmwareCommand.ts@@ -291,7 +291,12 @@ export const runFirmwareCommand = async (context: {};};-/** Preserve tool failure diagnostics when an accepted exit 1 has no usable report. */+/**+ * Consume the report a completed command was asked to write. A successful exit+ * status is not analysis Evidence by itself: an absent, empty or malformed report+ * fails with the observed report state and command facts, without retrying or+ * substituting an empty result.+ */export const readFirmwareCommandReport = async (context: {path: string;engine: string;@@ -308,33 +313,43 @@ export const readFirmwareCommandReport = async (context: {);} catch (cause: unknown) {if (cause instanceof ArtifactReaderFailure) throw cause;- if (context.execution.exit_code === 1)- throw new ProviderAdapterError(context.engine, context.operation, {+ const { engine, operation, execution } = context;+ const reportFailure =+ cause instanceof AnalysisOutputError+ ? cause.reason+ : `Report could not be read: ${cause instanceof Error ? cause.message : String(cause)}`;+ const diagnostics = {+ ...(cause instanceof AnalysisOutputError ? cause.diagnostics : {}),+ report_path: context.path,+ report_failure: reportFailure,+ command: execution.command,+ args: execution.args,+ resource_limiter: execution.resource_limiter,+ exit_code: execution.exit_code ?? null,+ signal: execution.signal,+ stdout: execution.stdout.text,+ stderr: execution.stderr.text,+ stdout_bytes: execution.stdout.bytes,+ stderr_bytes: execution.stderr.bytes,+ };+ if (execution.exit_code === 1)+ throw new ProviderAdapterError(engine, operation, {cause,diagnostics: {reason:"Tool exited 1 without a usable analysis report; inspect stderr for startup, sandbox or dependency failures",- report_failure:- cause instanceof Error ? cause.message : String(cause),- exit_code: 1,- signal: context.execution.signal,- stdout: context.execution.stdout.text,- stderr: context.execution.stderr.text,- stdout_bytes: context.execution.stdout.bytes,- stderr_bytes: context.execution.stderr.bytes,+ ...diagnostics,},});- const diagnostics = `stdout (${context.execution.stdout.bytes} bytes): ${context.execution.stdout.text}; stderr (${context.execution.stderr.bytes} bytes): ${context.execution.stderr.text}`;- if (cause instanceof AnalysisOutputError)- throw new AnalysisOutputError(- context.operation,- `${cause.reason}; ${diagnostics}`,- { cause },- );throw new AnalysisOutputError(- context.operation,- `Tool did not produce the expected complete report: ${context.path}; ${diagnostics}`,- { cause },+ operation,+ `${engine} exited ${String(execution.exit_code)} without a usable report: ${reportFailure}`,+ {+ cause,+ diagnostics,+ userMessage: `${engine} exited successfully but left no usable report (${reportFailure}), so ${operation} produced no Evidence. A successful exit status is not an empty or complete result.`,+ remediationAction: `Review diagnostics.report_state, the exit status and captured stdout/stderr. REA did not retry or substitute an empty result. diagnostics.command and diagnostics.args record what ran; their workspace paths are REA-private and removed after the attempt, so they cannot be replayed as-is. Rerun the same REA request to check whether this is intermittent; each attempt uses a fresh workspace. If it recurs, copy the selected input bytes into a new directory and run diagnostics.command with the same flags, replacing every private path with your copy and a new report path, under the documented firmware resource limits; confirm that it writes the requested report. \`rea doctor\` checks configuration only and cannot recover this report.`,+ },);}};diff --git a/src/firmware/FirmwareFiles.ts b/src/firmware/FirmwareFiles.tsindex 1451af610..699f276e3 100644--- a/src/firmware/FirmwareFiles.ts+++ b/src/firmware/FirmwareFiles.ts@@ -188,7 +188,11 @@ export class FirmwareFileAccess {);}- /** Read a complete bounded report; oversized data is never reported as complete. */+ /**+ * Read a complete bounded report; oversized data is never reported as complete.+ * Each refusal records its observed report state, so an absent or empty report+ * is never conflated with an empty scan or a malformed one.+ */async report(path: string,operation: string,@@ -201,11 +205,14 @@ export class FirmwareFileAccess {FIRMWARE_LIMITS.reportBytes,);if (bytes === undefined)- throw new AnalysisOutputError(+ throw firmwareReportFailure(operation,+ "oversized",`Report exceeded ${FIRMWARE_LIMITS.reportBytes} bytes`,);assertArtifactReadActive(signal);+ if (bytes.length === 0)+ throw firmwareReportFailure(operation, "empty", "Report is empty");try {const value: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(@@ -214,25 +221,57 @@ export class FirmwareFileAccess {);return value;} catch (cause: unknown) {- throw new AnalysisOutputError(+ throw firmwareReportFailure(operation,+ "invalid_json","Tool report is not valid complete JSON",- { cause },+ cause,);}}).catch((cause: unknown) => {- throw firmwareAdmissionFailure(- cause,- (primary) =>- new AnalysisOutputError(operation, "Report is not a regular file", {- cause: primary,- }),+ throw mapArtifactFileFailure(cause, (primary) =>+ primary instanceof NonRegularFileReadError+ ? firmwareReportFailure(+ operation,+ "not_regular_file",+ "Report is not a regular file",+ primary,+ )+ : primary instanceof Error &&+ "code" in primary &&+ primary.code === "ENOENT"+ ? firmwareReportFailure(+ operation,+ "missing",+ "Report was not created",+ primary,+ )+ : primary,);}),);}}+/** Observed state of a producer report that cannot supply analysis Evidence. */+type FirmwareReportState =+ | "missing"+ | "empty"+ | "oversized"+ | "invalid_json"+ | "not_regular_file";++const firmwareReportFailure = (+ operation: string,+ state: FirmwareReportState,+ reason: string,+ cause?: unknown,+) =>+ new AnalysisOutputError(operation, reason, {+ cause,+ diagnostics: { report_state: state },+ });+/** Preserve admission semantics inside the same exact owner's physical outcome. */const firmwareAdmissionFailure = (cause: unknown,diff --git a/tests/boundary/firmware/firmwareIntegration.test.ts b/tests/boundary/firmware/firmwareIntegration.test.tsindex d2f1a2287..13cfadb00 100644--- a/tests/boundary/firmware/firmwareIntegration.test.ts+++ b/tests/boundary/firmware/firmwareIntegration.test.ts@@ -730,7 +730,7 @@ it("retains startup stderr when Unblob exits 1 without a report", async () => {diagnostics: {exit_code: 1,stderr: expect.stringContaining("Landlock sandbox is not available"),- report_failure: expect.stringContaining("ENOENT"),+ report_state: "missing",},},});@@ -740,25 +740,51 @@ it("retains startup stderr when Unblob exits 1 without a report", async () => {await assertFirmwareCleanup(fixture.launches);});-it("distinguishes a successful process with missing output from startup failure", async () => {- const fixture = await firmwareFixture("missing-report");- const result = await fixture.service.execute("extract_firmware", {- path: fixture.path,- output_directory: fixture.output,- });- expect(result).toMatchObject({- ok: false,- error: {- _tag: "AnalysisOutputError",- reason: expect.stringContaining("expected complete report"),- },- });- if (result.ok) throw new Error("Expected missing-output failure");- expect(projectAnalysisError(result.error)).toMatchObject({- details: { reason: expect.stringContaining("Producer forgot its report") },- });- await assertFirmwareCleanup(fixture.launches);-});+it.each([+ { operation: "inspect_firmware_regions", engine: "binwalk" },+ { operation: "extract_firmware", engine: "unblob" },+] as const)(+ "keeps $engine's missing report after exit 0 distinct from an empty result",+ async ({ operation, engine }) => {+ const fixture = await firmwareFixture("missing-report");+ const result = await fixture.service.execute(operation, {+ path: fixture.path,+ ...(operation === "extract_firmware"+ ? { output_directory: fixture.output }+ : {}),+ });+ if (result.ok) throw new Error("Expected missing-report failure");+ const error = {+ code: "unreadable_output",+ retryable: false,+ message: expect.stringContaining("not an empty or complete result"),+ details: {+ reason: `${engine} exited 0 without a usable report: Report was not created`,+ diagnostics: {+ report_state: "missing",+ report_path: expect.stringMatching(/report\.json$/),+ command: expect.any(String),+ args: expect.any(Array),+ exit_code: 0,+ signal: null,+ stderr: "Producer forgot its report\n",+ },+ },+ remediation: {+ action: expect.stringContaining("did not retry or substitute"),+ },+ };+ expect(projectAnalysisError(result.error)).toMatchObject(error);+ expect(projectAnalysisError(result.error).message).not.toContain(+ "rea doctor",+ );+ expect(+ delivery.toCallToolResult(result, toolContract(operation))+ .structuredContent,+ ).toMatchObject({ error });+ await assertFirmwareCleanup(fixture.launches);+ },+);it("cancels an owned active process and permits the next queued operation", async () => {const fixture = await firmwareFixture("stall");diff --git a/tests/boundary/firmware/firmwareReportFiles.test.ts b/tests/boundary/firmware/firmwareReportFiles.test.tsindex 69360ef25..741585672 100644--- a/tests/boundary/firmware/firmwareReportFiles.test.ts+++ b/tests/boundary/firmware/firmwareReportFiles.test.ts@@ -6,6 +6,10 @@ import {inventoryFirmwareOutput,FirmwareFileAccess,} from "../../../src/firmware/FirmwareFiles.js";+import { readFirmwareCommandReport } from "../../../src/firmware/FirmwareCommand.js";+import { FIRMWARE_LIMITS } from "../../../src/firmware/FirmwareRelease.js";+import { AnalysisError } from "../../../src/domain/analysisErrorBase.js";+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";it.each([@@ -35,6 +39,78 @@ it.each([},);+it.each([+ ["missing", "Report was not created", async () => {}],+ ["empty", "Report is empty", (path: string) => writeFile(path, "")],+ [+ "invalid_json",+ "Tool report is not valid complete JSON",+ (path: string) => writeFile(path, '[{"Analysis":'),+ ],+ [+ "oversized",+ `Report exceeded ${FIRMWARE_LIMITS.reportBytes} bytes`,+ (path: string) =>+ writeFile(path, Buffer.alloc(FIRMWARE_LIMITS.reportBytes + 1, 0x20)),+ ],+ [+ "not_regular_file",+ "Report is not a regular file",+ (path: string) => mkdir(path),+ ],+] as const)(+ "keeps report state %s after a successful exit distinct from an empty scan",+ async (state, reason, prepare) => {+ const root = await createTestTempDirectory("rea-firmware-report-");+ const path = join(root, "report.json");+ await prepare(path);+ const failure: unknown = await readFirmwareCommandReport({+ path,+ engine: "binwalk",+ operation: "inspect_firmware_regions",+ execution: {+ stdout: { text: "", bytes: 0, observedBytes: 0 },+ stderr: { text: "", bytes: 0, observedBytes: 0 },+ exit_code: 0,+ signal: null,+ command: "/opt/binwalk",+ args: ["--quiet", "--log", path, "/work/firmware.bin"],+ resource_limiter: "/usr/bin/prlimit",+ },+ files: new FirmwareFileAccess(),+ }).catch((cause: unknown) => cause);+ if (!(failure instanceof AnalysisError))+ throw new Error("Expected a typed report failure");+ const projected = projectAnalysisError(failure);+ expect(projected).toMatchObject({+ code: "unreadable_output",+ retryable: false,+ message: expect.stringContaining("not an empty or complete result"),+ details: {+ reason: `binwalk exited 0 without a usable report: ${reason}`,+ diagnostics: {+ report_state: state,+ report_path: path,+ command: "/opt/binwalk",+ args: ["--quiet", "--log", path, "/work/firmware.bin"],+ resource_limiter: "/usr/bin/prlimit",+ exit_code: 0,+ signal: null,+ stdout_bytes: 0,+ stderr_bytes: 0,+ },+ },+ });+ // Generic doctor advice is not presented as a repair for a missing report.+ expect(projected.message).not.toContain("rea doctor");+ // Recorded arguments name a removed private workspace; recovery must not+ // present them as a replayable command.+ expect(projected.remediation.action).toMatch(+ /diagnostics\.report_state.*cannot be replayed as-is.*replacing every private path/,+ );+ },+);+it("preserves valid Unicode and a literal replacement character in producer JSON", async () => {const root = await createTestTempDirectory("rea-firmware-report-");const path = join(root, "report.json");