Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
refactor(firmware): group layered source and verification (#878)
ysopwnable507e8b3c7be7
diff --git a/docs/capability-migration.md b/docs/capability-migration.mdindex 00205397b..278cd5e5f 100644--- a/docs/capability-migration.md+++ b/docs/capability-migration.md@@ -224,3 +224,20 @@ explicit downloader and fixed manifest belong to `scripts/fixtures/android/`.`tests/fixtures/android/`, with matching boundary and composition ownership. RealJADX CLI/MCP parity requires the fixed APK and existing audited JAR; syntheticprotocol/cancellation success does not establish that engine or an unverified host.++## Firmware layer and verification ownership++Firmware workflows and their existing typed port live in+`src/application/firmware/`, pure request/result semantics in+`src/domain/firmware/`, and named contracts in `src/contracts/firmware/`.+`src/firmware/` keeps producer commands, report parsing, source copies, publication+and cleanup; `src/composition/firmware.ts` supplies a fresh typed factory.++The real lane belongs to `scripts/verify/firmware/analysis.mjs`; the fixture runner+and its unchanged Python producer belong together in `scripts/fixtures/firmware/`.+The npm command names and selected `REA_FIRMWARE_FIXTURE_ROOT` are unchanged. The+runner retains its working-directory-relative default; the verifier retains its+repository-root default. Both point to `_reference/firmware-integration/generated`+when invoked through the documented npm commands. Optional ext4/Ghidra lanes keep+their own prerequisites. Source-fixture generation and synthetic producer tests+do not establish real Binwalk/Unblob analysis or another host's execution support.diff --git a/docs/testing.md b/docs/testing.mdindex 2f919b1fb..5777d973d 100644--- a/docs/testing.md+++ b/docs/testing.md@@ -429,6 +429,12 @@ unknown chunks, depth limits and extracted child digests. The optionalNeither optional toolchain is a base-lane prerequisite. See[firmware analysis](firmware-analysis.md) for limits and unverified formats.+The real entrypoint is `scripts/verify/firmware/analysis.mjs`; the fixture runner+and unchanged Python producer belong together in `scripts/fixtures/firmware/`.+Producer fixtures and boundaries remain in `tests/fixtures/firmware/` and+`tests/boundary/firmware/`. Source-fixture generation proves the runner and+independent oracle; actual Binwalk/Unblob CLI/MCP proof requires selected tools.+### JavaScript source recoveryBuild once with `npm run build:cached`, then run `npm run verify:javascript:recovery`.diff --git a/package.json b/package.jsonindex 6330c6bb4..518f17955 100644--- a/package.json+++ b/package.json@@ -140,8 +140,8 @@"verify:javascript:digests": "npm run build:cached && node scripts/verify-large-javascript-digests.mjs","verify:application-workflows": "npm run build:cached && node scripts/verify-local-application-workflows.mjs","verify:managed": "npm run build:cached && node scripts/verify-managed-conformance.mjs",- "verify:firmware": "npm run build:cached && node scripts/verify-real-firmware.mjs",- "fixtures:firmware": "node scripts/generate-firmware-fixtures.mjs",+ "verify:firmware": "npm run build:cached && node scripts/verify/firmware/analysis.mjs",+ "fixtures:firmware": "node scripts/fixtures/firmware/generate.mjs","verify:android": "npm run build:cached && node scripts/verify/android/analysis.mjs","fixtures:android": "node scripts/fixtures/android/fetch.mjs","verify:agent": "npm run build:cached && node scripts/verify-agent-experience.mjs",diff --git a/scripts/generate-firmware-fixtures.mjs b/scripts/fixtures/firmware/generate.mjssimilarity index 93%rename from scripts/generate-firmware-fixtures.mjsrename to scripts/fixtures/firmware/generate.mjsindex e19ac1af1..3fe2dc07a 100644--- a/scripts/generate-firmware-fixtures.mjs+++ b/scripts/fixtures/firmware/generate.mjs@@ -34,7 +34,7 @@ const ext4 =: [];for (const command of ext4) await exec(command, ["-V"]);const generated = await exec(process.env.REA_FIRMWARE_PYTHON ?? "python3", [- fileURLToPath(new URL("./lib/generate-firmware-fixture.py", import.meta.url)),+ fileURLToPath(new URL("./generate.py", import.meta.url)),root,process.env.REA_FIRMWARE_CC ?? "cc",...ext4,diff --git a/scripts/lib/generate-firmware-fixture.py b/scripts/fixtures/firmware/generate.pysimilarity index 100%rename from scripts/lib/generate-firmware-fixture.pyrename to scripts/fixtures/firmware/generate.pydiff --git a/scripts/lib/catalog-core.mjs b/scripts/lib/catalog-core.mjsindex 470441005..3e719e600 100644--- a/scripts/lib/catalog-core.mjs+++ b/scripts/lib/catalog-core.mjs@@ -43,7 +43,7 @@ const SOURCE_PATHS = {nativeContracts: "dist/contracts/nativeToolContracts.js",artifactContracts: "dist/contracts/artifactToolContracts.js",managedContracts: "dist/contracts/managedToolContracts.js",- firmwareContracts: "dist/contracts/firmwareToolContracts.js",+ firmwareContracts: "dist/contracts/firmware/firmwareToolContracts.js",firmwareProvider: "dist/firmware/FirmwareRelease.js",androidContracts: "dist/contracts/android/androidToolContracts.js",androidProvider: "dist/android/JadxRelease.js",diff --git a/scripts/verify-real-firmware.mjs b/scripts/verify/firmware/analysis.mjssimilarity index 97%rename from scripts/verify-real-firmware.mjsrename to scripts/verify/firmware/analysis.mjsindex a811e99b7..f72a78b4a 100644--- a/scripts/verify-real-firmware.mjs+++ b/scripts/verify/firmware/analysis.mjs@@ -14,12 +14,12 @@ import { fileURLToPath } from "node:url";import { promisify } from "node:util";import { Client } from "@modelcontextprotocol/client";import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";-import { firmwareResultSchemas } from "../dist/domain/firmwareAnalysis.js";-import { parseEvidence } from "../dist/domain/evidence.js";-import { hashFirmwareFile } from "../dist/firmware/FirmwareFiles.js";+import { firmwareResultSchemas } from "../../../dist/domain/firmware/firmwareAnalysis.js";+import { parseEvidence } from "../../../dist/domain/evidence.js";+import { hashFirmwareFile } from "../../../dist/firmware/FirmwareFiles.js";const exec = promisify(execFile);-const repository = resolve(dirname(fileURLToPath(import.meta.url)), "..");+const repository = resolve(dirname(fileURLToPath(import.meta.url)), "../../..");const entrypoint = resolve(process.env.REA_FIRMWARE_TEST_ENTRYPOINT ??join(repository, "scripts/rea.mjs"),diff --git a/src/application/FirmwareAnalysisPort.ts b/src/application/firmware/FirmwareAnalysisPort.tssimilarity index 56%rename from src/application/FirmwareAnalysisPort.tsrename to src/application/firmware/FirmwareAnalysisPort.tsindex 5b21e6e8f..a82d6c994 100644--- a/src/application/FirmwareAnalysisPort.ts+++ b/src/application/firmware/FirmwareAnalysisPort.ts@@ -1,10 +1,10 @@import type {AnalysisExecution,ExecutionOptions,-} from "./AnalysisProvider.js";-import type { FirmwareRequest } from "../domain/firmwareAnalysis.js";-import type { AnalysisError } from "../domain/analysisErrorBase.js";-import type { Result } from "../domain/result.js";+} from "../AnalysisProvider.js";+import type { FirmwareRequest } from "../../domain/firmware/firmwareAnalysis.js";+import type { AnalysisError } from "../../domain/analysisErrorBase.js";+import type { Result } from "../../domain/result.js";/** File-oriented firmware engines; executable admission remains a separate operation. */export interface FirmwareAnalysisPort {diff --git a/src/application/FirmwareAnalysisService.ts b/src/application/firmware/FirmwareAnalysisService.tssimilarity index 79%rename from src/application/FirmwareAnalysisService.tsrename to src/application/firmware/FirmwareAnalysisService.tsindex 6fcc4ad92..eac38240b 100644--- a/src/application/FirmwareAnalysisService.ts+++ b/src/application/firmware/FirmwareAnalysisService.ts@@ -1,18 +1,18 @@-import type { ExecutionOptions } from "./AnalysisProvider.js";+import type { ExecutionOptions } from "../AnalysisProvider.js";import type { FirmwareAnalysisPort } from "./FirmwareAnalysisPort.js";import {firmwareRequestSchema,type FirmwareOperation,-} from "../domain/firmwareAnalysis.js";+} from "../../domain/firmware/firmwareAnalysis.js";import {AnalysisCancelledError,AnalysisInputError,AnalysisOutputError,-} from "../domain/analysisErrorCore.js";-import type { AnalysisError } from "../domain/analysisErrorBase.js";-import { createEvidence, type Evidence } from "../domain/evidence.js";-import { jsonObjectSchema } from "../domain/jsonValue.js";-import { err, ok, type Result } from "../domain/result.js";+} from "../../domain/analysisErrorCore.js";+import type { AnalysisError } from "../../domain/analysisErrorBase.js";+import { createEvidence, type Evidence } from "../../domain/evidence.js";+import { jsonObjectSchema } from "../../domain/jsonValue.js";+import { err, ok, type Result } from "../../domain/result.js";/** Shared CLI/MCP validation and Evidence composition for arbitrary firmware files. */export class FirmwareAnalysisService {diff --git a/src/cli/firmwareCommands.ts b/src/cli/firmwareCommands.tsindex dcaf9f6f4..961b44386 100644--- a/src/cli/firmwareCommands.ts+++ b/src/cli/firmwareCommands.ts@@ -1,10 +1,10 @@import { z } from "incur";-import { FirmwareAnalysisService } from "../application/FirmwareAnalysisService.js";+import { FirmwareAnalysisService } from "../application/firmware/FirmwareAnalysisService.js";import { createFirmwareAnalysisProvider } from "../composition/firmware.js";import { CLI_COMMANDS } from "../cliCommandNames.js";import { logCliCommand } from "../cliLogging.js";import { projectAnalysisError } from "../domain/analysisErrorProjection.js";-import type { FirmwareOperation } from "../domain/firmwareAnalysis.js";+import type { FirmwareOperation } from "../domain/firmware/firmwareAnalysis.js";import type { Logger } from "../logger.js";import type { CliInstance } from "./types.js";import { withCommandCancellation } from "./commandCancellation.js";diff --git a/src/composition/firmware.ts b/src/composition/firmware.tsindex d2cca7dd9..f3bed0293 100644--- a/src/composition/firmware.ts+++ b/src/composition/firmware.ts@@ -1,4 +1,4 @@-import type { FirmwareAnalysisPort } from "../application/FirmwareAnalysisPort.js";+import type { FirmwareAnalysisPort } from "../application/firmware/FirmwareAnalysisPort.js";import type { FirmwareLauncher } from "../firmware/FirmwareCommand.js";import { FirmwareProvider } from "../firmware/FirmwareProvider.js";diff --git a/src/contracts/contractSnapshot.test.ts b/src/contracts/contractSnapshot.test.tsindex 9811c71d0..7b9346e8e 100644--- a/src/contracts/contractSnapshot.test.ts+++ b/src/contracts/contractSnapshot.test.ts@@ -6,7 +6,7 @@ import { OFFICIAL_TOOL_CONTRACTS } from "./officialToolContracts.js";import { SESSION_TOOL_CONTRACTS } from "./sessionToolContracts.js";import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";-import { FIRMWARE_TOOL_CONTRACTS } from "./firmwareToolContracts.js";+import { FIRMWARE_TOOL_CONTRACTS } from "./firmware/firmwareToolContracts.js";import { ANDROID_TOOL_CONTRACTS } from "./android/androidToolContracts.js";import { MANAGED_TOOL_CONTRACTS } from "./managedToolContracts.js";import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managedWorkflowToolContracts.js";diff --git a/src/contracts/firmwareToolContracts.ts b/src/contracts/firmware/firmwareToolContracts.tssimilarity index 89%rename from src/contracts/firmwareToolContracts.tsrename to src/contracts/firmware/firmwareToolContracts.tsindex 188c6caa8..c93c8f903 100644--- a/src/contracts/firmwareToolContracts.ts+++ b/src/contracts/firmware/firmwareToolContracts.ts@@ -1,10 +1,10 @@import {firmwareInputSchemas,firmwareResultSchemas,-} from "../domain/firmwareAnalysis.js";-import type { ToolContract } from "./toolContractTypes.js";-import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";-import { toolContractMetadata } from "./toolEffects.js";+} from "../../domain/firmware/firmwareAnalysis.js";+import type { ToolContract } from "../toolContractTypes.js";+import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";+import { toolContractMetadata } from "../toolEffects.js";/** Explicit local firmware observations and extraction, backed by caller-supplied tools. */export const FIRMWARE_TOOL_CONTRACTS = [diff --git a/src/contracts/toolContracts.test.ts b/src/contracts/toolContracts.test.tsindex 05b3f10d3..e230d23d6 100644--- a/src/contracts/toolContracts.test.ts+++ b/src/contracts/toolContracts.test.ts@@ -6,7 +6,7 @@ import { SESSION_TOOL_CONTRACTS } from "./sessionToolContracts.js";import { TOOL_CONTRACTS } from "./toolContracts.js";import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";import { MANAGED_TOOL_CONTRACTS } from "./managedToolContracts.js";-import { FIRMWARE_TOOL_CONTRACTS } from "./firmwareToolContracts.js";+import { FIRMWARE_TOOL_CONTRACTS } from "./firmware/firmwareToolContracts.js";import { ANDROID_TOOL_CONTRACTS } from "./android/androidToolContracts.js";import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managedWorkflowToolContracts.js";import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.tsindex b3a2170e9..c5de12fd2 100644--- a/src/contracts/toolContracts.ts+++ b/src/contracts/toolContracts.ts@@ -1,7 +1,7 @@import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";import { ARTIFACT_TOOL_CONTRACTS } from "./artifactToolContracts.js";import { MANAGED_TOOL_CONTRACTS } from "./managedToolContracts.js";-import { FIRMWARE_TOOL_CONTRACTS } from "./firmwareToolContracts.js";+import { FIRMWARE_TOOL_CONTRACTS } from "./firmware/firmwareToolContracts.js";import { ANDROID_TOOL_CONTRACTS } from "./android/androidToolContracts.js";import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managedWorkflowToolContracts.js";import { BROWSER_PROVIDER_TOOL_CONTRACTS } from "./browserProviderToolContracts.js";diff --git a/src/domain/firmwareAnalysis.ts b/src/domain/firmware/firmwareAnalysis.tssimilarity index 97%rename from src/domain/firmwareAnalysis.tsrename to src/domain/firmware/firmwareAnalysis.tsindex 85a90731b..31bb12c3f 100644--- a/src/domain/firmwareAnalysis.ts+++ b/src/domain/firmware/firmwareAnalysis.ts@@ -1,6 +1,6 @@import { z } from "zod";-import { digestSchema } from "./digests.js";-import { jsonValueSchema } from "./jsonValue.js";+import { digestSchema } from "../digests.js";+import { jsonValueSchema } from "../jsonValue.js";const bytes = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);const range = z.strictObject({ offset: bytes, length: bytes.positive() });diff --git a/src/firmware/FirmwareFiles.ts b/src/firmware/FirmwareFiles.tsindex 92c801756..ad63b49de 100644--- a/src/firmware/FirmwareFiles.ts+++ b/src/firmware/FirmwareFiles.ts@@ -16,7 +16,7 @@ import {AnalysisInputError,AnalysisOutputError,} from "../domain/analysisErrorCore.js";-import type { FirmwareRequest } from "../domain/firmwareAnalysis.js";+import type { FirmwareRequest } from "../domain/firmware/firmwareAnalysis.js";import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";import { FIRMWARE_LIMITS } from "./FirmwareRelease.js";diff --git a/src/firmware/FirmwareProvider.ts b/src/firmware/FirmwareProvider.tsindex 6845ab60a..610c91f1c 100644--- a/src/firmware/FirmwareProvider.ts+++ b/src/firmware/FirmwareProvider.ts@@ -1,6 +1,6 @@import { join, isAbsolute } from "node:path";import { z } from "zod";-import type { FirmwareAnalysisPort } from "../application/FirmwareAnalysisPort.js";+import type { FirmwareAnalysisPort } from "../application/firmware/FirmwareAnalysisPort.js";import {createAnalysisExecution,type ExecutionOptions,@@ -8,7 +8,7 @@ import {import {firmwareResultSchemas,type FirmwareRequest,-} from "../domain/firmwareAnalysis.js";+} from "../domain/firmware/firmwareAnalysis.js";import { AnalysisError } from "../domain/analysisErrorBase.js";import {AnalysisCancelledError,diff --git a/src/firmware/FirmwarePublication.ts b/src/firmware/FirmwarePublication.tsindex db49244b8..56b011145 100644--- a/src/firmware/FirmwarePublication.ts+++ b/src/firmware/FirmwarePublication.ts@@ -4,7 +4,7 @@ import type { z } from "zod";import { SafeOutputTree } from "../artifacts/SafeOutputTree.js";import { AnalysisOutputError } from "../domain/analysisErrorCore.js";import { ProviderCleanupError } from "../domain/providerCleanupError.js";-import { firmwareResultSchemas } from "../domain/firmwareAnalysis.js";+import { firmwareResultSchemas } from "../domain/firmware/firmwareAnalysis.js";import { hashFirmwareFile, type FirmwareEntry } from "./FirmwareFiles.js";import type { normalizeUnblobReport } from "./FirmwareReports.js";diff --git a/src/server/createServer.ts b/src/server/createServer.tsindex 89a9a0098..7f3280970 100644--- a/src/server/createServer.ts+++ b/src/server/createServer.ts@@ -25,8 +25,8 @@ import { registerEnhancedTools } from "./registerEnhancedTools.js";import { registerJavaScriptRuntimeObservationTools } from "./registerJavaScriptRuntimeObservationTools.js";import { registerManagedTools } from "./registerManagedTools.js";import { registerFirmwareTools } from "./registerFirmwareTools.js";-import { FirmwareAnalysisService } from "../application/FirmwareAnalysisService.js";-import type { FirmwareAnalysisPort } from "../application/FirmwareAnalysisPort.js";+import { FirmwareAnalysisService } from "../application/firmware/FirmwareAnalysisService.js";+import type { FirmwareAnalysisPort } from "../application/firmware/FirmwareAnalysisPort.js";import { createFirmwareAnalysisProvider } from "../composition/firmware.js";import { registerAndroidTools } from "./registerAndroidTools.js";import { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js";diff --git a/src/server/registerFirmwareTools.ts b/src/server/registerFirmwareTools.tsindex 3c5f4a103..66c763bff 100644--- a/src/server/registerFirmwareTools.ts+++ b/src/server/registerFirmwareTools.ts@@ -1,9 +1,9 @@import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";import type { McpServer, ServerContext } from "@modelcontextprotocol/server";-import type { FirmwareAnalysisService } from "../application/FirmwareAnalysisService.js";+import type { FirmwareAnalysisService } from "../application/firmware/FirmwareAnalysisService.js";import { toolContract } from "../contracts/toolContracts.js";import type { ToolContract } from "../contracts/toolContractTypes.js";-import type { FirmwareOperation } from "../domain/firmwareAnalysis.js";+import type { FirmwareOperation } from "../domain/firmware/firmwareAnalysis.js";import type { Logger } from "../logger.js";import { logToolExecution } from "./toolLogging.js";import { toolRegistrationOptions } from "./toolRegistrationOptions.js";diff --git a/tests/boundary/firmware/firmwareIntegration.test.ts b/tests/boundary/firmware/firmwareIntegration.test.tsindex c94e079c7..262451714 100644--- a/tests/boundary/firmware/firmwareIntegration.test.ts+++ b/tests/boundary/firmware/firmwareIntegration.test.ts@@ -4,8 +4,8 @@ import {firmwareFixture,assertFirmwareCleanup,} from "../../fixtures/firmware/provider.js";-import { firmwareResultSchemas } from "../../../src/domain/firmwareAnalysis.js";-import { FirmwareAnalysisService } from "../../../src/application/FirmwareAnalysisService.js";+import { firmwareResultSchemas } from "../../../src/domain/firmware/firmwareAnalysis.js";+import { FirmwareAnalysisService } from "../../../src/application/firmware/FirmwareAnalysisService.js";import { FirmwareProvider } from "../../../src/firmware/FirmwareProvider.js";import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";import { toolContract } from "../../../src/contracts/toolContracts.js";diff --git a/tests/boundary/mcp/firmwareMcp.test.ts b/tests/boundary/mcp/firmwareMcp.test.tsindex 92a8a58e6..954b33a2d 100644--- a/tests/boundary/mcp/firmwareMcp.test.ts+++ b/tests/boundary/mcp/firmwareMcp.test.ts@@ -1,6 +1,6 @@import { Client, InMemoryTransport } from "@modelcontextprotocol/client";import { expect, it as test, onTestFinished } from "vitest";-import { FIRMWARE_TOOL_CONTRACTS } from "../../../src/contracts/firmwareToolContracts.js";+import { FIRMWARE_TOOL_CONTRACTS } from "../../../src/contracts/firmware/firmwareToolContracts.js";import { parseEvidence } from "../../../src/domain/evidence.js";import { createServer } from "../../../src/server/createServer.js";import { createTestBinarySession } from "../../fixtures/binarySession.js";diff --git a/tests/fixtures/firmware/provider.ts b/tests/fixtures/firmware/provider.tsindex 2c2de73ac..b6e32b9da 100644--- a/tests/fixtures/firmware/provider.ts+++ b/tests/fixtures/firmware/provider.ts@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";import { access, rm, writeFile } from "node:fs/promises";import { expect, onTestFinished } from "vitest";import { createFirmwareAnalysisProvider } from "../../../src/composition/firmware.js";-import { FirmwareAnalysisService } from "../../../src/application/FirmwareAnalysisService.js";+import { FirmwareAnalysisService } from "../../../src/application/firmware/FirmwareAnalysisService.js";import { spawnOwnedProviderProcess } from "../../../src/process/ProviderProcess.js";import { createTestTempDirectory } from "../temporaryDirectory.js";