Native runtime and bridges
REA connects analysis and process services to native tools through small cross-language bridges and controlled runtime processes. The design keeps tool-specific work in its own runtime while returning checked observations, limits, errors, and cleanup state to the main application. It also provides portable readers for native artifacts such as ELF, PE, Mach-O, crash reports, and Windows shortcuts. See Bridge implementations for the bridge-specific view.
Bridge architecture
The bridge architecture separates a common request model from the runtime that performs the work. A provider starts or discovers a session, sends bounded requests, checks the reply, and turns the result into analysis evidence or process observations.
The main bridge forms are:
| Bridge form | Runtime | Purpose |
|---|---|---|
| Started local session | Headless Ghidra or Hopper bridge | Analyse one admitted target in an isolated session |
| Discovered local plugin | Cutter plugin | Reach an active user session without starting the application |
| Embedded tool script | LLDB | Observe a running native program |
| Allowlisted host command | macOS Xcode tools | Read native metadata and run bounded inspection commands |
| Owned artifact decoder | pwntools, pwndbg, or a portable reader | Decode an admitted artifact or recorded crash without launching the artifact |
Each session has a private runtime area, a run identity, and a session proof. The client binds replies to the session and target before it exposes them to higher layers. This prevents a reachable socket, file, process, or reply from being mistaken for the requested target.
This diagram shows how a common request becomes a provider action and returns as a bounded observation.
flowchart LR
A[Analysis or process request] --> B[Provider client]
B --> C[Private session and identity checks]
C --> D[Native tool or decoder runtime]
D --> E[Tool reply or observation]
E --> F[Validated provider result]
F --> G[Evidence, diagnostics, or process state]
Session boundaries
The session boundary gives one operation a private place for descriptors, sockets, logs, snapshots, and result files. It also owns the lifetime of processes and temporary data. Normal close, cancellation, startup failure, and timeout all attempt cleanup. If cleanup is not proven complete, later work stays blocked or keeps the cleanup owner for retry.
References: src/…/PrivateRuntimeRoot.ts• L13-91 src/…/ProviderProcess.ts• L21-53 src/…/OwnedCommand.ts• L158-195 src/…/WindowsPrivateRuntime.ts• L58-92
Authentication and identity
Authentication proves that a reply came from the session that received the request. Target identity adds a second check so a path with the same name cannot replace the admitted file or document. Native process work applies the same rule to the selected executable, architecture, digest, loaded modules, and termination state.
These checks support safe failure. A stale session, changed document, ambiguous target, or missing termination proof becomes unavailable or partial instead of being silently mapped to another target.
References: src/…/CutterBridgeClient.ts• L20-75 src/…/CutterBridgeService.ts• L101-168 src/…/SignatureTargetBinding.ts• L98-203 src/…/NativeCallObservation.ts• L50-111 src/…/NativeUiObservation.ts• L164-227
Request and result contracts
The bridge contract carries operation names, parameters, request identity, limits, and structured results. The TypeScript side validates input and output before it creates provider-neutral executions or evidence. Replies retain bounded output, exit state, observed byte counts, and incomplete state so a tool response cannot become an unbounded memory or transport load.
The same contract separates preparation failure from failure after launch. It also lets static readers and artifact decoders retain valid facts while marking unsupported, unknown, or partial coverage.
References: src/…/CutterBridgeClient.ts• L38-75 src/…/CutterBridgeService.ts• L81-170 src/…/CommandRunner.ts• L37-141 src/…/NativeCommandAnalysisError.ts• L40-224 src/…/AppleDispatchMetadata.ts• L304-381
Platform runtime support
Platform support provides the process, file, and host-tool controls that bridges need. The application selects a runtime path from the host platform and reports a capability only when the required control is present and proven.
POSIX runtime support
On POSIX hosts, provider processes run in dedicated process groups and carry a run token. Before a signal is sent, the supervisor rechecks the live process identity, group relation, and token. If ownership is uncertain, cleanup fails closed instead of signaling an unrelated process.
Short-lived commands wait for both process output and the output consumer. Cancellation and timeout stop the owned process before the command returns. An unconfirmed cleanup remains retryable rather than being reported as complete.
References: src/…/ProviderProcess.ts• L178-250 src/…/ProcessOwnership.ts• L342-512 src/…/OwnedCommand.ts• L221-417 src/…/CommandRunner.ts• L505-602
Windows native runtime
Windows uses one package-owned Node-API native addon for controls that JavaScript cannot safely reproduce. The loader checks the host, package metadata, artifact identity, architecture, ABI, and native self-test before providers can claim those controls.
The addon supplies private runtime access, safe local-path admission, retained descriptor access, and owned process trees through Job Objects. Failed handle closure remains an authority problem until the system proves that the handle is gone. A missing native guarantee is not replaced with a weaker guess.
References: src/…/WindowsNativeLoader.ts• L27-77 src/…/WindowsNativeLoader.ts• L108-169 src/…/WindowsPrivateRuntime.ts• L58-95 native/…/authority.hpp• L59-79 native/…/handle_close.hpp• L14-60
Windows process runtime
The Windows process runtime places a child in an owned Job Object before the child resumes. It captures bounded output, supports admitted protocol input, observes memory-limit notifications, and waits for the full job during cleanup.
Bridge clients can therefore distinguish normal exit from a memory limit, incomplete output, failed cleanup, or missing native control. A requested memory limit is never silently dropped when the addon cannot enforce it.
References: native/…/process.cc• L22-68 native/…/process.cc• L91-213 src/…/WindowsOwnedProcess.ts• L38-107 src/…/ProviderProcess.ts• L55-74
Analysis runtimes
Analysis runtimes expose different native tools through one provider model. The provider checks host and target support first. It then resolves a profile, starts or connects to the runtime, and maps tool output into the shared analysis contract.
Headless analysis sessions
Ghidra runs as an isolated headless import for one target. Hopper uses its supported application launcher and Python bridge. Both paths bind the session to a target and provider profile before analysis begins. Their process ownership differs by host, so availability and cleanup results reflect whether REA owns the launched application.
References: src/…/GhidraProvider.ts• L77-123 src/…/GhidraLauncher.ts• L50-88 src/…/HopperProvider.ts• L42-101 src/…/BridgeLauncher.ts• L41-187
Live plugin sessions
Cutter is reached through a plugin inside the active application. The client discovers private session descriptors, authenticates a loopback connection, and sends commands to the UI dispatcher. The service turns plugin replies into evidence while retaining session generation and partial identity.
This lifecycle differs from a headless launch because REA does not own the Cutter application. If the plugin cannot prove terminal completion, the session stays blocked instead of repeating a possibly unsafe command.
References: src/…/CutterBridgeClient.ts• L243-280 src/…/CutterBridgeService.ts• L35-75 src/…/CutterBridgeService.ts• L148-170
macOS native inspection
The macOS provider combines allowlisted Xcode commands with bounded readers for static Mach-O metadata. It presents read-only inspection, signatures, property lists, native call observation, native UI observation, Apple dispatch metadata, and recorded crash-report inspection through one capability model.
The capability profile states whether an operation only reads an artifact or may launch a process, show UI, use the network, or write files. Each command runs without a shell under a deadline and output budget. Static readers use the same selected source and keep unknown or partial coverage visible.
References: src/…/NativeMacOSProvider.ts• L192-247 src/…/NativeMacOSProvider.ts• L287-419 src/…/NativeMacOSProvider.ts• L1106-1208 src/…/NativeMacOSProviderMetadata.ts• L1-180 src/…/CommandRunner.ts• L158-267
Mach-O image selection
Mach-O inspection treats a universal file as a container of architecture slices. One slice is selected before commands or metadata readers collect evidence. The selected tool identity is then checked against the FAT table and the thin header.
That selected slice supplies the address and file-range context for load commands, fixups, imports, exports, entrypoints, initializers, and build facts. Conflicting or ambiguous slices stop inspection. Unresolved fixups, encryption state, UUID disagreement, and incomplete command coverage remain explicit instead of becoming invented addresses or facts.
References: src/…/NativeMachoSelectedSlice.ts• L15-128 src/…/NativeMachoInspection.ts• L175-249 src/…/NativeMachoInspection.ts• L325-409 src/…/MachoBinaryProjection.ts• L155-179
Objective-C and Swift metadata
Apple dispatch metadata gives analysis consumers a static view of Objective-C classes, methods, properties, protocols, categories, and Swift nominal types, conformances, witness slots, and class vtable slots. It reads file metadata without loading target code or claiming runtime behavior.
The reader binds observations to one admitted Mach-O image and applies shared record and input limits. External bindings, unresolved relative pointers, unsupported Swift forms, malformed sibling records, and exhausted budgets affect the relevant facet while independent records remain useful. Protocol declarations describe requirements; they do not establish handler targets.
References: src/…/AppleDispatchMetadata.ts• L78-180 src/…/AppleObjcCategories.ts• L16-120 src/…/AppleObjcClassImportBindings.ts• L1-136 src/…/AppleObjcDispatchFacets.ts• L84-120 src/…/AppleSwiftNominalTypes.ts• L29-117 src/…/AppleSwiftVtables.ts• L37-120
Native process operations
Native process operations use the same runtime rules as analysis bridges but focus on observations from a running target or bounded host-tool output. The operation starts only an owned target or tracer, limits time and retained output, and returns only what the runtime can prove.
macOS inspection commands
The macOS command runner resolves an allowlisted executable before launch, records its identity, applies a deadline, bounds output, and retains cleanup ownership when the process tree does not stop. Failures distinguish unavailable tools, cancellation, timeout, output limit, non-zero exit, I/O failure, and failed preparation.
This boundary supports Mach-O inspection, signature checks, architecture listing, Swift demangling, and property-list reads. Property-list projection keeps source types and large integers visible when a simpler JSON value would lose them. A conversion limit stays distinct from source absence.
References: src/…/CommandRunner.ts• L28-141 src/…/CommandRunner.ts• L158-267 src/…/NativeCommandAnalysisError.ts• L135-224 src/…/NativePlistSource.ts• L266-353 src/…/NativeMacOSProvider.ts• L1594-1657
LLDB observation sessions
The LLDB bridge runs inside LLDB's embedded Python runtime and records native calls from registers and memory reads. It does not evaluate target expressions or run target code for the tracer. The target is held at launch until the host confirms its identity. The host and tracer check file and module identity again before recording the run.
The result is a bounded observation rather than a claim that every call was seen. Journal, output, readback, and cleanup limits remain visible. REA does not claim that the target is gone until the bridge or host proves termination.
References: bridge/…/rea_lldb_tracer.py• L647-934 src/…/NativeCallObservation.ts• L50-307 src/…/LldbCallTracer.ts• L98-157 src/…/LldbCallTracer.ts• L620-988 src/…/LldbRetainedObservations.ts• L59-282
Native UI sessions
Native UI work uses a helper runtime for an already-running macOS application window. The helper captures screenshots or accessibility data and runs explicitly selected actions. It does not launch the target, change permissions, or restore application data.
The provider serializes UI sessions for one client and checks process and window identity after each helper response. It validates capture data and keeps caller limits separate from fixed helper limits. A later capture or cleanup failure produces a partial scenario with completed steps retained.
References: src/…/NativeUiObservation.ts• L68-337 src/…/NativeUiHelperRuntime.ts• L15-123 src/…/NativeUiInterruptionControl.ts• L7-69
Owned artifact decoder sessions
Owned artifact decoders run a tool-specific decoder over a stable private snapshot. The decoder never launches the selected artifact as a host process. It returns a schema-checked report with the artifact digest, bounded diagnostics, and any partial or resource state.
The pwntools profile admits a Linux x64 host and a pinned engine identity. Recorded-crash analysis can add an optional pwndbg stage without changing the base static evidence. Each stage keeps its own limits, diagnostics, and cleanup state.
References: src/…/PwntoolsRecordedCrashProvider.ts• L29-178 src/…/RecordedCrashSourceBindings.ts• L12-82 src/…/RecordedCrashStructureBindings.ts• L23-90 src/…/CoreFileMappingAuthority.ts• L1-30
Portable native artifact analysis
Portable artifact analysis reads stable snapshots without executing the selected image. A shared container view describes file-backed mappings, executable regions, sections, zero-fill ranges, and architecture before a feature reader examines metadata.
Binary container admission
The common admission layer distinguishes a corrupt recognized binary from a container outside parser coverage. It maps virtual ranges to file bytes and refuses missing or conflicting mappings. Feature readers use the same image identity and address rules for ELF, PE, and thin or universal Mach-O inputs.
This prevents a virtual address from being treated as a file location by default. A missing, zero-fill, or ambiguous mapping stays unknown.
References: src/…/BinaryContainer.test.ts• L1-180 src/…/NativeSectionDirectory.test.ts• L1-180 src/…/PeImage.test.ts• L1-180
ELF structural evidence
ELF readers provide static evidence for exports, notes, dependencies, debug links, DWARF compile units, unwind ranges, kernel metadata, initializers, hardening, pointer relocations, and Android JNI candidates. They do not execute the image, invoke the loader, resolve host paths, boot a kernel, or establish runtime registration.
The readers share stable artifact identity and bounded work. They retain valid rows when possible and mark malformed, unsupported, absent, partial, or unknown coverage separately. Newer evidence includes FDO metadata as an unverified producer declaration, GNU debug-link and build-id comparisons, first-level DWARF unit facts, dynamic dependency and version declarations, and initializer slots with relocation-aware resolution.
| Evidence | System-level meaning | Boundary |
|---|---|---|
| Notes and FDO metadata | Producer declarations, build identity, ABI facts, and properties | Declarations are not runtime proof; compressed or over-limit data can remain unknown |
| Debug links and DWARF units | Links to separate debug artifacts and compile-unit facts | Candidate matching and unit walks are bounded; child DIEs and runtime debug loading are not read |
| Dependencies and exports | Declared libraries, symbols, versions, and search paths | Paths are reported as written; the host loader is not run |
| Unwind ranges and initializers | Static function ranges and startup or finalizer slots | Indirect, unresolved, or unmapped values remain incomplete or unknown |
| Kernel and JNI metadata | Embedded build data, module declarations, and static JNI candidates | Images are not executed and registration or invocation is not established |
References: src/…/ElfNoteParser.ts• L737-949 src/…/ElfFdoNote.ts• L12-109 src/…/ElfDebugLinkProvider.ts• L54-134 src/…/DwarfUnitsProvider.ts• L58-187 src/…/DwarfUnitParser.ts• L114-160 src/…/ElfDependencyParser.ts• L125-134 src/…/ElfUnwindTables.ts• L248-339 src/…/NativeInitializersProvider.ts• L60-171 src/…/KernelModuleParser.ts• L77-127
PE structural evidence
PE readers turn one stable image into bounded evidence about imports, exports, load configuration, resources, and certificate containers. They use image mappings and data directories to relate file bytes to reported addresses without loading or executing the image.
The readers keep structure separate from runtime effect. Certificate parsing reports WIN_CERTIFICATE and PKCS#7 structure without verifying signatures, chains, timestamps, or Authenticode coverage. Resource parsing inventories the type, name, language, and icon-group tree without loading payloads or inferring Windows language fallback. RVA conflicts, directory errors, and entry or metadata limits remain explicit.
References: src/…/PeCertificateParser.ts• L24-69 src/…/PeImportsProvider.ts• L35-80 src/…/PeLoadConfigParser.ts• L129-251 src/…/PeResourcesProvider.ts• L40-101 src/…/peResourceInventory.ts• L64-408
Mach-O structural evidence
Mach-O readers combine native command output with bounded binary projection. The projection gives common facts about commands, segments, dependencies, entrypoints, and build metadata. The inspection layer adds symbols, dynamic imports and exports, UUIDs, encryption facts, and limitations for the selected slice.
Static initializers and hardening use the same selected image. This keeps architecture, file offsets, fixups, and address mapping tied to one artifact rather than allowing a universal container or a second tool to supply a different image.
References: src/…/MachoBinaryProjection.ts• L155-179 src/…/NativeMachoInspection.ts• L64-107 src/…/NativeInitializersProvider.ts• L111-171 src/…/MachoHardening.ts• L267-342
Apple crash report evidence
Apple .ips analysis reads a recorded crash report without starting the recorded process. It preserves report metadata, exception and termination facts, thread registers, frames, loaded images, type mismatches, and bounded integer text.
An optional join uses UUID, architecture, and __TEXT identity from a selected Mach-O or dSYM. It adds static addresses only for one compatible slice. A completed base report remains available if the join fails or reaches its own limit.
References: src/…/AppleIpsProvider.ts• L54-165 src/…/AppleIpsParser.test.ts• L35-60 src/…/AppleIpsFieldReader.ts• L25-110
Windows shortcut evidence
Windows shortcut analysis reads Shell Link bytes as a static artifact. It reports header flags, target ID-list items, local and network link information, string fields, extra data blocks, and derived observations without resolving or executing the target.
Admission rejects network-share paths and directory links before file reads. The parser keeps ANSI text, Unicode text, stored identifiers, and partial structural coverage distinct. Missing terminators, malformed blocks, and limits become issues instead of being treated as absent data.
References: src/…/WindowsShortcutProvider.ts• L48-175 src/…/WindowsShortcutParser.ts• L1436-1489
Change checklist
When these files or sections are changed, remember to consider these:
- Keep session descriptor fields aligned between the launcher, bridge runtime, startup handshake, and Windows descriptor reader.
- Keep provider identity and target identity checks aligned with the profile that selected the target. A path check alone is not enough for imported, reopened, snapshotted, or launched native documents.
- Preserve the difference between owned launcher lifetime and external application lifetime when changing cleanup or cancellation.
- Keep command completion aligned with process exit and output-consumer completion.
- Keep native macOS capability availability, provider identity, analysis profiles, operation effects, deadlines, executable identity, and output allowances aligned.
- Keep native metadata readers tied to the shared virtual-to-file mapping contract. An absent, ambiguous, or zero-fill mapping must not become a valid pointer or string source.
- Keep Mach-O CPU policy, selected slice offsets, fixup coverage, command facts, UUID reconciliation, encryption facts, and initializer records tied to one image.
- Keep Objective-C and Swift facet coverage aligned with list limits, record budgets, unresolved bindings, and independent sibling records.
- Keep ELF note, debug-link, DWARF, dependency, unwind, kernel, initializer, relocation, JNI, export, and FDO limits distinct from format absence.
- Keep PE image mappings, certificate structure, resource-tree shape, RVA checks, and cryptographic validity claims separate.
- Keep Windows shortcut path admission separate from Shell Link parsing. Keep ANSI and Unicode text limits separate.
- Keep pwntools snapshot identity, producer limits, reply schema, optional pwndbg enrichment, and cleanup ownership aligned.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Session, provider, or target identity does not match | The session is rejected or the provider becomes unavailable | Authenticate each request and verify the admitted target before serving work |
| Owned process cleanup cannot prove the full tree stopped | A new operation is blocked or cleanup remains retryable | Retain ownership records and retry only after verified settlement |
| Command preparation fails or a deadline or output limit is reached | No unsafe command result is claimed; the phase and cleanup state remain visible | Separate preparation from post-launch failure and use fixed budgets |
| Mach-O slice, fixup, or UUID selection is absent or ambiguous | Inspection refuses to read or join a different architecture | Require one matching slice identity and keep unresolved coverage unknown |
| Objective-C or Swift binding data is unresolved | The affected facet is partial while independent records remain available | Preserve decoded records with per-facet reasons |
| LLDB journal, readback, or target termination proof is incomplete | The observation is partial and the target may remain owned | Parse bounded prefixes and retain cleanup ownership until termination is proved |
| Artifact mapping, RVA, or section range is absent or conflicting | A pointer, string, or address remains unknown | Use the shared mapping index and reject ambiguous spans |
| ELF, PE, IPS, or shortcut work exceeds a parser or input bound | The affected report is partial, unsupported, or a typed resource failure | Charge limits before retaining facts and keep fixed allowances separate from caller limits |
| A PE certificate or kernel-module signature is present | Structure is reported without cryptographic validity | Keep parsing separate from signature and chain verification |
| A shortcut reaches a network share or linked ancestor | Offline inspection is refused before the path is opened | Reject remote or linked paths during admission |
| A pwntools or pwndbg worker cannot finalize while its files remain owned | Partial evidence is returned and later work is blocked | Retain the runtime owner and retry cleanup before reuse |
Key files
| File | Why to read it |
|---|---|
| src/…/NativeMacOSProvider.ts | Main entry point for macOS inspection, metadata, calls, UI, crash reports, and app resources. |
| src/…/CommandRunner.ts | Shared allowlist, executable identity, bounded capture, deadline, and cleanup contract. |
| src/…/WindowsNativeLoader.ts | Admission of packaged Windows native authority. |
| src/…/WindowsOwnedProcess.ts | Windows Job Object lifecycle and process result states. |
| src/…/GhidraLauncher.ts | Session contract for a headless analysis runtime. |
| src/…/CutterBridgeClient.ts and src/…/CutterBridgeService.ts | Discovery, authentication, plugin access, and live-session completion. |
| src/…/NativeMachoInspection.ts and src/…/NativeMachoSelectedSlice.ts | Mach-O command evidence and selected-image identity. |
| src/…/AppleDispatchMetadata.ts | Bounded Objective-C and Swift metadata evidence. |
| src/…/NativeCallObservation.ts and src/…/LldbCallTracer.ts | Native-call request, observation, identity, and cleanup lifecycle. |
| src/…/NativeUiObservation.ts | Helper responses, target checks, actions, deadlines, and partial scenarios. |
| src/…/PwntoolsRecordedCrashProvider.ts | Stable recorded-crash decoder boundary and provider identity. |
| src/…/BinaryContainer.test.ts | Shared binary admission and virtual-to-file mapping rules. |
| src/…/ElfNoteParser.ts and src/…/ElfDebugLinkProvider.ts | Bounded ELF note evidence and separate debug-file matching. |
| src/…/DwarfUnitsProvider.ts | Compile-unit evidence from stable DWARF sections. |
| src/…/ElfDependencyParser.ts and src/…/NativeInitializersProvider.ts | Static ELF dependency and cross-format initializer evidence. |
| src/…/BinaryHardeningProvider.ts | Common hardening report across ELF, PE, and Mach-O. |
| src/…/PeResourcesProvider.ts and src/…/PeCertificateParser.ts | Bounded PE resources and certificate structure. |
| src/…/AppleIpsProvider.ts | Recorded Apple crash-report reading and optional image join. |
| src/…/WindowsShortcutProvider.ts and src/…/WindowsShortcutParser.ts | Windows path admission and offline Shell Link evidence. |