mirror of
https://github.com/morluto/rea.git
synced 2026-11-20 05:32:44 +00:00
* feat(uefi): add pure-TS UEFI firmware volume/FFS parser with inspect/extract tools
Add a dependency-free rea-uefi provider that maps AMI/Aptio flash images:
- inspect_uefi_firmware: aligned _FVH discovery, volume-relative FFS walking,
guided section/compression classification, conservative PSP-directory probing,
embedded-volume rescan and leftover-region classification; incremental SHA-256
and explicit integrity notes.
- extract_uefi_firmware: whole-image/volume/FFS-file/section extraction with
LZMA-custom/LZMAF86 and AMD-zlib decoding, SafeOutputTree staging, derivations
and extraction_gaps.
- UefiArtifactReader + 'uefi' format wiring across inventory/domain/contracts
so parsed volumes and extracted PE32/TE files hand off to deep-provider
analysis (open_binary -> Ghidra).
* feat(uefi): add inspect_uefi_nvram for AMI NVRAM variable stores
Add a pure-TypeScript tool that maps the vendor AMI NVRAM variable stores
(factory-default "StdDefaults" and peers) inside a flash image:
- scan the raw image for NVAR entry chains ("NVAR" + u16 total size +
u32 attribute 0x8[23]FFFFFF + state + NUL-terminated name + data),
- recurse into a container entry whose data is itself an NVAR chain, so the
StdDefaults setup variables surface as depth/parent_offset rows,
- report attributes, state, data range, SHA-256 and trailing padding per entry.
Verified against B550 AORUS Elite V2 FId: one StdDefaults store at 0x37090 with
the 11 expected nested variables (Setup, PlatformLang, AMITSESetup, XhciDID,
GcSensorVarName, PCI_COMMON, SioSetupData, UsbSupport, NetworkStackVar,
SecureBootSetup, Setup). Exposed as MCP tool and inspect-uefi-nvram CLI command.
* fix(uefi): address review on checksums, compression, guided sections, NVRAM bounds
- FFS file checksum: verify the two's-complement invariant (payload sum +
stored byte == 0 mod 256) instead of comparing sums, and encode the correct
complement in the fixture builder.
- Compression sections (type 0x01): use the 9-byte header and classify EFI
standard compression instead of 'none', so extraction reports a gap rather
than publishing compressed bytes as a raw section.
- GUID-defined sections: derive GUID/data-offset/attributes from the parsed
common header size (compact or extended) and reject out-of-range payload
offsets.
- AMI NVRAM: bound recursive chains to the enclosing container's data end and
report partial coverage when a valid nested chain is cut by max_depth.
* fix(uefi): bound decode memory, serialize operations, enforce deadline, mark truncation
- LZMA worker: enforce max_output_bytes while decoding through a bounded output
sink, so an oversized stream is rejected during expansion instead of after a
full decompression plus a second Buffer copy.
- Provider: serialize admitted operations (the promised single decode-worker
lane must not become one worker per overlapping call) and apply one
whole-request deadline that covers every decode stage, not a fresh per-stream
timer. close() drains the queue and the resource scope.
- Scan: track truncated sections of known type and report coverage partial
instead of complete when a section declares more bytes than are present.
* fix(uefi): cancellable queue, timeout surfacing, availability and reader omissions
- Queue: check the caller signal before enqueue and when a job reaches the head,
and race the queued promise against abort so a cancelled wait returns
immediately instead of blocking behind the active request.
- Deadline: track the internal deadline and return AnalysisTimeoutError instead
of the AnalysisCancelledError that runOwnedCommand reports for any external
abort, preserving the real failure reason for CLI/MCP callers.
- CapabilityInventory: treat inspect_uefi_nvram like the other bundled rea-uefi
tools so discovery does not demand Unblob for it.
- UefiArtifactReader: report image truncation through onOmission so inventory
coverage reflects the unread suffix even when no volume was found.
* fix(uefi): limit early cancellation to unstarted jobs and preserve timeout cleanup
- #raceWithAbort only returns early for jobs that have not started; once a
request is running, await it so worker cleanup and completed output are
preserved instead of being discarded by a bare cancellation.
- Reclassify a deadline-induced cancellation as AnalysisTimeoutError while
keeping its cause and cleanup observations, and never override a different
primary failure.
* docs(licenses): record UEFI decoder dependency notices
* fix(uefi): preserve stream provenance and bound firmware analysis
* feat(uefi): decode LZMAF86 guided sections
* fix(uefi): validate publication before commit and order decoder cleanup
* fix(uefi): preserve unsupported volumes and extraction gaps
---------
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
Documentation directory
REA documentation is organized by reader task and document owner. This directory
links every authored guide; the site also serves separate
product pages. The VitePress documentation source is this docs/ tree.
Getting started
- Installation and setup
- Client configuration and troubleshooting
- CLI and Evidence
- Guided MCP prompts and completion
Native binaries
- Native binary investigation
- Go binary build metadata
- DWARF compile units
- Offline binary diagnostics
- ELF separate debug files
- ELF and Mach-O initializer functions
- ELF unwind function ranges
- Linux kernel build config
- Recorded crash evidence
- CycloneDX dependencies
- Windows Shell Link shortcuts
- Acquired NTFS metadata and change journals
JavaScript and Electron
- JavaScript Application Graph
- Cross-layer JavaScript application workflows
- JavaScript artifact reconstruction
- JavaScript source recovery
- Passive Node and Electron runtime observation
- JavaScript static/runtime reconciliation
- Electron file-page observation
- V8 code cache inspection
Browser and captured websites
- Website observation with CDP
- Browser scenario contract
- Website runtime source attribution
- Historical web network captures
- HTTP/3 capture lab
- Captured website source locations
- Captured website module relationships
- Captured website scripts and static JavaScript analysis
Android applications
- Static Android APK analysis
- Apktool resource decoding
- ADB device inspection and acquisition
- Flutter build identification
Apple applications
.NET assemblies
Firmware
HarmonyOS packages
WebAssembly
EVM contracts
Databases and recorded packets
Process capture and instrumentation
Signal recordings
Provider setup and formats
- Ghidra provider semantics
- DOS MZ and COM analysis with Ghidra
- Optional NativeAOT metadata recovery
- MIPS ELF analysis through Ghidra
- PSP static ELF analysis through Ghidra
- RISC-V ELF analysis through Ghidra
- Windows Ghidra P0
- Headerless raw-binary analysis with Ghidra
- IDA provider
- JEB instrumentation and analysis
Contracts and evidence
Development and verification
- Settings and recovery
- REA limit inventory
- MCP tool design
- Testing REA
- Client and agent verification
- Reconstruction readiness conformance
- Releasing REA
- REA roadmap
Release migrations
Architecture and authoring
- Architecture map
- Documentation ownership and contribution model
- Feature specifications
- Architectural decision records
Machine-owned documentation
| Path | Owner and update command |
|---|---|
public/product-catalog.json |
Ignored contract projection; npm run docs:generate |
verification/managed-conformance-*.json |
Ignored managed conformance projections; npm run evidence:generate |
error-contract.schema.json |
Tracked schema from contracts; npm run docs:error-schema |
user-visible-errors.csv |
Generated error code and category per domain and provider-owned error case; npm run docs:error-schema |
releases/<version>.contributions.json |
Durable release contribution record; follow the release guide |
assets/ |
Shared authored images referenced by guides |
Do not edit generated catalogs or evidence to change product facts. Change their canonical contracts or producer and regenerate. Historical release records retain the exact commit messages and references from the release they describe.
Additional guides
- Offline API contract inventory
- Bun standalone executables
- Deno compile executables
- Capability composition and ownership
- .NET single-file bundles
- ESP flash images
- U-Boot FIT images
- Measure MCP catalog costs in Codex
- Offline Playwright traces
- Testing lanes and provider verification
- UF2 and DfuSe images
- WeChat mini-program wxapkg archives
- Binary hardening
- Desktop application capture
- Desktop application export
- Desktop application state
- Desktop application tasks
- Desktop build computer
- Desktop build witness
- iNES containers
- Build RL environments with REA
- Agent environments from recorded captures
- Android boot and vendor_boot images
- APK signature schemes
- Android OTA update payloads
- Apple IPS crash reports
- Static analysis in GitHub Actions
- Desktop installation directories
- Flattened devicetree inspection
- Electron fuse state
- ELF note tables
- ELF dependency tables
- Erlang BEAM files
- ESP images
- GameCube DOL analysis through Ghidra
- PowerPC ELF analysis through Ghidra
- Godot PCK archives
- Static CUDA and HIP code objects
- Intel HEX and S-record images
- IL2CPP metadata
- Static JavaScript route inventory
- Linux kernel modules
- Kuna provider
- Maven POM and Gradle module metadata
- Model file declarations
- Match native functions across builds
- Node.js single executable applications
- NuGet packages
- PE Authenticode certificate tables
- PE import and delay-load tables
- PE TLS callbacks and load configuration
- Python packaged applications
- CPython pyc inspection
- Reconstruction coverage
- Release exposure
- Reverse-engineering tool integrations
- Rust binary dependency metadata
- U-Boot legacy uImage containers
- UnityFS AssetBundle archives