Files
reverse-engineering-anything/docs/bun-standalone.md
T
morluto 0b19b06bf6 fix(native): share ELF, PE, and Mach-O framing across artifact readers (#12156)
* fix(elf): share dynamic table singleton validation

* fix(elf): share note storage and framing across readers

Refs #12130

* fix(elf): retain zero-filled load mapping ambiguity

Refs #12136

* fix(pe): share header extent admission

Refs #12143

* fix(macho): share embedded section backing checks

Refs #12142

* fix(pe): share header facts and validate resource directory order

* fix(macho): require complete carrier load command framing

* fix(pe): probe declared resource headers by file offset

* fix(elf): preserve zero-fill observations across mapping gaps

* refactor(pe): share positional COFF header observation (#12173)

* fix(elf): check load-map agreement across section extents (#12175)

* fix(elf): check load-map agreement across section extents

* fix(elf): preserve agreed section links across unreadable tables
2026-11-19 03:49:13 +00:00

5.0 KiB

Bun standalone executables

inspect-artifact inventories embedded Bun module graphs in Mach-O __BUN,__bun, PE .bun, ELF .bun, and appended trailers. extract-artifact writes their stored module contents through the existing safe output tree. Neither operation executes the executable or decompiles bytecode.

rea inspect-artifact ./hello --json
rea extract-artifact ./hello --json

In MCP, open the executable with open_binary, then call inspect_artifact. Use detail: "summary" for large graphs and inspect_analysis_view to page retained Evidence. The root metadata's entry_point_logical_path is the reader-owned location of its entry module. Use it as an inventory logical_paths filter, then read selected node fields with the returned content identity. This also works for names mapped to indexed extraction paths. The complete Evidence stays retained; no source-name normalization is needed in the caller.

The root reports the carrier, layout, module count, entry point, raw flags and compile exec-argv. Each module retains its source name, loader and encoding values, entry-point status, sizes and SHA-256. Sourcemaps, bytecode and module-info regions are separate children. Source names such as /$bunfs/root/main.js remain in metadata; extraction uses a relative path. Unsafe or non-UTF-8 names receive an indexed path and retain their source spelling or bytes. Virtual names deeper than the selected path_parts allowance (default 256) also use an indexed path with an explicit limitation, preventing unbounded path-tree work while retaining the source fact. Duplicate names remain separate occurrences; ordinary extraction collision rules apply.

The recognized record shapes are the 36-byte Bun 1.3.3 layout and the 52-byte Bun 1.3.9 layout. These labels identify structural layouts, not a detected compiler version. Bun does not store an explicit revision identifier: unknown table sizes and ambiguous known layouts are unsupported. A future layout that is byte-for-byte compatible cannot be distinguished. Invalid pointers and truncated claimed sections are malformed. A named Mach-O section is also malformed when it declares zero-fill or falls outside its containing segment's file or virtual address range. A confirmed section graph requires a complete Mach-O load command table. An absent trailer without a named section does not establish a Bun graph. Unknown enum values remain raw, with a null name.

Sourcemaps are stored Bun regions, not necessarily standalone JSON source maps. Extracted contents retain their original encoding. Use JavaScript analysis only on compatible source files; bytecode is retained as evidence, not decoded.

Module parsing reads exact metadata ranges rather than loading stored asset bodies or whole pages around small pointers. A cache retains at most 256 KiB and 1,024 ranges for one reader preparation. Cumulative uncached metadata reads default to 256 MiB, checked before allocation or I/O. The module table, decoded strings and combined logical path tree have separate admission checks; by default at most 250,000 distinct path prefixes are admitted before inventory construction. Stored bodies are range-streamed for hashing and extraction. Header/suffix observations are reused only for the same admitted file state, with selected-path checks before publication.

Both artifact operations accept artifact_limits.bun. Its independent controls are payload_bytes, module_count, representation_bytes, metadata_read_bytes, recognition_table_bytes, recognition_load_command_bytes, path_parts and path_nodes. Failed recognition remains explicitly limited instead of proving absence. ELF section names are examined at their actual offsets, including names beyond a large section-name prefix. Select artifact_limits.expanded_bytes to change the aggregate referenced-plaintext work allowance.

For a reported metadata-read refusal, keep the same carrier and retry with --artifact-limits '{"bun":{"metadata_read_bytes":536870912}}' or the equivalent MCP artifact_limits object. Omitted fields keep defaults. The response names the effective limit and exact repair; accepted overrides are reported separately from caller selections. Changes apply on the next call without restarting REA. Summary and selected extraction do not change the producer's admission.

See limits and recovery for admission ceilings. Synthetic tests cover the carriers and malformed declarations. Run node scripts/verify-bun-standalone.mjs after npm run build:cached for local Bun verification, and add --docker to compile a Linux fixture with oven/bun:1.4.0. Bun and Docker are fixture producers only and are not installed by REA.

Layout references: Bun 1.3.3 serializer and Bun 1.3.9 serializer.

The current 52-byte record order can also be checked in the Bun 1.4.4 Rust serializer.