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 / debugger-and-disassembler-integrations

Debugger and disassembler integrations

REA connects external reverse-engineering tools to one investigation surface. Disassembler adapters provide static views of a binary. Debugger and command adapters provide controlled access to live tool sessions or one-shot inspection. Each adapter keeps tool identity, observed output, and limits of that output visible. This page is a child of Reverse-engineering toolchains and relates to Ghidra integration.

Integration model

An adapter is the boundary between REA and one external tool. A bridge is a process or plugin service that carries requests into a tool that REA cannot call directly. The server keeps these boundaries separate from the normal binary session and closes resources that it owns during shutdown.

Analysis providers attach one tool view to one binary session. Debugger sessions use their own session IDs. Command tools may change the active artifact, so their output does not automatically keep provider-backed analysis valid.

This diagram shows how a caller-selected tool produces an observation for the investigation session.

flowchart LR
    A[Caller selects tool] --> B{Tool boundary}
    B --> C[Analysis provider]
    B --> D[Owned debugger process]
    B --> E[Live GUI bridge]
    C --> F[Analysis result]
    D --> G[Command output]
    E --> G
    F --> H[Investigation session]
    G --> H

Tool availability means that REA can reach the configured boundary. It does not mean that the external product has analyzed every target or that REA can safely stop a live target.

Provider-backed analysis

Provider-backed analysis binds one binary session to one external analysis view. IDA and Hopper support common questions about procedures, strings, assembly, pseudocode, and relationships. Kuna supplies a related static view. The selected provider records its profile and limits with each result, so an unsupported or incomplete view is not mistaken for empty data. Hopper can add caller and reference observations from a bounded forward scan when its native relationship view is not enough.

IDA admits x86, x86-64, ARM, and ARM64 executable inputs. It refuses non-executable targets, raw binaries, GameCube DOL files, and architecture lanes without a verified path. Universal Mach-O support depends on the selected mode: headless mode can prepare a private slice, while attached mode cannot prove which slice the open GUI database uses. Unsupported targets are directed to Ghidra integration.

IDA readiness reports configuration and private-workspace admission without starting the upstream service. The resolved registration still determines the compatibility profile used to expose capabilities and bind a client to the selected target and profile. The adapter keeps provider availability separate from target support, so a configured IDA service can still refuse a particular input.

Hopper resolves a target profile before its client starts. The profile records the selected loader path, launcher identity, target kind, and Mach-O slice when a slice was prepared. A configured loader override replaces the derived loader choice, so the profile does not claim a function-coordinate mapping that depends on the derived loader. Hopper declines raw binaries and unverified architecture lanes rather than guessing a loader.

The normal sequence is:

  1. Select a provider when opening the binary.
  2. Let the provider resolve its target support and analysis profile.
  3. Ask common analysis tools for focused facts or a function dossier.
  4. Reopen the binary after an external command may have changed the target or analysis state.

References: src/…/AnalysisProvider.ts• L35-62 src/…/IdaProvider.ts• L61-77 src/…/IdaProvider.ts• L195-267 src/…/IdaProvider.ts• L268-349 src/…/IdaProvider.ts• L351-385 src/…/IdaCallGraph.ts• L16-52 src/…/IdaOperationRunner.ts• L273-333 src/…/HopperProvider.ts• L116-245 src/…/HopperAnalysisProfile.ts• L68-215 src/…/HopperAnalysisProfile.ts• L242-309 src/…/registerSessionTools.ts• L307-325

Independent debugger sessions

GDB and Rizin debugger sessions are separate from the active binary-analysis session. REA starts each debugger process, gives the inferior a caller-selected output terminal, and uses a session ID for later commands and status checks. Closing a session closes the REA-owned process, but it does not by itself prove that the debugged program stopped.

Debugger commands are unrestricted. They can change target state or access local system resources. REA therefore returns raw output with a completion state and keeps the active analysis session separate when a command may have changed the target. Session admission also limits the number of sessions, queued commands, and retained output so a debugger cannot consume unbounded REA resources.

GDB close first inspects its recursive inferior list. One live inferior can be detached only when its output route and process identity are proven. Multiple inferiors or an unverified route require the caller to choose an explicit disposition before close continues. Rizin uses a fresh completion marker and a new inferior readback during cleanup. It never reuses old frames as proof that a target detached.

GDB startup records the initially selected executable as the session subject and publishes a session only after its machine-interface checks complete. It can retry with the supported older machine-interface dialect when the first startup failure is safe to retry. The provider identity is gnu.gdb, and observations from the REA-run session use controlled replay as their authority. Later unrestricted console commands do not rebind that initial subject or establish the current inferior's identity.

GDB machine-interface records are parsed as typed result or stream records. Result records preserve tokens, result classes, and nested values. Stream records keep console, target, and log output separate. C-string values retain their encoded bytes until valid UTF-8 text is requested. The parser rejects malformed framing, invalid strings, and excessive nesting before those records enter session output.

References: src/…/GdbMiRecord.ts• L4-17 src/…/GdbMiRecord.ts• L25-53 src/…/GdbMiRecord.ts• L72-137 src/…/GdbMiRecord.ts• L160-220 src/…/GdbMiRecord.ts• L223-341 src/…/GdbProviderIdentity.ts• L3-39 src/…/GdbSessionManager.ts• L548-669 src/…/GdbSessionManager.ts• L1146-1323 src/…/GdbSessionManager.ts• L1334-1375 src/…/GdbSessionManager.ts• L1402-1533 src/…/RizinDebugSessionManager.ts• L315-362 src/…/RizinDebugSessionManager.ts• L398-728 src/…/RizinDebugSessionManager.ts• L789-889 src/…/RizinDebugSessionManager.ts• L1233-1258 src/…/RizinDebugSessionManager.ts• L1452-1538 src/…/registerGdbTools.ts• L28-153 src/…/registerRizinDebugTools.ts• L22-133

Disassembler adapters

The disassembler adapters use different ownership models. IDA connects to a caller-supplied MCP service. Hopper uses a REA-managed client and bridge. Cutter connects to a live GUI plugin. Kuna runs a caller-supplied command and builds a local analysis view. These models determine how REA selects a target and what identity it can prove.

IDA adapter

The IDA adapter speaks to an existing IDA MCP service in attached or headless mode. Attached mode reads the open GUI database. Headless mode asks the upstream service to analyze a private copy of the executable. REA does not install, launch, or license IDA.

An IDA registration may use a local command or a local HTTP endpoint. A command registration gives REA an owned stdio transport. An HTTP registration uses the configured streamable endpoint. The native protocol is attached-only. The modern compatibility profile is the headless database-supervisor profile. REA reads the registration before startup and uses the selected mode to resolve target support and capabilities. Authentication values remain available to the connection but are excluded from provider identity.

Readiness checks validate the registration and, for headless mode, the private workspace before any live IDA connection. The doctor check does not launch IDA and does not create workspace entries while it checks the selected parent. Diagnostic text is bounded and removes configured transport credentials from plain text, URLs, and JSON-shaped replies. HTTP error bodies are reduced to supported media types before they enter diagnostics.

IDA exposes read-only analysis such as procedure and string search, assembly, pseudocode, cross-references, and selected relationship queries. The headless profile also supports containing-procedure lookup. The adapter accepts complete producer results, checks the target before and after an operation, and keeps raw upstream observations beside the normalized result. Legacy attached mode can expose direct caller queries. Modern and native profiles do not claim direct call edges from code references. On non-x86 modern targets, the adapter uses the upstream call graph for function edges, but computed call sites and unrecognized callees remain unknown. A missing proof remains unavailable rather than inferred.

The adapter admits supported executable lanes and rejects inputs that cannot be bound to the selected IDA profile. A universal Mach-O input is supported in headless mode because REA can prepare the selected slice privately. Attached mode cannot prove which slice the GUI opened, so it requires a thin input. GameCube DOL and other declined architecture and format lanes are directed to Ghidra integration.

IDA input checks also enforce operation-specific boundaries before startup. For example, cross-reference queries require an explicit hexadecimal address and regex searches require a valid expression. Native results must include complete JSON text, while modern and legacy results must provide one supported structured or text value. REA releases only the headless worker and private workspace that it can prove it owns. If upstream release or connection cleanup is not confirmed, the workspace and cleanup owner remain available for retry.

References: src/…/IdaConfiguration.ts• L22-138 src/…/IdaConfiguration.ts• L138-219 src/…/IdaDoctor.ts• L17-99 src/…/IdaProvider.ts• L195-267 src/…/IdaProvider.ts• L268-385 src/…/IdaProvider.ts• L395-437 src/…/IdaCallGraph.ts• L78-187 src/…/IdaMcpConnection.ts• L66-103 src/…/IdaMcpConnection.ts• L120-188 src/…/IdaMcpConnection.ts• L201-247 src/…/IdaMcpConnection.ts• L411-645 src/…/IdaMcpConnection.ts• L655-823 src/…/IdaOperationRunner.ts• L273-333 src/…/IdaOperationRunner.ts• L492-616 src/…/IdaSessionClient.ts• L668-759 src/…/IdaSessionClient.ts• L769-856 src/…/IdaConfiguration.test.ts• L33-108 src/…/IdaDoctor.test.ts• L14-40

Hopper adapter

The Hopper adapter starts or reaches Hopper for the selected target and connects to REA's Python bridge. The bridge binds requests to one Hopper document and keeps Hopper API work in its supported runtime. REA maps Hopper observations into the common analysis operations.

Hopper supports executable and saved-database lanes only where the selected launcher can provide the bridge. On macOS, the current launcher cannot start the bridge for a saved database, so that lane is unavailable. Executables must use a supported format and architecture. Hopper declines raw binaries, DOS inputs, GameCube DOL, and architecture lanes without a verified loader path. These targets are directed to Ghidra instead of being opened through an uncertain loader.

The analysis profile records a fingerprint of the selected Hopper launcher. It also records the loader arguments and any prepared Mach-O image. Derived loader arguments can establish a function-coordinate context. A configured loader override is kept as caller input and does not create that derived coordinate claim. This keeps later observations tied to the loader choice that actually opened the target.

Hopper relationships use a live result policy because the GUI can change the document without a revision token. Caller and incoming-reference operations may reconcile the native reply with a bounded scan of Hopper's procedure inventory. The scan keeps observed callers and call sites while marking coverage unknown when time, page size, retained data, cancellation, or inventory changes stop the scan.

The client shares one startup attempt among callers, but each caller keeps its own wait and cancellation. Startup admits the request and reply ceilings before it acquires resources. The authenticated health reply must agree with the request ceiling and identify the expected bridge process. These checks bind later requests and cleanup to the same run. Provider health distinguishes startup, active analysis, connection loss, and an exited or unreachable provider, so retry guidance can tell the caller whether to wait, retry, or restart.

The bridge uses an authenticated, line-based message contract. Responses carry either a JSON result or a typed remote error. Progress and diagnostic events are tied to a request ID. The response stream validates UTF-8 and each complete message, and it rejects malformed messages or response IDs that cannot belong to the current request set. A request queue serializes wire use, removes work that expires before transmission, and keeps an active wire request reserved until a late reply is consumed. This prevents a timed-out or cancelled reply from being assigned to a later request. The launcher passes the agreed request ceiling into the bridge before the bridge starts, so both ends reject inconsistent message sizes.

For an executable, REA records the source identity and the launcher identity before launch. A Mach-O container is checked for a unique admitted slice. When a private thin image is needed, REA copies it and verifies the source digest, selected header, and container table before Hopper uses it. File-offset results are mapped back to the original executable only when the source and loaded image identify the same slice.

The client authenticates each private bridge session and sends requests through a serial boundary. A cancelled wait does not make an active Hopper request safe to reuse. Close first tries an authenticated document shutdown, then releases the bridge and owned processes in order. If the document, external Hopper application, prepared image, runtime directory, or launcher lease is not proven released, REA retains that resource for a later cleanup retry. Mutating Hopper operations and live analysis observations are not safe for snapshot replay. Hopper errors preserve whether the failure came from launch, connection, analysis, authorization, or a remote request, and they expose provider health and retry guidance to the caller.

References: src/…/HopperProvider.ts• L72-114 src/…/HopperProvider.ts• L116-245 src/…/HopperProvider.ts• L267-374 src/…/HopperAnalysisProfile.ts• L68-215 src/…/HopperAnalysisProfile.ts• L218-309 src/…/BridgeLauncher.ts• L118-143 src/…/BridgeLauncher.ts• L280-357 src/…/BridgeLauncher.ts• L665-690 src/…/HopperClient.ts• L127-230 src/…/HopperClient.ts• L360-449 src/…/HopperClient.ts• L635-733 src/…/HopperClient.ts• L849-1041 src/…/HopperClient.ts• L1240-1335 src/…/HopperErrors.ts• L28-102 src/…/HopperErrors.ts• L233-307 src/…/HopperErrors.ts• L309-463 src/…/HopperFileOffset.ts• L62-147 src/…/HopperImageCopy.ts• L23-54 src/…/HopperMachOImage.ts• L88-126 src/…/HopperMachOImage.ts• L441-525 src/…/HopperCleanup.ts• L43-141 src/…/HopperResponseStream.ts• L14-49 src/…/protocol.ts• L11-119 src/…/HopperErrorProjection.test.ts• L34-153

Cutter adapter

The Cutter adapter connects to a live Cutter instance with the REA Python plugin loaded. Cutter provides a Rizin command path for the active document. A session descriptor and document generation keep a tab switch or reload from being mistaken for the same document.

The shared Cutter bridge service validates command input, discovers live sessions, and turns command results into Evidence. It first retries any earlier command cleanup. A command whose completion is unknown remains pending until the bridge returns an exact terminal receipt, so the service does not send a later command into an uncertain UI state.

Discovery also classifies the running plugin by its published SHA-256. A matching digest identifies the packaged REA plugin. A missing digest leaves the source unknown, while another digest marks the plugin as modified. REA gives a recovery action instead of treating an unverified plugin as the packaged one. If the packaged plugin cannot be read, it reports the installation failure and sends no Cutter command.

Discovery reads private descriptors and proves the live peer with an authenticated challenge. Each command carries a second proof and the expected document generation. Request and response sizes use the same admitted ceiling. The response decoder bounds the complete authenticated frame while it handles socket chunks, so a large or malformed frame cannot grow without limit.

Cutter command replies now state whether execution was not started, completed, failed, or unknown. A successful transport reply does not prove completion when the bridge omits that state. JSON-mode command output preserves unsafe integer values as decimal strings instead of rounding them in JavaScript. If a response is malformed or missing after dispatch, REA returns unknown execution and blocks a new command until an exact receipt or connection watermark confirms completion.

References: src/…/CutterBridgeSource.ts• L8-66 src/…/CutterBridgeService.ts• L45-146 src/…/CutterBridgeService.ts• L148-240 src/…/CutterBridgeClient.ts• L251-275 src/…/CutterBridgeClient.ts• L392-507 src/…/CutterBridgeClient.ts• L510-687 src/…/CutterBridgeClient.ts• L690-755 src/…/CutterBridgeClient.ts• L805-985 src/…/CutterBridgeClient.ts• L987-1181 src/…/CutterBridgeClient.ts• L1200-1262 src/…/cutterCommandResponse.ts• L9-75 src/…/cutterAuthenticatedResponse.ts• L43-83

Kuna adapter

Kuna is a caller-supplied static analysis provider for executable ELF and thin Mach-O images on Linux and macOS. It answers procedure, string, pseudocode, assembly, call relationship, and reference questions without a GUI. REA does not download, install, or update the Kuna executable.

The provider checks the configured executable identity before it commits an analysis profile and again during each run. It can cache a whole-program export for later reads while keeping single-function pseudocode available during export. Results state which source produced the answer and retain the limits of Kuna's static view. Inferred procedure entries and relationship results do not prove that an absent item does not exist.

References: src/…/KunaProvider.ts• L44-169 src/…/KunaInstallation.ts• L351-617 src/…/KunaProjectCache.ts• L219-235 src/…/KunaSessionClient.ts• L225-233 src/…/KunaProviderCapabilities.ts• L35-60

Debugger and command adapters

The command adapters support persistent debugging and one-shot inspection. GDB and Rizin keep a process session for several commands. GNU objdump and stand-alone Rizin inspect an artifact without a provider session. JEB uses a caller-started analysis client for project and decompiler work.

GDB sessions

The GDB adapter starts GDB in machine-interface mode and exposes start, console, status, and close operations. A session returns debugger records together with console, target, and log output. Persistent sessions are available on Linux because REA verifies the inferior's output terminal and process identity before it detaches an inferior during close. Startup reserves session capacity and can use the supported MI version fallback before publishing the session.

GDB observations identify the GNU GDB provider and the executable admitted at startup. The session authority is controlled replay: later console commands can change live target state, but they do not change the subject recorded for the session. This keeps the observation subject stable while still exposing the unrestricted console's effects.

REA does not infer target ownership from a process ID or path. If it cannot verify a durable output terminal or the disposition of a live inferior, close requires explicit caller action. Read-only inferior-TTY inspections preserve the verified output-sink proof. Commands that can alter output routing revoke that proof. Startup is published only after the MI protocol and required terminal checks are ready. A failed stop keeps the session and cleanup owner for a later retry.

GDB command turns are serialized with bounded queue admission. A caller cancellation removes its wait result but does not let the queued turn bypass an earlier command. MI result and stream records are parsed from complete lines, with nested tuples and lists preserved as typed values and C-string escapes decoded to bytes. If records exceed the output cap or cannot be framed, the adapter returns partial output with unknown completion instead of treating it as a finished command. The status view exposes recent MI records and transport diagnostics so the caller can distinguish a closed session from a complete command result.

References: src/…/GdbMiRecord.ts• L4-17 src/…/GdbMiRecord.ts• L25-53 src/…/GdbMiRecord.ts• L72-137 src/…/GdbMiRecord.ts• L160-220 src/…/GdbMiRecord.ts• L223-341 src/…/GdbProviderIdentity.ts• L3-39 src/…/GdbSessionManager.ts• L548-669 src/…/GdbSessionManager.ts• L866-1139 src/…/GdbSessionManager.ts• L1146-1323 src/…/GdbSessionManager.ts• L1334-1375 src/…/GdbSessionManager.ts• L1402-1533 src/…/GdbSessionManager.ts• L1587-1629 src/…/registerGdbTools.ts• L42-153

Rizin debugger sessions

The Rizin debugger adapter starts a persistent Rizin process with NUL-framed output and an optional debugger backend. It requires a caller-selected Linux terminal for inferior input and output. Before a live inferior can outlive Rizin, REA verifies the terminal route and the debugger setting that controls inferior lifetime.

Each command ends with a private completion marker. Output can contain interleaved session and backend frames, so the result states that scope. A timeout, oversized frame, invalid protocol sequence, or lost correlation makes completion unknown. REA returns partial Evidence when it can and stops or retains the owned session according to what cleanup proves. Before each command, Rizin's known inferior inventory is cleared because unrestricted debugger commands can create or replace inferiors. A session also limits its command queue and retained output.

Rizin close reports an unknown target state unless the owned process and inferior disposition are proven. Cleanup can synchronize with a fresh marker, then read the current inferior inventory and verify process identity, output routing, isolated inferior input, and detach state. It never reuses old frames as inferior readback. Unsolicited frames, late output, or a failed marker stop the session from being reused.

References: src/…/RizinDebuggerProviderIdentity.ts• L1-6 src/…/RizinDebugSessionManager.ts• L315-362 src/…/RizinDebugSessionManager.ts• L398-728 src/…/RizinDebugSessionManager.ts• L789-889 src/…/RizinDebugSessionManager.ts• L1019-1127 src/…/RizinDebugSessionManager.ts• L1203-1271 src/…/RizinDebugSessionManager.ts• L1288-1449 src/…/RizinDebugSessionManager.ts• L1452-1669 src/…/registerRizinDebugTools.ts• L35-133

Static command tools

GNU objdump and stand-alone Rizin provide raw inspection without a persistent provider session. Objdump covers common binary metadata and disassembly views. Stand-alone Rizin runs one caller-selected command with user startup settings and scripts suppressed while installed plugins remain available. Both return bounded output as Evidence. The Rizin command boundary retains the resolved input path while keeping the static tool identity separate from the Rizin debugger identity.

When a stand-alone Rizin call supplies architecture, bitness, CPU, or a base address, REA records the request but does not prove that Rizin applied it. A base-address call uses a raw map and skips format loaders, so sections, symbols, and entry points are not established by that call. These commands can still affect the active investigation context. A command that mutates the bound artifact or leaves work running retires the active analysis session. The caller must reopen the binary after the external work settles.

References: src/…/registerReverseEngineeringTools.ts• L23-44 src/…/RizinCommand.ts• L1-40 src/…/RizinProviderIdentity.ts• L1-6 docs/reverse-engineering-tools.md• L15-26 docs/reverse-engineering-tools.md• L42-58

JEB client

The JEB adapter uses a caller-started JEB client that serves MCP over a local streamable HTTP endpoint. It does not install or launch JEB. The adapter inspects the client, opens or creates a project when supported, lists project units, and requests decompilation for a code item. Availability reflects the tools advertised by the live client rather than a fixed catalog.

The endpoint uses HTTP or HTTPS on literal loopback and the /mcp route. It does not accept URL credentials, query strings, or fragments. The connection discovers the live tool catalog, shares one client and transport across callers, and applies one selected deadline to catalog work and each tool call. Discovery pages the catalog under that deadline. A failed connection invalidates and closes its owner before another one can use it. Diagnostics retain the caller-selected endpoint spelling.

JEB resolves and analyzes the artifact on the engine host. Project responses include input-file digests and top-level units, which lets Evidence describe what the remote engine opened. A full unit page can still mean that more units exist. A decompile request without a unit path can use the project's first code unit, so the effective unit is then unknown. If the engine reply completes but client metadata cannot be read, JEB keeps the primary observation as partial rather than discarding it. Engine refusal details remain the engine's result. REA does not infer a recovery action from an unknown vendor response. JEB resource failures can also identify a JVM memory or native-thread exhaustion report and return recovery guidance for the user's engine process.

References: src/…/jebMcpEndpoint.ts• L6-63 src/…/JebMcpDeadline.ts• L13-101 src/…/JebMcpConnection.ts• L24-73 src/…/JebMcpConnection.ts• L186-356 src/…/JebProvider.ts• L121-157 src/…/JebProvider.ts• L206-321 src/…/JebProvider.ts• L324-407 src/…/JebProvider.ts• L434-581 src/…/JebProvider.test.ts• L217-352 src/…/JebProvider.test.ts• L752-936

Bridge processes

Bridge processes keep tool-specific APIs outside the main REA request path while preserving a narrow request and result boundary. Hopper's bridge runs inside Hopper's runtime. Cutter's plugin runs inside Cutter and exposes an authenticated loopback service. IDA and JEB use external MCP boundaries. GDB and Rizin use owned process boundaries rather than a shared GUI bridge.

The bridge lifecycle has three parts:

  1. Discover or start the external tool.
  2. Bind requests to a session, target, or document identity.
  3. Confirm completion and release resources that REA owns.

Authentication and completion proof matter most for GUI bridges. Cutter proves both peers, checks the plugin source when the running plugin publishes a digest, and retains completion receipts. Hopper binds the bridge to the selected document, authenticates the socket, validates response framing and IDs, serializes requests, and records process health. IDA and JEB retain their client, worker, transport, or workspace owner when upstream cleanup is not proven. GDB and Rizin retain debugger ownership when process or inferior state is not proven. An adapter fails closed when it cannot tell which document, target, or request produced the result.

References: src/…/CutterBridgeSource.ts• L28-66 src/…/CutterBridgeService.ts• L61-146 src/…/CutterBridgeClient.ts• L987-1181 src/…/cutterAuthenticatedResponse.ts• L48-83 src/…/BridgeLauncher.ts• L181-203 src/…/HopperClient.ts• L175-230 bridge/hopper_bridge.py• L145-214 src/…/IdaMcpConnection.ts• L66-89 src/…/IdaSessionClient.ts• L858-1044 src/…/JebMcpConnection.ts• L130-164 src/…/GdbSessionManager.ts• L535-576 src/…/RizinDebugSessionManager.ts• L193-240

Registered tools

The server registers these adapter groups beside the common analysis and session tools. A group may expose a persistent MCP session, a common provider surface, or a one-shot command.

AdapterMCP tools or surfaceMain use
IDACommon binary-analysis tools after open_binary with provider idaProcedure, string, assembly, pseudocode, and relationship inspection
HopperCommon binary-analysis tools after open_binary with provider hopperStatic analysis, navigation, references, and selected annotations
KunaCommon binary-analysis tools after open_binary with provider kunaStatic analysis from a caller-supplied executable
Cutterlist_cutter_sessions, cutter_commandCommands in a live Cutter document
GDBstart_gdb_session, gdb_console, gdb_session_status, close_gdb_sessionPersistent GDB debugging
Rizin debuggerstart_rizin_debug_session, rizin_debug_command, rizin_debug_session_status, close_rizin_debug_sessionPersistent Rizin debugging
Static toolsinspect_with_objdump, execute_rizin_commandOne-shot artifact inspection
JEBinspect_jeb_client, open_jeb_project, list_jeb_units, decompile_jeb_itemProject, unit, and decompiler inspection

The composition root creates the debugger managers, GUI bridge service, and external analysis providers. It registers them on the same MCP server and closes their owned resources during shutdown.

References: src/…/createServer.ts• L540-577 src/…/createServer.ts• L580-636 src/…/createServer.ts• L717-740 src/…/createServer.ts• L751-781 src/…/registerCutterTools.ts• L15-69 src/…/registerGdbTools.ts• L28-153 src/…/registerRizinDebugTools.ts• L22-133 src/…/registerJebTools.ts• L10-49

Session effects and Evidence

Every adapter reports what it observed and what it could not prove. Evidence keeps the producing provider, operation parameters, result, raw output where needed, and limitations together. This prevents output from a changed GUI, stale target, or unfinished debugger command from looking like a complete fact.

External command tools are not read-only substitutes for provider-backed analysis. Cutter commands, debugger commands, stand-alone Rizin commands, and some close operations can retire the active binary-analysis session. After the external work settles, the caller must call open_binary again before using provider-backed analysis.

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep provider capability lists aligned with provider selection and the common analysis operation contract.
  • Keep bridge authentication, document or target identity, completion receipts, and cleanup retry behavior aligned.
  • Keep MCP schemas, tool registration, and matching CLI inputs aligned for each adapter.
  • Preserve the distinction between returned output and proven command completion.
  • When process ownership or terminal checks change, review close behavior, shutdown, and retained cleanup diagnostics together.
  • When a provider changes its target identity rules, update Evidence subjects and limitation claims with the new proof boundary.
  • When a provider changes startup sharing or deadline ownership, preserve per-caller failure attribution and the exact cleanup owner.
  • When a cache key or external executable identity changes, review profile identity, reuse, eviction, and stale-result checks together.
  • When an IDA registration or Hopper image rule changes, review readiness, profile commitment, private-copy identity, and client binding together.
  • When a bridge request ceiling changes, update both sides of the bridge and keep discovery, framing, and response limits consistent.
  • When an IDA credential or diagnostic rule changes, review profile identity, redaction, bounded error text, JSON and URL diagnostics, and transport failure causes together.
  • When IDA relationship or containment rules change, review processor selection, advertised upstream tools, producer completeness, address identity, and coverage claims together.
  • When Hopper image preparation changes, review ordinary executable copies, Mach-O slice selection, file-offset mapping, document shutdown, and cleanup ownership together.
  • When Hopper relationship reconciliation changes, review scan budgets, work-scope reuse, compact evidence, coverage limits, and live cache policy together.
  • When Hopper response framing changes, review UTF-8 decoding, request IDs, late replies, protocol aborts, and retry eligibility together.
  • When debugger output limits change, review partial-result meaning, completion status, protocol shutdown, and retained cleanup ownership together.
  • When GDB or Rizin inferior discovery changes, review terminal proof, process identity, detach behavior, and the rule that arbitrary commands invalidate known inferior state together.
  • When GDB MI parsing changes, review token correlation, result and stream record classes, nested-value bounds, byte decoding, and partial completion reporting together.
  • When GDB command classification changes, keep exact read-only inferior-TTY inspections from revoking the verified output-sink proof while preserving fail-closed behavior for compound or mutating commands.
  • When the Cutter plugin source check changes, review packaged-file availability, published digest states, recovery text, and the rule that an unverified source cannot be treated as packaged.
  • When Cutter execution-state or JSON number handling changes, review response parsing, Evidence limitations, completion acknowledgement, and retry blocking together.
  • When the JEB endpoint parser changes, keep the default loopback route, /mcp path, and provider remediation text aligned.
  • When JEB live tool discovery or its shared deadline changes, keep supported-operation reporting, dispatch checks, partial observations, timeout guidance, and client cleanup aligned.

Important failure modes

TriggerConsequenceGuard
IDA registration is invalid or native protocol is used in headless modeThe provider is unavailable before analysis startsValidate the registration and keep native protocol attached-only
IDA headless workspace is missing or not usableReadiness rejects the provider before it connects to IDACheck the private workspace parent without creating a workspace or launching IDA
IDA diagnostic contains configured credentials or malformed JSONError output can leak secrets or misidentify encoded valuesBound the source and redact credential forms in text, URLs, and JSON
IDA returns truncated, malformed, wrong-target, or incomplete native dataNo complete observation is establishedRequire complete producer content and check target identity around each operation
IDA call-graph results lack a valid root, contain inconsistent lookup rows, or omit a required truncation markerThe relationship read fails or keeps callee coverage unknownValidate the root and lookup batch, and require the producer's coverage marker
IDA headless input or worker binding changesResults may describe a different input or workerUse a private verified copy and require the expected active worker
IDA worker release or connection close is unverifiedThe private workspace or upstream work remains ownedRetain the cleanup owner and retry only after release is proven
Hopper target profile selects an unsupported format, architecture, or unresolved Mach-O containerHopper does not open the target through a verified loader pathUse a supported target or select the directed Ghidra profile
Hopper loader arguments are overriddenDerived function coordinates are not claimedRecord the configured loader source and omit derived coordinate context
Hopper saved-database launch is requested on macOSThe bridge cannot be started for the saved documentOpen an executable target or use a supported host and launch route
Hopper source changes while an executable or thin Mach-O image is preparedThe temporary image may no longer represent the admitted fileVerify the source digest, selected header, and container table before launch
Hopper bridge ceiling differs from the client ceilingStartup or later requests fail at the bridge boundaryPass the admitted ceiling into bootstrap and reject mismatched health data
Hopper loses its authenticated bridge or external processRequests fail and provider health stays failedRetry only after the bridge and owned resources are verified
Hopper request expires or is cancelled while its wire reply is still activeA later request could receive the old replyKeep the active request on the wire until its reply is consumed
Hopper bridge emits malformed JSON, invalid UTF-8, or an unknown response IDThe bridge protocol fails and the response cannot be trustedValidate each response and event against the strict message contract
Hopper document shutdown or external application exit is not confirmedThe document, prepared image, or runtime files remain ownedReconnect for authenticated cleanup and retain each unverified resource
Hopper caller scan reaches a time, page, retention, or inventory-change limitObserved relationships remain useful but coverage is unknownReturn scan facts and partial native evidence instead of claiming exhaustive callers
Hopper startup or analysis failure loses its provider stateThe caller may retry while the provider is still busy or unreachablePreserve stage, provider state, request facts, and retry action in the error projection
Hopper private display helper emits no single valid diagnosticLinux launch readiness is unknown or fails without a trusted causeRequire one bounded, schema-valid private-display diagnostic record
Cutter plugin digest is missing or differs from the packaged pluginThe session source is unknown or modified and recovery is requiredCompare the published SHA-256 with the packaged plugin before sending commands
Cutter packaged plugin cannot be readSource identity cannot be checked and no command is sentReport the broken installation and reinstall the packaged plugin
Cutter peer proof, document generation, request proof, or bridge size ceiling is invalidDiscovery or command execution is rejectedRe-discover the session and require authenticated identity and matching limits
Cutter response omits execution state or returns malformed output after dispatchCommand completion is unknown and a retry could duplicate effectsRequire explicit terminal state and retain the request until an exact receipt or watermark confirms it
Cutter JSON output contains an unsafe integerJavaScript number conversion could change the observed valuePreserve unsafe integer literals as decimal strings in command output
Cutter response frame exceeds its admitted limit or is malformedThe response cannot be trusted and the command may have completedBound frame decoding and report unknown execution when a sent request lacks a valid reply
GDB MI input is malformed, has invalid string data, or exceeds nesting boundsThe record cannot be correlated or safely exposed as structured outputParse complete records with strict framing, byte validation, and a bounded nesting depth
GDB or Rizin lacks a verified durable output terminalClose cannot safely detach a live inferiorStart with a caller-selected Linux terminal and check status before close
A GDB console command can change inferior output routingThe verified detach proof becomes stale and close cannot safely detach a live inferiorPreserve the proof only for exact read-only TTY inspections; revoke it for other commands
GDB reports multiple inferiors or an unverified live inferior at closeAutomatic close refuses to choose a target dispositionUse gdb_console to detach or terminate each remaining inferior, then retry close_gdb_session
GDB MI records exceed the retention cap or cannot be framedOutput is partial and command completion is unknownKeep the records as partial Evidence and retain the cleanup owner
Rizin output times out, exceeds a frame limit, or loses correlationCompletion is unknown and the session may be stopped or retainedTreat partial output as partial Evidence and retry cleanup before reuse
Rizin receives unsolicited frames before a command or after correlation is lostLater output cannot be safely attributed to a commandFail the protocol and stop the owned session before reuse
Rizin cleanup reuses old frames or cannot verify the inferior's identity or output routeDetach state is unknown and the target cannot be safely releasedSynchronize with a fresh marker and read back current inferiors, process identity, and descriptors
A debugger or command tool changes the active artifactThe active binary-analysis session is retiredWait for external work to settle, then call open_binary again
JEB endpoint is not loopback /mcp, or the client is unreachableJEB is rejected or reported unavailableUse the default local endpoint or configure a running local JEB MCP client
JEB catalog or tool call reaches the shared deadlineThe result is unavailable and the client or transport is invalidatedRespect the configured deadline and retry connection cleanup before reuse
JEB engine metadata fails after a primary replyThe operation cannot be fully assembledPreserve the primary observation as partial and report the metadata failure
JEB reports JVM heap or native-thread exhaustionThe engine refuses the operation and may remain resource constrainedReport the engine's exhaustion area and apply recovery guidance to the user's JEB JVM

Key files

FileWhy to read it
src/…/AnalysisProvider.tsDefines the shared provider and analysis result boundary
src/…/IdaConfiguration.tsShows IDA registration modes, endpoint limits, and request deadlines
src/…/IdaDoctor.tsShows non-invasive IDA readiness checks
src/…/IdaInput.tsShows the operation input boundary for IDA queries
src/…/IdaProvider.tsShows IDA availability, target admission, profile binding, and owned-resource cleanup
src/…/IdaCallGraph.tsShows processor-neutral callee coverage and upstream graph limits
src/…/IdaOperationRunner.tsShows IDA containment, pagination, disassembly, decompilation, and relationship mapping
src/…/IdaMcpConnection.tsShows MCP transport, result decoding, diagnostics, and cleanup
src/…/IdaSessionClient.tsShows target checks, readiness, observations, and worker cleanup
src/…/BridgeLauncher.tsShows Hopper launch modes, bridge bootstrap, image preparation, and process ownership
src/…/HopperClient.tsShows Hopper startup sharing, bridge requests, health, and cleanup ownership
src/…/HopperAnalysisProfile.tsShows Hopper loader selection, launcher identity, and profile commitments
src/…/HopperErrors.tsShows Hopper failure stages, provider health, and caller retry guidance
src/…/HopperProvider.tsShows Hopper host and target support, launch, bridge use, and result mapping
src/…/HopperMachOImage.tsShows Mach-O slice admission and verified thin-image preparation
src/…/HopperFileOffset.tsShows mapping from Hopper image offsets to verified source coordinates
src/…/HopperImageCopy.tsShows digest-checked executable copies and retained file cleanup
src/…/HopperCleanup.tsShows authenticated document shutdown and retained resources
src/…/HopperResponseStream.tsShows incremental bridge framing and response identity checks
src/…/protocol.tsDefines the Hopper response, error, progress, and diagnostic contract
src/…/CutterBridgeSource.tsShows how REA identifies the packaged or modified Cutter plugin
src/…/CutterBridgeService.tsShows Cutter command validation, Evidence projection, and completion-gated cleanup
src/…/CutterBridgeClient.tsShows Cutter discovery, authentication, request limits, and completion proof
src/…/cutterCommandResponse.tsShows exact handling of unsafe JSON integers in Cutter output
src/…/cutterAuthenticatedResponse.tsShows bounded authenticated Cutter response framing
src/…/GdbMiRecord.tsDefines the typed GDB machine-interface record parser
src/…/GdbProviderIdentity.tsDefines the GDB provider identity, version, and observation authority
src/…/GdbSessionManager.tsShows owned GDB sessions, MI records, limits, inferior cleanup, and TTY proof handling
src/…/RizinDebuggerProviderIdentity.tsDefines the Rizin debugger identity
src/…/RizinDebugSessionManager.tsShows Rizin startup, sessions, output correlation, limits, and detach checks
src/…/RizinCommand.tsShows the one-shot Rizin command boundary and its unverified input limits
src/…/RizinProviderIdentity.tsDefines the static Rizin command identity
src/…/jebMcpEndpoint.tsShows the JEB endpoint boundary and loopback rules
src/…/JebMcpDeadline.tsShows the shared JEB discovery and call deadline contract
src/…/JebProvider.tsShows JEB availability, project, unit, decompiler, and engine-resource handling
src/…/JebMcpConnection.tsShows JEB catalog discovery, session reuse, deadlines, and calls
src/…/JebMcpConnectionOwner.tsShows ownership and retryable cleanup for JEB client resources
src/…/createServer.tsShows adapter construction, registration, and shutdown
src/…/registerCutterTools.tsShows the Cutter MCP group
src/…/registerGdbTools.tsShows the GDB MCP group
src/…/registerRizinDebugTools.tsShows the Rizin debugger MCP group
src/…/registerJebTools.tsShows the JEB MCP group