Introducing a new way to review your PRs.

Read the announcement

morluto / rea

Reverse engineer anything with agents, from app behavior down to native binaries.

View on GitHub

27 documents · Updated Nov 20, 2026

docs / native-runtime-and-bridges

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 formRuntimePurpose
Started local sessionHeadless Ghidra or Hopper bridgeAnalyse one admitted target in an isolated session
Discovered local pluginCutter pluginReach an active user session without starting the application
Embedded tool scriptLLDBObserve a running native program
Allowlisted host commandmacOS Xcode toolsRead native metadata and run bounded inspection commands
Owned artifact decoderpwntools, pwndbg, or a portable readerDecode 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.

EvidenceSystem-level meaningBoundary
Notes and FDO metadataProducer declarations, build identity, ABI facts, and propertiesDeclarations are not runtime proof; compressed or over-limit data can remain unknown
Debug links and DWARF unitsLinks to separate debug artifacts and compile-unit factsCandidate matching and unit walks are bounded; child DIEs and runtime debug loading are not read
Dependencies and exportsDeclared libraries, symbols, versions, and search pathsPaths are reported as written; the host loader is not run
Unwind ranges and initializersStatic function ranges and startup or finalizer slotsIndirect, unresolved, or unmapped values remain incomplete or unknown
Kernel and JNI metadataEmbedded build data, module declarations, and static JNI candidatesImages 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

TriggerConsequenceGuard
Session, provider, or target identity does not matchThe session is rejected or the provider becomes unavailableAuthenticate each request and verify the admitted target before serving work
Owned process cleanup cannot prove the full tree stoppedA new operation is blocked or cleanup remains retryableRetain ownership records and retry only after verified settlement
Command preparation fails or a deadline or output limit is reachedNo unsafe command result is claimed; the phase and cleanup state remain visibleSeparate preparation from post-launch failure and use fixed budgets
Mach-O slice, fixup, or UUID selection is absent or ambiguousInspection refuses to read or join a different architectureRequire one matching slice identity and keep unresolved coverage unknown
Objective-C or Swift binding data is unresolvedThe affected facet is partial while independent records remain availablePreserve decoded records with per-facet reasons
LLDB journal, readback, or target termination proof is incompleteThe observation is partial and the target may remain ownedParse bounded prefixes and retain cleanup ownership until termination is proved
Artifact mapping, RVA, or section range is absent or conflictingA pointer, string, or address remains unknownUse the shared mapping index and reject ambiguous spans
ELF, PE, IPS, or shortcut work exceeds a parser or input boundThe affected report is partial, unsupported, or a typed resource failureCharge limits before retaining facts and keep fixed allowances separate from caller limits
A PE certificate or kernel-module signature is presentStructure is reported without cryptographic validityKeep parsing separate from signature and chain verification
A shortcut reaches a network share or linked ancestorOffline inspection is refused before the path is openedReject remote or linked paths during admission
A pwntools or pwndbg worker cannot finalize while its files remain ownedPartial evidence is returned and later work is blockedRetain the runtime owner and retry cleanup before reuse

Key files

FileWhy to read it
src/…/NativeMacOSProvider.tsMain entry point for macOS inspection, metadata, calls, UI, crash reports, and app resources.
src/…/CommandRunner.tsShared allowlist, executable identity, bounded capture, deadline, and cleanup contract.
src/…/WindowsNativeLoader.tsAdmission of packaged Windows native authority.
src/…/WindowsOwnedProcess.tsWindows Job Object lifecycle and process result states.
src/…/GhidraLauncher.tsSession contract for a headless analysis runtime.
src/…/CutterBridgeClient.ts and src/…/CutterBridgeService.tsDiscovery, authentication, plugin access, and live-session completion.
src/…/NativeMachoInspection.ts and src/…/NativeMachoSelectedSlice.tsMach-O command evidence and selected-image identity.
src/…/AppleDispatchMetadata.tsBounded Objective-C and Swift metadata evidence.
src/…/NativeCallObservation.ts and src/…/LldbCallTracer.tsNative-call request, observation, identity, and cleanup lifecycle.
src/…/NativeUiObservation.tsHelper responses, target checks, actions, deadlines, and partial scenarios.
src/…/PwntoolsRecordedCrashProvider.tsStable recorded-crash decoder boundary and provider identity.
src/…/BinaryContainer.test.tsShared binary admission and virtual-to-file mapping rules.
src/…/ElfNoteParser.ts and src/…/ElfDebugLinkProvider.tsBounded ELF note evidence and separate debug-file matching.
src/…/DwarfUnitsProvider.tsCompile-unit evidence from stable DWARF sections.
src/…/ElfDependencyParser.ts and src/…/NativeInitializersProvider.tsStatic ELF dependency and cross-format initializer evidence.
src/…/BinaryHardeningProvider.tsCommon hardening report across ELF, PE, and Mach-O.
src/…/PeResourcesProvider.ts and src/…/PeCertificateParser.tsBounded PE resources and certificate structure.
src/…/AppleIpsProvider.tsRecorded Apple crash-report reading and optional image join.
src/…/WindowsShortcutProvider.ts and src/…/WindowsShortcutParser.tsWindows path admission and offline Shell Link evidence.