[PR #844] [MERGED] fix(firmware): accept the verified Binwalk and Unblob release lines #2281

New issue

Closed

opened 2026-10-16 21:16:42 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:16:42 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/844
Author: @morluto
Created: 10/7/2026
Status: ✅ Merged
Merged: 10/7/2026
Merged by: @morluto

Base: main ← Head: cursor/firmware-version-line-6404

📝 Commits (2)

c665a9e fix(firmware): accept the verified Binwalk and Unblob release lines
0f10d20 chore(docs): regenerate skill metadata after firmware contract text

📊 Changes

15 files changed (+249 additions, -32 deletions)

View changed files

📝 docs/firmware-analysis.md (+7 -3)
📝 docs/product-catalog.json (+2 -2)
📝 docs/testing.md (+3 -1)
📝 docs/verification/managed-conformance-manifest.json (+2 -2)
📝 skills/reverse-engineer-anything/SKILL.md (+1 -1)
📝 src/application/CapabilityInventory.ts (+1 -1)
📝 src/contracts/firmwareToolContracts.ts (+2 -2)
📝 src/firmware/FirmwareProvider.ts (+22 -14)
📝 src/firmware/FirmwareRelease.ts (+1 -1)
➕ src/firmware/FirmwareVersion.test.ts (+50 -0)
➕ src/firmware/FirmwareVersion.ts (+116 -0)
📝 src/generatedMcpToolCatalog.ts (+1 -1)
📝 tests/boundary/firmware/firmwareIntegration.test.ts (+31 -0)
📝 tests/fixtures/firmware/producer.mjs (+6 -3)
📝 tests/fixtures/firmware/provider.ts (+4 -1)

📄 Description

Summary

Binwalk and Unblob were the remaining caller-supplied tools rejected by an exact --version string. Inspection required stdout binwalk 3.1.0 and extraction required stdout 26.6.4. A later patch on the same line never reached the report parser, and a match stored that constant as the engine version.

Admission now follows the audited release line. Binwalk 3.1.x and Unblob 26.6.x are accepted. 3.1.0 and 26.6.4 stay the verified builds. Another build on the line is reported as observed and carries a limitation that the report parser was verified against the audited release. Other lines, and banners that are not the observed producer shape, stay unsupported and the error names the accepted line.

Problem and expected behavior

inspect_firmware_regions and extract_firmware threw AnalysisCapabilityUnavailableError when the banner was not exactly the audited string. The engine record and Evidence provider version then used that constant rather than the banner that ran.

The report parsers already reject a producer representation they do not understand. The version gate should admit the release line those parsers were written for, keep the observed version, and say when the build is not the one the parser was verified against. Real verify:firmware still uses Binwalk 3.1.0 and Unblob 26.6.4.

Change and scope

src/firmware/FirmwareVersion.ts parses Binwalk's binwalk <version> banner and Unblob's bare version token.
Same major.minor as the audited release is accepted, including a distro suffix such as 3.1.0-1. 3.2.0 and 26.7.0 are not.
Evidence and the engine record use the observed version. A compatible build adds one limitation.
Tool descriptions, doctor remediation, and firmware docs name the line and the verified build.
Not changed: JADX's exact server version, because that JAR is SHA-256 pinned; the Linux Hopper launcher hash; NativeAOT fixture SDK 8.0.416; session handshakes; and verify:ghidra requiring 12.1.4. Those compare a launched identity or a byte-stable fixture, not a caller-supplied install line.

Contract and boundary impact

Semantic owner and earliest changed stage: firmware command admission, after --version and before report parsing.
CLI and MCP/tool-catalog contract: tool descriptions now say Binwalk 3.1.x (verified with 3.1.0) and Unblob 26.6.x (verified with 26.6.4). Schemas are unchanged. Generated catalog digests moved with that text.
Provider, bridge, target-format, or platform compatibility: Linux caller-supplied Binwalk and Unblob admission widens from two exact banners to those release lines.
Evidence, artifact, provenance, or reconstruction contract: provider version and engine.version are the observed release. Source revision stays unknown. Compatible builds add one limitation.
Process execution, authorization, cleanup, or containment impact: none.
Generated metadata (docs/product-catalog.json), package, or installation impact: catalog tool digest updated. No package or installer change.

Evidence and regression coverage

Tests added or updated: src/firmware/FirmwareVersion.test.ts covers verified banners, a later patch, a distro suffix, another line, and a banner that is not the producer shape. tests/boundary/firmware/firmwareIntegration.test.ts covers a 3.1.2 inspection result and a 3.2.0 rejection that names Binwalk 3.1.x.
Base reproduction or other evidence: the previous gate compared stdout with binwalk 3.1.0 or 26.6.4 and then assigned version: expected.
User-visible CLI/MCP output (if applicable): a Binwalk 3.2.0 banner reports Unsupported tool version binwalk 3.2.0; accepted releases are Binwalk 3.1.x (verified with 3.1.0). A 3.1.2 result includes This session uses Binwalk 3.1.2. The report parser is verified against 3.1.0; other 3.1.x builds are accepted and the observed version is reported.
Remaining proof gaps: npm run verify:firmware was not run. This environment does not have Binwalk or Unblob. Acceptance of 3.1.x and 26.6.x is a parser-contract claim, not a new real-tool proof.

For evidence-bearing changes:

Observed, derived, and inferred claims remain distinguishable.
Artifact identity, source provenance, and failed attempts remain preserved.
Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

npx vitest run src/firmware/FirmwareVersion.test.ts tests/boundary/firmware/firmwareIntegration.test.ts src/firmware/FirmwareReports.test.ts src/firmware/FirmwareCommand.test.ts — 40 tests passed.
npm run build:cached, then node scripts/generate-mcp-tool-catalog.mjs and node scripts/generate-product-catalog.mjs — catalogs regenerated.
npm run check:fast during pre-push — typecheck and lint passed.
Real Binwalk/Unblob verification was not performed.

Compatibility, safety, and release

Breaking changes or migration steps: none. The audited banners still pass and no longer add the unverified-build limitation.
Real Hopper/Ghidra, browser, or OS coverage: not applicable. Firmware real-provider verification was not run.
Package or release metadata impact: generated product-catalog tool digest only.
Security, privacy, process, or containment review: none. REA still does not install Binwalk or Unblob, and it still refuses a banner from another release line before parsing a report.

Review checklist

The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/844 **Author:** [@morluto](https://github.com/morluto) **Created:** 10/7/2026 **Status:** ✅ Merged **Merged:** 10/7/2026 **Merged by:** [@morluto](https://github.com/morluto) **Base:** `main` ← **Head:** `cursor/firmware-version-line-6404` --- ### 📝 Commits (2) - [`c665a9e`](https://github.com/morluto/rea/commit/c665a9e4bfb670a63f3b7c37621e0ae3a66fba95) fix(firmware): accept the verified Binwalk and Unblob release lines - [`0f10d20`](https://github.com/morluto/rea/commit/0f10d206a139e8fbf95f61a68c12b0538ebea5d7) chore(docs): regenerate skill metadata after firmware contract text ### 📊 Changes **15 files changed** (+249 additions, -32 deletions) <details> <summary>View changed files</summary> 📝 `docs/firmware-analysis.md` (+7 -3) 📝 `docs/product-catalog.json` (+2 -2) 📝 `docs/testing.md` (+3 -1) 📝 `docs/verification/managed-conformance-manifest.json` (+2 -2) 📝 `skills/reverse-engineer-anything/SKILL.md` (+1 -1) 📝 `src/application/CapabilityInventory.ts` (+1 -1) 📝 `src/contracts/firmwareToolContracts.ts` (+2 -2) 📝 `src/firmware/FirmwareProvider.ts` (+22 -14) 📝 `src/firmware/FirmwareRelease.ts` (+1 -1) ➕ `src/firmware/FirmwareVersion.test.ts` (+50 -0) ➕ `src/firmware/FirmwareVersion.ts` (+116 -0) 📝 `src/generatedMcpToolCatalog.ts` (+1 -1) 📝 `tests/boundary/firmware/firmwareIntegration.test.ts` (+31 -0) 📝 `tests/fixtures/firmware/producer.mjs` (+6 -3) 📝 `tests/fixtures/firmware/provider.ts` (+4 -1) </details> ### 📄 Description  ## Summary Binwalk and Unblob were the remaining caller-supplied tools rejected by an exact `--version` string. Inspection required stdout `binwalk 3.1.0` and extraction required stdout `26.6.4`. A later patch on the same line never reached the report parser, and a match stored that constant as the engine version. Admission now follows the audited release line. Binwalk 3.1.x and Unblob 26.6.x are accepted. `3.1.0` and `26.6.4` stay the verified builds. Another build on the line is reported as observed and carries a limitation that the report parser was verified against the audited release. Other lines, and banners that are not the observed producer shape, stay unsupported and the error names the accepted line. ## Problem and expected behavior `inspect_firmware_regions` and `extract_firmware` threw `AnalysisCapabilityUnavailableError` when the banner was not exactly the audited string. The engine record and Evidence provider version then used that constant rather than the banner that ran. The report parsers already reject a producer representation they do not understand. The version gate should admit the release line those parsers were written for, keep the observed version, and say when the build is not the one the parser was verified against. Real `verify:firmware` still uses Binwalk 3.1.0 and Unblob 26.6.4. ## Change and scope - `src/firmware/FirmwareVersion.ts` parses Binwalk's `binwalk <version>` banner and Unblob's bare version token. - Same major.minor as the audited release is accepted, including a distro suffix such as `3.1.0-1`. `3.2.0` and `26.7.0` are not. - Evidence and the engine record use the observed version. A compatible build adds one limitation. - Tool descriptions, doctor remediation, and firmware docs name the line and the verified build. - Not changed: JADX's exact server version, because that JAR is SHA-256 pinned; the Linux Hopper launcher hash; NativeAOT fixture SDK `8.0.416`; session handshakes; and `verify:ghidra` requiring 12.1.4. Those compare a launched identity or a byte-stable fixture, not a caller-supplied install line. ## Contract and boundary impact - Semantic owner and earliest changed stage: firmware command admission, after `--version` and before report parsing. - CLI and MCP/tool-catalog contract: tool descriptions now say Binwalk 3.1.x (verified with 3.1.0) and Unblob 26.6.x (verified with 26.6.4). Schemas are unchanged. Generated catalog digests moved with that text. - Provider, bridge, target-format, or platform compatibility: Linux caller-supplied Binwalk and Unblob admission widens from two exact banners to those release lines. - Evidence, artifact, provenance, or reconstruction contract: provider version and `engine.version` are the observed release. Source revision stays unknown. Compatible builds add one limitation. - Process execution, authorization, cleanup, or containment impact: none. - Generated metadata (`docs/product-catalog.json`), package, or installation impact: catalog tool digest updated. No package or installer change. ## Evidence and regression coverage - Tests added or updated: `src/firmware/FirmwareVersion.test.ts` covers verified banners, a later patch, a distro suffix, another line, and a banner that is not the producer shape. `tests/boundary/firmware/firmwareIntegration.test.ts` covers a 3.1.2 inspection result and a 3.2.0 rejection that names `Binwalk 3.1.x`. - Base reproduction or other evidence: the previous gate compared stdout with `binwalk 3.1.0` or `26.6.4` and then assigned `version: expected`. - User-visible CLI/MCP output (if applicable): a Binwalk 3.2.0 banner reports `Unsupported tool version binwalk 3.2.0; accepted releases are Binwalk 3.1.x (verified with 3.1.0).` A 3.1.2 result includes `This session uses Binwalk 3.1.2. The report parser is verified against 3.1.0; other 3.1.x builds are accepted and the observed version is reported.` - Remaining proof gaps: `npm run verify:firmware` was not run. This environment does not have Binwalk or Unblob. Acceptance of 3.1.x and 26.6.x is a parser-contract claim, not a new real-tool proof. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npx vitest run src/firmware/FirmwareVersion.test.ts tests/boundary/firmware/firmwareIntegration.test.ts src/firmware/FirmwareReports.test.ts src/firmware/FirmwareCommand.test.ts` — 40 tests passed. - `npm run build:cached`, then `node scripts/generate-mcp-tool-catalog.mjs` and `node scripts/generate-product-catalog.mjs` — catalogs regenerated. - `npm run check:fast` during pre-push — typecheck and lint passed. - Real Binwalk/Unblob verification was not performed. ## Compatibility, safety, and release - Breaking changes or migration steps: none. The audited banners still pass and no longer add the unverified-build limitation. - Real Hopper/Ghidra, browser, or OS coverage: not applicable. Firmware real-provider verification was not run. - Package or release metadata impact: generated product-catalog tool digest only. - Security, privacy, process, or containment review: none. REA still does not install Binwalk or Unblob, and it still refuses a banner from another release line before parsing a report. ## Review checklist - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims.  <div><a href="https://cursor.com/agents/bc-44a88d98-6d9b-4da2-a464-22f0c2a36404?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-44a88d98-6d9b-4da2-a464-22f0c2a36404&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:16:42 +00:00