Introducing a new way to review your PRs.

Read the announcement

morluto / rea

Reverse engineer anything with agents, from app behavior down to native binaries.

View on GitHub

27 documents · Updated Nov 20, 2026

docs / firmware-and-embedded-analysis

Firmware and embedded analysis

Firmware and embedded analysis turns local images into evidence about their layout, contents, and hardware description. It supports external tools for broad firmware carving and portable readers for ESP images and flattened device trees. This page is a child of Artifact and application analysis and relates to UEFI firmware inspection, Binary diagnostics and comparison, Application reconstruction, and JavaScript and desktop reconstruction.

Analysis model

Embedded analysis starts with a stable local file and returns findings with source identity, locations, and limits. The workflow does not run firmware, connect to a device, or treat a decoded address as proof of runtime behavior.

Static target inspection

Static target inspection reads bytes without changing the source or executing extracted code. The result keeps observed facts separate from derived facts, so callers can see which conclusions come from file structure and which depend on a format rule.

The main target classes are:

  • Generic firmware files that need signature scanning or extraction.
  • ESP32-family images and complete ESP flash dumps.
  • Flattened device-tree blobs (DTBs), which describe hardware and boot settings.
  • Native files found after extraction, which can be sent to the native analysis workflows described in Binary diagnostics and comparison.

References: docs/firmware-analysis.md• L1-10 docs/esp-image.md• L1-7 docs/devicetree.md• L1-7 src/…/devicetree.ts• L47-94

Provider-backed firmware analysis

The firmware provider covers broad inspection and extraction through separate caller-supplied engines. Region inspection uses Binwalk, while extraction uses Unblob; configuring one does not make the other available. The provider runs only on Linux and requires an absolute path to the selected tool and its resource limiter. It records the compatible engine version, executable identity, raw report, and known limits in Evidence.

Before an engine reads the source, the shared file boundary admits a non-empty regular file, copies the exact bytes into private staging, and records the source digest. It can also stage a caller-selected byte range. Cancellation before this admission creates no snapshot. If the requested path uses a supported parent or final symlink, admission follows the filesystem-selected file while Evidence keeps the requested path and the selected bytes' digest. The provider checks the selected tool version before analysis and runs it with bounded CPU, address-space, file-output, diagnostic, and deadline limits. It serializes work for one provider instance and retries retained cleanup before it admits later work. This gives the CLI and MCP the same meaning for paths, byte ranges, time limits, partial coverage, and cleanup outcomes.

The provider workflow has this shape:

flowchart LR
    I[Local firmware file] --> A[Source admission]
    A --> S[Private snapshot]
    S --> E[Caller-supplied engine]
    E --> R[Normalized report]
    R --> V[Verified inventory or region findings]
    V --> O[Evidence and recovery limits]

References: src/…/FirmwareSourceAdmission.test.ts• L16-105 src/…/firmwareToolRequirements.ts• L24-47 src/…/FirmwareCommand.ts• L77-157 src/…/FirmwareProvider.ts• L180-214 src/…/FirmwareProvider.ts• L353-445 src/…/FirmwareFiles.ts• L111-201

Firmware image workflows

Generic firmware analysis answers two different questions: where recognizable regions occur, and what can be safely extracted from selected bytes. Keeping these questions separate makes a missing extraction dependency different from a failed region scan.

Region inspection

Region inspection finds producer-reported signature candidates and their file offsets. It reports the producer's size and confidence values, but it does not prove that a region is a valid partition, has a usable address, or represents executable code.

Use this workflow to decide which part of a large image needs closer inspection. A returned region can then become the input to extraction or to a later artifact or native workflow.

References: docs/firmware-analysis.md• L94-128 src/…/firmwareToolContracts.ts• L13-29 src/…/firmwareAnalysis.ts• L155-172 src/…/FirmwareReports.ts• L195-227

Firmware extraction

Firmware extraction materializes regular files from the whole image or from a caller-selected byte range. It checks the producer report against the selected snapshot, verifies the extracted bytes before publication, and returns file digests, producer lineage, diagnostics, and explicit gaps so a partial result remains useful without looking complete.

Extraction can stop at an unknown or encrypted chunk, a missing format extractor, a failed stage, a depth limit, or a staging limit. extraction_gaps names the affected input path and points to a recovery instruction when an existing capability can continue the work. For nested files, the gap range is relative to that published child; it does not pretend that decompressed offsets are offsets in the original image. A continuation can point to the child as a new input or explain why the same extraction cannot advance. A nested extraction test protects these coverage and recovery rules.

The output directory must be absent before publication. REA publishes regular files only and keeps links and special entries as metadata. It does not execute the result, follow symbolic links, or preserve executable permission bits. It applies both a file-count budget and a byte budget to the private staging tree, so an extraction that exceeds either budget fails instead of producing an incomplete inventory. A producer must also leave a usable report; a successful process exit alone does not create Evidence. Failed cleanup can retain the private workspace and its recovery state instead of allowing uncertain ownership to be discarded.

The extraction flow has this shape:

flowchart LR
    I[Selected input bytes] --> P[Producer task graph]
    P --> N[Normalized files and coverage]
    N --> G[Gap and continuation records]
    N --> V[Hash and size checks]
    V --> O[Safe output directory]
    G --> E[Evidence with limits]
    O --> E

References: src/…/FirmwareCommand.ts• L411-497 src/…/FirmwareFiles.ts• L234-297 src/…/FirmwareFiles.ts• L359-538 src/…/FirmwareReports.ts• L230-639 src/…/FirmwarePublication.ts• L91-280 src/…/FirmwarePublication.ts• L284-510 src/…/FirmwareNestedCoverage.test.ts• L148-264

ESP analysis

ESP analysis uses the artifact workflow rather than the external firmware engines. It reads ESP structure directly from the file, which makes app images, bootloaders, and flash dumps available on hosts that do not have esptool or ESP-IDF installed.

ESP image inspection

An ESP image is an app image, OTA download, or second-stage bootloader with ESP image headers and segments. Inspection identifies the chip and instruction set, segment layout, descriptors, checksum and digest status, trailing coverage, and observed Secure Boot v2 signature blocks.

The findings describe what the bytes contain. A checksum or digest mismatch stays visible but does not hide readable segments. A signature block is observed and compared with the image digest; the analysis does not verify the public-key signature or device eFuse state.

Segment inventory is not disassembly and does not create a native memory map. A selected native child must pass the normal executable and architecture checks before it enters a native provider workflow.

References: docs/esp-image.md• L34-47 docs/esp-image.md• L67-104 docs/esp-image.md• L168-192 docs/esp-image.md• L254-260

ESP flash dump inspection

A complete ESP flash dump adds the bootloader, partition table, partitions, OTA records, and a derived boot selection to the image-level facts. The reader can locate the table at a caller-selected address, the default address, or a valid aligned scan result.

The caller must provide flash_offset when the file starts at a later flash address. The result reports declared partitions and the bytes present in the dump, including missing or truncated regions. It does not decrypt flash-encrypted data or decode NVS, FAT, SPIFFS, or other data partitions.

The derived boot selection explains which app the bootloader would prefer from the available table and OTA records. It is not a claim about the partition that was running on a device.

References: docs/esp-flash-image.md• L17-61 docs/esp-flash-image.md• L80-100 docs/esp-flash-image.md• L181-227 docs/esp-flash-image.md• L247-251

Device-tree analysis

A device tree is a structured hardware description. The device-tree workflow reads a local flattened device-tree blob (DTB) through a stable identity-checked snapshot and turns its nodes, properties, reservations, and selected links into navigable evidence.

Device-tree inspection

Device-tree inspection supports FDT versions 16 and 17 without an external tool or target runtime. It validates the header and full declared tree, then derives common strings, cell values, reg tuples, aliases, and selected single-cell phandle links.

The provider admits one bounded regular file through the shared artifact resource scope. It maps format errors, parse limits, source identity changes, selected-file errors, and other I/O failures to typed analysis errors instead of returning an incomplete report. The report keeps property offsets and bounded raw bytes beside derived values. It preserves exact multi-cell addresses and marks malformed, conflicting, unresolved, or ambiguous links as unknown instead of guessing. Limits also cover decoded output and repeated paths, not only the source file size. Binding-specific reference arrays, overlays, address translation through ranges, and live hardware state remain outside the workflow.

References: docs/devicetree.md• L1-7 docs/devicetree.md• L14-37 src/…/devicetree.ts• L18-94 src/…/DevicetreeProvider.ts• L36-78 src/…/DevicetreeProvider.ts• L81-160 src/…/DevicetreeParser.test.ts• L23-120 src/…/DevicetreeParser.test.ts• L135-220 src/…/DevicetreeParser.test.ts• L253-320 src/…/DevicetreeService.ts• L50-87

Evidence views

Large device-tree and artifact results can use a summary as the first response while retaining the complete Evidence in the session. A later analysis view selects nodes, properties for one exact path, reservations, or references without reopening the source file.

This pattern keeps the initial response small while preserving the full parsed result for follow-up questions. The same retained-summary approach is useful for ESP flash inventories, where a caller can first review the layout and then request selected entries.

References: docs/devicetree.md• L39-61 docs/esp-image.md• L15-18 src/…/registerDevicetreeTool.ts• L11-33 src/…/artifactToolContracts.ts• L19-38

Access workflows

The CLI and MCP expose the same analysis intent through different request shapes. The CLI resolves operator-relative paths before shared validation, while MCP clients use the server's target and Evidence session model.

CLI workflows

The firmware commands provide one-shot generic inspection and extraction. The artifact commands provide ESP image and flash-dump inspection and extraction, and the device-tree command provides direct DTB inspection.

GoalCLI entry point
Find generic firmware regionsrea inspect-firmware-regions <path>
Extract generic firmware contentsrea extract-firmware <path> <output-directory>
Inspect an ESP image or flash dumprea inspect-artifact <path>
Force ESP flash-dump interpretationrea inspect-artifact <path> --target-format esp-flash-image
Inspect a flattened device treerea inspect-devicetree <path>

Generic extraction accepts a byte range and bounded depth. ESP flash inspection accepts the flash and partition-table offsets when the dump origin or table location needs to be explicit. The firmware commands resolve operator-relative paths, honor cancellation, and pass bounded analysis or publication settings into the shared service.

References: src/…/firmwareCommands.ts• L18-119 src/…/artifactCommands.ts• L213-256 src/…/artifactCommands.ts• L258-334 docs/devicetree.md• L9-12

MCP workflows

MCP clients call inspect_firmware_regions or extract_firmware for the external-engine path. For ESP targets, the client opens the file with open_binary, calls inspect_artifact or extract_artifact, and can request selected findings through inspect_analysis_view. For a DTB, the client calls inspect_devicetree with the local path and may ask for a summary first.

All of these operations return Evidence-backed results. The Evidence carries the artifact identity, provider identity, observed limitations, and enough source location data to connect an embedded finding to a later native or application analysis step.

References: src/…/firmwareToolContracts.ts• L13-49 src/…/binaryDiagnosticsToolContracts.ts• L71-91 src/…/artifactToolContracts.ts• L82-94 src/…/registerDevicetreeTool.ts• L20-33

Capability boundaries

Capability discovery treats generic firmware inspection and extraction as separate host-dependent features. It can advertise neither, one, or both based on Linux support and the caller's configured tools. Each advertised engine must also be a readable executable regular file at an absolute path, and the firmware runner needs an executable absolute-path resource limiter. Before a request runs, the selected engine must provide a supported version banner. Portable ESP and device-tree readers have different requirements because they do not depend on those external engines.

The important boundary is between static evidence and claims about a live target. These workflows do not emulate firmware, validate all hardware bindings, decrypt protected contents, prove signature validity, or report the device's running partition. Use the returned limitations and next probes before treating a finding as complete.

References: src/…/CapabilityInventory.ts• L80-118 src/…/FirmwareCommand.ts• L81-157 src/…/FirmwareProvider.ts• L424-445 src/…/FirmwareRelease.ts• L3-10 docs/esp-flash-image.md• L214-227

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep the firmware operation-to-engine mapping aligned with capability discovery, tool contracts, and both CLI and MCP registration.
  • Keep executable-path, version-admission, resource-limiter, and release-limit rules aligned between capability discovery and firmware execution.
  • Keep source admission cancellation, symlink selection, requested-path identity, and staged-byte digest rules aligned between the firmware provider and Evidence.
  • Keep source snapshot rules, staging budgets, output inventory, and Evidence coverage aligned when extraction limits change.
  • Keep process, report, diagnostic, and publication deadlines distinct when provider cleanup or output handling changes.
  • Keep ESP flash origin and partition-table inputs aligned across target identity, layout facts, extraction ranges, and comparison behavior.
  • Keep summary view collection names and parent Evidence links aligned with the full device-tree and artifact result schemas.
  • When a new partial extraction condition is added, update normalized coverage, extraction_gaps, and its recovery instruction. For nested inputs, keep ranges relative to input_path and do not invent original-file offsets.
  • When publication checks change, keep producer-reported hashes and sizes aligned with the materialized regular files and keep non-file entries as metadata.
  • When device-tree admission or error projection changes, keep file bounds, stable identity checks, parse limits, and typed failure categories aligned with the parser contract.
  • When device-tree derivation rules change, keep malformed and ambiguous values unresolved and keep decoded-output limits aligned with the parser contract.

Important failure modes

TriggerConsequenceGuard
Binwalk or Unblob is missing, not on Linux, or not at an absolute configured pathThe matching firmware operation is unavailableConfigure the required caller-supplied engine and keep inspection and extraction configuration separate
The configured engine or resource limiter is not a readable executable regular file, or the engine version is unsupportedThe operation is rejected before target analysisUse the required absolute executable paths and a supported engine release
Cancellation arrives before source admissionNo private source snapshot is created and the operation is cancelledRetry with a live cancellation signal when the source is ready to be admitted
The source is empty, too large, inaccessible, or not a regular fileThe firmware operation is rejected before provider analysisSelect a stable readable regular file within the input allowance
A producer exits successfully but does not write a usable report, or its diagnostics exceed the capture allowanceThe operation produces no EvidenceInspect the captured process facts and rerun with a valid producer setup within the fixed release limits
The report hash, size, task identity, or parent-child links disagree with the selected snapshotThe extraction is rejected instead of publishing untrusted findingsTreat the producer report and the staged bytes as one verified input graph
Unblob lacks a format extractor or reaches an encrypted, unknown, depth-limited, failed, or staging-limited chunkExtraction returns partial coverage or an explicit resource failureFollow the gap's continuation instruction. For a nested gap, use its published child path rather than repeating the same whole-child extraction
The extraction destination already existsPublication is refused rather than overwriting prior outputUse a fresh absent directory with an existing writable parent
A provider reports a path outside its private input or output tree, or a regular file disagrees with its reportThe extraction result is rejected as untrusted outputKeep provider paths within the owned staging areas and require hash and size agreement before publication
A flash dump starts at a non-zero address without flash_offsetPartition addresses can be wrong or the file is refused as a misplaced imageReopen it as esp-flash-image with the dump's flash origin
A DTB is malformed, unsupported, or exceeds a file, node, property, depth, or decoded-output budgetThe operation returns a typed error without partial successProvide an FDT v16/v17 file within the selected parser limits
A DTB changes during the stable read or fails its identity checkThe operation reports a source identity or read failure instead of using unstable bytesAnalyze a regular file that remains unchanged during admission
A DTB contains malformed or conflicting phandles or reg tuplesDerived links or addresses remain unknown instead of representing a guessed targetTreat unresolved and ambiguous values as limits of the evidence
A Secure Boot v2 block or image digest does not matchThe mismatch is reported, but signature validity is not establishedTreat integrity and signature fields as observations and verify trust with device-specific tools

Key files

FileWhy to read it
docs/firmware-analysis.mdProduct scope, generic firmware limits, extraction coverage, and next-probe guidance
docs/esp-image.mdESP app and bootloader facts, segment meaning, integrity, and signature boundaries
docs/esp-flash-image.mdFlash layout, partition facts, OTA selection, origin handling, and extraction scope
docs/devicetree.mdDTB facts, derived links, retained views, and input budgets
src/…/FirmwareProvider.tsShared external-engine workflow, Evidence provenance, serialized requests, partial results, and cleanup behavior
src/…/FirmwareSourceAdmission.test.tsGuarantees for cancellation before snapshot creation and filesystem-selected symlink sources
src/…/FirmwareCommand.tsTool admission, version checks, bounded provider execution, captured diagnostics, and report validation
src/…/FirmwareRelease.tsFixed input, report, diagnostic, process, and CPU limits for the firmware integration
src/…/FirmwareFiles.tsSource admission, private snapshots, report reads, extraction staging budgets, and safe output inventory
src/…/FirmwareReports.tsProducer report validation, task lineage, byte coverage, nested findings, and extraction gaps
src/…/FirmwarePublication.tsHash-checked publication, safe output handling, and gap continuation guidance
src/…/FirmwareNestedCoverage.test.tsGuarantees for nested child coverage, child-relative gaps, and continuation guidance
src/…/firmwareToolContracts.tsPublic generic firmware MCP operations and their input/output contracts
src/…/firmwareAnalysis.tsGeneric firmware request, result, gap, and continuation shapes
src/…/artifactToolContracts.tsESP artifact inspection and extraction contract within the broader artifact provider
src/…/binaryDiagnosticsToolContracts.tsDevice-tree MCP contract and its summary-view behavior
src/…/DevicetreeProvider.tsStable DTB admission, parser execution, resource ownership, and typed input or resource failures
src/…/firmwareCommands.tsCLI entry points for generic firmware inspection and extraction
src/…/artifactCommands.tsCLI target selection for ESP flash images and artifact operations
src/…/DevicetreeParser.test.tsParser guarantees for format errors, exact values, unresolved links, and decoded-output limits