134 lines
7.8 KiB
Markdown
134 lines
7.8 KiB
Markdown
# Native, managed, and packaged artifacts
|
|
|
|
## 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](https://github.com/morluto/rea/blob/main/docs/recorded-crashes.md)
|
|
for exact upstream profiles, bounds and verification coverage.
|
|
|
|
## 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.
|
|
|
|
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` includes the
|
|
complete tool inventory with availability reasons and remediation. When choosing
|
|
a tool, use its entry in that result; `tools/list` retains the complete catalog
|
|
when the target or provider state changes.
|
|
|
|
## 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.
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
### .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.
|
|
|
|
For deeper type recovery, the optional third-party
|
|
[Ghidra NativeAOT analyzer](https://github.com/Washi1337/ghidra-nativeaot)
|
|
rehydrates ReadyToRun metadata and can recover method tables, type relationships,
|
|
frozen objects, and strings. This is a Ghidra extension with its own install and
|
|
interactive workflow; it is not currently part of REA's managed parser or
|
|
headless Ghidra bridge. Treat its annotations as analysis evidence, retain the
|
|
binary identity, and do not present recovered types as original source. Header
|
|
discovery may require a symbol or analyst identification of the ReadyToRun
|
|
header, depending on the binary and analyzer version.
|
|
|
|
## Packages and extraction
|
|
|
|
Use `inspect_artifact` for application bundles, archives, ZIP/APK/IPA/MSIX/AppX,
|
|
ASAR, DMG, or PKG inputs. A PKG inventory includes Distribution, PackageInfo,
|
|
the pre/postinstall scripts, and the gzip payload's files. Pbzx payloads are
|
|
recorded only. Checksums declared in the PKG's table of contents are verified;
|
|
with `integrity_policy: "record-and-continue"`, a mismatched member stays in
|
|
the graph as `mismatched`, with the declared and observed values, and is not
|
|
expanded. Inspect it 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 takes no arguments
|
|
and 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](https://github.com/morluto/rea/blob/main/docs/ghidra-dos.md).
|
|
|
|
### 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.
|