Reverse-engineering toolchains
REA turns separate reverse-engineering and debugging products into one bounded investigation surface. It selects a product that can admit the target, binds the product to the target and its analysis context, and returns observations with their source and limits. This lets an investigation move from static facts to live target state without treating different products as interchangeable.
The Ghidra integration page explains Ghidra target lanes, profiles, and saved analysis state. The debugger and disassembler integrations page explains debugger sessions, disassembler bridges, and their product-specific limits.
Investigation surface
The investigation surface is the shared set of questions REA can ask about a target. It covers target identity, procedures, symbols, strings, instructions, references, pseudocode, memory, and runtime state. Each provider reports its own coverage, so an unavailable or incomplete question remains visible.
The main paths are:
- A binary session binds one target to one provider and one analysis profile.
- Focused operations answer one investigation question. A function dossier joins the main observations about one procedure.
- Static adapters provide native or managed-code views through external products.
- Persistent GDB and Rizin sessions add controlled live state to static analysis.
- Linked Evidence joins observations into call paths, behavior comparisons, static/runtime checks, and verification work.
All paths share the provider contract across the CLI and MCP. Results stay tied to the target, provider, profile, and known limits. A target is data, not authority to select later tool actions.
References: src/…/GhidraProvider.ts• L171-229 src/…/IdaProvider.ts• L110-175 src/…/GdbSessionManager.ts• L402-449
Provider roles
Provider selection is a routing decision. REA checks product readiness and target support before it starts analysis. A provider is selected because it can answer the question within its admitted boundary, not because REA ranks its output as better.
| Provider | Investigation role | Boundary |
|---|---|---|
| Ghidra | Broad native analysis with explicit target interpretation | Caller-supplied installation and private analysis state |
| Hopper | Native analysis through a private bridge | Host, architecture, document, and process limits |
| IDA | Native analysis through an attached or headless MCP service | Live registration, compatibility profile, workspace, and target identity |
| JEB | Managed-code project and decompilation inspection | Caller-started local MCP service and admitted project units |
| GNU objdump | Fast file and disassembly inspection | One-shot raw output |
| Rizin | One-shot inspection and persistent debugging | Caller-selected executable and command effects |
| GDB | Persistent debugging | Owned Linux debugger sessions |
| Cutter | Commands against a local Cutter document | Authenticated local bridge and command completion |
| Kuna | Native executable decompilation | Configured tool and admitted executable formats |
The registry rejects a target when its format, architecture, role, host, or external service falls outside a provider boundary. Ghidra admits a broad set of native formats and architectures through target-specific profiles. IDA admits verified x86 and ARM families through a selected MCP mode. Hopper admits executable or database targets subject to its host and document rules. Provider identity remains part of the evidence even when two products answer a similar question.
References: src/…/GhidraProvider.ts• L281-343 src/…/IdaProvider.ts• L268-317 src/…/HopperAnalysisProfile.ts• L242-309
Session admission
Session admission binds the target, provider, profile, external product, and evidence record before useful work starts. Readiness checks can inspect a product without starting analysis. The first target-bound operation starts or connects to the selected product.
When an investigator opens a target, REA follows this sequence:
- Identify the target and inspect product readiness.
- Check target support and resolve the analysis profile.
- Start or connect to the selected product when an operation needs it.
- Validate the live product identity and route the operation.
- Return normalized observations with raw source facts and limits.
- Close the session, or retain failed cleanup for recovery.
The profile is the product's interpretation of the target. It can include loader, language, analysis policy, caller seeds, extensions, saved analysis state, and resource limits. A changed profile means a changed analysis context, so REA does not silently reuse an observation under new settings.
This diagram shows how target admission becomes a bounded observation.
flowchart LR
A[Target] --> B[Provider readiness]
B --> C[Target support and profile]
C --> D[Bound session]
D --> E[Investigation operation]
E --> F[Validated product observation]
F --> G[Evidence with limits]
D --> H[Verified close or retained cleanup]
References: src/…/GhidraProvider.ts• L186-229 src/…/GhidraProvider.ts• L391-432 src/…/IdaProvider.ts• L195-265 src/…/HopperClient.ts• L451-685
Evidence boundaries
Evidence is the common record for observations from different products. It keeps the source provider, target, profile, operation, result, and limits together. Raw output stays available when normalization would hide a fact from the producing product.
REA keeps these meanings separate:
- Decompiled text is product output. It is not recovered source code.
- Complete means complete within the provider's stated scope. It does not prove that hidden code or behavior is absent.
- A partial or unknown relationship result is not an empty complete graph.
- Caller seeds and analyst names are assertions or edits. They are not discoveries made by the provider.
- Restored projects and saved analysis describe retained state. They are not fresh observations.
- Debugger commands and bridge commands may write files, reach a shell, use the network, or change the target. Their side effects remain part of the evidence boundary.
- A load-image verification result compares provider observations with the admitted target and profile. It can report a mismatch without claiming that the provider output is verified.
This model lets higher-level workflows combine static and runtime facts without hiding which product produced each fact or how much the fact proves.
References: src/…/GdbSessionManager.ts• L415-449 src/…/GdbSessionManager.ts• L1202-1253 src/…/RizinDebugSessionManager.ts• L117-167 src/…/CutterBridgeService.ts• L168-226
Ghidra integration
Ghidra is REA's broad native-analysis path. It admits a caller-supplied installation and a target profile before it starts a private headless session. Readiness checks cover the installation, declared release, Java runtime, headless launcher, native decompiler, and platform-specific runtime authority before the provider becomes available. The verified release is Ghidra 12.2 with Java 25. Other accepted 12.x releases at or above 12.2 remain marked as compatible but unverified.
Ghidra supports header-based native targets and explicit raw or special-format lanes when their admission rules fit. The profile records the target interpretation and analysis policy. It can also commit caller seed files, optional analysis extensions, disabled analyzers, and verified architecture or ABI choices before analysis. REA snapshots these inputs into the private run and checks the reported outcomes. Seeded facts remain distinct from Ghidra discoveries.
The Ghidra surface joins inventory and function analysis. It can provide load-image facts, bytes and file offsets, symbols, strings, procedures, instructions, references, function dossiers, annotations, native value-flow observations, and decompilation. Function results carry provider limitations and relationship coverage. A load-image result can independently compare target identity, mappings, entry points, and relocation facts for verified special-format lanes. PE metadata such as PDB and NativeAOT observations remains separate from claims of complete debug-symbol coverage.
Ghidra can use a private copy of an existing project or an owned saved Program checkpoint. Existing project content is fingerprinted before admission and opened through a private copy. Restored analysis is retained history, not fresh analysis. Normal close can save owned state, while failed publication or cleanup keeps the owning session and its private resources available for recovery.
The bridge uses an authenticated private transport. REA checks request and reply limits before dispatch and validates the run, provider, profile, target, language, image base, and capability set before it creates Evidence. A failed handshake, changed target, changed seed or extension, malformed reply, incomplete load-image verification, or unverified cleanup blocks a trusted session rather than causing a fallback to another interpretation.
See Ghidra integration for target lanes, profile rules, bridge behavior, and saved analysis state.
References: src/…/GhidraProvider.ts• L171-229 src/…/GhidraProvider.ts• L391-632 src/…/GhidraClient.ts• L1025-1203 src/…/GhidraProviderClient.ts• L1036-1245
Ghidra installation admission
Ghidra installation admission is a readiness check, not an analysis run. It verifies the selected release, the host and native tool match, the headless launcher, and a 64-bit full JDK that satisfies the installation's declared Java range. This keeps a broken or mismatched installation from failing after a target has been opened.
References: src/…/GhidraInstallation.ts• L350-430 src/…/GhidraInstallation.ts• L888-1043 src/…/GhidraReleasePolicy.ts• L1-11
Ghidra analysis profiles
An analysis profile binds the target's format, architecture, loader, language, address rules, analysis policy, and optional caller inputs. The same commitment is checked again when the session opens, so a changed installation or configuration requires a new profile instead of silently changing the meaning of an existing result.
References: src/…/GhidraAnalysisProfile.ts• L126-181 src/…/GhidraAnalysisProfile.ts• L209-381 src/…/GhidraProviderClient.ts• L349-576
Ghidra private sessions
Each session receives an immutable target snapshot and a private runtime. REA launches the headless product with the committed profile, connects to an authenticated bridge, and accepts operations only after the bridge proves the expected run, target, profile, language, image base, and capabilities. Existing projects are read-only private copies. Owned checkpoints can be restored and saved as retained analysis state.
References: src/…/GhidraTargetSnapshot.ts• L29-129 src/…/GhidraLauncher.ts• L291-420 src/…/GhidraClient.ts• L1025-1203 src/…/GhidraSessionValues.ts• L159-212
Ghidra load-image verification
Load-image verification compares product-reported mappings and entry facts with the exact admitted source snapshot. It is strongest for the explicit DOS MZ, DOS COM, raw-binary, and GameCube DOL lanes. Other formats retain measured observations without claiming format-specific verification.
References: src/…/GhidraLoadImageAttest.ts• L49-243 src/…/GhidraLoadImageValues.ts• L111-209 src/…/GhidraDosSnapshot.ts• L27-136
External MCP integrations
Some products run as MCP services that REA does not own. These adapters connect to a caller-selected endpoint, discover the live tool set, check the compatibility profile, and preserve the upstream service identity. They do not turn a remote service into a local analysis engine.
IDA integration
IDA supports attached and headless MCP compatibility profiles. The selected profile controls which investigation questions are available and whether REA connects to an existing service or uses a private workspace. Readiness checks validate the registration and workspace without claiming that IDA has already analyzed a target. The removed legacy protocol is rejected rather than guessed.
IDA admits executable inputs for verified x86 and ARM families. It refuses raw binaries, analysis databases, and unsupported formats. A universal Mach-O target remains unknown until the connection mode can prove the selected slice. Attached mode cannot prove that identity from the whole-file digest alone. Doctor checks describe registration and private-workspace readiness without starting IDA or exposing transport credentials.
The adapter creates a client only for the exact target and profile that it resolved. This keeps a later client request from silently changing the registered service or the analysis context.
References: src/…/IdaProvider.ts• L79-107 src/…/IdaProvider.ts• L195-265 src/…/IdaProvider.ts• L268-385 src/…/IdaConfiguration.test.ts• L324-403 src/…/IdaDoctor.test.ts• L102-133
JEB integration
JEB provides managed-code project and decompilation views through a caller-started local MCP service. REA discovers the current tool catalog and reports only the operations the live engine advertises. A project page can be partial when the request does not cover the full unit set.
JEB keeps engine metadata, selected endpoint, project units, and decompilation output tied to each observation. A reachable engine refusal remains an engine refusal. REA does not infer a different target format or invoke an unasked recovery operation.
References: src/…/JebProvider.test.ts• L124-161 src/…/JebProvider.test.ts• L319-352 src/…/JebProvider.test.ts• L754-832
Hopper integration
Hopper provides native analysis through a private bridge session. REA resolves loader arguments and Mach-O image selection before startup, fingerprints the selected launcher, and keeps the selected document and bridge run tied to one provider profile. The adapter preserves upstream reply contracts and distinguishes a busy, exited, unreachable, or authorization-blocked provider so recovery does not become an unsafe retry.
References: src/…/HopperAnalysisProfile.ts• L68-215 src/…/HopperClient.ts• L177-211 src/…/HopperClient.ts• L558-685 src/…/HopperErrors.ts• L104-187 src/…/HopperErrors.ts• L319-461
Cutter integration
Cutter provides commands against a live local document. REA discovers only authenticated bridges in a private descriptor directory, checks that the bridge source and request ceiling match the running release, and binds each command to the observed document generation. A command with unknown completion is retained as a partial observation and blocks new work until the bridge confirms its terminal receipt.
JSON-mode replies preserve large integer literals as strings when JavaScript cannot represent them exactly. Cutter output therefore keeps the provider's numeric meaning without claiming that a partial or malformed reply is complete.
References: src/…/CutterBridgeClient.ts• L392-507 src/…/CutterBridgeClient.ts• L510-671 src/…/CutterBridgeClient.ts• L1063-1262 src/…/CutterBridgeService.ts• L61-146 src/…/cutterCommandResponse.ts• L9-74
Debugger sessions
Debugger sessions add live target control to static investigation. REA owns the debugger process, serializes commands, bounds retained output, and records whether command completion and target state are known. GDB and Rizin are persistent Linux sessions because their safety boundary depends on Linux process and descriptor checks.
The common lifecycle is:
- Start the owned debugger and establish its output route.
- Verify the selected inferior terminal and live process identity.
- Send one serialized command through a bounded output channel.
- Return output with completion, truncation, decoding, and side-effect limits.
- Verify inferior disposition and process cleanup before close.
An unrestricted debugger command may access the local shell, files, network, and target controls. If output correlation, target disposition, or cleanup cannot be proved, REA retains the session and asks for recovery. The session target remains the file selected at startup. Later commands do not silently rebind it.
GDB sessions
GDB uses its machine interface to correlate command records with their requests. Startup launches a private GDB process, tries MI3 before MI2 when needed, disables automatic loading, identifies the reported GDB version, and publishes readiness only after it confirms the selected executable and any caller-selected inferior TTY. On supported Linux hosts, REA checks the live inferior's output descriptors through /proc before it treats that TTY as a durable output sink.
Each session records the initially selected file and its identity. Later unrestricted console commands do not silently replace that session target or establish the identity of the current inferior. Console commands run in order and return bounded MI records, console output, completion state, decoding facts, and truncation limits. The MI parser keeps protocol structure and byte-valued C strings explicit. If GDB returns to its prompt without a safe result boundary, REA uses a separate read-only MI query to confirm command-loop return. It does not guess the original result.
Close first obtains a complete recursive inferior list. It refuses automatic close when several inferiors remain or when one live inferior has no verified durable TTY. The caller must explicitly detach or terminate those inferiors. Protocol loss, command timeout, invalid result framing, or incomplete owned-process cleanup leaves partial Evidence and retains the session for recovery.
References: src/…/GdbMiRecord.ts• L4-17 src/…/GdbMiRecord.ts• L75-125 src/…/GdbProviderIdentity.ts• L3-39 src/…/GdbSessionManager.ts• L548-669 src/…/GdbSessionManager.ts• L1146-1331 src/…/GdbSessionManager.ts• L1402-1533
Rizin sessions
Rizin uses bounded NUL-delimited output frames and an explicit completion marker. REA serializes commands and rejects unsolicited or late frames because they can no longer be assigned to the correct command. A truncated frame, lost marker, invalid text, or overfull queued-frame budget makes the command and target state uncertain.
Before detach, REA checks the inferior inventory, process identity, output descriptors, input separation, and exit policy. It returns a durable target-state result only when the selected inferior is detached or its verified end is known. Cleanup can first synchronize a stopped session with a fresh private marker, but it still repeats the inventory and identity checks.
References: src/…/RizinDebugSessionManager.ts• L789-986 src/…/RizinDebugSessionManager.ts• L1452-1684 src/…/RizinDebugSessionManager.ts• L1802-1949
See Debugger and disassembler integrations for product-specific debugger, disassembler, and bridge coverage.
Toolchain workflows
An investigation can move from broad discovery to focused static analysis and then to live confirmation. Each stage uses the product that fits the question while Evidence keeps the source and uncertainty attached.
Typical paths include:
- Use objdump or Rizin for a quick raw view when exact product text is useful.
- Use Ghidra, Hopper, Kuna, or IDA for procedures, references, instructions, and decompiler views.
- Use JEB for managed-code units and decompilation.
- Use GDB or Rizin when a static question needs live state or behavior.
- Use Cutter when the investigation already lives in its local UI document.
- Feed linked observations into call-path, changed-behavior, static/runtime-correlation, or reconstruction-verification workflows.
The next step depends on the question and the provider's declared coverage. A partial or unknown result should lead to a targeted probe. It should not trigger an automatic provider switch or a stronger claim.
This diagram shows how direct observations become linked investigation results.
flowchart LR
A[Provider observation] --> B[Evidence]
B --> C[Evidence links]
C --> D[Derived workflow]
D --> E[Inference with limits]
References: src/…/GhidraProviderClient.ts• L1036-1212 src/…/GdbSessionManager.ts• L1202-1255 src/…/RizinDebugSessionManager.ts• L960-987
Change checklist
When these files or sections are changed, remember to consider these:
- Keep provider capability declarations aligned with target admission, profile resolution, and CLI and MCP operation contracts.
- Keep provider and profile identity aligned with Evidence and session handshake checks.
- Keep Ghidra release admission aligned with Java bounds, native decompiler checks, launcher arguments, and the bridge's reported provider version.
- Keep Ghidra target lanes aligned with installation admission, profile resolution, seeds, extensions, checkpoints, load-image attestation, and live client admission.
- Keep Ghidra existing-project and checkpoint rules aligned with target format, host, language, and analysis settings.
- Keep Ghidra request and reply limits aligned across configuration, wire admission, bridge behavior, cleanup, and error projection.
- Keep IDA registration, protocol selection, compatibility profiles, live tool catalogs, workspace admission, database identity, and target identity checks aligned.
- Keep IDA universal Mach-O support aligned with the connection mode that can prove the selected slice.
- Keep Hopper loader selection, launcher fingerprint, private bridge identity, reply contracts, provider health, and cleanup rules aligned.
- Keep Cutter descriptor security, bridge source identity, request ceilings, document generation, completion receipts, exact JSON output, and cleanup recovery aligned.
- Keep GDB startup target hashing, MI dialect fallback, provider version identity, automatic-loading policy, inferior TTY checks, command framing, output limits, inferior disposition, and cleanup recovery aligned.
- Keep Rizin frame limits, completion markers, command serialization, target identity checks, inferior disposition, cleanup synchronization, and cleanup recovery aligned.
- Keep child-page boundaries aligned: Ghidra-specific behavior belongs in Ghidra integration, while debugger, disassembler, and bridge detail belongs in Debugger and disassembler integrations.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A target or host falls outside a provider boundary | The requested capability is unavailable | Check readiness, target support, and profile before startup |
| A Ghidra release, Java runtime, native decompiler, or profile differs from the admitted context | The session is refused before trusted analysis continues | Inspect the installation and compare the live handshake with the committed profile |
| A Ghidra seed, extension, target snapshot, or special-format load fact changes | The session or load-image result cannot prove which input was analyzed | Snapshot and digest the input, then fail closed on changed identity or mismatched outcome |
| A selected existing Ghidra project changes after admission | The private session is refused because its analysis history no longer matches the profile | Fingerprint the selected project and verify the private copy before opening it |
| A Ghidra request or reply exceeds the admitted bridge limit | The request or result is refused or returned as partial | Admit the limit at the session boundary and preserve the exact resource constraint |
| IDA registration uses the removed legacy protocol, omits a required mode, or has no usable private workspace | IDA is unavailable and REA does not guess a protocol or create an unsafe workspace | Validate registration, protocol, workspace, and live capability profile before binding the client |
| An attached IDA connection cannot prove a universal Mach-O slice | The target remains unsupported in that mode | Use a thin input or a mode that establishes slice identity |
| Hopper launcher, host, document, prepared image, bridge reply, or authorization admission fails | Hopper cannot create a trusted analysis client | Preserve the provider state and select a valid target or recovery action instead of repeating an unsafe request |
| Cutter bridge source or request ceiling differs from the packaged REA context | No command is sent to the bridge | Authenticate the bridge and compare source and limits before dispatch |
| A Cutter command has an invalid reply, changed document generation, or unknown completion | The command effect and active document state are uncertain | Preserve partial Evidence and require an exact completion receipt before new commands |
| GDB output loses MI framing, contains invalid result bytes, or exceeds a command deadline | Command completion and target state become uncertain | Preserve partial records, stop unsafe correlation, and retain the session when cleanup is incomplete |
| GDB close finds multiple live inferiors or no verified output sink | Automatic close refuses to choose an inferior disposition | Explicitly detach or terminate each inferior, then retry close_gdb_session |
| Rizin emits unsolicited frames, a truncated frame, or no completion marker | Later output cannot be assigned safely to a command | Stop the session, synchronize only during cleanup, and require fresh inferior verification |
| Debugger process cleanup is unverified | A live target or owned process may remain | Retain the session and require cleanup recovery |
| A JEB endpoint refuses a request or omits a required payload | The operation returns a typed engine or protocol failure | Preserve the upstream response and do not infer recovery |
Key files
| File | Why to read it |
|---|---|
| src/…/GhidraProvider.ts | Shows Ghidra readiness, target admission, profile binding, and client creation. |
| src/…/GhidraInstallation.ts | Shows installation, release, Java, and native-tool readiness. |
| src/…/GhidraAnalysisProfile.ts | Shows how target interpretation and analysis policy become a bound Ghidra profile. |
| src/…/GhidraProviderClient.ts | Shows how Ghidra replies, load-image checks, and limitations become investigation observations. |
| src/…/GhidraClient.ts | Shows the private authenticated session, request queue, target snapshot, and checkpoint lifetime. |
| src/…/IdaProvider.ts | Shows IDA registration, compatibility profiles, target support, and exact client binding. |
| src/…/IdaConfiguration.test.ts | Shows registration protocol boundaries and refusal of the removed legacy mode. |
| src/…/IdaDoctor.test.ts | Shows setup-time workspace checks without starting IDA or exposing credentials. |
| src/…/HopperAnalysisProfile.ts | Shows Hopper target and loader admission before bridge startup. |
| src/…/HopperClient.ts | Shows the Hopper bridge lifetime, request contract, health state, and cleanup boundary. |
| src/…/HopperErrors.ts | Shows how Hopper launch, protocol, timeout, and provider-state failures guide recovery. |
| src/…/CutterBridgeClient.ts | Shows Cutter discovery, authenticated commands, generation checks, bounded replies, and completion receipts. |
| src/…/CutterBridgeService.ts | Shows how Cutter command output becomes Evidence and retained cleanup. |
| src/…/GdbMiRecord.ts | Shows the structured MI and stream record boundary used for GDB correlation. |
| src/…/GdbSessionManager.ts | Shows persistent GDB admission, MI command correlation, bounded output, inferior handling, and close recovery. |
| src/…/RizinDebugSessionManager.ts | Shows Rizin framing, command completion, inferior verification, and cleanup synchronization. |