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:
- Select a provider when opening the binary.
- Let the provider resolve its target support and analysis profile.
- Ask common analysis tools for focused facts or a function dossier.
- 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:
- Discover or start the external tool.
- Bind requests to a session, target, or document identity.
- 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.
| Adapter | MCP tools or surface | Main use |
|---|---|---|
| IDA | Common binary-analysis tools after open_binary with provider ida | Procedure, string, assembly, pseudocode, and relationship inspection |
| Hopper | Common binary-analysis tools after open_binary with provider hopper | Static analysis, navigation, references, and selected annotations |
| Kuna | Common binary-analysis tools after open_binary with provider kuna | Static analysis from a caller-supplied executable |
| Cutter | list_cutter_sessions, cutter_command | Commands in a live Cutter document |
| GDB | start_gdb_session, gdb_console, gdb_session_status, close_gdb_session | Persistent GDB debugging |
| Rizin debugger | start_rizin_debug_session, rizin_debug_command, rizin_debug_session_status, close_rizin_debug_session | Persistent Rizin debugging |
| Static tools | inspect_with_objdump, execute_rizin_command | One-shot artifact inspection |
| JEB | inspect_jeb_client, open_jeb_project, list_jeb_units, decompile_jeb_item | Project, 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,
/mcppath, 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
| Trigger | Consequence | Guard |
|---|---|---|
| IDA registration is invalid or native protocol is used in headless mode | The provider is unavailable before analysis starts | Validate the registration and keep native protocol attached-only |
| IDA headless workspace is missing or not usable | Readiness rejects the provider before it connects to IDA | Check the private workspace parent without creating a workspace or launching IDA |
| IDA diagnostic contains configured credentials or malformed JSON | Error output can leak secrets or misidentify encoded values | Bound the source and redact credential forms in text, URLs, and JSON |
| IDA returns truncated, malformed, wrong-target, or incomplete native data | No complete observation is established | Require 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 marker | The relationship read fails or keeps callee coverage unknown | Validate the root and lookup batch, and require the producer's coverage marker |
| IDA headless input or worker binding changes | Results may describe a different input or worker | Use a private verified copy and require the expected active worker |
| IDA worker release or connection close is unverified | The private workspace or upstream work remains owned | Retain the cleanup owner and retry only after release is proven |
| Hopper target profile selects an unsupported format, architecture, or unresolved Mach-O container | Hopper does not open the target through a verified loader path | Use a supported target or select the directed Ghidra profile |
| Hopper loader arguments are overridden | Derived function coordinates are not claimed | Record the configured loader source and omit derived coordinate context |
| Hopper saved-database launch is requested on macOS | The bridge cannot be started for the saved document | Open an executable target or use a supported host and launch route |
| Hopper source changes while an executable or thin Mach-O image is prepared | The temporary image may no longer represent the admitted file | Verify the source digest, selected header, and container table before launch |
| Hopper bridge ceiling differs from the client ceiling | Startup or later requests fail at the bridge boundary | Pass the admitted ceiling into bootstrap and reject mismatched health data |
| Hopper loses its authenticated bridge or external process | Requests fail and provider health stays failed | Retry only after the bridge and owned resources are verified |
| Hopper request expires or is cancelled while its wire reply is still active | A later request could receive the old reply | Keep the active request on the wire until its reply is consumed |
| Hopper bridge emits malformed JSON, invalid UTF-8, or an unknown response ID | The bridge protocol fails and the response cannot be trusted | Validate each response and event against the strict message contract |
| Hopper document shutdown or external application exit is not confirmed | The document, prepared image, or runtime files remain owned | Reconnect for authenticated cleanup and retain each unverified resource |
| Hopper caller scan reaches a time, page, retention, or inventory-change limit | Observed relationships remain useful but coverage is unknown | Return scan facts and partial native evidence instead of claiming exhaustive callers |
| Hopper startup or analysis failure loses its provider state | The caller may retry while the provider is still busy or unreachable | Preserve stage, provider state, request facts, and retry action in the error projection |
| Hopper private display helper emits no single valid diagnostic | Linux launch readiness is unknown or fails without a trusted cause | Require one bounded, schema-valid private-display diagnostic record |
| Cutter plugin digest is missing or differs from the packaged plugin | The session source is unknown or modified and recovery is required | Compare the published SHA-256 with the packaged plugin before sending commands |
| Cutter packaged plugin cannot be read | Source identity cannot be checked and no command is sent | Report the broken installation and reinstall the packaged plugin |
| Cutter peer proof, document generation, request proof, or bridge size ceiling is invalid | Discovery or command execution is rejected | Re-discover the session and require authenticated identity and matching limits |
| Cutter response omits execution state or returns malformed output after dispatch | Command completion is unknown and a retry could duplicate effects | Require explicit terminal state and retain the request until an exact receipt or watermark confirms it |
| Cutter JSON output contains an unsafe integer | JavaScript number conversion could change the observed value | Preserve unsafe integer literals as decimal strings in command output |
| Cutter response frame exceeds its admitted limit or is malformed | The response cannot be trusted and the command may have completed | Bound 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 bounds | The record cannot be correlated or safely exposed as structured output | Parse complete records with strict framing, byte validation, and a bounded nesting depth |
| GDB or Rizin lacks a verified durable output terminal | Close cannot safely detach a live inferior | Start with a caller-selected Linux terminal and check status before close |
| A GDB console command can change inferior output routing | The verified detach proof becomes stale and close cannot safely detach a live inferior | Preserve the proof only for exact read-only TTY inspections; revoke it for other commands |
| GDB reports multiple inferiors or an unverified live inferior at close | Automatic close refuses to choose a target disposition | Use gdb_console to detach or terminate each remaining inferior, then retry close_gdb_session |
| GDB MI records exceed the retention cap or cannot be framed | Output is partial and command completion is unknown | Keep the records as partial Evidence and retain the cleanup owner |
| Rizin output times out, exceeds a frame limit, or loses correlation | Completion is unknown and the session may be stopped or retained | Treat partial output as partial Evidence and retry cleanup before reuse |
| Rizin receives unsolicited frames before a command or after correlation is lost | Later output cannot be safely attributed to a command | Fail the protocol and stop the owned session before reuse |
| Rizin cleanup reuses old frames or cannot verify the inferior's identity or output route | Detach state is unknown and the target cannot be safely released | Synchronize with a fresh marker and read back current inferiors, process identity, and descriptors |
| A debugger or command tool changes the active artifact | The active binary-analysis session is retired | Wait for external work to settle, then call open_binary again |
JEB endpoint is not loopback /mcp, or the client is unreachable | JEB is rejected or reported unavailable | Use the default local endpoint or configure a running local JEB MCP client |
| JEB catalog or tool call reaches the shared deadline | The result is unavailable and the client or transport is invalidated | Respect the configured deadline and retry connection cleanup before reuse |
| JEB engine metadata fails after a primary reply | The operation cannot be fully assembled | Preserve the primary observation as partial and report the metadata failure |
| JEB reports JVM heap or native-thread exhaustion | The engine refuses the operation and may remain resource constrained | Report the engine's exhaustion area and apply recovery guidance to the user's JEB JVM |
Key files
| File | Why to read it |
|---|---|
| src/…/AnalysisProvider.ts | Defines the shared provider and analysis result boundary |
| src/…/IdaConfiguration.ts | Shows IDA registration modes, endpoint limits, and request deadlines |
| src/…/IdaDoctor.ts | Shows non-invasive IDA readiness checks |
| src/…/IdaInput.ts | Shows the operation input boundary for IDA queries |
| src/…/IdaProvider.ts | Shows IDA availability, target admission, profile binding, and owned-resource cleanup |
| src/…/IdaCallGraph.ts | Shows processor-neutral callee coverage and upstream graph limits |
| src/…/IdaOperationRunner.ts | Shows IDA containment, pagination, disassembly, decompilation, and relationship mapping |
| src/…/IdaMcpConnection.ts | Shows MCP transport, result decoding, diagnostics, and cleanup |
| src/…/IdaSessionClient.ts | Shows target checks, readiness, observations, and worker cleanup |
| src/…/BridgeLauncher.ts | Shows Hopper launch modes, bridge bootstrap, image preparation, and process ownership |
| src/…/HopperClient.ts | Shows Hopper startup sharing, bridge requests, health, and cleanup ownership |
| src/…/HopperAnalysisProfile.ts | Shows Hopper loader selection, launcher identity, and profile commitments |
| src/…/HopperErrors.ts | Shows Hopper failure stages, provider health, and caller retry guidance |
| src/…/HopperProvider.ts | Shows Hopper host and target support, launch, bridge use, and result mapping |
| src/…/HopperMachOImage.ts | Shows Mach-O slice admission and verified thin-image preparation |
| src/…/HopperFileOffset.ts | Shows mapping from Hopper image offsets to verified source coordinates |
| src/…/HopperImageCopy.ts | Shows digest-checked executable copies and retained file cleanup |
| src/…/HopperCleanup.ts | Shows authenticated document shutdown and retained resources |
| src/…/HopperResponseStream.ts | Shows incremental bridge framing and response identity checks |
| src/…/protocol.ts | Defines the Hopper response, error, progress, and diagnostic contract |
| src/…/CutterBridgeSource.ts | Shows how REA identifies the packaged or modified Cutter plugin |
| src/…/CutterBridgeService.ts | Shows Cutter command validation, Evidence projection, and completion-gated cleanup |
| src/…/CutterBridgeClient.ts | Shows Cutter discovery, authentication, request limits, and completion proof |
| src/…/cutterCommandResponse.ts | Shows exact handling of unsafe JSON integers in Cutter output |
| src/…/cutterAuthenticatedResponse.ts | Shows bounded authenticated Cutter response framing |
| src/…/GdbMiRecord.ts | Defines the typed GDB machine-interface record parser |
| src/…/GdbProviderIdentity.ts | Defines the GDB provider identity, version, and observation authority |
| src/…/GdbSessionManager.ts | Shows owned GDB sessions, MI records, limits, inferior cleanup, and TTY proof handling |
| src/…/RizinDebuggerProviderIdentity.ts | Defines the Rizin debugger identity |
| src/…/RizinDebugSessionManager.ts | Shows Rizin startup, sessions, output correlation, limits, and detach checks |
| src/…/RizinCommand.ts | Shows the one-shot Rizin command boundary and its unverified input limits |
| src/…/RizinProviderIdentity.ts | Defines the static Rizin command identity |
| src/…/jebMcpEndpoint.ts | Shows the JEB endpoint boundary and loopback rules |
| src/…/JebMcpDeadline.ts | Shows the shared JEB discovery and call deadline contract |
| src/…/JebProvider.ts | Shows JEB availability, project, unit, decompiler, and engine-resource handling |
| src/…/JebMcpConnection.ts | Shows JEB catalog discovery, session reuse, deadlines, and calls |
| src/…/JebMcpConnectionOwner.ts | Shows ownership and retryable cleanup for JEB client resources |
| src/…/createServer.ts | Shows adapter construction, registration, and shutdown |
| src/…/registerCutterTools.ts | Shows the Cutter MCP group |
| src/…/registerGdbTools.ts | Shows the GDB MCP group |
| src/…/registerRizinDebugTools.ts | Shows the Rizin debugger MCP group |
| src/…/registerJebTools.ts | Shows the JEB MCP group |