references/native-and-artifacts.md
18.5 KB查看排版效果| 1 | # Native, managed, and packaged artifacts |
| 2 | |
| 3 | ## Go build metadata |
| 4 | |
| 5 | Use `inspect_go_binary` for an explicit local ELF, PE or thin Mach-O when the |
| 6 | question concerns the embedded compiler version, module/dependency versions, |
| 7 | local replacements or build settings. No `open_binary`, Go installation or |
| 8 | target execution is required. The CLI equivalent is `inspect-go-binary PATH`. |
| 9 | Preserve artifact SHA-256, original file ranges, framed module bytes and every |
| 10 | unparsed module-text line. A missing record is an unknown, not proof of a |
| 11 | non-Go binary; observed metadata does not authenticate its claims. Function, |
| 12 | source and type recovery remain a separate native-analysis question. |
| 13 | |
| 14 | ## Rust dependency metadata |
| 15 | |
| 16 | Use `inspect_rust_binary` for an explicit local ELF, PE, or thin Mach-O when |
| 17 | the question concerns the cargo-auditable crate list embedded in `.dep-v0` |
| 18 | (Mach-O: `__DATA,.dep-v0`). No `open_binary`, Rust installation, or target |
| 19 | execution is required. The CLI equivalent is `inspect-rust-binary PATH`. |
| 20 | Preserve artifact SHA-256, package order, dependency indices, and the section |
| 21 | file range. A missing section is null metadata, not proof the binary has no |
| 22 | dependencies. An omitted package kind stays null. A rustc commit hash is |
| 23 | inferred from a read-only `/rustc/<40-hex>/` path and does not by itself |
| 24 | identify the compiler. See [Rust binaries](https://github.com/morluto/rea/blob/main/docs/rust-binaries.md). |
| 25 | |
| 26 | ## SQLite snapshots |
| 27 | |
| 28 | Use `inspect_sqlite_database` with an explicit local database snapshot for its |
| 29 | schema and optional rows from one exact ordinary table. It requires Node.js |
| 30 | 24.x >=24.15 or 26+ with the native `DatabaseSync.limits` API. It also consumes the |
| 31 | existing sibling `-wal`; retain both original digests when citing its result. |
| 32 | Default output is a compact inventory; a selected table expands only its own |
| 33 | schema and samples 20 rows. Select `columns` to avoid irrelevant or large cells, |
| 34 | and request `schema_scope: "database"` only for complete schema details. |
| 35 | Choose `row_limit` when a finite sample is useful and keep truncation and |
| 36 | unspecified row order explicit. Virtual tables, shadow tables and views are |
| 37 | schema facts, not row-read targets. REA inspects private copies and leaves |
| 38 | the source files untouched; obtain a coherent quiescent database/WAL snapshot |
| 39 | before inspection. See [SQLite snapshots](https://github.com/morluto/rea/blob/main/docs/sqlite-databases.md). |
| 40 | |
| 41 | ## Recorded Linux crashes |
| 42 | |
| 43 | Use `inspect_recorded_crash` with an explicit Linux x86-64 ELF core path to |
| 44 | inspect historical thread registers, signals, raw notes and original file |
| 45 | ranges. It is independent of the active disassembler target. Source-bound |
| 46 | register values and note bytes are observations; missing notes, signal-thread |
| 47 | association and current executable/library identity remain unknown. PIDs are |
| 48 | historical metadata and never authorize live attach or control. |
| 49 | |
| 50 | The optional `include_debugger_context` facet adds mapping candidates through |
| 51 | caller-supplied GDB/pwndbg in an owned core-only session. Display names do not |
| 52 | establish current file identity; zero reported flags leave permissions unknown. |
| 53 | Requested unavailable context fails with setup guidance. See |
| 54 | [recorded crashes](https://github.com/morluto/rea/blob/main/docs/recorded-crashes.md) |
| 55 | for exact upstream profiles, bounds and verification coverage. |
| 56 | |
| 57 | ## Offline ELF layout |
| 58 | |
| 59 | Use `inspect_binary_layout` with an explicit local ELF path for file-backed |
| 60 | sections, symbols, relocations, linkage names, and static mitigation inferences |
| 61 | without opening a disassembler target. When that complete record is already |
| 62 | retained, call `inspect_analysis_view` for a summary, mitigations or linkage |
| 63 | facet, one section or symbol, or a stable page. Do not re-run the decoder to |
| 64 | read a single object. |
| 65 | |
| 66 | ## Offline WASM |
| 67 | |
| 68 | Use `inspect_wasm_artifact` with caller-supplied WABT for selected local bytes. |
| 69 | For counts, validation and WAT identity, select `detail: "summary"` on the first |
| 70 | MCP call. The complete original Evidence stays retained; use |
| 71 | `normalized_result.parent_evidence_id` for exact exports or text pages. Omitted |
| 72 | or complete detail keeps the existing complete result. |
| 73 | For a completed result, use `inspect_analysis_view` with its reported retained |
| 74 | reference for a summary or `view: {kind: "wasm", facet: "exports", offset: 0, limit: 32}`. |
| 75 | Facets also include sections, imports, candidates, glue, WAT, headers, details |
| 76 | and tool profile. Text offsets count UTF-16 code units; follow `next_offset`. |
| 77 | The complete source remains retained after an oversized MCP reply. No target |
| 78 | execution or network acquisition is implied, and WAT is decoded representation. |
| 79 | |
| 80 | ## Native targets |
| 81 | |
| 82 | After `open_binary`, use focused search, procedure, or function tools directly. |
| 83 | Use `binary_overview` when target metadata or inventory context helps answer the |
| 84 | question. Prefer literal search, names, decompilation, callers, callees, and |
| 85 | cross-references. Addresses and recovered pseudocode are analysis observations, |
| 86 | not original source. Provider unavailability and unsupported metadata remain |
| 87 | unknown rather than false. |
| 88 | |
| 89 | For a completed `analyze_function` dossier, use `inspect_analysis_view` with |
| 90 | `view: {kind: "native", facet: "value_flow_operations", offset: 0, limit: 32}` |
| 91 | and the exact retained Evidence ID to read selected facts without reanalysis. |
| 92 | Native facets also include procedure, pseudocode, assembly, basic blocks, |
| 93 | comments, callers/callees, references, unresolved calls, referenced strings and |
| 94 | names, the native API record, and value-flow summaries. Pseudocode offsets and limits count UTF-16 |
| 95 | code units; use the returned `next_offset` for continuation. Provider limitations |
| 96 | and unavailable facts remain explicit; the complete parent Evidence is retained. |
| 97 | |
| 98 | `inspect_macho` on a large framework returns megabytes of imports and exports. |
| 99 | Select `detail: "summary"` for slice identity, UUID and per-collection counts, |
| 100 | then page rows with `view: {kind: "macho", facet: "exports", offset: 0, limit: 64}` |
| 101 | and `normalized_result.parent_evidence_id`. Facets are entrypoints, |
| 102 | architectures, build_metadata, load_commands, dependencies, imports, exports, |
| 103 | segments and provenance. `source_exhaustive: false` means unreturned symbols |
| 104 | may exist. |
| 105 | |
| 106 | To see which functions or Objective-C methods a Mach-O actually calls in one |
| 107 | run, use `observe_native_calls` with explicit breakpoints and a bounded |
| 108 | `duration_ms`/`max_events`. It launches a new process under LLDB, so the target |
| 109 | runs and may change files or use the network. Hardened-runtime targets need the |
| 110 | `get-task-allow` entitlement. |
| 111 | |
| 112 | Use `binary_session` with no arguments to check the open target, selected |
| 113 | provider, and alignment. Its default `result.tool_availability` carries a |
| 114 | complete inventory grouped by shared facts. Expand each group's `names` and |
| 115 | inherit the inventory-level client requirements unless a group overrides them; |
| 116 | availability, reasons, remediation, modes, and flags remain inline. The |
| 117 | `effects` and `annotations` arrays name true flags from fixed vocabularies, so an |
| 118 | omitted known flag is false. `tools/list` remains the canonical source for full |
| 119 | tool schemas when target or provider state changes. |
| 120 | |
| 121 | Provider capability groups carry provider identity and ordered limitations. |
| 122 | Prepend each set's `shared_limitations` to a group's `limitations` to recover the |
| 123 | operation's full ordered list. Candidate capabilities describe possible |
| 124 | providers. Top-level session capabilities describe the current route, and |
| 125 | `analysis_provider_binding` identifies the selected provider. |
| 126 | |
| 127 | ## Static memory and original file bytes |
| 128 | |
| 129 | For Ghidra, `read_bytes` reads initialized analysis memory, including loader |
| 130 | fixups; it does not read a running process. Check `returned_bytes` and `complete` |
| 131 | before decoding a table. An incomplete read is missing coverage, not a zero-filled |
| 132 | tail. Use `list_segments` to inspect the selected block's initialization and address-space |
| 133 | facts, and retain unavailable facts as unknown. |
| 134 | |
| 135 | Use `address_to_file_offset` to anchor one observed address to original file |
| 136 | bytes. A mapping for the first address does not establish a contiguous mapping |
| 137 | for an entire table, and loader fixups can make analysis bytes differ from source |
| 138 | bytes. Keep source ranges and analysis-memory observations separate. |
| 139 | |
| 140 | A pointer table can refer to writable slots populated by a constructor rather |
| 141 | than directly to immutable resources. An uninitialized block or an observed zero |
| 142 | does not establish the slot's later runtime value. Follow `xrefs` and the relevant |
| 143 | writer's assembly or pseudocode; distinguish recorded assignments from inferred |
| 144 | execution order. Do not replace unreadable bytes with zeros or conclude that a |
| 145 | resource is absent without the necessary initialization evidence. |
| 146 | |
| 147 | ## DOS MZ with Ghidra |
| 148 | |
| 149 | For an admitted DOS MZ target, use `inspect_native_load_image` to check measured |
| 150 | loaded bytes, file mappings, relocations and the entry against the immutable |
| 151 | snapshot. Keep `mismatch` and `unsupported` explicit. Verified import covers the |
| 152 | reported static image, not runtime DOS or PC-98 hardware behavior. |
| 153 | |
| 154 | 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. |
| 155 | |
| 156 | Complete function body ranges use inclusive ends and can contain gaps. Do not |
| 157 | treat the enclosing span as code. |
| 158 | For packed targets, retain the original and separately derived artifact identities; |
| 159 | decompiling an unpacking stub does not recover the unpacked program. |
| 160 | |
| 161 | When reading Objective-C dispatch metadata, distinguish class implementation |
| 162 | methods from protocol requirements: class methods report null requirement |
| 163 | flags, while decoded protocol declarations retain required and optional facts. |
| 164 | Property attributes remain raw name/value tokens; use the property's |
| 165 | `atomicity` field for the decoded `N` marker or the default atomic behavior. |
| 166 | Null class/meta flags, ivar counts, atomicity, or read-only values mean the |
| 167 | selected provider did not establish that fact. Symbol names alone do not prove |
| 168 | that a class is a root class or has no ivars. |
| 169 | |
| 170 | ## Managed PE/CLI |
| 171 | |
| 172 | Start with `inspect_managed_artifact`. REA's canonical managed inspection is |
| 173 | execution-free: do not claim it loaded, reflected, executed, or resolved the |
| 174 | assembly. Keep managed/native boundaries and unavailable reconstruction facts |
| 175 | explicit. A bring-your-own reconstruction oracle is separate from the canonical |
| 176 | parser and must not become an implicit setup dependency. |
| 177 | |
| 178 | For identity/classification questions, `inspect_managed_artifact` can explicitly |
| 179 | select `detail: "summary"` on the first MCP call. It retains complete metadata |
| 180 | and returns a linked overview with full classification/evidence, nullable |
| 181 | module/MVID, frameworks, metadata coverage/issues/limitations and returned-row |
| 182 | counts. Default complete requests remain unchanged. Read original rows with |
| 183 | `inspect_analysis_view`, source `normalized_result.parent_evidence_id`, and |
| 184 | `view: {kind: "managed", collection: "attributes", offset: 0, limit: 16}`. |
| 185 | Collections are `references`, `resources` and `attributes`. Paging does not |
| 186 | repeat parsing. Returned-row exhaustion |
| 187 | does not prove complete metadata or absence under partial/unavailable coverage; |
| 188 | preserve build-local tokens and their artifact/MVID scope. |
| 189 | |
| 190 | `inspect_managed_members` always returns the assembly-wide `member_refs`, even |
| 191 | for one selected type. For questions about a selected type, select |
| 192 | `detail: "summary"` with `type_names`; it returns the selection (with unmatched |
| 193 | names), coverage and per-collection counts. Page rows with |
| 194 | `view: {kind: "managed-members", collection: "call_edges", offset: 0, limit: 64}` |
| 195 | over `types`, `exported_types`, `fields`, `methods`, `member_refs`, `call_edges`, |
| 196 | `field_accesses` or `user_strings`. |
| 197 | |
| 198 | ### .NET NativeAOT |
| 199 | |
| 200 | NativeAOT binaries contain native machine code, so ordinary CIL decompilers |
| 201 | cannot recover the original method bodies. When managed metadata/CIL is absent, |
| 202 | classify that as a native-analysis route rather than claiming source recovery. |
| 203 | Open the native image with the selected deep provider and inspect functions, |
| 204 | strings, calls, and references; describe decompiler output as pseudocode and |
| 205 | inference. |
| 206 | |
| 207 | NativeAOT images can be PE/COFF, ELF, or Mach-O executables and shared |
| 208 | libraries. Use file bytes and loader metadata rather than suffixes to identify |
| 209 | them. For packaged apps, inventory/extract with REA's artifact tools and retain |
| 210 | the exact contained image identity. PDB, ELF debug, or dSYM sidecars are |
| 211 | additional evidence only when the provider accepts and matches them. |
| 212 | |
| 213 | REA has a built-in read-only snapshot parser for x64 PE targets with .NET 8 RTR |
| 214 | 9.1 metadata. An optional headless Ghidra adapter adds database annotations and |
| 215 | broader metadata recovery on Linux; it requires an explicitly configured |
| 216 | NativeAOT JAR. These are separate routes. The built-in parser also runs on |
| 217 | Windows Ghidra P0; read frozen literals from its report, because |
| 218 | `search_strings` does not include them. See the |
| 219 | [NativeAOT guide](https://github.com/morluto/rea/blob/main/docs/ghidra-nativeaot.md) |
| 220 | for setup, supported layouts, and host restrictions. Preserve binary identity |
| 221 | and distinguish derived metadata from Ghidra database observations. Recovered |
| 222 | types and native pseudocode are not original C# source. Windows Ghidra P0 has |
| 223 | no database mutation authority. |
| 224 | |
| 225 | ## Packages and extraction |
| 226 | |
| 227 | Use `inspect_artifact` for application bundles, archives, ZIP/APK/IPA/MSIX/AppX, |
| 228 | ASAR, or DMG inputs when the artifact graph and findings help answer the |
| 229 | question. It returns the complete artifact graph inline. Cite graph manifest |
| 230 | IDs when using them. |
| 231 | |
| 232 | For an IPA or a macOS `.app`, ZIP, or DMG, pass the inventory Evidence to |
| 233 | `project_apple_application_graph`. It reports application roots and nested |
| 234 | bundles by path convention: app extensions, XPC services, frameworks, login |
| 235 | items, system and driver extensions, and plug-ins. It also lists privileged |
| 236 | helpers, launchd plists, symlinks, and each bundle's `info_plist_path` and |
| 237 | executable candidates. Roles are path conventions, not parsed plists; read the |
| 238 | listed plists with `inspect_plist`. |
| 239 | |
| 240 | After `open_binary` on a `.app` or Mach-O, use `trace_dylib_resolution` to see |
| 241 | which file each `@rpath`, `@loader_path` and `@executable_path` load reaches for |
| 242 | every executable in the bundle. It also lists missing or weak loads and earlier |
| 243 | `@rpath` candidates that are absent. Narrow large bundles with `roots` or |
| 244 | `architecture`. System paths stay undetermined because the dyld shared cache |
| 245 | provides them. |
| 246 | |
| 247 | Use `extract_artifact` when materialized files are needed. It extracts the active |
| 248 | target and accepts optional `integrity_policy`; see the [MCP contracts](https://github.com/morluto/rea/blob/main/docs/mcp-contracts.md). |
| 249 | It materializes all regular files into a fresh temporary directory chosen by |
| 250 | REA. Symlinks and encrypted entries are inventory facts, not extractable files. |
| 251 | The result reports the materialized directory; callers do not choose the |
| 252 | destination. No separate permission grant is needed. |
| 253 | |
| 254 | Native DMG traversal automatically uses a read-only mount on supported macOS |
| 255 | hosts, with an owned temporary mount directory and cleanup. It needs no approval |
| 256 | flag. Unsupported hosts or mount failures remain explicit limitations; do not |
| 257 | claim child inventory when only root identity is available. Extraction is a |
| 258 | separate filesystem-writing operation. |
| 259 | |
| 260 | For headerless DOS COM, explicitly open with `format: "dos-com"` (CLI |
| 261 | `--target-format dos-com`). Inspect the load image before trusting function |
| 262 | analysis: the entry is `0x10100`, file offset zero, with imposed real-mode segment |
| 263 | context. PSP/stack/device state remains unmodeled. See [DOS guide](https://github.com/morluto/rea/blob/main/docs/ghidra-dos.md). |
| 264 | |
| 265 | For other headerless images (embedded firmware without ELF/Mach-O/PE/MZ |
| 266 | headers), open with `format: "raw-binary"`, `architecture` (`x86`, `x86_64`, |
| 267 | `arm`, `arm64`, `6502`, or `m68k`), and `entry_point` (`0x` hex). File offset 0 is mapped at |
| 268 | that address. Hopper and IDA refuse this interpretation; Ghidra uses |
| 269 | `BinaryLoader` with a generic language: big-endian for `m68k`, little-endian |
| 270 | otherwise. Big-endian ARM, Thumb-only, and Cortex-M variants are unsupported. |
| 271 | `6502` selects NMOS 6502; the entry and complete file mapping must fit within |
| 272 | `0x0000..0xffff`. 65C02, 65816, cartridge containers, bank switching, and mapper |
| 273 | semantics are unsupported. `m68k` requires an even entry and decodes the 68040 |
| 274 | superset of the 68000 family; Amiga/Atari containers and vector-table entry |
| 275 | discovery are unsupported. Windows Ghidra P0 admits raw images only for `6502`. See [raw binary guide](https://github.com/morluto/rea/blob/main/docs/raw-binary.md). |
| 276 | |
| 277 | ### Function annotations in Ghidra |
| 278 | |
| 279 | 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. |
| 280 | |
| 281 | ## Offline PE resource inventory |
| 282 | |
| 283 | Use `inspect_pe_resources` with an absolute `path`, or |
| 284 | `rea inspect-pe-resources ./selected.exe --json`, for portable PE32/PE32+ |
| 285 | resource inspection without opening a native target. Preserve returned Evidence: |
| 286 | type/name/language IDs and UTF-16 names, original directory/data/payload ranges, |
| 287 | code pages, payload hashes and static icon-group references. Same-language icon |
| 288 | resolution is explicit; missing references and size mismatch remain visible. |
| 289 | Other payloads are opaque, and this operation does not decode images or simulate |
| 290 | Windows resource loading. Consult the budgets and supported tree profile in |
| 291 | [offline binary diagnostics](https://github.com/morluto/rea/blob/main/docs/binary-diagnostics.md). |
| 292 | |
| 293 | For exact core-module import/export differences, use `compare_wasm_interfaces` |
| 294 | with two complete inspection Evidence records (or current-session retained |
| 295 | references) and explicit scope. Preserve unknown types/duplicate names; static |
| 296 | interface equality is not runtime compatibility. CLI accepts complete inline |
| 297 | Evidence in `rea compare-wasm-interfaces input.json --json`. |
文件内容是平台检查时读出的文本，只供查看。平台不会运行包里的任何脚本或程序。
