rea/.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md

Native, managed, and packaged artifacts

Go build metadata

Use inspect_go_binary for an explicit local ELF, PE or thin Mach-O when the question concerns the embedded compiler version, module/dependency versions, local replacements or build settings. No open_binary, Go installation or target execution is required. The CLI equivalent is inspect-go-binary PATH. Preserve artifact SHA-256, original file ranges, framed module bytes and every unparsed module-text line. A missing record is an unknown, not proof of a non-Go binary; observed metadata does not authenticate its claims. Function, source and type recovery remain a separate native-analysis question.

Rust dependency metadata

Use inspect_rust_binary for an explicit local ELF, PE, or thin Mach-O when the question concerns the cargo-auditable crate list embedded in .dep-v0 (Mach-O: __DATA,.dep-v0). No open_binary, Rust installation, or target execution is required. The CLI equivalent is inspect-rust-binary PATH. Preserve artifact SHA-256, package order, dependency indices, and the section file range. A missing section is null metadata, not proof the binary has no dependencies. An omitted package kind stays null. A rustc commit hash is inferred from a read-only /rustc/<40-hex>/ path and does not by itself identify the compiler. See Rust binaries.

SQLite snapshots

Use inspect_sqlite_database with an explicit local database snapshot for its schema and optional rows from one exact ordinary table. It requires Node.js 24.x >=24.15 or 26+ with the native DatabaseSync.limits API. It also consumes the existing sibling -wal; retain both original digests when citing its result. Default output is a compact inventory; a selected table expands only its own schema and samples 20 rows. Select columns to avoid irrelevant or large cells, and request schema_scope: "database" only for complete schema details. Choose row_limit when a finite sample is useful and keep truncation and unspecified row order explicit. Virtual tables, shadow tables and views are schema facts, not row-read targets. REA inspects private copies and leaves the source files untouched; obtain a coherent quiescent database/WAL snapshot before inspection. See SQLite snapshots.

Recorded Linux crashes

Use inspect_recorded_crash with an explicit Linux x86-64 ELF core path to inspect historical thread registers, signals, raw notes and original file ranges. It is independent of the active disassembler target. Source-bound register values and note bytes are observations; missing notes, signal-thread association and current executable/library identity remain unknown. PIDs are historical metadata and never authorize live attach or control.

The optional include_debugger_context facet adds mapping candidates through caller-supplied GDB/pwndbg in an owned core-only session. Display names do not establish current file identity; zero reported flags leave permissions unknown. Requested unavailable context fails with setup guidance. See recorded crashes for exact upstream profiles, bounds and verification coverage.

Offline ELF layout

Use inspect_binary_layout with an explicit local ELF path for file-backed sections, symbols, relocations, linkage names, and static mitigation inferences without opening a disassembler target. When that complete record is already retained, call inspect_analysis_view for a summary, mitigations or linkage facet, one section or symbol, or a stable page. Do not re-run the decoder to read a single object.

Offline WASM

Use inspect_wasm_artifact with caller-supplied WABT for selected local bytes. For counts, validation and WAT identity, select detail: "summary" on the first MCP call. The complete original Evidence stays retained; use normalized_result.parent_evidence_id for exact exports or text pages. Omitted or complete detail keeps the existing complete result. For a completed result, use inspect_analysis_view with its reported retained reference for a summary or view: {kind: "wasm", facet: "exports", offset: 0, limit: 32}. Facets also include sections, imports, candidates, glue, WAT, headers, details and tool profile. Text offsets count UTF-16 code units; follow next_offset. The complete source remains retained after an oversized MCP reply. No target execution or network acquisition is implied, and WAT is decoded representation.

Native targets

After open_binary, use focused search, procedure, or function tools directly. Use binary_overview when target metadata or inventory context helps answer the question. Prefer literal search, names, decompilation, callers, callees, and cross-references. Addresses and recovered pseudocode are analysis observations, not original source. Provider unavailability and unsupported metadata remain unknown rather than false.

For a completed analyze_function dossier, use inspect_analysis_view with view: {kind: "native", facet: "value_flow_operations", offset: 0, limit: 32} and the exact retained Evidence ID to read selected facts without reanalysis. Native facets also include procedure, pseudocode, assembly, basic blocks, comments, callers/callees, references, unresolved calls, referenced strings and names, the native API record, and value-flow summaries. Pseudocode offsets and limits count UTF-16 code units; use the returned next_offset for continuation. Provider limitations and unavailable facts remain explicit; the complete parent Evidence is retained.

inspect_macho on a large framework returns megabytes of imports and exports. Select detail: "summary" for slice identity, UUID and per-collection counts, then page rows with view: {kind: "macho", facet: "exports", offset: 0, limit: 64} and normalized_result.parent_evidence_id. Facets are entrypoints, architectures, build_metadata, load_commands, dependencies, imports, exports, segments and provenance. source_exhaustive: false means unreturned symbols may exist.

To see which functions or Objective-C methods a Mach-O actually calls in one run, use observe_native_calls with explicit breakpoints and a bounded duration_ms/max_events. It launches a new process under LLDB, so the target runs and may change files or use the network. Hardened-runtime targets need the get-task-allow entitlement.

Use binary_session with no arguments to check the open target, selected provider, and alignment. Its default result.tool_availability carries a complete inventory grouped by shared facts. Expand each group's names and inherit the inventory-level client requirements unless a group overrides them; availability, reasons, remediation, modes, and flags remain inline. The effects and annotations arrays name true flags from fixed vocabularies, so an omitted known flag is false. tools/list remains the canonical source for full tool schemas when target or provider state changes.

Provider capability groups carry provider identity and ordered limitations. Prepend each set's shared_limitations to a group's limitations to recover the operation's full ordered list. Candidate capabilities describe possible providers. Top-level session capabilities describe the current route, and analysis_provider_binding identifies the selected provider.

DOS MZ with Ghidra

For an admitted DOS MZ target, use inspect_native_load_image to check measured loaded bytes, file mappings, relocations and the entry against the immutable snapshot. Keep mismatch and unsupported explicit. Verified import covers the reported static image, not runtime DOS or PC-98 hardware behavior.

For Ghidra decompilation, procedure_pseudo_code also accepts procedure: "file-offset:0x..."; CLI rea decompile <path> --file-offset=0x... --provider ghidra resolves the source byte offset internally. An unresolved 0x-prefixed numeric procedure selector also falls back to a unique file mapping. Existing symbols and analysis addresses win; multiple mappings fail as ambiguous. Preserve the returned file-offset and address locations and raw selection observations. ELF virtual addresses are distinct from file offsets; never assume an arbitrary offset plus image base is an analysis address.

Use read_bytes for initialized analysis memory and address_to_file_offset to anchor one observed address to original file bytes. Loader fixups can change a word; a source offset does not imply byte equality. Complete function body ranges use inclusive ends and can contain gaps. Do not treat the enclosing span as code. For packed targets, retain the original and separately derived artifact identities; decompiling an unpacking stub does not recover the unpacked program.

When reading Objective-C dispatch metadata, distinguish class implementation methods from protocol requirements: class methods report null requirement flags, while decoded protocol declarations retain required and optional facts. Property attributes remain raw name/value tokens; use the property's atomicity field for the decoded N marker or the default atomic behavior. Null class/meta flags, ivar counts, atomicity, or read-only values mean the selected provider did not establish that fact. Symbol names alone do not prove that a class is a root class or has no ivars.

Managed PE/CLI

Start with inspect_managed_artifact. REA's canonical managed inspection is execution-free: do not claim it loaded, reflected, executed, or resolved the assembly. Keep managed/native boundaries and unavailable reconstruction facts explicit. A bring-your-own reconstruction oracle is separate from the canonical parser and must not become an implicit setup dependency.

For identity/classification questions, inspect_managed_artifact can explicitly select detail: "summary" on the first MCP call. It retains complete metadata and returns a linked overview with full classification/evidence, nullable module/MVID, frameworks, metadata coverage/issues/limitations and returned-row counts. Default complete requests remain unchanged. Read original rows with inspect_analysis_view, source normalized_result.parent_evidence_id, and view: {kind: "managed", collection: "attributes", offset: 0, limit: 16}. Collections are references, resources and attributes. Paging does not repeat parsing. Returned-row exhaustion does not prove complete metadata or absence under partial/unavailable coverage; preserve build-local tokens and their artifact/MVID scope.

.NET NativeAOT

NativeAOT binaries contain native machine code, so ordinary CIL decompilers cannot recover the original method bodies. When managed metadata/CIL is absent, classify that as a native-analysis route rather than claiming source recovery. Open the native image with the selected deep provider and inspect functions, strings, calls, and references; describe decompiler output as pseudocode and inference.

NativeAOT images can be PE/COFF, ELF, or Mach-O executables and shared libraries. Use file bytes and loader metadata rather than suffixes to identify them. For packaged apps, inventory/extract with REA's artifact tools and retain the exact contained image identity. PDB, ELF debug, or dSYM sidecars are additional evidence only when the provider accepts and matches them.

REA has a built-in read-only snapshot parser for x64 PE targets with .NET 8 RTR 9.1 metadata. An optional headless Ghidra adapter adds database annotations and broader metadata recovery on Linux; it requires an explicitly configured NativeAOT JAR. These are separate routes. The built-in parser also runs on Windows Ghidra P0; read frozen literals from its report, because search_strings does not include them. See the NativeAOT guide for setup, supported layouts, and host restrictions. Preserve binary identity and distinguish derived metadata from Ghidra database observations. Recovered types and native pseudocode are not original C# source. Windows Ghidra P0 has no database mutation authority.

Packages and extraction

Use inspect_artifact for application bundles, archives, ZIP/APK/IPA/MSIX/AppX, ASAR, or DMG inputs when the artifact graph and findings help answer the question. It returns the complete artifact graph inline. Cite graph manifest IDs when using them.

For an IPA or a macOS .app, ZIP, or DMG, pass the inventory Evidence to project_apple_application_graph. It reports application roots and nested bundles by path convention: app extensions, XPC services, frameworks, login items, system and driver extensions, and plug-ins. It also lists privileged helpers, launchd plists, symlinks, and each bundle's info_plist_path and executable candidates. Roles are path conventions, not parsed plists; read the listed plists with inspect_plist.

After open_binary on a .app or Mach-O, use trace_dylib_resolution to see which file each @rpath, @loader_path and @executable_path load reaches for every executable in the bundle. It also lists missing or weak loads and earlier @rpath candidates that are absent. Narrow large bundles with roots or architecture. System paths stay undetermined because the dyld shared cache provides them.

Use extract_artifact when materialized files are needed. It extracts the active target and accepts optional integrity_policy; see the MCP contracts. It materializes all regular files into a fresh temporary directory chosen by REA. Symlinks and encrypted entries are inventory facts, not extractable files. The result reports the materialized directory; callers do not choose the destination. No separate permission grant is needed.

Native DMG traversal automatically uses a read-only mount on supported macOS hosts, with an owned temporary mount directory and cleanup. It needs no approval flag. Unsupported hosts or mount failures remain explicit limitations; do not claim child inventory when only root identity is available. Extraction is a separate filesystem-writing operation.

For headerless DOS COM, explicitly open with format: "dos-com" (CLI --target-format dos-com). Inspect the load image before trusting function analysis: the entry is 0x10100, file offset zero, with imposed real-mode segment context. PSP/stack/device state remains unmodeled. See DOS guide.

For other headerless images (embedded firmware without ELF/Mach-O/PE/MZ headers), open with format: "raw-binary", architecture (x86, x86_64, arm, arm64, or 6502), and entry_point (0x hex). File offset 0 is mapped at that address. Hopper and IDA refuse this interpretation; Ghidra uses BinaryLoader with a little-endian generic language. Big-endian, Thumb-only, and Cortex-M variants are unsupported. 6502 selects NMOS 6502; the entry and complete file mapping must fit within 0x0000..0xffff. 65C02, 65816, cartridge containers, bank switching, and mapper semantics are unsupported. Windows Ghidra P0 admits raw images only for 6502. See raw binary guide.

Function annotations in Ghidra

Use annotate_native_function for one function name and/or entry comments, with at least one explicit change. Review its annotation readback and refreshed dossier inline. Changes are atomic and session-scoped; empty comments clear them, omitted fields preserve them. Later MCP calls observe edits until close. CLI annotate-native-function returns the updated analysis before discarding the session. Original executable bytes are unchanged; edits invalidate immutable snapshots. Windows P0 does not admit database mutations. For naming only, set_address_name / set_addresses_names also work with Ghidra: they name function entries or data addresses (primary labels) and return compact per-address success booleans instead of a dossier.

Offline PE resource inventory

Use inspect_pe_resources with an absolute path, or rea inspect-pe-resources ./selected.exe --json, for portable PE32/PE32+ resource inspection without opening a native target. Preserve returned Evidence: type/name/language IDs and UTF-16 names, original directory/data/payload ranges, code pages, payload hashes and static icon-group references. Same-language icon resolution is explicit; missing references and size mismatch remain visible. Other payloads are opaque, and this operation does not decode images or simulate Windows resource loading. Consult the budgets and supported tree profile in offline binary diagnostics.

For exact core-module import/export differences, use compare_wasm_interfaces with two complete inspection Evidence records (or current-session retained references) and explicit scope. Preserve unknown types/duplicate names; static interface equality is not runtime compatibility. CLI accepts complete inline Evidence in rea compare-wasm-interfaces input.json --json.