diff --git a/.gitmodules b/.gitmodules
index 26ba5d77b..eb512836e 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,3 +1,9 @@
[submodule "third_party/jadx-headless-mcp"]
path = third_party/jadx-headless-mcp
url = https://github.com/1013503897/jadx-headless-mcp.git
+[submodule "third_party/binwalk"]
+ path = third_party/binwalk
+ url = https://github.com/ReFirmLabs/binwalk.git
+[submodule "third_party/unblob"]
+ path = third_party/unblob
+ url = https://github.com/onekey-sec/unblob.git
diff --git a/.jscpd.json b/.jscpd.json
index 033f1baed..a620363ba 100644
--- a/.jscpd.json
+++ b/.jscpd.json
@@ -9,7 +9,7 @@
".codex/**",
".devin/**",
"tests/fixtures/**",
- "third_party/jadx-headless-mcp/**",
+ "third_party/**",
"tests/conformance/**/*.c",
"tests/conformance/**/*.m",
"tests/conformance/**/*.swift",
diff --git a/.oxfmtrc.json b/.oxfmtrc.json
index ead50ecd7..633bd7bc3 100644
--- a/.oxfmtrc.json
+++ b/.oxfmtrc.json
@@ -11,6 +11,6 @@
"CHANGELOG.md",
"package-lock.json",
"_reference/**",
- "third_party/jadx-headless-mcp/**"
+ "third_party/**"
]
}
diff --git a/.oxlintrc.json b/.oxlintrc.json
index 566026a85..4fd28e0d8 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -140,6 +140,6 @@
".codex",
".devin",
".factory",
- "third_party/jadx-headless-mcp"
+ "third_party"
]
}
diff --git a/README.md b/README.md
index 3c37518d9..24c75db20 100644
--- a/README.md
+++ b/README.md
@@ -151,6 +151,8 @@ Update either installation with `rea update`.
Native binary analysis requires [Hopper](https://www.hopperapp.com/) or [Ghidra](#ghidra-analysis-provider). Hopper is separate software with its own license; its demo supports analysis with vendor-defined limits. REA can use Ghidra that you have already installed.
+Firmware region inspection and explicit extraction use caller-supplied Binwalk and Unblob on Linux. See [Firmware analysis](docs/firmware-analysis.md) for setup, provenance, resource limits and native handoff.
+
Static APK analysis uses a separately supplied headless JADX JAR and Java, with no emulator or APK execution. See [Android analysis](docs/android-analysis.md) for setup, CLI/MCP operations, coverage and public test fixtures.
Windows Ghidra support is experimental for native x86-64 PE applications on local NTFS. The package bundles native Job Object, private-DACL, and path-admission controls. See [Windows Ghidra P0](docs/windows-ghidra-p0.md) for prerequisites and verified scope.
@@ -316,6 +318,7 @@ See [native investigation](docs/native-investigation.md) for keyed archives, ins
| Native macOS utilities | 7 | Mach-O metadata, code signatures, plists, architectures, and Swift demangling without launching Hopper |
| Artifact graph | 5 | directory and package inventories, compiled Interface Builder files, Apple asset catalogs, and extraction |
| Managed PE/CLI | 7 | .NET identity, metadata, CIL instructions, native dependencies, reconstruction imports, and build comparisons |
+| Firmware | 2 | Linux firmware region inspection and explicit extraction |
| Android APK | 5 | package and manifest declarations, class search, member inventories, method decompilation, and incoming static references |
| Browser observation | 9 | page structure, network metadata, scripts, source maps, WebMCP discovery, screenshots, and capture comparisons |
| Electron analysis | 5 | renderer observation, static app mapping, and static/runtime reconciliation |
@@ -468,6 +471,8 @@ flowchart LR
REA --> Browser["Browser CDP provider"]
REA --> Android["Android static provider
headless JADX adapter"]
Android --> Runtime
+ REA --> Firmware["Firmware providers
Binwalk / Unblob adapters"]
+ Firmware --> Runtime
REA --> Process["Process capture provider"]
Runtime --> Target["Target software"]
Process --> Target
diff --git a/README_ar.md b/README_ar.md
index 6a5c4ca6d..53d76b84d 100644
--- a/README_ar.md
+++ b/README_ar.md
@@ -209,6 +209,7 @@ rea setup
| أدوات macOS الأصلية | 7 | بيانات Mach-O والتوقيعات وplist والمعماريات واستعادة أسماء Swift |
| الملفات والحزم | 5 | فحص الدلائل والحزم وInterface Builder وموارد Apple والاستخراج |
| .NET PE/CLI | 7 | هوية التجميع والبيانات الوصفية وCIL والاستدعاءات الأصلية والمقارنة واستيراد إعادة البناء |
+| البرامج الثابتة | 2 | فحص مناطق البرامج الثابتة واستخراجها الصريح على Linux |
| Android APK | 5 | بيانات الحزمة وmanifest والبحث عن الأصناف والأعضاء وفك ترجمة الأساليب والمراجع الثابتة |
| مراقبة المتصفح | 9 | الصفحات والبرامج النصية وخرائط المصدر وWebMCP والصور ومقارنة الالتقاط |
| تحليل Electron | 5 | مراقبة الصفحات وبنية التطبيق وربط النتائج الثابتة بنتائج التشغيل |
diff --git a/README_ja.md b/README_ja.md
index b07275b8c..8b948423a 100644
--- a/README_ja.md
+++ b/README_ja.md
@@ -198,6 +198,7 @@ REA は手順 1〜5 のバイナリ解析を処理し、手順 6 はエージェ
| macOS ネイティブ | 7 | Mach-O メタデータ、署名、plist、アーキテクチャ、Swift 名の復元 |
| ファイルとパッケージ | 5 | ディレクトリとパッケージ、Interface Builder、Apple リソース、抽出 |
| .NET PE/CLI | 7 | アセンブリ識別、メタデータ、CIL、ネイティブ呼び出し、比較、再構築の取り込み |
+| ファームウェア | 2 | Linux の領域検査と明示的な展開 |
| Android APK | 5 | パッケージと manifest、クラス検索、メンバー一覧、メソッド逆コンパイル、静的参照 |
| ブラウザー観察 | 9 | ページ、スクリプト、ソースマップ、WebMCP、スクリーンショット、比較 |
| Electron 解析 | 5 | ページ観察、アプリ構造、静的・実行時結果の対応付け |
diff --git a/README_ko.md b/README_ko.md
index 644e66e81..79ad1ac3f 100644
--- a/README_ko.md
+++ b/README_ko.md
@@ -199,6 +199,7 @@ REA는 1–5단계의 바이너리 분석을 처리합니다. 6단계는 에이
| macOS 네이티브 | 7 | Mach-O 메타데이터, 서명, plist, 아키텍처, Swift 이름 복원 |
| 파일과 패키지 | 5 | 디렉터리와 패키지 검사, Interface Builder, Apple 리소스, 추출 |
| .NET PE/CLI | 7 | 어셈블리 식별, 메타데이터, CIL, 네이티브 호출, 비교, 재구성 가져오기 |
+| 펌웨어 | 2 | Linux 펌웨어 영역 검사 및 명시적 추출 |
| Android APK | 5 | 패키지와 manifest, 클래스 검색, 멤버 목록, 메서드 디컴파일, 정적 참조 |
| 브라우저 관찰 | 9 | 페이지, 스크립트, 소스 맵, WebMCP, 스크린샷, 캡처 비교 |
| Electron 분석 | 5 | 페이지 관찰, 앱 구조, 정적·런타임 결과 연결 |
diff --git a/README_zh.md b/README_zh.md
index 0142c3a54..44b0e52db 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -198,6 +198,7 @@ REA 负责第 1–5 步中的二进制分析。第 6 步由智能体使用其常
| macOS 原生工具 | 7 | Mach-O 元数据、代码签名、plist、架构与 Swift 符号还原 |
| 制品检查 | 5 | 目录与软件包检查、Interface Builder、Apple 资源目录与提取 |
| .NET PE/CLI | 7 | 程序集身份、元数据、CIL、原生调用声明、成员比较与重建导入 |
+| 韧体 | 2 | Linux 韧体区域识别与显式解包 |
| Android APK | 5 | 包与 manifest 声明、class 搜索、成员清单、方法反编译与静态引用 |
| 浏览器观察 | 9 | 页面、脚本、来源映射、WebMCP 工具、截图与捕获比较 |
| Electron 分析 | 5 | 页面观察、应用结构与静态/运行时结果关联 |
diff --git a/docs/architecture.mermaid b/docs/architecture.mermaid
index 34d0a58fc..e93c53767 100644
--- a/docs/architecture.mermaid
+++ b/docs/architecture.mermaid
@@ -25,6 +25,7 @@ graph TD
AUX["src/artifacts/ + src/native/
disjoint artifact and native capabilities"]
BROWSER["src/browser/
Loopback CDP transport
exact-origin passive observation"]
DOTNET["src/dotnet/
Managed static metadata provider
PE/CLI metadata inventory, members, IL"]
+ FIRMWARE["src/firmware/
Binwalk / Unblob adapters
owned processes, report normalization, private extraction"]
ANDROID["src/android/
Static APK adapter
owned SDK stdio, pinned headless JADX, normalization"]
REFERENCE["src/reference/
Filesystem reference-source reader
bounded traversal, validation, errors"]
end
@@ -62,6 +63,9 @@ graph TD
MAIN --> SERVER
MAIN --> APP
CLI --> APP
+ APP --> FIRMWARE
+ FIRMWARE --> PROCESS
+ FIRMWARE --> CONTRACTS
APP --> ANDROID
ANDROID --> PROCESS
ANDROID --> CONTRACTS
diff --git a/docs/firmware-analysis.md b/docs/firmware-analysis.md
new file mode 100644
index 000000000..ccdca5bef
--- /dev/null
+++ b/docs/firmware-analysis.md
@@ -0,0 +1,173 @@
+# Firmware analysis
+
+REA integrates **Binwalk 3.1.0** for region inspection and **Unblob 26.6.4** for
+explicit extraction. This first firmware milestone is verified on Linux x64.
+No device, root privilege, mount, emulation or execution of extracted programs
+is needed. Arbitrary firmware bytes do not pass native executable admission;
+select a returned ELF separately for supported Ghidra analysis.
+
+## Caller-supplied tools
+
+Provide existing tools using absolute executable paths, scoped to your shell:
+
+```sh
+export REA_BINWALK_COMMAND=/absolute/path/to/binwalk
+export REA_UNBLOB_COMMAND=/absolute/path/to/unblob
+```
+
+REA does not install these tools, their dependencies or system packages. It
+checks the actual tool version when executing a request. Inspection and
+extraction have independent prerequisites; one does not require the other.
+Both require util-linux `prlimit`, normally `/usr/bin/prlimit`; override its
+absolute path with `REA_FIRMWARE_PRLIMIT_COMMAND` if needed.
+
+Unblob needs the external extractor for the selected format on its inherited
+`PATH`: for example, `debugfs` for ext2/ext3/ext4. Its default Landlock sandbox
+and skip rules stay enabled. Sandbox startup failures remain actionable errors;
+REA does not retry with `--no-sandbox`. Missing extractors reported in a valid
+analysis report retain partial results and dependency names inline.
+
+Upstream sources are preserved unmodified as optional pinned submodules:
+
+```sh
+git submodule update --init third_party/binwalk third_party/unblob
+```
+
+Normal REA builds and npm packages do not include or build these sources or
+engine binaries. See [upstream provenance](../third_party/README.md).
+
+## CLI and MCP
+
+```sh
+rea inspect-firmware-regions /path/to/firmware.bin
+rea extract-firmware /path/to/firmware.bin /path/to/new-output
+rea extract-firmware /path/to/firmware.bin /path/to/selected-output \
+ --offset 64 --length 4096 --max-depth 3
+```
+
+The corresponding MCP tools accept the same intent:
+
+```json
+{
+ "name": "inspect_firmware_regions",
+ "arguments": { "path": "/path/to/firmware.bin" }
+}
+```
+
+```json
+{
+ "name": "extract_firmware",
+ "arguments": {
+ "path": "/path/to/firmware.bin",
+ "output_directory": "/path/to/new-output",
+ "range": { "offset": 64, "length": 4096 },
+ "max_depth": 3
+ }
+}
+```
+
+Both return Evidence with the original path and SHA-256, raw producer reports,
+actual executable path/digest, version and limitations. Binwalk signature UUIDs
+and Unblob blob IDs are producer-local identities; compare content hashes and
+source ranges across runs. A matching version does not attest an installed
+build's source revision, so that field remains unknown.
+
+### Interpret the results
+
+- Region offsets refer to bytes in the original firmware. `reported_size`
+ preserves Binwalk's output; `size_basis=provider_reported_validation_unknown`
+ reflects that Binwalk can replace unknown lengths with the next signature or
+ EOF before serialization. Neither a signature nor its confidence byte proves
+ a valid partition, encryption or runtime behavior.
+- Extraction returns regular file paths, independently verified SHA-256 values,
+ producer hashes when available, chunks, diagnostics and task derivations.
+ Unblob's task report is unordered; REA resolves relationships by paths and
+ blob IDs. Logical references use `$input`, `$output`, or `$output/`
+ so a real file named `$input` stays distinct from the original input.
+ Chunk offsets belong to the task's input file. Only chunks in the
+ selected input have a known `root_file_range`, adjusted by the selected offset.
+- Decompressed children have unknown original byte ranges and runtime addresses.
+ Task lineage does not establish a byte-for-byte mapping through decompression.
+- `partial` marks unknown/encrypted chunks, reported extraction problems,
+ unpublished links/special files or reached depth limits. `complete` means the
+ engine finished its configured extraction without those reported conditions;
+ default skip rules and format coverage still apply. It does not establish
+ complete firmware reconstruction.
+- The destination must be absent, absolute, with an existing parent. Publication
+ uses exclusive, symlink-resistant writes and durable digest readback. Existing
+ destinations are never overwritten. This is not an atomic directory rename:
+ a new tree can be visible while files are written. Failed uncommitted output
+ is rolled back. Symlinks and special files are recorded without publication;
+ empty directories, ownership and executable permission bits are not reproduced.
+
+Select a verified native child for the existing tools:
+
+```json
+{
+ "name": "open_binary",
+ "arguments": {
+ "path": "/path/from/extraction/usr/bin/program",
+ "provider_id": "ghidra"
+ }
+}
+```
+
+Then use `analyze_function`, `inspect_native_api` or the other native primitives.
+Native architecture and executable validation still apply. This milestone does
+not add MIPS/PPC/RISC-V decompilation, raw flash load profiles, bootloader/device
+tree semantics, vulnerability scanning, emulation or hardware runtime capture.
+
+## Resource and lifecycle policy
+
+- Nonempty regular firmware inputs: at most **128 MiB**, copied and hashed into
+ a private workspace before analysis. No in-place source modification.
+- One queued heavy operation per provider instance; Binwalk one thread and
+ Unblob one worker. No automatic parallel extraction engines.
+- **120-second** deadline; inherited **1 GiB per-process address-space** limit,
+ 120 CPU seconds and zero core-dump allowance through `prlimit`.
+- JSON reports: at most **8 MiB**; oversized reports fail without a truncated
+ success. 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` /
+ `--max-output-files`). Depth defaults to 3, allowed range 1–10.
+
+Staging budgets are polled and rechecked after exit; short-lived overshoot is
+possible. The inherited file-size limit bounds each file, not total storage;
+address-space limits are per process, not an aggregate memory quota. Worker
+count is not CPU affinity for every external extractor. These limits do not
+claim cgroup/container containment. Cancellation cleans the owned process group
+before removing its workspace; uncertain cleanup retains resources and blocks
+further operations in that provider instance.
+
+## Verification
+
+Generate small public, source-derived fixtures into ignored `_reference/`:
+
+```sh
+npm run fixtures:firmware
+npm run verify:firmware
+```
+
+Fixture generation requires existing Python 3 and a host C compiler (`cc`);
+override with `REA_FIRMWARE_PYTHON` / `REA_FIRMWARE_CC`. The independent oracle
+records gzip offset/length and extracted file hashes. Real verification checks
+CLI/MCP, full-file and selected-range extraction, unknown chunks, depth limits,
+content parity and unchanged source bytes. No binary fixture is committed.
+
+Additional lanes are explicit, so the base lane stays small:
+
+```sh
+# Existing mke2fs and debugfs required; put debugfs on the scoped PATH.
+REA_FIRMWARE_VERIFY_EXT4=1 npm run fixtures:firmware
+REA_FIRMWARE_VERIFY_EXT4=1 npm run verify:firmware
+
+# Existing Ghidra 12.1.4 and Java required.
+REA_FIRMWARE_VERIFY_GHIDRA=1 npm run verify:firmware
+```
+
+`REA_FIRMWARE_MKE2FS_COMMAND` selects the optional ext4 fixture producer.
+`REA_FIRMWARE_FIXTURE_ROOT` selects generated data storage.
+`REA_FIRMWARE_TEST_ENTRYPOINT` can select an isolated installed npm package's
+`scripts/rea.mjs` to verify the packaged CLI/MCP workflow. Real coverage here is
+generated gzip/USTAR/ext4 with a Linux x64 ELF child; SquashFS, UBIFS, proprietary
+firmware, other hosts and architectures remain unverified.
diff --git a/docs/product-catalog.json b/docs/product-catalog.json
index 3e8fce0a3..12f92c452 100644
--- a/docs/product-catalog.json
+++ b/docs/product-catalog.json
@@ -10,7 +10,7 @@
"skill_version": "24"
},
"tools": {
- "total": 123,
+ "total": 125,
"families": [
{
"id": "direct",
@@ -121,6 +121,12 @@
"verify_managed_native_boundaries"
]
},
+ {
+ "id": "firmware",
+ "surface": "firmware-provider",
+ "count": 2,
+ "tools": ["extract_firmware", "inspect_firmware_regions"]
+ },
{
"id": "android",
"surface": "android-provider",
@@ -215,6 +221,12 @@
]
},
"providers": [
+ {
+ "id": "binwalk",
+ "name": "Binwalk",
+ "version": "3.1.0",
+ "capabilities": ["inspect_firmware_regions"]
+ },
{
"id": "ghidra",
"name": "Ghidra",
@@ -418,6 +430,12 @@
"list_javascript_runtime_targets",
"observe_javascript_runtime"
]
+ },
+ {
+ "id": "unblob",
+ "name": "Unblob",
+ "version": "26.6.4",
+ "capabilities": ["extract_firmware"]
}
],
"setup_clients": [
@@ -495,7 +513,7 @@
}
],
"cli": {
- "primary_count": 78,
+ "primary_count": 80,
"commands": [
"address-to-file-offset",
"analyze",
@@ -526,6 +544,7 @@
"evidence-export",
"evidence-import",
"extract-artifact",
+ "extract-firmware",
"function",
"import-managed-reconstruction",
"import-reference-source",
@@ -536,6 +555,7 @@
"inspect-artifact",
"inspect-asset-catalog",
"inspect-electron-page",
+ "inspect-firmware-regions",
"inspect-keyed-archive",
"inspect-macho",
"inspect-managed-artifact",
@@ -585,15 +605,15 @@
},
"runtime_catalog": {
"counts": {
- "cli_commands": 78,
- "mcp_tools": 123,
+ "cli_commands": 80,
+ "mcp_tools": 125,
"mcp_prompts": 6
},
"digests": {
- "tools_sha256": "6e60913fad4c67f3a12aa8bf5113971ce6a57e9492ce402c8cd9e539d6fde01f",
+ "tools_sha256": "45a8aea00dba2a8ad8563b4943cd177d07b14889bc9b823bc39b89b6ddb26d2c",
"prompts_sha256": "ef2de8814390b340623c32001610aa2709d90bed51537b6e562ab3abf144ab4d",
- "combined_sha256": "d5fbda3a283916ab3489a62fe88aeb89da8b0a7b19c248e3742c970b1b51600e",
- "providers_sha256": "e60c6e949f499fe8a015a20ff36752516ce57edcb1ce355f0308361c8d322dd6"
+ "combined_sha256": "297aced29e7ce5e845c505d5f2e9e2dee42b7ed3e628f088f424fe8088c9e8dc",
+ "providers_sha256": "dfba0ee59f12c82cdfb5320e7e0d70a114e533b2cb88afd15db9b9a4a175c9b0"
}
}
}
diff --git a/docs/testing.md b/docs/testing.md
index 00fe3a3f0..468e8e210 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -311,3 +311,15 @@ allows a host-permission-boundary-only result and explicitly reports
Both commands reject a changed executable digest and clean up the fixture
process and helper. These lanes require an interactive macOS desktop. See [native investigation](native-investigation.md)
for the exact ABI, authority, graph and observation boundaries.
+
+### Firmware adapters
+
+`npm run fixtures:firmware` uses existing Python 3 and a host C compiler to make
+an ignored gzip/USTAR firmware fixture and independent offset/hash oracle.
+`npm run verify:firmware` requires caller-supplied Binwalk 3.1.0, Unblob 26.6.4
+and util-linux prlimit on Linux. It verifies CLI/MCP parity, selected ranges,
+unknown chunks, depth limits and extracted child digests. The optional
+`REA_FIRMWARE_VERIFY_EXT4=1` lane requires existing mke2fs/debugfs; the separate
+`REA_FIRMWARE_VERIFY_GHIDRA=1` lane checks a selected host ELF through real Ghidra.
+Neither optional toolchain is a base-lane prerequisite. See
+[firmware analysis](firmware-analysis.md) for limits and unverified formats.
diff --git a/docs/verification/managed-conformance-manifest.json b/docs/verification/managed-conformance-manifest.json
index a490af7d7..21c2f003d 100644
--- a/docs/verification/managed-conformance-manifest.json
+++ b/docs/verification/managed-conformance-manifest.json
@@ -1,5 +1,5 @@
{
- "manifest_id": "ecm_42bc9f06a00e9c510cb57605d7f1cde613e2762ea0c59bf3915e032147a7c493",
+ "manifest_id": "ecm_18ee96f3c7c08df6a29b2075b8dadf6e7053e88c52a65cecb35aea374112cbc6",
"verifier": {
"id": "rea-managed-conformance",
"version": "1"
@@ -13,7 +13,7 @@
"skill_digests": [
{
"skill_id": "reverse-engineer-anything",
- "sha256": "ace0a167b9161d9d96c9f5cd65ff0bb39e483c3426e6cc86aac5c7c9893c31cb"
+ "sha256": "f72e03be44a47ba176e6aac47c85e930fe1fe5723b650dacbd5873f28a3b3f8f"
}
],
"claims": [
diff --git a/package.json b/package.json
index f318f28fe..5952cfacc 100644
--- a/package.json
+++ b/package.json
@@ -136,6 +136,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:android": "npm run build:cached && node scripts/verify-real-android.mjs",
"fixtures:android": "node scripts/fetch-android-fixtures.mjs",
"verify:agent": "npm run build:cached && node scripts/verify-agent-experience.mjs",
diff --git a/scripts/generate-firmware-fixtures.mjs b/scripts/generate-firmware-fixtures.mjs
new file mode 100644
index 000000000..e19ac1af1
--- /dev/null
+++ b/scripts/generate-firmware-fixtures.mjs
@@ -0,0 +1,42 @@
+import { execFile } from "node:child_process";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+const root = resolve(
+ process.env.REA_FIRMWARE_FIXTURE_ROOT ??
+ "_reference/firmware-integration/generated",
+);
+for (const [command, args, purpose] of [
+ [
+ process.env.REA_FIRMWARE_PYTHON ?? "python3",
+ ["--version"],
+ "Python 3 standard-library fixture generator",
+ ],
+ [
+ process.env.REA_FIRMWARE_CC ?? "cc",
+ ["--version"],
+ "host ELF fixture compiler",
+ ],
+]) {
+ try {
+ await exec(command, args);
+ } catch (cause) {
+ throw new Error(`fixtures:firmware requires ${purpose}: ${command}`, {
+ cause,
+ });
+ }
+}
+const ext4 =
+ process.env.REA_FIRMWARE_VERIFY_EXT4 === "1"
+ ? [process.env.REA_FIRMWARE_MKE2FS_COMMAND ?? "mke2fs"]
+ : [];
+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)),
+ root,
+ process.env.REA_FIRMWARE_CC ?? "cc",
+ ...ext4,
+]);
+console.log(generated.stdout.trim());
diff --git a/scripts/lib/catalog-builders.mjs b/scripts/lib/catalog-builders.mjs
index 925df632b..65abdd196 100644
--- a/scripts/lib/catalog-builders.mjs
+++ b/scripts/lib/catalog-builders.mjs
@@ -31,6 +31,11 @@ export const toolFamilyCatalog = (sources) => {
...sources.managedWorkflowContracts.MANAGED_WORKFLOW_TOOL_CONTRACTS,
],
},
+ {
+ id: "firmware",
+ surface: "firmware-provider",
+ contracts: sources.firmwareContracts.FIRMWARE_TOOL_CONTRACTS,
+ },
{
id: "android",
surface: "android-provider",
@@ -118,6 +123,18 @@ export const providerCatalog = (sources) => {
contracts:
sources.managedWorkflowContracts.MANAGED_WORKFLOW_TOOL_CONTRACTS,
},
+ {
+ identity: sources.firmwareProvider.BINWALK_PROVIDER_IDENTITY,
+ contracts: sources.firmwareContracts.FIRMWARE_TOOL_CONTRACTS.filter(
+ ({ name }) => name === "inspect_firmware_regions",
+ ),
+ },
+ {
+ identity: sources.firmwareProvider.UNBLOB_PROVIDER_IDENTITY,
+ contracts: sources.firmwareContracts.FIRMWARE_TOOL_CONTRACTS.filter(
+ ({ name }) => name === "extract_firmware",
+ ),
+ },
{
identity: sources.androidProvider.JADX_PROVIDER_IDENTITY,
contracts: sources.androidContracts.ANDROID_TOOL_CONTRACTS,
diff --git a/scripts/lib/catalog-core.mjs b/scripts/lib/catalog-core.mjs
index a62d2c436..54891b460 100644
--- a/scripts/lib/catalog-core.mjs
+++ b/scripts/lib/catalog-core.mjs
@@ -43,6 +43,8 @@ const SOURCE_PATHS = {
nativeContracts: "dist/contracts/nativeToolContracts.js",
artifactContracts: "dist/contracts/artifactToolContracts.js",
managedContracts: "dist/contracts/managedToolContracts.js",
+ firmwareContracts: "dist/contracts/firmwareToolContracts.js",
+ firmwareProvider: "dist/firmware/FirmwareRelease.js",
androidContracts: "dist/contracts/androidToolContracts.js",
androidProvider: "dist/android/JadxRelease.js",
managedWorkflowContracts: "dist/contracts/managedWorkflowToolContracts.js",
diff --git a/scripts/lib/generate-firmware-fixture.py b/scripts/lib/generate-firmware-fixture.py
new file mode 100644
index 000000000..e472805a4
--- /dev/null
+++ b/scripts/lib/generate-firmware-fixture.py
@@ -0,0 +1,43 @@
+"""Generate firmware bytes using standard format producers, with an independent oracle."""
+import gzip
+import hashlib
+import io
+import json
+from pathlib import Path
+import subprocess
+import sys
+import tarfile
+
+root = Path(sys.argv[1]).resolve()
+root.mkdir(parents=True, exist_ok=True)
+source = root / "probe.c"
+source.write_text("int firmware_probe(int x){return x*7+3;} int main(void){return firmware_probe(4);}\n")
+subprocess.run([sys.argv[2], "-O0", "-g", "-fno-inline", str(source), "-o", str(root / "probe")], check=True)
+payloads = {"etc/rea.conf": b"rea_fixture=true\n", "usr/bin/probe": (root / "probe").read_bytes()}
+buffer = io.BytesIO()
+with tarfile.open(fileobj=buffer, mode="w", format=tarfile.USTAR_FORMAT) as archive:
+ for name, data in payloads.items():
+ info = tarfile.TarInfo(name)
+ info.size = len(data)
+ info.mode = 0o644
+ info.mtime = 0
+ archive.addfile(info, io.BytesIO(data))
+compressed = gzip.compress(buffer.getvalue(), mtime=0)
+image = b"REA firmware fixture\n".ljust(64, b"\xff") + compressed + b"\x00" * 128
+(root / "firmware.bin").write_bytes(image)
+(root / "oracle.json").write_text(json.dumps({
+ "generator": "Python tarfile USTAR + gzip; host cc; no target execution",
+ "offset": 64, "length": len(compressed), "size": len(image),
+ "sha256": hashlib.sha256(image).hexdigest(),
+ "files": {name: {"sha256": hashlib.sha256(data).hexdigest(), "size": len(data)} for name, data in payloads.items()},
+}, indent=2) + "\n")
+print(root)
+
+if len(sys.argv) > 3:
+ tree = root / "ext4-root"
+ tree.mkdir(exist_ok=True)
+ for name, data in payloads.items():
+ target = tree / name
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_bytes(data)
+ subprocess.run([sys.argv[3], "-q", "-t", "ext4", "-F", "-d", str(tree), str(root / "ext4.bin"), "8192"], check=True)
diff --git a/scripts/verify-real-firmware.mjs b/scripts/verify-real-firmware.mjs
new file mode 100644
index 000000000..a811e99b7
--- /dev/null
+++ b/scripts/verify-real-firmware.mjs
@@ -0,0 +1,254 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import {
+ access,
+ mkdir,
+ mkdtemp,
+ readFile,
+ rm,
+ symlink,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+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";
+
+const exec = promisify(execFile);
+const repository = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const entrypoint = resolve(
+ process.env.REA_FIRMWARE_TEST_ENTRYPOINT ??
+ join(repository, "scripts/rea.mjs"),
+);
+if (process.platform !== "linux")
+ throw new Error(
+ "verify:firmware requires Linux; other hosts are not verified",
+ );
+for (const variable of ["REA_BINWALK_COMMAND", "REA_UNBLOB_COMMAND"]) {
+ const path = process.env[variable];
+ if (path === undefined)
+ throw new Error(
+ `verify:firmware requires ${variable}; see docs/firmware-analysis.md`,
+ );
+ await access(path);
+}
+const fixtureRoot = resolve(
+ process.env.REA_FIRMWARE_FIXTURE_ROOT ??
+ join(repository, "_reference/firmware-integration/generated"),
+);
+await access(join(fixtureRoot, "oracle.json")).catch((cause) => {
+ throw new Error(
+ "verify:firmware requires generated fixtures; run npm run fixtures:firmware",
+ { cause },
+ );
+});
+const oracle = JSON.parse(
+ await readFile(join(fixtureRoot, "oracle.json"), "utf8"),
+);
+const path = join(fixtureRoot, "firmware.bin");
+assert.equal(await hashFirmwareFile(path), oracle.sha256);
+const root = await mkdtemp(join(tmpdir(), "rea-real-firmware-"));
+const environment = Object.fromEntries(
+ Object.entries(process.env).filter(([, value]) => value !== undefined),
+);
+const client = new Client({ name: "rea-real-firmware-verifier", version: "1" });
+const cli = async (args, env = environment) => {
+ const response = await exec(
+ process.execPath,
+ [entrypoint, ...args, "--format", "json"],
+ {
+ env,
+ cwd: repository,
+ timeout: 150_000,
+ maxBuffer: 16 * 1024 * 1024,
+ },
+ );
+ return parseEvidence(JSON.parse(response.stdout));
+};
+const call = async (name, args) => {
+ const response = await client.callTool(
+ { name, arguments: args },
+ { timeout: 150_000 },
+ );
+ assert.notEqual(response.isError, true, JSON.stringify(response));
+ assert.ok(response.structuredContent !== undefined);
+ return response.structuredContent;
+};
+const verifyRegions = (evidence) => {
+ assert.equal(evidence.subject.digest.sha256, oracle.sha256);
+ const result = firmwareResultSchemas.inspect_firmware_regions.parse(
+ evidence.normalized_result,
+ );
+ const gzip = result.regions.find(
+ (region) => region.signature === "gzip" && region.offset === oracle.offset,
+ );
+ assert.ok(
+ gzip !== undefined,
+ "Binwalk must find the independently generated gzip offset",
+ );
+ assert.equal(gzip.reported_size, oracle.length);
+ assert.equal(gzip.size_basis, "provider_reported_validation_unknown");
+ return result.regions.map(({ provider_id, ...region }) => region);
+};
+const verifyFiles = async (evidence) => {
+ const result = firmwareResultSchemas.extract_firmware.parse(
+ evidence.normalized_result,
+ );
+ assert.ok(result.chunks.some((chunk) => chunk.handler === "gzip"));
+ for (const [suffix, expected] of Object.entries(oracle.files)) {
+ const file = result.files.find((candidate) =>
+ candidate.relative_path.endsWith(`/${suffix}`),
+ );
+ assert.ok(file !== undefined, `Missing extracted ${suffix}`);
+ assert.equal(file.sha256, expected.sha256);
+ assert.equal(file.size, expected.size);
+ assert.equal(await hashFirmwareFile(file.path), expected.sha256);
+ assert.equal(file.original_file_range, null);
+ assert.equal(file.runtime_address, null);
+ }
+ return result;
+};
+try {
+ const inspected = await cli(["inspect-firmware-regions", path]);
+ const cliRegions = verifyRegions(inspected);
+ const extracted = await cli([
+ "extract-firmware",
+ path,
+ join(root, "cli-output"),
+ ]);
+ const cliFiles = await verifyFiles(extracted);
+ assert.equal(cliFiles.coverage, "partial");
+ assert.ok(
+ cliFiles.chunks.some(
+ (chunk) =>
+ chunk.handler === null &&
+ chunk.range.offset === 0 &&
+ chunk.range.length === 64,
+ ),
+ );
+ await client.connect(
+ new StdioClientTransport({
+ command: process.execPath,
+ args: [entrypoint, "mcp"],
+ cwd: repository,
+ env: environment,
+ stderr: "pipe",
+ }),
+ { timeout: 30_000 },
+ );
+ const inspectedMcp = await call("inspect_firmware_regions", { path });
+ const mcpEvidence = parseEvidence(inspectedMcp.evidence);
+ assert.deepEqual(verifyRegions(mcpEvidence), cliRegions);
+ const extractedMcp = await call("extract_firmware", {
+ path,
+ output_directory: join(root, "mcp-output"),
+ });
+ const mcpFiles = await verifyFiles(parseEvidence(extractedMcp.evidence));
+ const contentIdentity = (result) =>
+ result.files.map(({ relative_path, sha256, size }) => ({
+ relative_path,
+ sha256,
+ size,
+ }));
+ assert.deepEqual(contentIdentity(mcpFiles), contentIdentity(cliFiles));
+ const selected = await call("extract_firmware", {
+ path,
+ output_directory: join(root, "selected-output"),
+ range: { offset: oracle.offset, length: oracle.length },
+ });
+ const selectedFiles = await verifyFiles(parseEvidence(selected.evidence));
+ assert.equal(selectedFiles.selection.offset, oracle.offset);
+ assert.equal(selectedFiles.selection.length, oracle.length);
+ const depth = await call("extract_firmware", {
+ path,
+ output_directory: join(root, "depth-output"),
+ max_depth: 1,
+ });
+ const depthResult = firmwareResultSchemas.extract_firmware.parse(
+ depth.result,
+ );
+ assert.equal(depthResult.coverage, "partial");
+ assert.ok(depthResult.depth_limited_paths.length > 0);
+ console.log(
+ "PASS real Binwalk/Unblob: CLI, MCP, independent offsets/digests, range extraction, unknown chunks and depth limits",
+ );
+ if (process.env.REA_FIRMWARE_VERIFY_EXT4 === "1") {
+ const ext4 = join(fixtureRoot, "ext4.bin");
+ await access(ext4);
+ const response = await call("extract_firmware", {
+ path: ext4,
+ output_directory: join(root, "ext4-output"),
+ });
+ const result = firmwareResultSchemas.extract_firmware.parse(
+ response.result,
+ );
+ assert.ok(result.chunks.some((chunk) => chunk.handler === "extfs"));
+ assert.equal(result.coverage, "complete");
+ for (const [suffix, expected] of Object.entries(oracle.files))
+ assert.equal(
+ result.files.find((file) => file.relative_path.endsWith(`/${suffix}`))
+ ?.sha256,
+ expected.sha256,
+ );
+ console.log("PASS real ext4 extraction with debugfs; no mounts");
+ // Preserve the process-ownership utility while withholding all extractors.
+ const withoutExtractors = join(root, "without-extractors");
+ await access("/bin/ps");
+ await mkdir(withoutExtractors);
+ await symlink("/bin/ps", join(withoutExtractors, "ps"));
+ const missing = await cli(
+ ["extract-firmware", ext4, join(root, "missing-extractor-output")],
+ { ...environment, PATH: withoutExtractors },
+ );
+ const partial = firmwareResultSchemas.extract_firmware.parse(
+ missing.normalized_result,
+ );
+ assert.equal(partial.coverage, "partial");
+ assert.ok(JSON.stringify(partial.diagnostics).includes("debugfs"));
+ console.log(
+ "PASS real missing-extractor diagnostics retained despite Unblob exit 1",
+ );
+ }
+ if (process.env.REA_FIRMWARE_VERIFY_GHIDRA === "1") {
+ if (process.env.GHIDRA_INSTALL_DIR === undefined)
+ throw new Error(
+ "Firmware Ghidra handoff requires GHIDRA_INSTALL_DIR and Java; see docs/ghidra.md",
+ );
+ const child = mcpFiles.files.find((file) =>
+ file.relative_path.endsWith("/usr/bin/probe"),
+ );
+ assert.ok(child !== undefined);
+ await call("open_binary", { path: child.path, provider_id: "ghidra" });
+ const dossier = await call("analyze_function", {
+ procedure: "firmware_probe",
+ });
+ const evidence = parseEvidence(dossier.evidence);
+ assert.equal(
+ evidence.subject.digest.sha256,
+ oracle.files["usr/bin/probe"].sha256,
+ );
+ const pseudocode = await call("procedure_pseudo_code", {
+ procedure: "firmware_probe",
+ });
+ assert.equal(parseEvidence(pseudocode.evidence).provider.id, "ghidra");
+ assert.ok(
+ JSON.stringify(evidence.normalized_result).includes("firmware_probe"),
+ );
+ await call("close_binary", {});
+ console.log(
+ "PASS real Ghidra handoff of the selected extracted host ELF, bound to its digest",
+ );
+ }
+ assert.equal(
+ await hashFirmwareFile(path),
+ oracle.sha256,
+ "Original firmware bytes must remain unchanged",
+ );
+} finally {
+ await client.close();
+ await rm(root, { recursive: true, force: true });
+}
diff --git a/skills/reverse-engineer-anything/SKILL.md b/skills/reverse-engineer-anything/SKILL.md
index ee7193ebc..7d9ce6374 100644
--- a/skills/reverse-engineer-anything/SKILL.md
+++ b/skills/reverse-engineer-anything/SKILL.md
@@ -3,8 +3,8 @@ name: reverse-engineer-anything
description: Reverse engineer native, managed, Electron/JavaScript, packaged, and browser applications with REA. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.
metadata:
version: "24"
- tool_count: 123
- catalog_digest: "d5fbda3a283916ab3489a62fe88aeb89da8b0a7b19c248e3742c970b1b51600e"
+ tool_count: 125
+ catalog_digest: "297aced29e7ce5e845c505d5f2e9e2dee42b7ed3e628f088f424fe8088c9e8dc"
---
# REA
diff --git a/src/application/CapabilityInventory.test.ts b/src/application/CapabilityInventory.test.ts
index 01162294c..6d0bf1b57 100644
--- a/src/application/CapabilityInventory.test.ts
+++ b/src/application/CapabilityInventory.test.ts
@@ -55,6 +55,27 @@ const entry = (
};
describe("capability inventory: provider status", () => {
+ it("reports firmware inspection and extraction prerequisites independently", () => {
+ const policy = {
+ processCaptureEnabled: true,
+ firmwareInspectionEnabled: true,
+ };
+ expect(entry("inspect_firmware_regions", status(), policy)).toMatchObject({
+ available: true,
+ surface: "firmware-provider",
+ });
+ expect(entry("extract_firmware", status(), policy)).toMatchObject({
+ available: false,
+ reason: "provider_missing",
+ remediation: expect.stringContaining("REA_UNBLOB_COMMAND"),
+ });
+ expect(
+ entry("extract_firmware", status(), {
+ processCaptureEnabled: true,
+ firmwareExtractionEnabled: true,
+ }),
+ ).toMatchObject({ available: true });
+ });
it("keeps Android APK operations target-free and reports their explicit engine prerequisite", () => {
expect(
entry("inspect_android_package", status(), {
diff --git a/src/application/CapabilityInventory.ts b/src/application/CapabilityInventory.ts
index 25cdfefe9..a7b277970 100644
--- a/src/application/CapabilityInventory.ts
+++ b/src/application/CapabilityInventory.ts
@@ -28,6 +28,8 @@ type ToolAvailabilityReason = "available" | ToolUnavailabilityReason;
type ProviderDescriptor = ProviderCapability;
export type AvailabilityPolicy = {
readonly processCaptureEnabled: boolean;
+ readonly firmwareInspectionEnabled?: boolean;
+ readonly firmwareExtractionEnabled?: boolean;
readonly androidAnalysisEnabled?: boolean;
readonly browserObservationEnabled?: boolean;
readonly browserScenarioEnabled?: boolean;
@@ -206,6 +208,19 @@ const workflowAvailabilityFor = ({
kind,
policy,
}: AvailabilityContext): Availability | null => {
+ if (kind === "firmware-provider") {
+ const enabled =
+ name === "inspect_firmware_regions"
+ ? policy.firmwareInspectionEnabled
+ : policy.firmwareExtractionEnabled;
+ return enabled === true
+ ? { reason: "available", remediation: null }
+ : {
+ reason: "provider_missing",
+ remediation:
+ "On Linux, provide an absolute REA_BINWALK_COMMAND (Binwalk 3.1.0) or REA_UNBLOB_COMMAND (Unblob 26.6.4) path and util-linux prlimit. Extraction also requires the selected format’s external extractor.",
+ };
+ }
if (kind === "android-provider")
return policy.androidAnalysisEnabled === true
? { reason: "available", remediation: null }
diff --git a/src/application/FirmwareAnalysisPort.ts b/src/application/FirmwareAnalysisPort.ts
new file mode 100644
index 000000000..5b21e6e8f
--- /dev/null
+++ b/src/application/FirmwareAnalysisPort.ts
@@ -0,0 +1,15 @@
+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";
+
+/** File-oriented firmware engines; executable admission remains a separate operation. */
+export interface FirmwareAnalysisPort {
+ execute(
+ request: FirmwareRequest,
+ options?: ExecutionOptions,
+ ): Promise>;
+}
diff --git a/src/application/FirmwareAnalysisService.ts b/src/application/FirmwareAnalysisService.ts
new file mode 100644
index 000000000..6fcc4ad92
--- /dev/null
+++ b/src/application/FirmwareAnalysisService.ts
@@ -0,0 +1,54 @@
+import type { ExecutionOptions } from "./AnalysisProvider.js";
+import type { FirmwareAnalysisPort } from "./FirmwareAnalysisPort.js";
+import {
+ firmwareRequestSchema,
+ type FirmwareOperation,
+} from "../domain/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";
+
+/** Shared CLI/MCP validation and Evidence composition for arbitrary firmware files. */
+export class FirmwareAnalysisService {
+ constructor(readonly provider: FirmwareAnalysisPort) {}
+
+ /** Execute an explicit inspection or extraction and preserve its producing identity. */
+ async execute(
+ operation: FirmwareOperation,
+ input: unknown,
+ options?: ExecutionOptions,
+ ): Promise> {
+ if (options?.signal?.aborted === true)
+ return err(new AnalysisCancelledError(operation));
+ const parsed = firmwareRequestSchema.safeParse({ operation, input });
+ if (!parsed.success)
+ return err(new AnalysisInputError(operation, { cause: parsed.error }));
+ const executed = await this.provider.execute(parsed.data, options);
+ if (!executed.ok) return executed;
+ const execution = executed.value;
+ if (execution.subject === null)
+ return err(
+ new AnalysisOutputError(
+ operation,
+ "Firmware execution did not bind its source artifact",
+ ),
+ );
+ return ok(
+ createEvidence(execution.subject, execution.provider, {
+ operation,
+ parameters: jsonObjectSchema.parse(parsed.data.input),
+ result: execution.result,
+ rawResult: execution.rawResult,
+ locations: execution.locations,
+ limitations: execution.limitations,
+ confidence: "observed",
+ }),
+ );
+ }
+}
diff --git a/src/cli.ts b/src/cli.ts
index 7d44bb746..739f84f72 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -7,6 +7,7 @@ import { registerCoreAnalysisCommands } from "./cli/coreAnalysisCommands.js";
import { registerUtilityCommands } from "./cli/utilityCommands.js";
import { registerArtifactCommands } from "./cli/artifactCommands.js";
import { registerManagedCommands } from "./cli/managedCommands.js";
+import { registerFirmwareCommands } from "./cli/firmwareCommands.js";
import { registerAndroidCommands } from "./cli/androidCommands.js";
import { registerEvidenceCommands } from "./cliEvidenceCommands.js";
import { registerProcessCommands } from "./cli/processCommands.js";
@@ -49,6 +50,7 @@ export const createCli = (
registerArtifactCommands(cli, logger);
registerManagedCommands(cli, logger);
registerAndroidCommands(cli, logger, environment);
+ registerFirmwareCommands(cli, logger, environment);
registerEvidenceCommands(cli, logger);
registerProcessCommands(cli, logger, environment);
registerBrowserCommands(cli, logger);
diff --git a/src/cli/firmwareCommands.ts b/src/cli/firmwareCommands.ts
new file mode 100644
index 000000000..6ed6d7fdf
--- /dev/null
+++ b/src/cli/firmwareCommands.ts
@@ -0,0 +1,100 @@
+import { z } from "incur";
+import { FirmwareAnalysisService } from "../application/FirmwareAnalysisService.js";
+import { FirmwareProvider } from "../firmware/FirmwareProvider.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 { Logger } from "../logger.js";
+import type { CliInstance } from "./types.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+
+/** One-shot firmware CLI commands backed by the same workflows as MCP. */
+export const registerFirmwareCommands = (
+ cli: CliInstance,
+ logger: Logger,
+ environment: Readonly>,
+): void => {
+ const service = new FirmwareAnalysisService(
+ new FirmwareProvider(environment),
+ );
+ const execute = (
+ name: string,
+ operation: FirmwareOperation,
+ input: unknown,
+ ) =>
+ withCommandCancellation((signal) =>
+ logCliCommand(logger, name, async () => {
+ const result = await service.execute(operation, input, { signal });
+ return result.ok ? result.value : projectAnalysisError(result.error);
+ }),
+ );
+ const path = z.string().describe("Local firmware path; never executed");
+ cli.command(CLI_COMMANDS.inspectFirmwareRegions, {
+ description:
+ "Inspect firmware signature candidates without extracting them",
+ args: z.object({ path }),
+ run: ({ args }) =>
+ execute(
+ CLI_COMMANDS.inspectFirmwareRegions,
+ "inspect_firmware_regions",
+ args,
+ ),
+ });
+ cli.command(CLI_COMMANDS.extractFirmware, {
+ description:
+ "Extract selected firmware bytes and return verified files and provenance",
+ args: z.object({
+ path,
+ outputDirectory: z
+ .string()
+ .describe("Absolute absent output directory; parent must exist"),
+ }),
+ options: z.object({
+ offset: z
+ .number()
+ .int()
+ .nonnegative()
+ .optional()
+ .describe("Selected byte offset; requires length"),
+ length: z
+ .number()
+ .int()
+ .positive()
+ .optional()
+ .describe("Selected byte length; requires offset"),
+ maxDepth: z
+ .number()
+ .int()
+ .optional()
+ .describe("Extraction depth, 1–10; default 3"),
+ maxOutputBytes: z
+ .number()
+ .int()
+ .optional()
+ .describe("Staging byte budget; default 256 MiB, maximum 512 MiB"),
+ maxOutputFiles: z
+ .number()
+ .int()
+ .optional()
+ .describe("Staging entry budget; default 10000"),
+ }),
+ run: ({ args, options }) =>
+ execute(CLI_COMMANDS.extractFirmware, "extract_firmware", {
+ path: args.path,
+ output_directory: args.outputDirectory,
+ ...(options.offset === undefined && options.length === undefined
+ ? {}
+ : { range: { offset: options.offset, length: options.length } }),
+ ...(options.maxDepth === undefined
+ ? {}
+ : { max_depth: options.maxDepth }),
+ ...(options.maxOutputBytes === undefined
+ ? {}
+ : { max_output_bytes: options.maxOutputBytes }),
+ ...(options.maxOutputFiles === undefined
+ ? {}
+ : { max_output_files: options.maxOutputFiles }),
+ }),
+ });
+};
diff --git a/src/cliCommandNames.ts b/src/cliCommandNames.ts
index e80698480..c4ecdc139 100644
--- a/src/cliCommandNames.ts
+++ b/src/cliCommandNames.ts
@@ -32,6 +32,8 @@ export const CLI_COMMANDS = Object.freeze({
resolveNativeCallTargets: "resolve-native-call-targets",
inspectAssetCatalog: "inspect-asset-catalog",
inspectManagedArtifact: "inspect-managed-artifact",
+ inspectFirmwareRegions: "inspect-firmware-regions",
+ extractFirmware: "extract-firmware",
inspectAndroidPackage: "inspect-android-package",
searchAndroidClasses: "search-android-classes",
inspectAndroidClass: "inspect-android-class",
diff --git a/src/contracts/contractSnapshot.test.ts b/src/contracts/contractSnapshot.test.ts
index 0503311ab..709d34060 100644
--- a/src/contracts/contractSnapshot.test.ts
+++ b/src/contracts/contractSnapshot.test.ts
@@ -8,6 +8,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 { ANDROID_TOOL_CONTRACTS } from "./androidToolContracts.js";
import { MANAGED_TOOL_CONTRACTS } from "./managedToolContracts.js";
import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managedWorkflowToolContracts.js";
@@ -75,6 +76,7 @@ describe("tool contract surface", () => {
...NATIVE_TOOL_CONTRACTS,
...ARTIFACT_TOOL_CONTRACTS,
...ANDROID_TOOL_CONTRACTS,
+ ...FIRMWARE_TOOL_CONTRACTS,
...MANAGED_TOOL_CONTRACTS,
...MANAGED_WORKFLOW_TOOL_CONTRACTS,
...BROWSER_TOOL_CONTRACTS,
diff --git a/src/contracts/firmwareToolContracts.ts b/src/contracts/firmwareToolContracts.ts
new file mode 100644
index 000000000..c3051dc2e
--- /dev/null
+++ b/src/contracts/firmwareToolContracts.ts
@@ -0,0 +1,47 @@
+import {
+ firmwareInputSchemas,
+ firmwareResultSchemas,
+} from "../domain/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 = [
+ {
+ name: "inspect_firmware_regions",
+ ...toolContractMetadata("inspect_firmware_regions"),
+ kind: "firmware-provider",
+ description:
+ "Inspect signature candidates in a local firmware file with Binwalk 3.1.0. Returns offsets, reported lengths, descriptions and raw confidence values. Length validation and runtime addresses remain unknown. No extraction or target execution. Linux, caller-supplied tool and util-linux prlimit required; 128 MiB input limit, one worker and 120-second deadline.",
+ inputSchema: firmwareInputSchemas.inspect_firmware_regions,
+ outputSchema: evidenceResultOf(
+ firmwareResultSchemas.inspect_firmware_regions,
+ ),
+ examples: [
+ {
+ title: "Inspect firmware regions",
+ input: { path: "/tmp/firmware.bin" },
+ },
+ ],
+ },
+ {
+ name: "extract_firmware",
+ ...toolContractMetadata("extract_firmware"),
+ kind: "firmware-provider",
+ description:
+ "Extract caller-selected firmware bytes with Unblob 26.6.4 into an absent output directory. Returns verified child paths/digests, task derivations, unknown chunks and extraction diagnostics inline. Preserves the default sandbox; publishes regular files only. Linux, caller-supplied tool, format-specific extractors and util-linux prlimit required. No mounts or extracted-code execution. Select a returned native file with open_binary for Ghidra analysis; decompressed offsets are not original-file addresses.",
+ inputSchema: firmwareInputSchemas.extract_firmware,
+ outputSchema: evidenceResultOf(firmwareResultSchemas.extract_firmware),
+ examples: [
+ {
+ title: "Extract selected firmware",
+ input: {
+ path: "/tmp/firmware.bin",
+ output_directory: "/tmp/firmware-output",
+ range: { offset: 64, length: 4096 },
+ },
+ },
+ ],
+ },
+] as const satisfies readonly ToolContract[];
diff --git a/src/contracts/toolContractTypes.ts b/src/contracts/toolContractTypes.ts
index 737daa557..c4234d25a 100644
--- a/src/contracts/toolContractTypes.ts
+++ b/src/contracts/toolContractTypes.ts
@@ -25,6 +25,7 @@ export const TOOL_KINDS = [
"artifact-provider",
"managed-provider",
"android-provider",
+ "firmware-provider",
"browser-provider",
"electron-provider",
"runtime-provider",
diff --git a/src/contracts/toolContracts.test.ts b/src/contracts/toolContracts.test.ts
index 2617e2bc3..0dc6a909f 100644
--- a/src/contracts/toolContracts.test.ts
+++ b/src/contracts/toolContracts.test.ts
@@ -6,6 +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 { ANDROID_TOOL_CONTRACTS } from "./androidToolContracts.js";
import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managedWorkflowToolContracts.js";
import { NATIVE_TOOL_CONTRACTS } from "./nativeToolContracts.js";
@@ -21,6 +22,7 @@ const GROUPS = {
artifact: ARTIFACT_TOOL_CONTRACTS,
managed: MANAGED_TOOL_CONTRACTS,
android: ANDROID_TOOL_CONTRACTS,
+ firmware: FIRMWARE_TOOL_CONTRACTS,
managed_workflow: MANAGED_WORKFLOW_TOOL_CONTRACTS,
browser_provider: BROWSER_PROVIDER_TOOL_CONTRACTS,
electron: ELECTRON_TOOL_CONTRACTS,
@@ -93,6 +95,8 @@ const PUBLISHED_TOOL_NAME_FLOOR = [
"inspect_electron_page",
"inspect_macho",
"inspect_managed_artifact",
+ "inspect_firmware_regions",
+ "extract_firmware",
"inspect_android_package",
"search_android_classes",
"inspect_android_class",
diff --git a/src/contracts/toolContracts.ts b/src/contracts/toolContracts.ts
index 56d66387d..ce7874c31 100644
--- a/src/contracts/toolContracts.ts
+++ b/src/contracts/toolContracts.ts
@@ -1,6 +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 { ANDROID_TOOL_CONTRACTS } from "./androidToolContracts.js";
import { MANAGED_WORKFLOW_TOOL_CONTRACTS } from "./managedWorkflowToolContracts.js";
import { BROWSER_PROVIDER_TOOL_CONTRACTS } from "./browserProviderToolContracts.js";
@@ -21,6 +22,7 @@ export const TOOL_CONTRACTS = [
...ARTIFACT_TOOL_CONTRACTS,
...MANAGED_TOOL_CONTRACTS,
...ANDROID_TOOL_CONTRACTS,
+ ...FIRMWARE_TOOL_CONTRACTS,
...MANAGED_WORKFLOW_TOOL_CONTRACTS,
...BROWSER_PROVIDER_TOOL_CONTRACTS,
...ELECTRON_TOOL_CONTRACTS,
diff --git a/src/contracts/toolEffects.ts b/src/contracts/toolEffects.ts
index 12c158b9e..2ad0adfcb 100644
--- a/src/contracts/toolEffects.ts
+++ b/src/contracts/toolEffects.ts
@@ -41,6 +41,17 @@ const sessionEvidence = effects({ mutatesSession: true });
/** Explicit effect audit for every public tool. */
export const TOOL_EFFECTS: Readonly> = {
+ inspect_firmware_regions: effects({
+ mutatesSession: true,
+ launchesProcess: true,
+ writesFilesystem: true,
+ }),
+ extract_firmware: effects({
+ mutatesSession: true,
+ launchesProcess: true,
+ writesFilesystem: true,
+ idempotent: false,
+ }),
inspect_android_package: effects({
mutatesSession: true,
launchesProcess: true,
diff --git a/src/domain/analysisErrorProjection.test.ts b/src/domain/analysisErrorProjection.test.ts
index f05d35bf4..5ab683417 100644
--- a/src/domain/analysisErrorProjection.test.ts
+++ b/src/domain/analysisErrorProjection.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
import {
AnalysisCapabilityUnavailableError,
AnalysisInputError,
+ AnalysisOutputError,
} from "./analysisErrorCore.js";
import { ArtifactOperationError } from "./artifactOperationError.js";
import { BinaryTargetError } from "./configurationErrors.js";
@@ -160,6 +161,23 @@ describe("analysis error projection: provider failures", () => {
});
describe("analysis error projection: caller contract", () => {
+ it("preserves the reported output constraint without exposing its internal cause", () => {
+ const projected = projectAnalysisError(
+ new AnalysisOutputError(
+ "extract_firmware",
+ "Report exceeded the declared byte budget",
+ { cause: new Error("private internal cause") },
+ ),
+ );
+ expect(projected).toMatchObject({
+ code: "unreadable_output",
+ details: {
+ operation: "extract_firmware",
+ reason: "Report exceeded the declared byte budget",
+ },
+ });
+ expect(JSON.stringify(projected)).not.toContain("private internal cause");
+ });
it("maps representative failures without exposing causes", () => {
const secretCause = new Error("secret-token");
const projected = [
diff --git a/src/domain/analysisErrorProjection.ts b/src/domain/analysisErrorProjection.ts
index 6f29499b4..b151a6fcf 100644
--- a/src/domain/analysisErrorProjection.ts
+++ b/src/domain/analysisErrorProjection.ts
@@ -10,6 +10,7 @@ import {
AnalysisCancelledError,
AnalysisCapabilityUnavailableError,
AnalysisInputError,
+ AnalysisOutputError,
AnalysisTimeoutError,
} from "./analysisErrorCore.js";
import { ArtifactOperationError } from "./artifactOperationError.js";
@@ -176,6 +177,8 @@ const errorDetails = (
const requestErrorDetails = (
error: AnalysisError,
): Readonly> | undefined => {
+ if (error instanceof AnalysisOutputError)
+ return { operation: error.operation, reason: error.reason };
if (error instanceof AnalysisInputError && error.issues.length > 0)
return {
operation: error.operation,
diff --git a/src/domain/firmwareAnalysis.ts b/src/domain/firmwareAnalysis.ts
new file mode 100644
index 000000000..85a90731b
--- /dev/null
+++ b/src/domain/firmwareAnalysis.ts
@@ -0,0 +1,145 @@
+import { z } from "zod";
+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() });
+const target = {
+ path: z.string().min(1).describe("Local firmware file; never executed"),
+};
+
+/** Explicit firmware inspection and extraction intent, independent of engines. */
+export const firmwareInputSchemas = {
+ inspect_firmware_regions: z.strictObject(target),
+ extract_firmware: z.strictObject({
+ ...target,
+ output_directory: z
+ .string()
+ .min(1)
+ .describe("Absolute, absent output directory; parent must exist"),
+ range: range
+ .optional()
+ .describe("Explicit file-byte interval; omit to extract the whole file"),
+ max_depth: z
+ .number()
+ .int()
+ .min(1)
+ .max(10)
+ .default(3)
+ .describe("Extraction depth; reaching it yields partial analysis"),
+ max_output_bytes: z
+ .number()
+ .int()
+ .min(1)
+ .max(512 * 1024 * 1024)
+ .default(256 * 1024 * 1024)
+ .describe(
+ "Staging file-byte budget, checked during extraction; transient overshoot is possible",
+ ),
+ max_output_files: z
+ .number()
+ .int()
+ .min(1)
+ .max(100_000)
+ .default(10_000)
+ .describe("Staging entry budget, including directories and links"),
+ }),
+} as const;
+
+/** Supported firmware operations. */
+export type FirmwareOperation = keyof typeof firmwareInputSchemas;
+/** Correlated, validated firmware request. */
+export type FirmwareRequest = {
+ [Name in FirmwareOperation]: {
+ operation: Name;
+ input: z.infer<(typeof firmwareInputSchemas)[Name]>;
+ };
+}[FirmwareOperation];
+/** Validate the operation with its exact input contract. */
+export const firmwareRequestSchema = z.discriminatedUnion("operation", [
+ z.strictObject({
+ operation: z.literal("inspect_firmware_regions"),
+ input: firmwareInputSchemas.inspect_firmware_regions,
+ }),
+ z.strictObject({
+ operation: z.literal("extract_firmware"),
+ input: firmwareInputSchemas.extract_firmware,
+ }),
+]);
+
+const engine = z.strictObject({
+ name: z.string(),
+ version: z.string(),
+ executable_path: z.string(),
+ executable_sha256: digestSchema,
+ source_revision: z.null(),
+ worker_count: z.literal(1),
+});
+const selection = z.strictObject({ ...range.shape, sha256: digestSchema });
+const chunk = z.strictObject({
+ input_path: z.string(),
+ provider_id: z.string(),
+ range,
+ handler: z.string().nullable(),
+ encrypted: z.boolean().nullable(),
+ root_file_range: range.nullable(),
+});
+
+/** Portable results retain reported boundaries, unknowns and extraction lineage. */
+export const firmwareResultSchemas = {
+ inspect_firmware_regions: z.strictObject({
+ engine,
+ input_size: bytes,
+ regions: z.array(
+ z.strictObject({
+ provider_id: z.string(),
+ offset: bytes,
+ reported_size: bytes,
+ signature: z.string(),
+ description: z.string(),
+ reported_confidence: z.number().int().min(0).max(255),
+ size_basis: z.literal("provider_reported_validation_unknown"),
+ }),
+ ),
+ coverage: z.literal("signature_scan"),
+ }),
+ extract_firmware: z.strictObject({
+ engine,
+ selection,
+ output_directory: z.string(),
+ coverage: z.enum(["complete", "partial"]),
+ files: z.array(
+ z.strictObject({
+ relative_path: z.string(),
+ path: z.string(),
+ size: bytes,
+ sha256: digestSchema,
+ reported_sha256: digestSchema.nullable(),
+ mime_type: z.string().nullable(),
+ analysis_depth: bytes.nullable(),
+ runtime_address: z.null(),
+ original_file_range: z.null(),
+ }),
+ ),
+ unpublished_entries: z.array(
+ z.strictObject({
+ relative_path: z.string(),
+ kind: z.enum(["symlink", "special"]),
+ link_target: z.string().nullable(),
+ }),
+ ),
+ chunks: z.array(chunk),
+ derivations: z.array(
+ z.strictObject({
+ parent_path: z.string(),
+ child_path: z.string(),
+ provider_blob_id: z.string(),
+ handler: z.string().nullable(),
+ parent_file_range: range.nullable(),
+ }),
+ ),
+ depth_limited_paths: z.array(z.string()),
+ diagnostics: z.array(jsonValueSchema),
+ published_bytes: bytes,
+ }),
+} as const;
diff --git a/src/firmware/FirmwareCommand.ts b/src/firmware/FirmwareCommand.ts
new file mode 100644
index 000000000..fe8f19f86
--- /dev/null
+++ b/src/firmware/FirmwareCommand.ts
@@ -0,0 +1,229 @@
+import { randomUUID } from "node:crypto";
+import { access, realpath } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute } from "node:path";
+import {
+ AnalysisCapabilityUnavailableError,
+ AnalysisCancelledError,
+ AnalysisTimeoutError,
+ AnalysisOutputError,
+} from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import {
+ spawnOwnedProviderProcess,
+ ProviderProcessSupervisor,
+ type OwnedProviderProcessSpawnOptions,
+ type SpawnedOwnedProviderProcess,
+} from "../process/ProviderProcess.js";
+import { cleanupOwnedProcessGroup } from "../process/ProcessOwnership.js";
+import { FIRMWARE_LIMITS } from "./FirmwareRelease.js";
+import {
+ hashFirmwareFile,
+ inventoryFirmwareOutput,
+ readFirmwareReport,
+} from "./FirmwareFiles.js";
+
+/** Injectable owned launcher for production protocol and lifecycle tests. */
+export type FirmwareLauncher = (
+ options: OwnedProviderProcessSpawnOptions,
+) => Promise;
+
+/** Resolve explicitly supplied executable paths; never install or search for engines. */
+export const resolveFirmwareCommand = async (
+ environment: Readonly>,
+ engine: "binwalk" | "unblob",
+ operation: string,
+) => {
+ const variable =
+ engine === "binwalk" ? "REA_BINWALK_COMMAND" : "REA_UNBLOB_COMMAND";
+ const configured = environment[variable];
+ if (
+ process.platform !== "linux" ||
+ configured === undefined ||
+ !isAbsolute(configured)
+ )
+ throw new AnalysisCapabilityUnavailableError(
+ engine,
+ operation,
+ `This integration requires Linux and an absolute ${variable} path to the caller-supplied tool`,
+ );
+ const command = await realpath(configured).catch((cause: unknown) => {
+ throw new AnalysisCapabilityUnavailableError(
+ engine,
+ operation,
+ `${variable} is unavailable: ${cause instanceof Error ? cause.message : String(cause)}`,
+ );
+ });
+ await access(command, constants.X_OK);
+ const limiter =
+ environment.REA_FIRMWARE_PRLIMIT_COMMAND ?? "/usr/bin/prlimit";
+ if (!isAbsolute(limiter))
+ throw new AnalysisCapabilityUnavailableError(
+ engine,
+ operation,
+ "REA_FIRMWARE_PRLIMIT_COMMAND must be absolute",
+ );
+ await access(limiter, constants.X_OK).catch(() => {
+ throw new AnalysisCapabilityUnavailableError(
+ engine,
+ operation,
+ `Resource limiter unavailable: ${limiter}; provide util-linux prlimit`,
+ );
+ });
+ return { command, limiter, sha256: await hashFirmwareFile(command) };
+};
+
+/** Execute one bounded provider command and verify its owned descendants have stopped. */
+export const runFirmwareCommand = async (context: {
+ engine: string;
+ operation: string;
+ command: string;
+ limiter: string;
+ args: readonly string[];
+ cwd: string;
+ environment: Readonly>;
+ signal: AbortSignal;
+ launcher?: FirmwareLauncher;
+ outputBudget?: { root: string; bytes: number; entries: number };
+ acceptReportedExtractionFailure?: boolean;
+}) => {
+ const { engine, operation, signal } = context;
+ signal.throwIfAborted();
+ const runId = `rea-firmware-${randomUUID()}`;
+ const spawned = await (context.launcher ?? spawnOwnedProviderProcess)({
+ command: context.limiter,
+ arguments: [
+ `--as=${FIRMWARE_LIMITS.addressSpaceBytes}`,
+ `--fsize=${context.outputBudget?.bytes ?? FIRMWARE_LIMITS.reportBytes}`,
+ "--core=0",
+ "--cpu=120",
+ "--",
+ context.command,
+ ...context.args,
+ ],
+ expectedCommand: null,
+ runId,
+ cwd: context.cwd,
+ hostEnvironment: context.environment,
+ env: {
+ TMPDIR: context.cwd,
+ OMP_NUM_THREADS: "1",
+ OPENBLAS_NUM_THREADS: "1",
+ RAYON_NUM_THREADS: "1",
+ NO_COLOR: "1",
+ },
+ });
+ const supervisor = new ProviderProcessSupervisor({
+ ...spawned,
+ ownsProcessLifetime: true,
+ cleanup:
+ spawned.cleanup ?? (() => cleanupOwnedProcessGroup(spawned.ownership)),
+ });
+ let failure: unknown;
+ try {
+ const deadline = Date.now() + FIRMWARE_LIMITS.timeoutMs;
+ while (!(await supervisor.waitForExit(100))) {
+ if (signal.aborted) throw new AnalysisCancelledError(operation);
+ if (Date.now() >= deadline)
+ throw new AnalysisTimeoutError(operation, FIRMWARE_LIMITS.timeoutMs);
+ if (context.outputBudget !== undefined)
+ await inventoryFirmwareOutput(
+ context.outputBudget.root,
+ context.outputBudget.bytes,
+ context.outputBudget.entries,
+ operation,
+ signal,
+ );
+ }
+ if (signal.aborted) throw new AnalysisCancelledError(operation);
+ } catch (cause: unknown) {
+ failure = cause;
+ }
+ const stopped = await supervisor.stop();
+ const snapshot = supervisor.snapshot();
+ supervisor.dispose();
+ if (stopped.status === "incomplete")
+ throw new ProviderCleanupError(engine, [runId, context.cwd], {
+ reason: stopped.reason,
+ leader_pid: spawned.ownership.leaderPid,
+ process_group_id: spawned.ownership.processGroupId,
+ exit_code: snapshot.exitCode ?? null,
+ signal: snapshot.signal ?? null,
+ stdout: snapshot.stdout.text,
+ stderr: snapshot.stderr.text,
+ stdout_bytes: snapshot.stdout.bytes,
+ stderr_bytes: snapshot.stderr.bytes,
+ previous_error: failure instanceof Error ? failure.message : null,
+ });
+ if (failure !== undefined) throw failure;
+ if (
+ snapshot.exitCode !== 0 &&
+ !(
+ context.acceptReportedExtractionFailure === true &&
+ snapshot.exitCode === 1
+ )
+ )
+ throw new ProviderAdapterError(engine, operation, {
+ diagnostics: {
+ reason:
+ "Tool failed; inspect exit status and stderr for format, dependency, sandbox or resource-limit failures",
+ exit_code: snapshot.exitCode ?? null,
+ signal: snapshot.signal ?? null,
+ stdout: snapshot.stdout.text,
+ stderr: snapshot.stderr.text,
+ stdout_bytes: snapshot.stdout.bytes,
+ stderr_bytes: snapshot.stderr.bytes,
+ },
+ });
+ return {
+ stdout: snapshot.stdout,
+ stderr: snapshot.stderr,
+ exit_code: snapshot.exitCode,
+ signal: snapshot.signal ?? null,
+ command: context.command,
+ args: [...context.args],
+ resource_limiter: context.limiter,
+ };
+};
+
+/** Preserve tool failure diagnostics when an accepted exit 1 has no usable report. */
+export const readFirmwareCommandReport = async (context: {
+ path: string;
+ engine: string;
+ operation: string;
+ execution: Awaited>;
+}): Promise => {
+ try {
+ return await readFirmwareReport(context.path, context.operation);
+ } catch (cause: unknown) {
+ if (context.execution.exit_code === 1)
+ throw new ProviderAdapterError(context.engine, context.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,
+ },
+ });
+ 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 },
+ );
+ }
+};
diff --git a/src/firmware/FirmwareFiles.ts b/src/firmware/FirmwareFiles.ts
new file mode 100644
index 000000000..92c801756
--- /dev/null
+++ b/src/firmware/FirmwareFiles.ts
@@ -0,0 +1,265 @@
+import { createHash } from "node:crypto";
+import { constants, createReadStream, createWriteStream } from "node:fs";
+import {
+ chmod,
+ lstat,
+ open,
+ readdir,
+ readlink,
+ realpath,
+} from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import {
+ AnalysisCancelledError,
+ AnalysisInputError,
+ AnalysisOutputError,
+} from "../domain/analysisErrorCore.js";
+import type { FirmwareRequest } from "../domain/firmwareAnalysis.js";
+import { readBoundedFileBytes } from "../process/BoundedFileBytes.js";
+import { FIRMWARE_LIMITS } from "./FirmwareRelease.js";
+
+/** One regular file or unpublished filesystem entry in a private extraction. */
+export interface FirmwareEntry {
+ readonly relativePath: string;
+ readonly path: string;
+ readonly size: number;
+ readonly kind: "file" | "symlink" | "special";
+ readonly linkTarget: string | null;
+}
+
+/** Hash a regular tool or extracted file without retaining its bytes in memory. */
+export const hashFirmwareFile = async (
+ path: string,
+ signal?: AbortSignal,
+): Promise => {
+ const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+ const hash = createHash("sha256");
+ try {
+ if (!(await handle.stat()).isFile())
+ throw new Error(`Not a regular file: ${path}`);
+ for await (const chunk of handle.createReadStream({ autoClose: false })) {
+ signal?.throwIfAborted();
+ hash.update(chunk);
+ }
+ } finally {
+ await handle.close();
+ }
+ return hash.digest("hex");
+};
+
+/** Copy and identify the exact bytes consumed by firmware providers. */
+export const snapshotFirmware = async (
+ request: FirmwareRequest,
+ root: string,
+ signal: AbortSignal,
+) => {
+ const sourcePath = resolve(request.input.path);
+ const source = await realpath(sourcePath);
+ const handle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+ const fullPath = join(root, "firmware.bin");
+ const hash = createHash("sha256");
+ let size = 0;
+ try {
+ const stat = await handle.stat();
+ if (
+ !stat.isFile() ||
+ stat.size === 0 ||
+ stat.size > FIRMWARE_LIMITS.inputBytes
+ )
+ throw new AnalysisInputError(request.operation, undefined, [
+ {
+ path: ["path"],
+ reason: "out_of_range",
+ message: `Firmware must be a nonempty regular file no larger than ${FIRMWARE_LIMITS.inputBytes} bytes`,
+ },
+ ]);
+ const meter = new Transform({
+ transform(chunk: Buffer, _encoding, callback) {
+ size += chunk.length;
+ if (size > FIRMWARE_LIMITS.inputBytes) {
+ callback(new Error("Firmware grew beyond the input byte budget"));
+ return;
+ }
+ hash.update(chunk);
+ callback(null, chunk);
+ },
+ });
+ await pipeline(
+ handle.createReadStream({ autoClose: false }),
+ meter,
+ createWriteStream(fullPath, { flags: "wx", mode: 0o600 }),
+ { signal },
+ );
+ } finally {
+ await handle.close();
+ }
+ await chmod(fullPath, 0o400);
+ const sha256 = hash.digest("hex");
+ const selected =
+ request.operation === "extract_firmware" ? request.input.range : undefined;
+ const offset = selected?.offset ?? 0;
+ const length = selected?.length ?? size;
+ if (length === 0 || offset > size || length > size - offset)
+ throw new AnalysisInputError(request.operation, undefined, [
+ {
+ path: ["range"],
+ reason: "out_of_range",
+ message: `Selected range must be within the ${size}-byte firmware file`,
+ },
+ ]);
+ let inputPath = fullPath;
+ if (selected !== undefined) {
+ inputPath = join(root, "selected.bin");
+ await pipeline(
+ createReadStream(fullPath, { start: offset, end: offset + length - 1 }),
+ createWriteStream(inputPath, { flags: "wx", mode: 0o600 }),
+ { signal },
+ );
+ await chmod(inputPath, 0o400);
+ }
+ return {
+ subject: { path: sourcePath, sha256, format: "file" as const },
+ size,
+ inputPath,
+ selection: {
+ offset,
+ length,
+ sha256:
+ selected === undefined
+ ? sha256
+ : await hashFirmwareFile(inputPath, signal),
+ },
+ };
+};
+
+/** Read a complete bounded report; oversized data is never reported as complete. */
+export const readFirmwareReport = async (
+ path: string,
+ operation: string,
+): Promise => {
+ const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+ try {
+ if (!(await handle.stat()).isFile())
+ throw new AnalysisOutputError(operation, "Report is not a regular file");
+ const bytes = await readBoundedFileBytes(
+ handle,
+ FIRMWARE_LIMITS.reportBytes,
+ );
+ if (bytes === undefined)
+ throw new AnalysisOutputError(
+ operation,
+ `Report exceeded ${FIRMWARE_LIMITS.reportBytes} bytes`,
+ );
+ try {
+ const value: unknown = JSON.parse(bytes.toString("utf8"));
+ return value;
+ } catch (cause: unknown) {
+ throw new AnalysisOutputError(
+ operation,
+ "Tool report is not valid complete JSON",
+ { cause },
+ );
+ }
+ } finally {
+ await handle.close();
+ }
+};
+
+/** Inventory private output without following links, enforcing aggregate staging budgets. */
+export const inventoryFirmwareOutput = async (
+ root: string,
+ maxBytes: number,
+ maxEntries: number,
+ operation: string,
+ signal?: AbortSignal,
+): Promise => {
+ const entries: FirmwareEntry[] = [];
+ const pending = [root];
+ let bytes = 0;
+ let count = 0;
+ while (pending.length > 0) {
+ if (signal?.aborted === true) throw new AnalysisCancelledError(operation);
+ const directory = pending.pop();
+ if (directory === undefined) break;
+ const directoryStat = await lstat(directory).catch((cause: unknown) => {
+ if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+ return undefined;
+ throw cause;
+ });
+ if (
+ directoryStat === undefined ||
+ !directoryStat.isDirectory() ||
+ directoryStat.isSymbolicLink()
+ )
+ continue;
+ const names = await readdir(directory).catch((cause: unknown) => {
+ if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+ return [];
+ throw cause;
+ });
+ for (const name of names.sort()) {
+ count++;
+ if (count > maxEntries)
+ throw new AnalysisOutputError(
+ operation,
+ `Staging entry budget exceeded (${maxEntries})`,
+ );
+ const path = join(directory, name);
+ const stat = await lstat(path).catch((cause: unknown) => {
+ if (
+ cause instanceof Error &&
+ "code" in cause &&
+ cause.code === "ENOENT"
+ )
+ return undefined;
+ throw cause;
+ });
+ if (stat === undefined) continue;
+ if (stat.isDirectory()) {
+ pending.push(path);
+ continue;
+ }
+ if (stat.isFile()) bytes += stat.size;
+ if (bytes > maxBytes)
+ throw new AnalysisOutputError(
+ operation,
+ `Staging byte budget exceeded (${maxBytes})`,
+ );
+ entries.push({
+ path,
+ relativePath: relative(root, path).split(sep).join("/"),
+ size: stat.size,
+ kind: stat.isSymbolicLink()
+ ? "symlink"
+ : stat.isFile()
+ ? "file"
+ : "special",
+ linkTarget: stat.isSymbolicLink() ? await readlink(path) : null,
+ });
+ }
+ }
+ return entries.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+};
+
+/** Bind producer paths to the selected input or private extraction tree. */
+export const firmwareLogicalPath = (
+ path: string,
+ inputPath: string,
+ outputRoot: string,
+): string => {
+ if (path === inputPath) return "$input";
+ const rel = relative(outputRoot, path);
+ if (
+ !isAbsolute(path) ||
+ rel === ".." ||
+ rel.startsWith(`..${sep}`) ||
+ isAbsolute(rel)
+ )
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ `Provider reported a path outside its owned output: ${path}`,
+ );
+ return rel === "" ? "$output" : `$output/${rel.split(sep).join("/")}`;
+};
diff --git a/src/firmware/FirmwareProvider.ts b/src/firmware/FirmwareProvider.ts
new file mode 100644
index 000000000..0cd612ce8
--- /dev/null
+++ b/src/firmware/FirmwareProvider.ts
@@ -0,0 +1,350 @@
+import { join, isAbsolute } from "node:path";
+import { z } from "zod";
+import type { FirmwareAnalysisPort } from "../application/FirmwareAnalysisPort.js";
+import {
+ createAnalysisExecution,
+ type ExecutionOptions,
+} from "../application/AnalysisProvider.js";
+import {
+ firmwareResultSchemas,
+ type FirmwareRequest,
+} from "../domain/firmwareAnalysis.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import {
+ AnalysisCancelledError,
+ AnalysisCapabilityUnavailableError,
+ AnalysisInputError,
+ AnalysisOutputError,
+ AnalysisTimeoutError,
+} from "../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../domain/providerCleanupError.js";
+import { err, ok } from "../domain/result.js";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+import { publishFirmwareExtraction } from "./FirmwarePublication.js";
+import {
+ FIRMWARE_LIMITS,
+ FIRMWARE_RELEASES,
+ BINWALK_PROVIDER_IDENTITY,
+ UNBLOB_PROVIDER_IDENTITY,
+} from "./FirmwareRelease.js";
+import {
+ resolveFirmwareCommand,
+ runFirmwareCommand,
+ readFirmwareCommandReport,
+ type FirmwareLauncher,
+} from "./FirmwareCommand.js";
+import { inventoryFirmwareOutput, snapshotFirmware } from "./FirmwareFiles.js";
+import {
+ normalizeBinwalkReport,
+ normalizeUnblobReport,
+} from "./FirmwareReports.js";
+
+type Outcome = Awaited>;
+const waitForPredecessor = (
+ predecessor: Promise,
+ operation: string,
+ signal?: AbortSignal,
+): Promise =>
+ new Promise((resolve, reject) => {
+ const abort = () => reject(new AnalysisCancelledError(operation));
+ signal?.addEventListener("abort", abort, { once: true });
+ if (signal?.aborted === true) abort();
+ void predecessor.then(() => {
+ signal?.removeEventListener("abort", abort);
+ resolve();
+ });
+ });
+const limitations = [
+ "Signature matches and reported sizes do not establish partition validity, encryption or runtime mappings. Binwalk may infer unknown lengths before emitting its report.",
+ "Only Linux is supported by this integration. One worker, inherited per-process address-space/file-size/CPU limits and a deadline constrain execution; staging byte and entry budgets are polled and may transiently overshoot. Limits are not aggregate process-memory or filesystem quotas.",
+ "Unblob's default sandbox and skip rules remain enabled. Missing external extractors, unknown chunks, encrypted chunks and depth limits yield partial coverage. Extracted code is never executed; only regular files are published, without executable permission bits.",
+ "The actual launcher executable is hashed. Interpreter, shared libraries and installed Python package dependencies are not independently attested; source revision remains unknown for caller-supplied builds.",
+] as const;
+
+/** Queued bring-your-own firmware adapters with private snapshots and owned cleanup. */
+export class FirmwareProvider implements FirmwareAnalysisPort {
+ #tail: Promise = Promise.resolve();
+ #cleanupFailure: AnalysisError | undefined;
+ constructor(
+ readonly environment: Readonly<
+ Record
+ > = process.env,
+ readonly launcher?: FirmwareLauncher,
+ ) {}
+
+ /** Inspect regions or explicitly extract selected bytes without changing the source. */
+ async execute(
+ request: FirmwareRequest,
+ options?: ExecutionOptions,
+ ): Promise {
+ const predecessor = this.#tail;
+ let release = () => {};
+ this.#tail = new Promise((resolve) => {
+ release = resolve;
+ });
+ // Cancel the caller promptly without letting a later request bypass its predecessor.
+ try {
+ await waitForPredecessor(predecessor, request.operation, options?.signal);
+ } catch (cause: unknown) {
+ void predecessor.then(release);
+ return err(
+ cause instanceof AnalysisError
+ ? cause
+ : new AnalysisCancelledError(request.operation),
+ );
+ }
+ try {
+ return await this.#execute(request, options);
+ } finally {
+ release();
+ }
+ }
+
+ async #execute(
+ request: FirmwareRequest,
+ options?: ExecutionOptions,
+ ): Promise {
+ let root: PrivateRuntimeRoot | undefined;
+ const engineName =
+ request.operation === "inspect_firmware_regions" ? "binwalk" : "unblob";
+ const deadline = AbortSignal.timeout(FIRMWARE_LIMITS.timeoutMs);
+ const signal =
+ options?.signal === undefined
+ ? deadline
+ : AbortSignal.any([options.signal, deadline]);
+ let outcome: Outcome;
+ try {
+ if (this.#cleanupFailure !== undefined) return err(this.#cleanupFailure);
+ if (signal.aborted) throw new AnalysisCancelledError(request.operation);
+ const command = await resolveFirmwareCommand(
+ this.environment,
+ engineName,
+ request.operation,
+ );
+ root = await PrivateRuntimeRoot.create({ prefix: "rea-firmware-" });
+ const target = await snapshotFirmware(request, root.path, signal);
+ const run = (
+ args: readonly string[],
+ outputBudget?: { root: string; bytes: number; entries: number },
+ ) =>
+ runFirmwareCommand({
+ engine: engineName,
+ operation: request.operation,
+ ...command,
+ args,
+ cwd: root?.path ?? "",
+ environment: this.environment,
+ signal,
+ ...(this.launcher === undefined ? {} : { launcher: this.launcher }),
+ ...(outputBudget === undefined
+ ? {}
+ : { outputBudget, acceptReportedExtractionFailure: true }),
+ });
+ const versionRun = await run(["--version"]);
+ const version = versionRun.stdout.text.trim();
+ const expected = FIRMWARE_RELEASES[engineName].version;
+ if (
+ versionRun.stdout.bytes > 1024 ||
+ (engineName === "binwalk"
+ ? version !== `binwalk ${expected}`
+ : version !== expected)
+ )
+ throw new AnalysisCapabilityUnavailableError(
+ engineName,
+ request.operation,
+ `Unsupported tool version ${version}; this adapter is verified against ${expected}`,
+ );
+ const engine = {
+ name: engineName,
+ version: expected,
+ executable_path: command.command,
+ executable_sha256: command.sha256,
+ source_revision: null,
+ worker_count: 1 as const,
+ };
+ const reportPath = join(root.path, "report.json");
+ let result: unknown;
+ let raw: unknown;
+ if (request.operation === "inspect_firmware_regions") {
+ const processRun = await run([
+ "--quiet",
+ "--search-all",
+ "--threads",
+ "1",
+ "--log",
+ reportPath,
+ target.inputPath,
+ ]);
+ const report = await readFirmwareCommandReport({
+ path: reportPath,
+ engine: engineName,
+ operation: request.operation,
+ execution: processRun,
+ });
+ result = firmwareResultSchemas.inspect_firmware_regions.parse({
+ engine,
+ input_size: target.size,
+ regions: normalizeBinwalkReport(
+ report,
+ target.inputPath,
+ target.size,
+ ),
+ coverage: "signature_scan",
+ });
+ raw = { report, execution: processRun, version_execution: versionRun };
+ } else {
+ if (!isAbsolute(request.input.output_directory))
+ throw new AnalysisInputError(request.operation, undefined, [
+ {
+ path: ["output_directory"],
+ reason: "invalid_format",
+ message: "Extraction output directory must be absolute",
+ },
+ ]);
+ const outputRoot = join(root.path, "extracted");
+ const processRun = await run(
+ [
+ "--process-num",
+ "1",
+ "--depth",
+ String(request.input.max_depth),
+ "--randomness-depth",
+ "0",
+ "--report",
+ reportPath,
+ "--log",
+ join(root.path, "unblob.log"),
+ "--extract-dir",
+ outputRoot,
+ target.inputPath,
+ ],
+ {
+ root: outputRoot,
+ bytes: request.input.max_output_bytes,
+ entries: request.input.max_output_files,
+ },
+ );
+ const report = await readFirmwareCommandReport({
+ path: reportPath,
+ engine: engineName,
+ operation: request.operation,
+ execution: processRun,
+ });
+ const normalized = normalizeUnblobReport(report, {
+ inputPath: target.inputPath,
+ outputRoot,
+ ...target.selection,
+ maxDepth: request.input.max_depth,
+ });
+ if (processRun.exit_code === 1 && normalized.diagnostics.length === 0)
+ throw new AnalysisOutputError(
+ request.operation,
+ "Unblob failed without a reported extraction diagnostic",
+ );
+ const entries = await inventoryFirmwareOutput(
+ outputRoot,
+ request.input.max_output_bytes,
+ request.input.max_output_files,
+ request.operation,
+ signal,
+ );
+ result = await publishFirmwareExtraction({
+ outputDirectory: request.input.output_directory,
+ entries,
+ normalized,
+ selection: target.selection,
+ engine,
+ signal,
+ });
+ raw = { report, execution: processRun, version_execution: versionRun };
+ }
+ outcome = ok(
+ createAnalysisExecution(
+ result,
+ engineName === "binwalk"
+ ? BINWALK_PROVIDER_IDENTITY
+ : UNBLOB_PROVIDER_IDENTITY,
+ {
+ subject: target.subject,
+ rawResult: raw,
+ limitations,
+ locations: [
+ {
+ kind: "file-offset-range",
+ start: target.selection.offset,
+ end: target.selection.offset + target.selection.length,
+ },
+ ],
+ },
+ ),
+ );
+ } catch (cause: unknown) {
+ outcome = err(
+ cause instanceof ProviderCleanupError
+ ? cause
+ : options?.signal?.aborted === true
+ ? new AnalysisCancelledError(request.operation)
+ : deadline.aborted
+ ? new AnalysisTimeoutError(
+ request.operation,
+ FIRMWARE_LIMITS.timeoutMs,
+ )
+ : cause instanceof AnalysisError
+ ? cause
+ : cause instanceof z.ZodError
+ ? new AnalysisOutputError(
+ request.operation,
+ "Tool report violated the pinned producer protocol",
+ { cause },
+ )
+ : new ProviderAdapterError(engineName, request.operation, {
+ cause,
+ diagnostics: {
+ reason:
+ cause instanceof Error
+ ? cause.message
+ : String(cause),
+ },
+ }),
+ );
+ if (!outcome.ok && outcome.error.cleanupIncomplete) {
+ this.#cleanupFailure =
+ root === undefined ||
+ outcome.error.cleanupResources.includes(root.path)
+ ? outcome.error
+ : new ProviderCleanupError(
+ engineName,
+ [...outcome.error.cleanupResources, root.path],
+ outcome.error instanceof ProviderAdapterError
+ ? (outcome.error.diagnostics ?? {
+ reason: outcome.error.message,
+ })
+ : { reason: outcome.error.message },
+ { cause: outcome.error },
+ );
+ }
+ }
+ // Never remove a workspace while process ownership remains uncertain.
+ if (this.#cleanupFailure !== undefined) return err(this.#cleanupFailure);
+ try {
+ await root?.close();
+ } catch (cause: unknown) {
+ this.#cleanupFailure = new ProviderCleanupError(
+ engineName,
+ [
+ root?.path ?? "unknown",
+ ...(outcome.ok && request.operation === "extract_firmware"
+ ? [request.input.output_directory]
+ : []),
+ ],
+ {
+ reason: cause instanceof Error ? cause.message : String(cause),
+ previous_result: outcome.ok ? outcome.value.result : null,
+ },
+ );
+ return err(this.#cleanupFailure);
+ }
+ return outcome;
+ }
+}
diff --git a/src/firmware/FirmwarePublication.ts b/src/firmware/FirmwarePublication.ts
new file mode 100644
index 000000000..db49244b8
--- /dev/null
+++ b/src/firmware/FirmwarePublication.ts
@@ -0,0 +1,115 @@
+import { createReadStream } from "node:fs";
+import { join } from "node:path";
+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 { hashFirmwareFile, type FirmwareEntry } from "./FirmwareFiles.js";
+import type { normalizeUnblobReport } from "./FirmwareReports.js";
+
+/** Publish verified regular files, preserving links as metadata and rolling back failed writes. */
+export const publishFirmwareExtraction = async (context: {
+ outputDirectory: string;
+ entries: readonly FirmwareEntry[];
+ normalized: ReturnType;
+ selection: { offset: number; length: number; sha256: string };
+ engine: z.infer["engine"];
+ signal: AbortSignal;
+}) => {
+ let tree: SafeOutputTree | undefined;
+ try {
+ const materialized = new Set(
+ context.entries
+ .filter((entry) => entry.kind === "file")
+ .map((entry) => `$output/${entry.relativePath}`),
+ );
+ for (const path of context.normalized.files.keys()) {
+ if (path !== "$input" && !materialized.has(path))
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ `Reported regular file is absent from materialized output: ${path}`,
+ );
+ }
+ const files = [];
+ const unpublished = [];
+ tree = await SafeOutputTree.create(context.outputDirectory);
+ for (const entry of context.entries) {
+ if (entry.kind !== "file") {
+ unpublished.push({
+ relative_path: entry.relativePath,
+ kind: entry.kind,
+ link_target: entry.linkTarget,
+ });
+ continue;
+ }
+ const logicalPath = `$output/${entry.relativePath}`;
+ const reported = context.normalized.files.get(logicalPath);
+ const sha256 = await hashFirmwareFile(entry.path, context.signal);
+ if (
+ (reported?.sha256 !== null &&
+ reported?.sha256 !== undefined &&
+ reported.sha256 !== sha256) ||
+ (context.normalized.sizes.has(logicalPath) &&
+ context.normalized.sizes.get(logicalPath) !== entry.size)
+ )
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ `Extracted bytes disagree with provider report: ${entry.relativePath}`,
+ );
+ await tree.write(
+ entry.relativePath,
+ createReadStream(entry.path),
+ sha256,
+ context.signal,
+ );
+ files.push({
+ relative_path: entry.relativePath,
+ path: join(tree.outputRoot, entry.relativePath),
+ size: entry.size,
+ sha256,
+ reported_sha256: reported?.sha256 ?? null,
+ mime_type: reported?.mimeType ?? null,
+ analysis_depth: reported?.depth ?? null,
+ runtime_address: null,
+ original_file_range: null,
+ });
+ }
+ const result = firmwareResultSchemas.extract_firmware.parse({
+ engine: context.engine,
+ selection: context.selection,
+ output_directory: tree.outputRoot,
+ coverage:
+ unpublished.length > 0 ? "partial" : context.normalized.coverage,
+ files,
+ unpublished_entries: unpublished,
+ chunks: context.normalized.chunks,
+ derivations: context.normalized.derivations,
+ depth_limited_paths: context.normalized.depth_limited_paths,
+ diagnostics: context.normalized.diagnostics,
+ published_bytes: files.reduce((sum, file) => sum + file.size, 0),
+ });
+ context.signal.throwIfAborted();
+ await tree.commit();
+ return result;
+ } catch (cause: unknown) {
+ try {
+ await tree?.rollback();
+ } catch (cleanupCause: unknown) {
+ throw new ProviderCleanupError(
+ "unblob",
+ [context.outputDirectory],
+ {
+ reason:
+ cleanupCause instanceof Error
+ ? cleanupCause.message
+ : String(cleanupCause),
+ previous_error:
+ cause instanceof Error ? cause.message : String(cause),
+ },
+ { cause: cleanupCause },
+ );
+ }
+ throw cause;
+ }
+};
diff --git a/src/firmware/FirmwareRelease.ts b/src/firmware/FirmwareRelease.ts
new file mode 100644
index 000000000..5a9a01ff1
--- /dev/null
+++ b/src/firmware/FirmwareRelease.ts
@@ -0,0 +1,34 @@
+/** Audited upstream sources; installed tool bytes are fingerprinted separately. */
+export const FIRMWARE_RELEASES = {
+ binwalk: {
+ version: "3.1.0",
+ revision: "4fdab3d464d97b68e0af9088df3f9e2e1545b21c",
+ repository: "https://github.com/ReFirmLabs/binwalk",
+ },
+ unblob: {
+ version: "26.6.4",
+ revision: "1fcc7a0a584a70a96c31f5a276c20944d199a089",
+ repository: "https://github.com/onekey-sec/unblob",
+ },
+} as const;
+
+/** Catalog identities; Evidence uses the version observed from the executed tool. */
+export const BINWALK_PROVIDER_IDENTITY = {
+ id: "binwalk",
+ name: "Binwalk",
+ version: FIRMWARE_RELEASES.binwalk.version,
+} as const;
+/** Catalog identity for explicit firmware extraction. */
+export const UNBLOB_PROVIDER_IDENTITY = {
+ id: "unblob",
+ name: "Unblob",
+ version: FIRMWARE_RELEASES.unblob.version,
+} as const;
+
+/** Resource policy for this Linux integration, not a claim of aggregate containment. */
+export const FIRMWARE_LIMITS = {
+ inputBytes: 128 * 1024 * 1024,
+ reportBytes: 8 * 1024 * 1024,
+ addressSpaceBytes: 1024 * 1024 * 1024,
+ timeoutMs: 120_000,
+} as const;
diff --git a/src/firmware/FirmwareReports.test.ts b/src/firmware/FirmwareReports.test.ts
new file mode 100644
index 000000000..8f658a6cc
--- /dev/null
+++ b/src/firmware/FirmwareReports.test.ts
@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+import {
+ normalizeBinwalkReport,
+ normalizeUnblobReport,
+} from "./FirmwareReports.js";
+
+const context = {
+ inputPath: "/private/input.bin",
+ outputRoot: "/private/output",
+ sha256: "a".repeat(64),
+ length: 20,
+ offset: 64,
+ maxDepth: 3,
+};
+const root = () => ({
+ task: {
+ path: context.inputPath,
+ depth: 0,
+ blob_id: "",
+ is_multi_file: false,
+ },
+ reports: [
+ {
+ __typename__: "StatReport",
+ path: context.inputPath,
+ size: 20,
+ is_file: true,
+ is_dir: false,
+ is_link: false,
+ link_target: null,
+ },
+ { __typename__: "HashReport", sha256: context.sha256 },
+ {
+ __typename__: "UnknownChunkReport",
+ id: "unknown",
+ start_offset: 0,
+ end_offset: 20,
+ size: 20,
+ randomness: null,
+ },
+ ],
+ subtasks: [],
+});
+
+describe("firmware producer boundaries", () => {
+ it("retains unknown chunks and their selected original-file range", () => {
+ const normalized = normalizeUnblobReport([root()], context);
+ expect(normalized.coverage).toBe("partial");
+ expect(normalized.chunks[0]).toMatchObject({
+ handler: null,
+ range: { offset: 0, length: 20 },
+ root_file_range: { offset: 64, length: 20 },
+ });
+ });
+ it("preserves unfamiliar report types as explicit diagnostics", () => {
+ const record = root();
+ const normalized = normalizeUnblobReport(
+ [
+ {
+ ...record,
+ reports: [
+ ...record.reports,
+ { __typename__: "FutureError", reason: "new producer facet" },
+ ],
+ },
+ ],
+ context,
+ );
+ expect(normalized.diagnostics).toEqual([
+ {
+ input_path: "$input",
+ report: { __typename__: "FutureError", reason: "new producer facet" },
+ },
+ ]);
+ expect(normalized.coverage).toBe("partial");
+ });
+ it("rejects unknown tasks outside the owned output and disconnected task graphs", () => {
+ const record = root();
+ for (const path of [
+ "/private/output/../escaped",
+ "/private/output/unconnected",
+ ]) {
+ const child = { ...record, task: { ...record.task, path, depth: 1 } };
+ expect(() => normalizeUnblobReport([record, child], context)).toThrow();
+ }
+ });
+ it("rejects absent root identity, inconsistent chunk bounds and duplicate tasks", () => {
+ const record = root();
+ expect(() => normalizeUnblobReport([], context)).toThrow("exactly one");
+ expect(() =>
+ normalizeUnblobReport(
+ [
+ {
+ ...record,
+ reports: record.reports.filter(
+ (report) => report.__typename__ !== "HashReport",
+ ),
+ },
+ ],
+ context,
+ ),
+ ).toThrow("hash");
+ expect(() =>
+ normalizeUnblobReport(
+ [
+ {
+ ...record,
+ reports: [
+ ...record.reports,
+ {
+ __typename__: "UnknownChunkReport",
+ id: "bad",
+ start_offset: 10,
+ end_offset: 21,
+ size: 11,
+ },
+ ],
+ },
+ ],
+ context,
+ ),
+ ).toThrow("bounds");
+ expect(() => normalizeUnblobReport([record, record], context)).toThrow(
+ "exactly one",
+ );
+ });
+ it("rejects empty, combined and extracting Binwalk reports", () => {
+ const record = {
+ Analysis: { file_path: context.inputPath, file_map: [], extractions: {} },
+ };
+ expect(normalizeBinwalkReport([record], context.inputPath, 20)).toEqual([]);
+ for (const report of [
+ [],
+ [record, record],
+ [
+ {
+ Analysis: {
+ ...record.Analysis,
+ extractions: { hit: { status: "success" } },
+ },
+ },
+ ],
+ ])
+ expect(() =>
+ normalizeBinwalkReport(report, context.inputPath, 20),
+ ).toThrow();
+ });
+});
diff --git a/src/firmware/FirmwareReports.ts b/src/firmware/FirmwareReports.ts
new file mode 100644
index 000000000..67826d0ad
--- /dev/null
+++ b/src/firmware/FirmwareReports.ts
@@ -0,0 +1,327 @@
+import { z } from "zod";
+import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
+import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
+import { digestSchema } from "../domain/digests.js";
+import { firmwareLogicalPath } from "./FirmwareFiles.js";
+
+const integer = z.number().int().min(0).max(Number.MAX_SAFE_INTEGER);
+const signature = z.object({
+ id: z.string().min(1),
+ offset: integer,
+ size: integer,
+ name: z.string(),
+ description: z.string(),
+ confidence: z.number().int().min(0).max(255),
+ always_display: z.boolean(),
+ extraction_declined: z.boolean(),
+});
+const scan = z.array(
+ z.object({
+ Analysis: z.object({
+ file_path: z.string(),
+ file_map: z.array(signature),
+ extractions: z.record(z.string(), jsonValueSchema),
+ }),
+ }),
+);
+const report = z.object({ __typename__: z.string() }).catchall(jsonValueSchema);
+const task = z.object({
+ path: z.string(),
+ depth: integer,
+ blob_id: z.string(),
+ is_multi_file: z.boolean(),
+});
+const extraction = z.array(
+ z.object({ task, reports: z.array(report), subtasks: z.array(task) }),
+);
+const stat = z.object({
+ __typename__: z.literal("StatReport"),
+ path: z.string(),
+ size: integer,
+ is_dir: z.boolean(),
+ is_file: z.boolean(),
+ is_link: z.boolean(),
+ link_target: z.string().nullable(),
+});
+const hashes = z.object({ sha256: digestSchema });
+const region = z.object({
+ id: z.string(),
+ start_offset: integer,
+ end_offset: integer,
+ size: integer,
+});
+const known = new Set([
+ "StatReport",
+ "HashReport",
+ "FileMagicReport",
+ "RandomnessReport",
+ "ChunkReport",
+ "UnknownChunkReport",
+ "CarveDirectoryReport",
+ "MultiFileReport",
+]);
+
+/** Interpret the pinned Binwalk report without inventing validated region lengths. */
+export const normalizeBinwalkReport = (
+ raw: unknown,
+ inputPath: string,
+ size: number,
+) => {
+ const records = scan.parse(raw);
+ const analysis = records[0]?.Analysis;
+ if (
+ records.length !== 1 ||
+ analysis?.file_path !== inputPath ||
+ Object.keys(analysis.extractions).length !== 0
+ )
+ throw new AnalysisOutputError(
+ "inspect_firmware_regions",
+ "Expected one inspection-only report for the selected immutable input",
+ );
+ return analysis.file_map.map((hit) => {
+ if (hit.offset >= size || hit.size > size - hit.offset)
+ throw new AnalysisOutputError(
+ "inspect_firmware_regions",
+ "Reported region lies outside the selected file",
+ );
+ return {
+ provider_id: hit.id,
+ offset: hit.offset,
+ reported_size: hit.size,
+ signature: hit.name,
+ description: hit.description,
+ reported_confidence: hit.confidence,
+ size_basis: "provider_reported_validation_unknown" as const,
+ };
+ });
+};
+
+/** Normalize Unblob's unordered task graph, retaining unknown and failed analyses. */
+export const normalizeUnblobReport = (
+ raw: unknown,
+ context: {
+ inputPath: string;
+ outputRoot: string;
+ sha256: string;
+ length: number;
+ offset: number;
+ maxDepth: number;
+ },
+) => {
+ const records = extraction.parse(raw);
+ const logical = (path: string) =>
+ firmwareLogicalPath(path, context.inputPath, context.outputRoot);
+ const roots = records.filter(
+ ({ task: item }) => item.path === context.inputPath && item.depth === 0,
+ );
+ if (roots.length !== 1)
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ "Expected exactly one selected input task",
+ );
+ const rootHash = roots[0]?.reports.find(
+ (r) => r.__typename__ === "HashReport",
+ );
+ if (
+ rootHash === undefined ||
+ hashes.parse(rootHash).sha256 !== context.sha256
+ )
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ "Unblob input hash disagrees with selected snapshot",
+ );
+ const files = new Map<
+ string,
+ { sha256: string | null; mimeType: string | null; depth: number }
+ >();
+ const sizes = new Map();
+ const depths: string[] = [];
+ const diagnostics: JsonValue[] = [];
+ const chunks: {
+ input_path: string;
+ provider_id: string;
+ range: { offset: number; length: number };
+ handler: string | null;
+ encrypted: boolean | null;
+ root_file_range: { offset: number; length: number } | null;
+ }[] = [];
+ const seen = new Set();
+ for (const record of records) {
+ const path = logical(record.task.path);
+ if (seen.has(path))
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ `Duplicate analysis task: ${path}`,
+ );
+ seen.add(path);
+ if (record.task.depth >= context.maxDepth) depths.push(path);
+ const metadata = record.reports.find(
+ (r) => r.__typename__ === "StatReport",
+ );
+ if (metadata === undefined)
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ `Missing StatReport: ${path}`,
+ );
+ const parsedStat = stat.parse(metadata);
+ if (parsedStat.path !== record.task.path)
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ `StatReport is bound to another task: ${path}`,
+ );
+ if (path === "$input" && parsedStat.size !== context.length)
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ "Unblob input size disagrees with selected snapshot",
+ );
+ if (
+ path === "$input" &&
+ (!parsedStat.is_file || parsedStat.is_link || parsedStat.is_dir)
+ )
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ "Selected input was not reported as a regular file",
+ );
+ sizes.set(path, parsedStat.size);
+ const hash = record.reports.find((r) => r.__typename__ === "HashReport");
+ const magic = record.reports.find(
+ (r) => r.__typename__ === "FileMagicReport",
+ );
+ if (parsedStat.is_file && !parsedStat.is_link)
+ files.set(path, {
+ sha256: hash === undefined ? null : hashes.parse(hash).sha256,
+ mimeType:
+ magic === undefined
+ ? null
+ : z.object({ mime_type: z.string() }).parse(magic).mime_type,
+ depth: record.task.depth,
+ });
+ for (const item of record.reports) {
+ if (!known.has(item.__typename__))
+ diagnostics.push(
+ jsonValueSchema.parse({ input_path: path, report: item }),
+ );
+ if (
+ item.__typename__ === "ChunkReport" ||
+ item.__typename__ === "UnknownChunkReport"
+ ) {
+ const parsed = region.parse(item);
+ if (
+ parsed.end_offset <= parsed.start_offset ||
+ parsed.end_offset > parsedStat.size ||
+ parsed.size !== parsed.end_offset - parsed.start_offset
+ )
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ `Invalid chunk bounds for ${path}`,
+ );
+ const detail =
+ item.__typename__ === "ChunkReport"
+ ? z
+ .object({
+ handler_name: z.string(),
+ is_encrypted: z.boolean(),
+ extraction_reports: z.array(jsonValueSchema),
+ })
+ .parse(item)
+ : null;
+ if (detail !== null)
+ for (const problem of detail.extraction_reports)
+ diagnostics.push({ input_path: path, report: problem });
+ chunks.push({
+ input_path: path,
+ provider_id: parsed.id,
+ range: { offset: parsed.start_offset, length: parsed.size },
+ handler: detail?.handler_name ?? null,
+ encrypted: detail?.is_encrypted ?? null,
+ root_file_range:
+ path === "$input"
+ ? {
+ offset: context.offset + parsed.start_offset,
+ length: parsed.size,
+ }
+ : null,
+ });
+ }
+ }
+ }
+ const recordsByPath = new Map(
+ records.map((record) => [record.task.path, record.task]),
+ );
+ const chunksByOrigin = new Map();
+ for (const item of chunks) {
+ const key = JSON.stringify([item.input_path, item.provider_id]);
+ if (chunksByOrigin.has(key))
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ `Duplicate chunk identity in ${item.input_path}`,
+ );
+ chunksByOrigin.set(key, item);
+ }
+ const derivations = records.flatMap((record) =>
+ record.subtasks.map((child) => {
+ const parentPath = logical(record.task.path);
+ const childPath = logical(child.path);
+ if (!seen.has(childPath))
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ `Missing child task: ${childPath}`,
+ );
+ const reportedChild = recordsByPath.get(child.path);
+ if (
+ reportedChild?.depth !== child.depth ||
+ reportedChild.blob_id !== child.blob_id ||
+ reportedChild.is_multi_file !== child.is_multi_file
+ )
+ throw new AnalysisOutputError(
+ "extract_firmware",
+ `Child task identity disagrees with its analysis: ${childPath}`,
+ );
+ const origin = chunksByOrigin.get(
+ JSON.stringify([parentPath, child.blob_id]),
+ );
+ return {
+ parent_path: parentPath,
+ child_path: childPath,
+ provider_blob_id: child.blob_id,
+ handler: origin?.handler ?? null,
+ parent_file_range: origin?.range ?? null,
+ };
+ }),
+ );
+ const reachable = new Set(["$input"]);
+ const pending = ["$input"];
+ const childrenByParent = new Map