feat(ida): support the official Hex-Rays IDA MCP headlessly (#4813)

* feat(ida): support the official Hex-Rays IDA MCP headlessly

Hex-Rays IDA MCP serves database reads only through execute_python, so
REA rejected it as an upstream. A `hexrays` headless stdio registration
now leases a private idalib worker through open_database, answers the
existing database-supervisor reads with a fixed, packaged, read-only
query module, and releases the lease with close_database, verified by
list_databases.

Observations record execute_python, the query and the module digest.
Tool errors are typed so a completed rejection is distinguished from an
unknown outcome; an unconfirmed release is retried and a late lease on
the private input is adopted.

Validated IDA source and bridge tests, static checks, docs, and npm run
verify:ida on Linux x64 against x86-64 and AArch64 ELF fixtures.

* feat(ida): name the Hex-Rays registration for its catalog

A registration without `protocol` that reaches the official Hex-Rays
server failed with only the missing database-supervisor tools. Startup
profile failures now report the advertised catalog, and when it is the
Hex-Rays one the message and recovery name the `hexrays` registration.

Refs #1416

* docs(ida): state Hex-Rays prerequisites and upstream session traces

Upstream needs IDA 9.4 or later with idalib, Python 3.11 or later, uv
and Git. The profile does not analyze databases open in the IDA GUI, and
the server keeps its own session traces outside REA's workspace.

Refs #1416

* fix(ida): skip inline data when scanning Hex-Rays calls

The call scan decoded every head that FuncItems yields. Inline data such
as a jump table can decode as a call and refer to a function or import,
which reported false callees and call-graph edges. Skip non-code heads
before decoding, as disassembly already does.

Refs #1416

* fix(ida): retain Hex-Rays health reads in evidence

The identity and readiness reads around each operation kept only their
parsed result, dropping the bridge digest and any engine output. Keep
them whole as health_observations beside the parsed metadata, in both
successful and partial-failure Evidence.

Refs #1416

* test(ida): list the Hex-Rays bridge in package fixtures

The packed-bridge verifier has required bridge/ida/hexrays_queries.py
since the Hex-Rays profile landed, but three package tests still built
their member lists without it. The verifier stopped at that file, so 21
cases failed or asserted on the wrong omission.

Refs #1416

* feat(ida): open existing IDA databases through the Hex-Rays profile

A headless open re-ran auto-analysis from the input binary, discarding
the names, types and comments of an existing database and taking far
longer on large targets. Target admission now identifies IDA databases
by their IDA1/IDA2 signature, and the hexrays profile opens a private
copy of one; Hopper and the other IDA profiles reject them.

The copy is required, not incidental: idalib repacks a database when
its last lease is released, even without a save. A database reports
the input it was created from, so the session is bound to the opened
copy's idb_path, and health now reports the input SHA-256 it records.

Validated with resolver, provider and session tests, check:fast,
docs:check and test:changed, plus a real Hex-Rays MCP run against a
1.4 GB SC2 .i64 whose original file was left byte-identical.

Refs #1416

* fix(ida): verify the private workspace of a database target by idb_path

* test(ida): fix Hex-Rays health stand-ins and Windows path and runtime teardown

* refactor(ida): resolve the registration once for target support

* docs(ida): record the real Hex-Rays run on an existing .i64

* docs(ida): make the Hex-Rays registration example install-neutral

* chore: keep merge-hook formatting outside the IDA change

* fix(ida): retain live Hex-Rays databases this server does not lease

A list_databases row with instance_id null is a live owner, not a stopped
database. Mapping it to the supervisor's released-worker shape made cleanup
delete files another client still held. Unleased rows stay active, so the
private path must leave inventory before the workspace is removed.

Accept idat inventory rows, hash the query bridge with sha256Hex, and
complete databaseEngine on Hopper fixtures added on main.

* fix(ida): report uncapped Hex-Rays call graphs

* docs(ida): link to the Hex-Rays bridge on GitHub

* fix(ida): verify Hex-Rays worker identity and cleanup

* feat(ida): support Hex-Rays idat headless workers

Refs #12921

* fix(ida): retain workspace after ambiguous Hex-Rays startup

* fix(ida): preserve typed Hex-Rays call edges and deadlines

* test(ida): verify Hex-Rays cleanup with a peer lease

* test(ci): use project deadlines for the Cutter verifier

* test(ida): keep verifier cleanup fixtures scoped to mocked modules

* fix(ida): retain the worker backend in partial evidence

---------

Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <morluto@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-11-20 17:58:27 -05:00
1 parent 339b6b5750
commit 6822ebe1f3
42 files changed
+2627 -194

No files matched your search

@@ -474,7 +474,10 @@ explicit path or endpoint and do not need it.
availability and leaves target support unknown.
For an existing IDA MCP configuration, use `open_binary` with the original
input binary and `provider_id: "ida"`; do not pass an `.idb` or `.i64` database.
input binary and `provider_id: "ida"`. Only the Hex-Rays (`hexrays`) profile
also admits an existing `.idb` or `.i64`: pass the database path to start from
its saved annotations instead of a fresh auto-analysis. REA analyzes a private
copy and never writes the selected database.
The native attached profile binds the already-open GUI input by SHA-256 and
leaves its database open. The modern headless profile creates and closes an
owned private database without saving; it reuses
@@ -474,7 +474,10 @@ explicit path or endpoint and do not need it.
availability and leaves target support unknown.
For an existing IDA MCP configuration, use `open_binary` with the original
input binary and `provider_id: "ida"`; do not pass an `.idb` or `.i64` database.
input binary and `provider_id: "ida"`. Only the Hex-Rays (`hexrays`) profile
also admits an existing `.idb` or `.i64`: pass the database path to start from
its saved annotations instead of a fresh auto-analysis. REA analyzes a private
copy and never writes the selected database.
The native attached profile binds the already-open GUI input by SHA-256 and
leaves its database open. The modern headless profile creates and closes an
owned private database without saving; it reuses
+336
View File
@@ -0,0 +1,336 @@
"""Read-only REA queries for the Hex-Rays IDA MCP's execute_python tool.
REA sends this module followed by one `_rea_query(tool, arguments_json)`
expression. Each query answers in the database-supervisor reply shape that
REA's headless IDA profile already validates, so the TypeScript adapter owns
interpretation while this module only observes the database. Nothing here
renames, retypes, patches, saves, or navigates.
Addresses cross the boundary as hexadecimal strings: REA decodes JSON numbers
as doubles, which cannot represent every 64-bit address exactly.
"""
import json
import re
import ida_auto
import ida_funcs
import ida_hexrays
import ida_idaapi
import ida_idp
import ida_lines
import ida_loader
import ida_nalt
import ida_name
import ida_segment
import ida_typeinf
import ida_ua
import ida_xref
import idautils
import idc
_BADADDR = ida_idaapi.BADADDR
_HEX_ADDRESS = re.compile(r"^0x[0-9a-f]+$", re.IGNORECASE)
# Paged reads rebuild their snapshot at offset 0, so one enumeration observes
# one consistent list. REA finishes each enumeration before starting another,
# so the lease retains only the most recent snapshot.
_rea_pages = globals().setdefault("_rea_pages", {})
def _hex(ea):
return f"0x{ea:x}"
def _function(f):
name = ida_funcs.get_func_name(f.start_ea) or f"sub_{f.start_ea:X}"
return {"addr": _hex(f.start_ea), "name": name, "size": _hex(f.size())}
def _address(text):
return int(text, 16) if _HEX_ADDRESS.match(text) else None
def _entry(text):
"""The function whose entry is exactly `text`, or None."""
ea = _address(text)
f = None if ea is None else ida_funcs.get_func(ea)
return f if f is not None and f.start_ea == ea else None
def _snapshot(key, offset, build):
if offset == 0 or key not in _rea_pages:
_rea_pages.clear()
_rea_pages[key] = build()
return _rea_pages[key]
def _cursor(end, total):
return {"next": end} if end < total else {"done": True}
def health():
return {
"status": "ok",
"input_path": ida_nalt.get_input_file_path(),
"input_sha256": (ida_nalt.retrieve_input_file_sha256() or b"").hex() or None,
"idb_path": ida_loader.get_path(ida_loader.PATH_TYPE_IDB) or None,
"imagebase": _hex(ida_nalt.get_imagebase()),
"auto_analysis_ready": bool(ida_auto.auto_is_ok()),
"module": ida_nalt.get_root_filename() or "",
}
def list_funcs(queries):
offset, count = queries["offset"], queries["count"]
total = ida_funcs.get_func_qty()
end = min(offset + count, total)
data = [_function(ida_funcs.getn_func(i)) for i in range(offset, end)]
return [{"data": data, "next_offset": end if end < total else None}]
def _lookup(query):
ea = _address(query)
if ea is None:
ea = ida_name.get_name_ea(_BADADDR, query)
if ea == _BADADDR:
return {"query": query, "fn": None, "error": "Not found"}
f = ida_funcs.get_func(ea)
if f is None:
return {"query": query, "fn": None, "error": "Not a function"}
return {"query": query, "fn": _function(f), "error": None}
def lookup_funcs(queries):
return [_lookup(query) for query in queries]
def find_regex(pattern, offset, limit):
def build():
matcher = re.compile(pattern)
return [
{"addr": _hex(item.ea), "string": text}
for item in idautils.Strings()
if matcher.search(text := str(item))
]
matches = _snapshot(("strings", pattern), offset, build)
end = min(offset + limit, len(matches))
return {"matches": matches[offset:end], "cursor": _cursor(end, len(matches))}
def decompile(addr, offset, max_lines):
f = _entry(addr)
if f is None:
return {"code": None, "error": "Not a function", "cursor": {"done": True}}
def build():
if not ida_hexrays.init_hexrays_plugin():
return "Hex-Rays decompiler is unavailable for this database"
try:
cfunc = ida_hexrays.decompile(f.start_ea)
except ida_hexrays.DecompilationFailure as failure:
return str(failure) or "Decompilation failed"
if cfunc is None:
return "Decompilation failed"
return [ida_lines.tag_remove(line.line) for line in cfunc.get_pseudocode()]
lines = _snapshot(("decompile", f.start_ea), offset, build)
if isinstance(lines, str):
return {"code": None, "error": lines, "cursor": {"done": True}}
end = min(offset + max_lines, len(lines))
return {
"code": "\n".join(lines[offset:end]),
"cursor": _cursor(end, len(lines)),
"line_count": end - offset,
"total_lines": len(lines),
}
def _signature(ea):
tif = ida_typeinf.tinfo_t()
if not ida_nalt.get_tinfo(tif, ea) and (
ida_typeinf.guess_tinfo(tif, ea) != ida_typeinf.GUESS_FUNC_OK
):
return {}
details = ida_typeinf.func_type_data_t()
if not tif.get_func_details(details):
return {}
return {
"return_type": str(details.rettype),
"arguments": [
{"name": arg.name or f"a{index + 1}", "type": str(arg.type)}
for index, arg in enumerate(details)
],
}
def disasm(addr, offset, max_instructions):
f = _entry(addr)
if f is None:
return {"asm": None, "error": "Not a function", "cursor": {"done": True}}
heads = _snapshot(
("disasm", f.start_ea),
offset,
lambda: [ea for ea in idautils.FuncItems(f.start_ea) if idc.is_code(idc.get_full_flags(ea))],
)
end = min(offset + max_instructions, len(heads))
asm = {
"name": _function(f)["name"],
"start_ea": _hex(f.start_ea),
"lines": [
{
"addr": _hex(ea),
"instruction": ida_lines.generate_disasm_line(ea, ida_lines.GENDSM_REMOVE_TAGS),
}
for ea in heads[offset:end]
],
**(_signature(f.start_ea) if offset == 0 else {}),
}
return {"asm": asm, "cursor": _cursor(end, len(heads))}
def _imports():
found = {}
def record(ea, name, ordinal):
found[ea] = name or f"ord_{ordinal}"
return True
for index in range(ida_nalt.get_import_module_qty()):
ida_nalt.enum_import_names(index, record)
return found
def _call_instructions(f):
insn = ida_ua.insn_t()
for ea in idautils.FuncItems(f.start_ea):
# Inline data, such as a jump table, can decode as a call and refer to a function.
if not idc.is_code(idc.get_full_flags(ea)):
continue
if not ida_ua.decode_insn(insn, ea) or not ida_idp.is_call_insn(insn):
continue
yield ea
def _call_targets(f):
"""Code and pointer references from the x86 callee scan."""
for ea in _call_instructions(f):
yield from idautils.CodeRefsFrom(ea, False)
yield from idautils.DataRefsFrom(ea)
def _function_entry_targets(f):
targets = set()
for ea in _call_instructions(f):
for xref in idautils.XrefsFrom(ea, ida_xref.XREF_FAR):
# Data and jump references at a call site do not establish call edges.
if not xref.iscode or (xref.type & ida_xref.XREF_MASK) not in (
ida_xref.fl_CN, ida_xref.fl_CF
):
continue
callee = ida_funcs.get_func(xref.to)
if callee is not None and callee.start_ea == xref.to:
targets.add(xref.to)
return sorted(targets)
def callees(addrs, limit):
rows = []
for addr in addrs:
f = _entry(addr)
if f is None:
rows.append({"callees": None, "error": "Not a function"})
continue
imports = _imports()
found = {}
for to in _call_targets(f):
if to in found:
continue
callee = ida_funcs.get_func(to)
if callee is not None:
# REA resolves an interior target to its containing function.
found[to] = {"addr": _hex(to), "name": _function(callee)["name"], "type": "internal"}
else:
# Imports, pointer slots and code outside every function stay
# visible by address instead of being dropped.
name = imports.get(to) or ida_name.get_name(to) or _hex(to)
found[to] = {"addr": _hex(to), "name": name, "type": "external"}
items = [found[to] for to in sorted(found)]
rows.append({"callees": items[:limit], "more": len(items) > limit})
return rows
def callgraph(roots, max_depth):
if max_depth != 0:
raise ValueError("REA requests depth-zero call graphs only")
rows = []
for root in roots:
f = _entry(root)
if f is None:
rows.append({"root": root, "error": "Not a function", "nodes": [], "edges": []})
continue
targets = _function_entry_targets(f)
rows.append(
{
"root": _hex(f.start_ea),
"nodes": [{"addr": _hex(f.start_ea), "name": _function(f)["name"]}]
+ [{"addr": _hex(to), "name": ida_funcs.get_func_name(to) or None} for to in targets],
"edges": [{"from": _hex(f.start_ea), "to": _hex(to), "type": "call"} for to in targets],
"truncated": False,
"per_func_capped": False,
"limit_reason": None,
}
)
return rows
def xrefs_to(addrs, limit):
rows = []
for addr in addrs:
ea = _address(addr)
if ea is None:
rows.append({"xrefs": None, "error": "Invalid address"})
continue
seen = set()
items = []
# Ordinary flow from the previous instruction is not a reference.
for xref in idautils.XrefsTo(ea, ida_xref.XREF_FAR):
kind = "code" if xref.iscode else "data"
if (xref.frm, kind) in seen:
continue
seen.add((xref.frm, kind))
f = ida_funcs.get_func(xref.frm)
items.append({"addr": _hex(xref.frm), "type": kind, "fn": None if f is None else _function(f)})
if len(items) > limit:
break
rows.append({"xrefs": items[:limit], "more": len(items) > limit})
return rows
def survey_binary(detail_level):
if detail_level != "minimal":
raise ValueError("REA requests the minimal survey only")
segments = []
for index in range(ida_segment.get_segm_qty()):
seg = ida_segment.getnseg(index)
segments.append({"start": _hex(seg.start_ea), "end": _hex(seg.end_ea), "size": _hex(seg.size())})
return {"statistics": {"total_segments": len(segments)}, "segments": segments}
_REA_QUERIES = {
"server_health": health,
"list_funcs": list_funcs,
"lookup_funcs": lookup_funcs,
"find_regex": find_regex,
"decompile": decompile,
"disasm": disasm,
"callees": callees,
"callgraph": callgraph,
"xrefs_to": xrefs_to,
"survey_binary": survey_binary,
}
def _rea_query(tool, arguments):
return _REA_QUERIES[tool](**json.loads(arguments))
+289
View File
@@ -0,0 +1,289 @@
"""Source-owned tests for the Hex-Rays IDA MCP query bridge.
The bridge runs inside IDA through execute_python. These tests execute it the
same way, as a script in a fresh namespace, against a small stand-in database
so reply shapes, paging and call classification are checked without IDA.
"""
import json
import os
import sys
import types
import unittest
from unittest import mock
SOURCE = os.path.join(os.path.dirname(__file__), "hexrays_queries.py")
BADADDR = 0xFFFFFFFFFFFFFFFF
XREF_FAR = 1
class Func:
def __init__(self, start, end, name):
self.start_ea, self.end_ea, self.name = start, end, name
def size(self):
return self.end_ea - self.start_ea
class StringItem:
def __init__(self, ea, text):
self.ea, self.text = ea, text
def __str__(self):
return self.text
class Xref:
def __init__(self, frm, iscode, flow=False):
self.frm, self.iscode, self.flow = frm, iscode, flow
FUNCS = [Func(0x1000, 0x1018, "main"), Func(0x2000, 0x2008, "helper")]
# address -> (text, is_call, code targets, data targets)
INSNS = {
0x1000: ("push rbp", False, [], []),
0x1004: ("call helper+4", True, [0x2004], []),
0x1008: ("call cs:puts_ptr", True, [], [0x5000]),
0x100C: ("call loc_3000", True, [0x3000], []),
0x1010: ("call helper", True, [0x2000], []),
# Inline data whose bytes decode as a call and that refers to an import.
0x1014: ("dq offset exit", True, [], [0x5008]),
0x2000: ("mov eax, 1", False, [], []),
0x2004: ("retn", False, [], []),
}
DATA_HEADS = {0x1014}
IMPORTS = {0x5000: "puts", 0x5008: "exit"}
NAMES = {"main": 0x1000, "helper": 0x2000, "data_label": 0x4000}
XREFS = {0x2000: [Xref(0x1004, True), Xref(0x1ffc, True, flow=True), Xref(0x1004, True)]}
STRINGS = [(0x6000 + index, f"string {index}") for index in range(5)]
PSEUDOCODE = ["int main(void)", "{", " helper();", " return 0;", "}"]
def get_func(ea):
return next((f for f in FUNCS if f.start_ea <= ea < f.end_ea), None)
def stand_ins():
m = {name: types.ModuleType(name) for name in (
"ida_auto", "ida_funcs", "ida_hexrays", "ida_idaapi", "ida_idp", "ida_lines",
"ida_loader", "ida_nalt", "ida_name", "ida_segment", "ida_typeinf", "ida_ua",
"ida_xref", "idautils", "idc",
)}
m["ida_auto"].auto_is_ok = lambda: True
m["ida_idaapi"].BADADDR = BADADDR
m["ida_funcs"].get_func = get_func
m["ida_funcs"].get_func_name = lambda ea: next((f.name for f in FUNCS if f.start_ea == ea), "")
m["ida_funcs"].get_func_qty = lambda: len(FUNCS)
m["ida_funcs"].getn_func = lambda index: FUNCS[index]
class DecompilationFailure(Exception):
pass
class Line:
def __init__(self, line):
self.line = line
def decompile(ea):
if ea != 0x1000:
raise DecompilationFailure("decompilation failure at 0x2000")
return types.SimpleNamespace(get_pseudocode=lambda: [Line(text) for text in PSEUDOCODE])
m["ida_hexrays"].DecompilationFailure = DecompilationFailure
m["ida_hexrays"].init_hexrays_plugin = lambda: True
m["ida_hexrays"].decompile = decompile
m["ida_lines"].tag_remove = lambda text: text
m["ida_lines"].GENDSM_REMOVE_TAGS = 1
m["ida_lines"].generate_disasm_line = lambda ea, flags: INSNS[ea][0]
m["ida_loader"].PATH_TYPE_IDB = 1
m["ida_loader"].get_path = lambda kind: "/private/input.i64"
m["ida_nalt"].get_input_file_path = lambda: "/private/input"
m["ida_nalt"].retrieve_input_file_sha256 = lambda: bytes.fromhex("ab" * 32)
m["ida_nalt"].get_imagebase = lambda: 0x400000
m["ida_nalt"].get_root_filename = lambda: "input"
m["ida_nalt"].get_tinfo = lambda tif, ea: False
m["ida_nalt"].get_import_module_qty = lambda: 1
def enum_import_names(index, callback):
for ea, name in IMPORTS.items():
callback(ea, name, 0)
m["ida_nalt"].enum_import_names = enum_import_names
m["ida_name"].get_name_ea = lambda start, name: NAMES.get(name, BADADDR)
m["ida_name"].get_name = lambda ea: {0x3000: "loc_3000"}.get(ea, "")
segments = [types.SimpleNamespace(start_ea=0x1000, end_ea=0x3000, size=lambda: 0x2000)]
m["ida_segment"].get_segm_qty = lambda: len(segments)
m["ida_segment"].getnseg = lambda index: segments[index]
m["ida_typeinf"].tinfo_t = object
m["ida_typeinf"].GUESS_FUNC_OK = 1
m["ida_typeinf"].guess_tinfo = lambda tif, ea: 0
m["ida_typeinf"].func_type_data_t = object
m["ida_ua"].insn_t = lambda: types.SimpleNamespace(ea=None)
def decode_insn(insn, ea):
insn.ea = ea
return 4
m["ida_ua"].decode_insn = decode_insn
m["ida_idp"].is_call_insn = lambda insn: INSNS[insn.ea][1]
m["ida_xref"].XREF_FAR = XREF_FAR
m["idautils"].FuncItems = lambda start: [ea for ea in sorted(INSNS) if get_func(ea).start_ea == start]
m["idautils"].CodeRefsFrom = lambda ea, flow: list(INSNS[ea][2])
m["idautils"].DataRefsFrom = lambda ea: list(INSNS[ea][3])
m["ida_xref"].fl_CF = 16
m["ida_xref"].fl_CN = 17
m["ida_xref"].fl_JN = 19
m["ida_xref"].dr_O = 1
m["ida_xref"].XREF_MASK = 31
def xrefs_from(ea, flags=0):
_, _, code_refs, data_refs = INSNS[ea]
return [
types.SimpleNamespace(to=target, type=m["ida_xref"].fl_CN, iscode=True)
for target in code_refs
] + [
types.SimpleNamespace(to=target, type=m["ida_xref"].dr_O, iscode=False)
for target in data_refs
]
m["idautils"].XrefsFrom = xrefs_from
def xrefs_to(ea, flags=0):
return [x for x in XREFS.get(ea, []) if not (flags & XREF_FAR and x.flow)]
m["idautils"].XrefsTo = xrefs_to
m["idautils"].Strings = lambda: [StringItem(ea, text) for ea, text in STRINGS]
# Flags stand in for their address, so is_code can consult DATA_HEADS.
m["idc"].get_full_flags = lambda ea: ea
m["idc"].is_code = lambda flags: flags not in DATA_HEADS
return m
class BridgeTest(unittest.TestCase):
def setUp(self):
modules = stand_ins()
patcher = mock.patch.dict(sys.modules, modules)
patcher.start()
self.addCleanup(patcher.stop)
with open(SOURCE, encoding="utf-8") as source:
self.code = compile(source.read(), "<ida-mcp>", "exec")
self.namespace = {}
exec(self.code, self.namespace)
def query(self, tool, arguments):
# REA embeds JSON text in a Python string literal; json.dumps of a str
# produces the same escapes JSON.stringify does for these inputs.
line = f"_rea_query({json.dumps(tool)}, {json.dumps(json.dumps(arguments))})"
return eval(line, self.namespace)
def test_lookup_reports_entries_containment_and_missing_names(self):
rows = self.query("lookup_funcs", {"queries": ["main", "0x2004", "data_label", "absent", 'a"\\\n
']})
self.assertEqual(rows[0]["fn"], {"addr": "0x1000", "name": "main", "size": "0x18"})
self.assertEqual(rows[1]["fn"]["addr"], "0x2000")
self.assertEqual([row["error"] for row in rows[2:]], ["Not a function", "Not found", "Not found"])
self.assertEqual(rows[4]["query"], 'a"\\\n
')
def test_pages_advance_and_finish(self):
first = self.query("decompile", {"addr": "0x1000", "offset": 0, "max_lines": 3})
second = self.query("decompile", {"addr": "0x1000", "offset": 3, "max_lines": 3})
self.assertEqual(first["cursor"], {"next": 3})
self.assertEqual(second["cursor"], {"done": True})
self.assertEqual(first["code"] + "\n" + second["code"], "\n".join(PSEUDOCODE))
self.assertNotIn("error", first)
functions = self.query("list_funcs", {"queries": {"offset": 1, "count": 5}})
self.assertEqual(functions, [{"data": [{"addr": "0x2000", "name": "helper", "size": "0x8"}], "next_offset": None}])
strings = self.query("find_regex", {"pattern": "(?s).*", "offset": 0, "limit": 4})
self.assertEqual(strings["cursor"], {"next": 4})
rest = self.query("find_regex", {"pattern": "(?s).*", "offset": 4, "limit": 4})
self.assertEqual(rest, {"matches": [{"addr": "0x6004", "string": "string 4"}], "cursor": {"done": True}})
def test_snapshot_retains_only_the_latest_enumeration(self):
self.query("decompile", {"addr": "0x1000", "offset": 0, "max_lines": 1})
self.query("disasm", {"addr": "0x1000", "offset": 0, "max_instructions": 1})
self.assertEqual(list(self.namespace["_rea_pages"]), [("disasm", 0x1000)])
def test_failures_are_explicit_rows(self):
failed = self.query("decompile", {"addr": "0x2000", "offset": 0, "max_lines": 10})
self.assertEqual(failed, {"code": None, "error": "decompilation failure at 0x2000", "cursor": {"done": True}})
interior = self.query("disasm", {"addr": "0x1004", "offset": 0, "max_instructions": 10})
self.assertEqual(interior["asm"], None)
self.assertEqual(self.query("callees", {"addrs": ["0x1004"], "limit": 5}), [{"callees": None, "error": "Not a function"}])
def test_callees_keep_every_direct_target(self):
[row] = self.query("callees", {"addrs": ["0x1000"], "limit": 500})
self.assertEqual(
row,
{
"callees": [
{"addr": "0x2000", "name": "helper", "type": "internal"},
{"addr": "0x2004", "name": "helper", "type": "internal"},
{"addr": "0x3000", "name": "loc_3000", "type": "external"},
{"addr": "0x5000", "name": "puts", "type": "external"},
],
"more": False,
},
)
[capped] = self.query("callees", {"addrs": ["0x1000"], "limit": 1})
self.assertTrue(capped["more"])
self.assertEqual(len(capped["callees"]), 1)
def test_callgraph_reports_function_entries_only(self):
[row] = self.query("callgraph", {"roots": ["0x1000"], "max_depth": 0})
# Interior, non-function and import targets are not graph edges.
self.assertEqual(row["edges"], [{"from": "0x1000", "to": "0x2000", "type": "call"}])
FUNCS.extend([Func(0x4000, 0x4008, "referenced_data"), Func(0x4100, 0x4108, "jump_target")])
self.addCleanup(lambda: FUNCS.__delitem__(slice(-2, None)))
xrefs_from = sys.modules["idautils"].XrefsFrom
code_refs_from = sys.modules["idautils"].CodeRefsFrom
data_refs_from = sys.modules["idautils"].DataRefsFrom
sys.modules["idautils"].CodeRefsFrom = lambda ea, flow: (
code_refs_from(ea, flow) + ([0x4100] if ea == 0x1010 else [])
)
sys.modules["idautils"].DataRefsFrom = lambda ea: (
data_refs_from(ea) + ([0x4000] if ea == 0x1010 else [])
)
def mixed_xrefs(ea, flags):
refs = xrefs_from(ea, flags)
if ea == 0x1010:
refs.extend([
types.SimpleNamespace(to=0x4000, type=sys.modules["ida_xref"].dr_O, iscode=False),
types.SimpleNamespace(to=0x4100, type=sys.modules["ida_xref"].fl_JN, iscode=True),
])
return refs
sys.modules["idautils"].XrefsFrom = mixed_xrefs
[mixed] = self.query("callgraph", {"roots": ["0x1000"], "max_depth": 0})
self.assertEqual(mixed["edges"], row["edges"])
with self.assertRaises(ValueError):
self.query("callgraph", {"roots": ["0x1000"], "max_depth": 1})
def test_xrefs_exclude_ordinary_flow_and_duplicates(self):
[row] = self.query("xrefs_to", {"addrs": ["0x2000"], "limit": 1000})
self.assertEqual(
row,
{"xrefs": [{"addr": "0x1004", "type": "code", "fn": {"addr": "0x1000", "name": "main", "size": "0x18"}}], "more": False},
)
def test_health_and_survey_shapes(self):
self.assertEqual(
self.query("server_health", {}),
{
"status": "ok",
"input_path": "/private/input",
"input_sha256": "ab" * 32,
"idb_path": "/private/input.i64",
"imagebase": "0x400000",
"auto_analysis_ready": True,
"module": "input",
},
)
# A database that recorded no input hash reports none, not an empty digest.
sys.modules["ida_nalt"].retrieve_input_file_sha256 = lambda: None
self.assertIsNone(self.query("server_health", {})["input_sha256"])
survey = self.query("survey_binary", {"detail_level": "minimal"})
self.assertEqual(survey["segments"], [{"start": "0x1000", "end": "0x3000", "size": "0x2000"}])
self.assertEqual(survey["statistics"], {"total_segments": 1})
if __name__ == "__main__":
unittest.main()
+50 -7
View File
@@ -1,8 +1,8 @@
# IDA provider
REA adapts an existing IDA MCP server into its native analysis tools. Headless IDA Pro analysis uses the [mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp) database supervisor; analysis of a database already open in the IDA GUI uses the separate [ida-free-mcp native plugin](https://github.com/0xshlomil/ida-free-mcp) for IDA Pro and IDA Free. Install and configure your selected engine and upstream MCP using their instructions. REA does not install, upgrade, activate, or license them, and does not bundle another IDA server.
REA adapts an existing IDA MCP server into its native analysis tools. Headless IDA Pro analysis uses the [mrexodia/ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp) database supervisor or the official [Hex-Rays IDA MCP](https://github.com/HexRaysSA/ida-mcp); analysis of a database already open in the IDA GUI uses the separate [ida-free-mcp native plugin](https://github.com/0xshlomil/ida-free-mcp) for IDA Pro and IDA Free. Install and configure your selected engine and upstream MCP using their instructions. REA does not install, upgrade, activate, or license them, and does not bundle another IDA server.
Choose one lifecycle mode in an upstream MCP JSON registration. An attached registration (the default mode) must also name its upstream protocol, `"protocol": "native"`. Headless registrations omit `protocol`. An attached registration without `protocol` is refused with a configuration error naming the choice. A registration that still names `"protocol": "legacy"` is refused with guidance to [migrate it](#migrate-a-legacy-attached-registration): the ida-pro-mcp 1.4 attached protocol has been removed, and REA never reads that value as another protocol. Set `REA_IDA_MCP_CONFIG` to that file, then select `ida` once through `REA_ANALYSIS_PROVIDER`, the CLI's `--provider ida`, or MCP's `open_binary.provider_id`. No provider startup occurs during discovery.
Choose one lifecycle mode in an upstream MCP JSON registration. An attached registration (the default mode) must also name its upstream protocol, `"protocol": "native"`. A headless database-supervisor registration omits `protocol`; the Hex-Rays profile sets `"protocol": "hexrays"`. An attached registration without `protocol` is refused with a configuration error naming the choice. A registration that still names `"protocol": "legacy"` is refused with guidance to [migrate it](#migrate-a-legacy-attached-registration): the ida-pro-mcp 1.4 attached protocol has been removed, and REA never reads that value as another protocol. Set `REA_IDA_MCP_CONFIG` to that file, then select `ida` once through `REA_ANALYSIS_PROVIDER`, the CLI's `--provider ida`, or MCP's `open_binary.provider_id`. No provider startup occurs during discovery.
## Supported upstream versions
@@ -12,10 +12,11 @@ Startup failures identify the accepted REA analysis operation. Missing-profile a
The headless profile is defined by the database-supervisor API, not by an upstream version string. The upstream source snapshot [`c133c385`](https://github.com/mrexodia/ida-pro-mcp/tree/c133c3853faa111a9b00ee615c013b720d0c4acd) includes `idb_close` (introduced by [upstream PR #495](https://github.com/mrexodia/ida-pro-mcp/pull/495)) alongside `idb_open` and `idb_list`. Earlier builds may report the same `2.0.0` version while lacking that tool, so REA checks the live catalog rather than treating a version number or branch name as a compatibility guarantee.
| Mode | Upstream profile | Known working |
| --------------------------------- | ------------------- | ------------------------------------------------------ |
| attached (`"protocol": "native"`) | ida-free-mcp plugin | see [the native bridge](#native-ida-mcp-bridge) |
| headless | database supervisor | builds serving `idb_open`, `idb_list`, and `idb_close` |
| Mode | Upstream profile | Known working |
| ---------------------------------- | ------------------- | ---------------------------------------------------------------------------------------- |
| attached (`"protocol": "native"`) | ida-free-mcp plugin | see [the native bridge](#native-ida-mcp-bridge) |
| headless | database supervisor | builds serving `idb_open`, `idb_list`, and `idb_close` |
| headless (`"protocol": "hexrays"`) | Hex-Rays IDA MCP | builds serving `open_database`, `list_databases`, `close_database`, and `execute_python` |
## Analyze an already-open GUI target
@@ -46,6 +47,11 @@ was established; failed registrations remain unavailable. Correct
launch environment. Restart/reconnect that server after changing its environment;
an export in another shell does not update a running server.
In attached mode, open the **original input binary** in REA, not an `.idb` or `.i64` database. Its SHA-256 must match IDA's recorded input hash.
REA checks the attached identity and image base around each analysis request. A mismatch or target switch fails with recovery guidance.
The original input must remain readable by REA; WSL can use its mounted alias while the GUI runs on Windows.
Attached profiles, including native mode, refuse universal Mach-O inputs at admission: every slice shares the recorded whole-file hash, so REA cannot verify which slice the GUI loaded.
Open a thin file extracted with `lipo -thin` in both IDA and REA, or use headless mode, which analyzes the selected slice.
An HTTP registration's `url` must use `http` or `https` without URL credentials,
and its host must be `localhost`, `127.0.0.1`, `[::1]`, or the Docker/Podman
host-gateway name `host.docker.internal` or `host.containers.internal`. Use a
@@ -194,6 +200,39 @@ When a completed `idb_open` response reports success or is otherwise ambiguous,
Headless cleanup uses the upstream database lifecycle. Abruptly terminating REA, its proxy, or the supervisor does not establish worker release. Prefer `close_binary` for MCP sessions; after an interrupted process, inspect upstream session inventory and retained workspace diagnostics before removing working files. This adapter does not claim Windows Job Object containment for the upstream detached workers.
## Use the official Hex-Rays IDA MCP
The `hexrays` protocol drives the [Hex-Rays IDA MCP](https://github.com/HexRaysSA/ida-mcp) headlessly. Upstream requires IDA 9.4 or later with idalib and Python 3.11 or later, with `uv` and Git on `PATH`; REA installs none of them. Register the server for stdio:
```json
{
"command": "ida-mcp",
"args": ["stdio", "--agent=rea"],
"mode": "headless",
"protocol": "hexrays"
}
```
The profile is headless and stdio only. Hex-Rays database leases belong to the MCP server process, so REA's own stdio child is what makes a lease provably REA's. Attached and HTTP Hex-Rays registrations are rejected, and analyzing a database already open in the IDA GUI is not supported. A registration that omits `protocol` but reaches a Hex-Rays server fails at startup with `advertised_tools` and a recovery naming the `hexrays` registration.
Use the stdio launch command and arguments from your existing installation. This profile accepts the `idalib` and `idat` headless backends. With the official plugin installed, [Hex-Rays can select `idat`](https://github.com/HexRaysSA/ida-mcp#manual-installation), which uses IDA's Python and installed plugins. To use `idalib` even with the plugin installed, add `"env": { "IDA_NEXUS_IDALIB_ONLY": "1" }` to the registration. The upstream `uvx --exclude-newer=1s` example can resolve newer releases than the version listed in [verification coverage](#verification).
REA copies and verifies the input in a private workspace as for the database supervisor, then calls `open_database` on that copy with `set_current: false`. Hex-Rays assigns the instance ID. REA checks that the open reply and inventory agree on the lease and headless backend, and that the inventory path binds it to the private input. Analysis Evidence records the bound backend as `raw_result.worker_backend`. An `idat` worker must also report its database path inside the private workspace. A GUI database is refused, and the open is treated as unverified.
### Start from an existing IDA database
The `hexrays` profile also opens an existing `.idb` or `.i64`, so analysis starts from its saved names, types and comments instead of a fresh auto-analysis. Pass the database itself to `open_binary` with `provider_id: "ida"`. REA identifies packed IDA databases by their `IDA1` or `IDA2` signature. The upstream loader also requires the corresponding `.idb` or `.i64` filename suffix. REA copies the whole file into the private workspace before opening it. The copy matters: idalib repacks a database when its last lease is released, even without a save, so opening the selected file directly would rewrite it. The selected database is only read.
For an executable, REA checks the private input path and file digest. When IDA reports a recorded input hash, REA compares it with the admitted copy, including the selected thin slice for a universal Mach-O. For a saved database, REA binds the opened copy by `idb_path`. Its `input_path` and `input_sha256` describe the original executable. Results reflect the database's saved content: unsaved changes held by another IDA session, including an unpacked `.id0`/`.id1` set beside it, are not included. Evidence subjects identify the database file, not the input binary. Attached and database-supervisor registrations reject database targets, and Hopper rejects IDA databases.
Hex-Rays MCP exposes database reads only through `execute_python`. REA therefore sends one fixed, read-only query module, [`bridge/ida/hexrays_queries.py`](https://github.com/morluto/rea/blob/main/bridge/ida/hexrays_queries.py), followed by a single `_rea_query(name, arguments_json)` call. The module answers the same database-supervisor reads REA already validates: health, function inventory and lookup, strings, paged pseudocode and assembly, callees, a depth-zero call graph, xrefs to an address, and a minimal segment survey. Caller-supplied text only ever reaches the module as JSON data, never as Python source, and REA forwards no other Python. Each observation records `execute_python` as the upstream tool, plus the query name, its arguments, and the module's SHA-256 instead of its body. The health reads behind each operation's identity checks are kept the same way, as `health_observations` beside the parsed metadata. Call scans skip data items inside functions.
`execute_python` waits for initial auto-analysis, so readiness is checked before the first read. Function sizes are enclosing spans, as with other IDA profiles. Strings come from IDA's default string list. Xrefs exclude ordinary flow from the preceding instruction. Callees on x86-only targets report every direct code or pointer target of a call instruction: targets inside a function are internal and resolve to that function, and imports, pointer slots, and code outside every function are reported by address as external. Indirect calls without a reference remain unknown. Other targets use the processor-neutral call graph, which reports function entries reached by IDA’s near or far call references. Direct callers remain unavailable for the same reason as in the database-supervisor profile. The observed Hex-Rays MCP does not truncate or preview `execute_python` results, and REA keeps every page to 100 items or fewer. Nonempty engine stdout and stderr are retained in the observation.
On close, REA releases its lease with `close_database`. Before removing the workspace, it checks `list_databases` for its lease ID and for any database path inside the workspace. An unleased row can represent a peer or a worker still shutting down. Nexus keeps an `idat` worker's lifetime lock through process exit. Hex-Rays can flush and repack the private database during analysis and release. These database writes stay in the private workspace.
An error or missing reply from `open_database` leaves startup unverified. For example, Nexus can return a startup timeout while the worker is still starting. An empty inventory does not establish that the worker stopped. On cleanup retry, REA can release an owned lease it finds for the private input. If startup remains unverified, REA keeps the workspace for manual recovery after the upstream worker has stopped. A GUI database is never released or closed. The Hex-Rays MCP also writes per-session JSONL traces of its tool calls under `~/.idapro/mcp/sessions/`.
## Connect an agent once
Add the registration path to the **REA** MCP entry's environment, keeping the upstream registration in its separate JSON file:
@@ -240,7 +279,7 @@ All profiles expose `list_documents` as the single target admitted for the sessi
No profile supports direct callers. Upstream code/data xref labels do not prove call edges, so `procedure_callers` is unavailable and the dossier marks callers unknown.
Complete body ranges, typed reference edges, CFG, referenced data, source locals, comment kinds, and database revision are unavailable. Empty unsupported dossier facets mean **unknown**, not observed absence. Whole-symbol inventory, mutation, debugging, arbitrary Python forwarding, and requested GUI navigation are outside this adapter's coverage. Check session availability before composing a workflow that needs those facets.
Complete body ranges, typed reference edges, CFG, referenced data, source locals, comment kinds, and database revision are unavailable. Empty unsupported dossier facets mean **unknown**, not observed absence. Whole-symbol inventory, mutation, debugging, arbitrary Python forwarding, and requested GUI navigation are outside this adapter's coverage; the Hex-Rays profile sends only its fixed query module. Check session availability before composing a workflow that needs those facets.
`provider.version` identifies the REA adapter; the profile explicitly records `version_scope: "rea-ida-adapter"`. The MCP handshake's `serverInfo` is separate and does not establish IDA or Python distribution versions. Raw observations preserve producer metadata and output. Attached hashes identify the recorded original input; headless identity uses the digest-verified private copy and observed worker input path. Neither proves source-code recovery or an unmodified analysis database.
@@ -248,12 +287,16 @@ Complete body ranges, typed reference edges, CFG, referenced data, source locals
Run `npm run verify:ida -- --target /absolute/path/to/program --procedure main` with a configured upstream server. It exercises production CLI and MCP tools, validates their output contracts and Evidence, checks original-input preservation and session cleanup, and keeps local target data out of its console summary. Supply `--package-root` to verify an extracted or installed package. See [testing](../development/testing.md) for the distinction between adapter tests and real-provider evidence.
For the Hex-Rays profile, pass `--expected-backend idat` or `--expected-backend idalib` to verify the backend that served the CLI and MCP reads. The verifier records the observed backends. Add `--verify-peer-cleanup` to open REA’s private copy from a second upstream connection, confirm REA retains the workspace while that peer holds a lease, and verify removal after the peer releases and REA retries close. For `idat` verification, use an IDA installation with the official plugin and record the MCP and Nexus versions in both Python environments. Full REA `idat` verification is tracked in [issue #12921](https://github.com/morluto/rea/issues/12921).
Native verification requires `--second-procedure other_function --second-marker unique_second_body_text`; these options remain optional for the other profiles. The marker must occur in the second function's pseudocode and be absent from the first; the verifier also checks that returning to the first restores its text.
The verifier requires the resolved procedure in both inventory and procedure search, then compares address, assembly, pseudocode, instruction windows and relationship results with the CLI/MCP dossier. Supply `--expected-string known_literal` to check a known positive string inventory/search result and `--expected-xref 0xSOURCE` to check a known reference source address. Choose those oracles independently from the operation under test. Without them, string and xref correctness are listed in `unverified`; valid output shapes alone do not establish those behaviors. Callee parity does not independently establish semantic completeness. Native callee successes must report an explicit truncation marker; missing markers remain protocol failures.
The initial real workflows used stdio registrations for the since-removed legacy Windows GUI profile and a Windows x64 headless supervisor with IDA 9.3. The headless workflow has also passed on macOS arm64 with IDA Professional 9.1 (build 9.1.250226) against the same upstream commit `c133c3853faa111a9b00ee615c013b720d0c4acd`, using a source-built arm64 Mach-O fixture; Mach-O C symbols carry a leading underscore, so the procedure name is `_rea_fixture_add`. Streamable HTTP is tested against a loopback MCP fixture with the pinned client SDK; a real IDA HTTP-supervisor workflow remains unverified. Linux headless engine operation, other IDA releases, architectures, and modern attached GUI tools require their corresponding real workflows before support is claimed.
The Hex-Rays profile has passed `npm run verify:ida` on Linux x64 against Hex-Rays IDA MCP 20261008.0.1 with idalib, using the public two-function fixture built as an x86-64 ELF, the same fixture with an added string literal for `--expected-string`, and a statically linked AArch64 ELF build that exercises the call-graph callee path. It has also passed with the x86-64 fixture's saved `.i64` as the target, holding a function renamed in that database; the selected database stayed byte-identical. These historical runs used an `idalib` worker. The exact Nexus version was not recorded. Full REA workflows on other hosts and with PE or Mach-O targets remain unverified.
Native Windows verification uses IDA Pro 9.3 with the public two-function fixture and Windows `whoami.exe`, using upstream `c9d15d98e8a143fc74f6e14037c48f63889b6d6c` with a loopback-listener change. It covers production CLI/MCP parity, distinct-function switching, identity and connection cleanup. See the [correctness and performance measurements](https://github.com/morluto/rea/blob/a2e2c29b59e8775b0e6aedb09a9eb16adf32646b/experiments/analysis-efficiency/ida-native-windows.md). This follow-up did not run Windows IDA Free or native macOS.
Headless readiness distinguishes an explicit `auto_analysis_ready: false` from
+1
View File
@@ -51,6 +51,7 @@
"dist",
"install.sh",
"bridge/hopper_bridge.py",
"bridge/ida/hexrays_queries.py",
"bridge/cutter/rea_bridge.py",
"bridge/native/NativeUIChildren.swift",
"bridge/native/NativeUIValues.swift",
+8
View File
@@ -0,0 +1,8 @@
export function privateIdaInput(
metadata: {
readonly input_path: string;
readonly idb_path: string | null;
},
target: string,
targetIsDatabase: boolean,
): string;
+13
View File
@@ -0,0 +1,13 @@
import assert from "node:assert/strict";
/**
* Path of REA's private copy in a headless session's metadata. A database
* records the executable it was built from, so its copy is the opened
* database, as IdaSessionClient binds it.
*/
export function privateIdaInput(metadata, target, targetIsDatabase) {
const path = targetIsDatabase ? metadata.idb_path : metadata.input_path;
assert.equal(typeof path, "string");
assert.notEqual(path, target);
return path;
}
+19 -16
View File
@@ -6,6 +6,7 @@ import { GHIDRA_BRIDGE_SOURCES } from "../src/ghidra/GhidraBridgeSources.ts";
const packedHopperBridge = "package/bridge/hopper_bridge.py";
const packedCutterBridge = "package/bridge/cutter/rea_bridge.py";
const packedHexRaysBridge = "package/bridge/ida/hexrays_queries.py";
const root = fileURLToPath(new URL("../", import.meta.url));
const packedAgentEnvSources = Object.values(AGENTENV_BRIDGE_SOURCES).map(
(url) => `package/${relative(root, fileURLToPath(url)).split(sep).join("/")}`,
@@ -23,6 +24,7 @@ export async function verifyPackedBridge({ tarball, packedFiles, commands }) {
for (const path of [
packedHopperBridge,
packedCutterBridge,
packedHexRaysBridge,
...packedAgentEnvSources,
...Object.values(GHIDRA_BRIDGE_SOURCES).map(
(name) => `package/bridge/ghidra/${name}`,
@@ -33,20 +35,21 @@ export async function verifyPackedBridge({ tarball, packedFiles, commands }) {
// Read the packed source without extracting into the caller's leased root.
// Only the interpreter's standard library is needed; caller-local modules
// and site startup hooks must not replace the parser or execute here.
await commands.exec("python3", [
"-I",
"-S",
"-c",
[
"import ast, sys, tarfile",
"with tarfile.open(sys.argv[1]) as archive:",
" member = archive.getmember(sys.argv[2])",
" if not member.isfile():",
" raise ValueError(f'{member.name} is not a regular file')",
" with archive.extractfile(member) as source:",
" ast.parse(source.read().decode('utf-8'), filename=sys.argv[2])",
].join("\n"),
tarball,
packedHopperBridge,
]);
for (const path of [packedHopperBridge, packedHexRaysBridge])
await commands.exec("python3", [
"-I",
"-S",
"-c",
[
"import ast, sys, tarfile",
"with tarfile.open(sys.argv[1]) as archive:",
" member = archive.getmember(sys.argv[2])",
" if not member.isfile():",
" raise ValueError(f'{member.name} is not a regular file')",
" with archive.extractfile(member) as source:",
" ast.parse(source.read().decode('utf-8'), filename=sys.argv[2])",
].join("\n"),
tarball,
path,
]);
}
+171 -14
View File
@@ -3,6 +3,7 @@ import {
assertFeatureTrace,
findMappedNonFunction,
} from "./lib/ida-feature-trace.mjs";
import { privateIdaInput } from "./lib/ida-private-input.mjs";
import { requireMcpToolError } from "./lib/mcp-verifier-results.mjs";
import {
verifierFailureReasons,
@@ -13,8 +14,8 @@ import { withVerifierResourceOwner } from "./lib/verifier-file-resources.mjs";
import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import { createReadStream } from "node:fs";
import { access, writeFile } from "node:fs/promises";
import { basename, dirname, join, resolve } from "node:path";
import { access, readdir, writeFile } from "node:fs/promises";
import { basename, dirname, isAbsolute, join, resolve } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { parseArgs } from "node:util";
import { Client } from "@modelcontextprotocol/client";
@@ -29,6 +30,8 @@ const { values } = parseArgs({
"second-marker": { type: "string" },
"expected-string": { type: "string" },
"expected-xref": { type: "string" },
"expected-backend": { type: "string" },
"verify-peer-cleanup": { type: "boolean" },
"package-root": { type: "string" },
report: { type: "string" },
},
@@ -61,6 +64,10 @@ const [
{ readIdaConfiguration, idaCompatibilityProfile },
{ createIdaMcpConnection },
{ idaAddressSchema },
{ hasIdaDatabaseSignature },
{ hexRaysOpenSchema, hexRaysListSchema, hexRaysCloseSchema },
{ sameIdaHostPath },
{ isPathWithinRoot },
] = await Promise.all([
importBuilt("contracts/toolContracts.js"),
importBuilt("domain/evidence.js"),
@@ -68,6 +75,10 @@ const [
importBuilt("ida/IdaConfiguration.js"),
importBuilt("ida/IdaMcpConnection.js"),
importBuilt("ida/IdaProtocolValues.js"),
importBuilt("domain/analysisDatabase.js"),
importBuilt("ida/IdaHexRaysProtocol.js"),
importBuilt("ida/IdaWorkspace.js"),
importBuilt("domain/localPath.js"),
]);
const config = await withVerifierResourceOwner(async (resourceScope) => {
const registration = await readIdaConfiguration(
@@ -85,6 +96,19 @@ if (
throw new Error(
"Native IDA verification requires --second-procedure and --second-marker to verify distinct-function switching; see docs/providers/ida-provider.md.",
);
const expectedBackend = values["expected-backend"];
if (
expectedBackend !== undefined &&
(config.protocol !== "hexrays" ||
(expectedBackend !== "idat" && expectedBackend !== "idalib"))
)
throw new Error(
"--expected-backend requires a Hex-Rays registration and an idat or idalib value.",
);
if (values["verify-peer-cleanup"] && config.protocol !== "hexrays")
throw new Error(
"--verify-peer-cleanup requires a Hex-Rays stdio registration.",
);
const environment = Object.fromEntries(
Object.entries({
...process.env,
@@ -96,6 +120,7 @@ const report = {
passed: false,
mode: config.mode,
protocol: idaCompatibilityProfile(config).protocol,
worker_backends: [],
checks: [],
observations: [],
unverified: [],
@@ -106,6 +131,7 @@ const expectedXref =
: idaAddressSchema.parse(values["expected-xref"]);
let phase = "target admission";
const workspaces = new Set();
let targetIsDatabase = false;
const databases = new Set();
const digest = async () => {
const hash = createHash("sha256");
@@ -124,12 +150,41 @@ const observe = (input) => {
assert.ok(
evidence.locations.some((location) => location.kind === "artifact-path"),
);
if (config.protocol === "hexrays") {
const backend = evidence.raw_result.worker_backend;
assert.ok(
backend === "idalib" || backend === "idat",
"Hex-Rays evidence must identify the bound worker backend.",
);
if (expectedBackend !== undefined)
assert.equal(
backend,
expectedBackend,
"Hex-Rays worker backend differed from the requested verification lane.",
);
if (!report.worker_backends.includes(backend))
report.worker_backends.push(backend);
}
if (config.mode === "headless") {
assert.notEqual(evidence.raw_result.metadata_before.input_path, target);
workspaces.add(dirname(evidence.raw_result.metadata_before.input_path));
workspaces.add(
dirname(
privateIdaInput(
evidence.raw_result.metadata_before,
target,
targetIsDatabase,
),
),
);
for (const observation of evidence.raw_result.observations) {
assert.equal(typeof observation.arguments.database, "string");
databases.add(observation.arguments.database);
// Hex-Rays reads select their lease by instance id through execute_python.
const database =
config.protocol === "hexrays"
? observation.arguments.instance_id
: observation.arguments.database;
if (config.protocol === "hexrays")
assert.equal(observation.tool, "execute_python");
assert.equal(typeof database, "string");
databases.add(database);
}
}
report.observations.push(evidence);
@@ -173,6 +228,68 @@ const cli = async () => {
report.checks.push("production CLI and complete function Evidence");
return dossier;
};
const verifyPeerCleanup = async (analysis, closeWithPeer, retryClose) => {
phase = "Hex-Rays peer lease cleanup";
const privateInput = privateIdaInput(
analysis.raw_result.metadata_before,
target,
targetIsDatabase,
);
const workspace = dirname(privateInput);
assert.ok(workspaces.has(workspace));
const peer = createIdaMcpConnection(config, process.env, {
platform: process.platform,
});
let instanceId;
const releasePeer = async () => {
if (instanceId === undefined) return;
hexRaysCloseSchema.parse(
await peer.call("close_database", { instance_id: instanceId }),
);
instanceId = undefined;
};
await withVerifierCleanup(async () => {
await peer.connect();
const lease = hexRaysOpenSchema.parse(
await peer.call("open_database", {
path: privateInput,
set_current: false,
}),
);
instanceId = lease.instance_id;
assert.equal(lease.backend, analysis.raw_result.worker_backend);
const retained = requireMcpToolError(await closeWithPeer());
assert.equal(retained.code, "cleanup_incomplete");
const resources = retained.details?.resources;
assert.ok(
Array.isArray(resources) && resources.includes(workspace),
"The cleanup error must identify the retained workspace.",
);
await access(privateInput);
const inventory = hexRaysListSchema.parse(
await peer.call("list_databases", {}),
);
const held = inventory.instances.find(
(row) => row.instance_id === instanceId,
);
assert.ok(held?.status === "current" || held?.status === "attached");
assert.equal(held.backend, lease.backend);
assert.ok(
sameIdaHostPath(held.path, privateInput),
"The peer lease must still bind the private input.",
);
await releasePeer();
await retryClose();
await assert.rejects(access(workspace), { code: "ENOENT" });
report.checks.push(
"a second Hex-Rays client retains the private database until its lease is released and REA retries cleanup",
);
}, [releasePeer, () => peer.close()]);
};
const mcp = async (cliDossier) => {
const client = new Client({ name: "rea-real-ida-verifier", version: "1" });
const transport = await createOwnedMcpStdioTransport({
@@ -384,7 +501,23 @@ const mcp = async (cliDossier) => {
});
assert.equal(invalid.isError, true);
assert.equal(requireMcpToolError(invalid).code, "invalid_request");
await call("close_binary", {});
if (values["verify-peer-cleanup"])
await verifyPeerCleanup(
analyzed,
() =>
client.callTool(
{ name: "close_binary", arguments: {} },
{ timeout: config.timeoutMs * 2 },
),
() => call("close_binary", {}),
);
else {
await call("close_binary", {});
if (config.protocol === "hexrays")
report.unverified.push(
"Peer-held Hex-Rays cleanup: --verify-peer-cleanup was not selected.",
);
}
opened = false;
report.checks.push(
"one MCP connection, positive procedure inventory/search, contract-valid tool results, invalid input, and close",
@@ -419,12 +552,26 @@ const cleanup = async () => {
"existing GUI target remains open with the original input identity",
);
} else {
const inventory = await upstream.call("idb_list", {});
assert.ok(
inventory.sessions.every(
(session) => !databases.has(session.session_id),
),
);
if (config.protocol === "hexrays") {
// Leases are per server process, so a fresh server proves release by
// listing no live database inside any REA private workspace.
const inventory = await upstream.call("list_databases", {});
assert.ok(
inventory.instances.every(({ path }) =>
[...workspaces].every(
(workspace) =>
!isAbsolute(path) || !isPathWithinRoot(workspace, path),
),
),
);
} else {
const inventory = await upstream.call("idb_list", {});
assert.ok(
inventory.sessions.every(
(session) => !databases.has(session.session_id),
),
);
}
for (const workspace of workspaces)
await assert.rejects(access(workspace), { code: "ENOENT" });
report.checks.push(
@@ -437,10 +584,17 @@ const cleanup = async () => {
};
try {
const before = await digest();
for await (const head of createReadStream(target, { end: 3 }))
targetIsDatabase = hasIdaDatabaseSignature(head);
const siblings = (await readdir(dirname(target))).sort();
await mcp(await cli());
await cleanup();
assert.equal(await digest(), before);
report.checks.push("original binary unchanged and never executed");
// Engines write databases beside their input; only the private copy may get one.
assert.deepEqual((await readdir(dirname(target))).sort(), siblings);
report.checks.push(
"original target bytes and sibling directory entries unchanged",
);
report.passed = true;
} catch (cause) {
report.failure = {
@@ -463,6 +617,9 @@ try {
{
passed: report.passed,
mode: report.mode,
...(report.worker_backends.length === 0
? {}
: { worker_backends: report.worker_backends }),
checks: report.checks,
unverified: report.unverified,
...(report.passed
+25 -1
View File
@@ -50,6 +50,10 @@ import {
cancelledBy,
carriedReason,
} from "../domain/analysisErrorCore.js";
import {
hasIdaDatabaseSignature,
type AnalysisDatabaseEngine,
} from "../domain/analysisDatabase.js";
import {
PE_CODEVIEW_PREFIX_BYTES,
type BinaryTarget,
@@ -497,18 +501,23 @@ const readOpenedBinaryTarget = async (
...(await identity()),
artifactSelectedPath: selectedPath,
});
const databaseEngine =
targetKind === undefined || targetKind === "database"
? await detectDatabaseEngine(path, handle, signal)
: null;
if (
targetKind === "database" ||
(targetKind === undefined &&
artifactFormat !== "ines" &&
artifactFormat !== "uefi" &&
artifactFormat !== "plist" &&
path.toLowerCase().endsWith(".hop"))
databaseEngine !== null)
)
return ok({
...(await identity()),
kind: "database",
format: "analysis-database",
databaseEngine,
});
if (artifactFormat !== undefined) {
const identity = await artifactIdentity();
@@ -696,6 +705,21 @@ const throwIfTargetResolutionCancelled = (signal?: AbortSignal): void => {
throw cancelledBy("resolve_binary_target", signal);
};
/** IDA databases carry a signature; Hopper databases are known only by suffix. */
const detectDatabaseEngine = async (
path: string,
handle: FileHandle,
signal?: AbortSignal,
): Promise<AnalysisDatabaseEngine | null> => {
throwIfTargetResolutionCancelled(signal);
const magic = Buffer.alloc(4);
const observed = await handle.read(magic, 0, magic.length, 0);
throwIfTargetResolutionCancelled(signal);
if (hasIdaDatabaseSignature(magic.subarray(0, observed.bytesRead)))
return "ida";
return path.toLowerCase().endsWith(".hop") ? "hopper" : null;
};
const detectArtifactFormat = async (
path: string,
source: StableRegularFileDescriptor,
@@ -34,6 +34,7 @@ const DATABASE_TARGET: BinaryTarget = {
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
databaseEngine: "hopper",
};
const ARTIFACT_TARGET: BinaryTarget = {
path: "/tmp/app.asar",
@@ -111,6 +111,7 @@ const TARGETS: TargetFixtures = {
...identity,
kind: "database",
format: "analysis-database",
databaseEngine: "hopper",
},
zip: { ...archive, format: "zip" },
ipa: { ...archive, format: "ipa" },
+10
View File
@@ -0,0 +1,10 @@
/** Engine whose saved analysis database a target holds. */
export type AnalysisDatabaseEngine = "ida" | "hopper";
/** Recognize packed IDA .idb ("IDA1") and .i64 ("IDA2") signatures, not database validity. */
export const hasIdaDatabaseSignature = (bytes: Uint8Array): boolean =>
bytes.length >= 4 &&
bytes[0] === 0x49 &&
bytes[1] === 0x44 &&
bytes[2] === 0x41 &&
(bytes[3] === 0x31 || bytes[3] === 0x32);
+3
View File
@@ -1,3 +1,4 @@
import type { AnalysisDatabaseEngine } from "./analysisDatabase.js";
import type { DolHeader } from "./gamecubeDol.js";
import type { TargetFormatsOfKind } from "./targetFormats.js";
@@ -318,6 +319,8 @@ export type BinaryTarget =
NonExecutableMetadata & {
readonly kind: "database";
readonly format: "analysis-database";
/** Engine identified at admission; null when the database is unidentified. */
readonly databaseEngine: AnalysisDatabaseEngine | null;
})
| (BinaryTargetIdentity &
NonExecutableMetadata & {
+2
View File
@@ -130,6 +130,7 @@ describe("Hopper name inventory labels", () => {
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
databaseEngine: "hopper",
});
try {
@@ -185,6 +186,7 @@ describe("Hopper list_names reply contract", () => {
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
databaseEngine: "hopper",
});
try {
+3
View File
@@ -295,6 +295,7 @@ describe("Hopper relationship coverage", () => {
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
databaseEngine: "hopper",
});
try {
const observed = await client.execute(operation, {
@@ -404,6 +405,7 @@ describe("Hopper caller reconciliation failures", () => {
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
databaseEngine: "hopper",
});
try {
const observed = await client.execute("procedure_callers", {
@@ -492,6 +494,7 @@ it("preserves pre-abort with invalid startup seed", async () => {
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
databaseEngine: "hopper",
});
const result = await client.execute(
"health",
+8
View File
@@ -176,6 +176,14 @@ export class HopperProvider implements AnalysisProviderCandidate {
reason: `Hopper cannot directly analyze ${target.kind} targets.`,
diagnostics,
};
if (target.kind === "database" && target.databaseEngine === "ida")
return {
status: "unsupported",
code: "target_format_unsupported",
reason:
"Hopper cannot open IDA databases. Select the ida provider or open the original executable.",
diagnostics,
};
if (target.kind === "database" && this.platform === "darwin")
return {
status: "unsupported",
@@ -154,6 +154,7 @@ const databaseTarget = (): BinaryTarget => ({
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
databaseEngine: "hopper",
});
const executableTarget: BinaryTarget = {
+1
View File
@@ -84,6 +84,7 @@ it.each(["search_strings", "search_procedures"] as const)(
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
databaseEngine: "hopper",
});
try {
const result = await client.execute(operation, {
+1
View File
@@ -223,6 +223,7 @@ const providerClient = () => {
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
databaseEngine: "hopper",
});
};
const nameRow = { address: "0x10", value: "main", provider_metadata: { n: 1 } };
+24 -5
View File
@@ -50,10 +50,11 @@ const common = {
* An attached registration names its upstream protocol. `"legacy"` (the
* removed ida-pro-mcp 1.4 GUI proxy) is still recognized so that a stored
* registration is refused with migration guidance rather than reported as an
* unknown value or read as another protocol. Headless mode has one protocol
* (the database supervisor).
* unknown value or read as another protocol. Headless mode uses the database
* supervisor when `protocol` is omitted, or `"hexrays"` for the official
* Hex-Rays IDA MCP.
*/
protocol: z.enum(["legacy", "native"]).optional(),
protocol: z.enum(["legacy", "native", "hexrays"]).optional(),
timeoutMs: z
.int()
.min(MIN_IDA_REQUEST_TIMEOUT_MS)
@@ -96,13 +97,24 @@ const registrationSchema = z
.strict(),
])
.refine(
(config) => config.protocol === undefined || config.mode === "attached",
"An IDA MCP protocol requires attached mode; headless registrations omit protocol",
(config) =>
config.protocol === undefined ||
config.protocol === "hexrays" ||
config.mode === "attached",
'An IDA MCP protocol requires attached mode; a headless registration omits protocol or sets "hexrays"',
)
.refine(
(config) => config.protocol !== undefined || config.mode !== "attached",
'attached IDA registrations must set protocol to "native" (ida-free-mcp plugin)',
)
// Hex-Rays database leases belong to the MCP server process. Only a stdio
// registration gives REA a server, and therefore leases, of its own.
.refine(
(config) =>
config.protocol !== "hexrays" ||
(config.mode === "headless" && "command" in config),
"The Hex-Rays IDA MCP protocol requires a headless stdio registration",
)
// Resolve the upstream protocol once; consumers never infer it from mode.
.transform((config, context) => {
if (config.protocol === "legacy") {
@@ -139,6 +151,13 @@ export const IDA_COMPATIBILITY_PROFILES = {
diagnosticIdentity: "database-supervisor",
diagnosticLabel: "headless",
},
hexrays: {
protocol: "hexrays",
mode: "headless",
identity: "hexrays-ida-mcp",
diagnosticIdentity: "hexrays",
diagnosticLabel: "Hex-Rays",
},
native: {
protocol: "native",
mode: "attached",
+662
View File
@@ -0,0 +1,662 @@
import { spawnSync } from "node:child_process";
import { access, readdir, rm, writeFile } from "node:fs/promises";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { createIdaTarget } from "../../tests/fixtures/idaMcp.js";
import { RecordingHexRaysIdaMcp } from "../../tests/fixtures/idaHexRaysMcp.js";
import { functionDossierSchema } from "../domain/native/functionDossier.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { IdaToolRejection, type IdaMcpConnection } from "./IdaMcpConnection.js";
import { readCallGraphCallees } from "./IdaCallGraph.js";
import { readIdaConfiguration } from "./IdaConfiguration.js";
import { IdaSessionClient } from "./IdaSessionClient.js";
import { runHexRaysQuery } from "./IdaHexRaysProtocol.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { RetainedResourceScope } from "../ports/AnalysisProvider.js";
import { WindowsPrivateRuntime } from "../windows/WindowsPrivateRuntime.js";
const roots: string[] = [];
const windowsRuntimes = new Set<WindowsPrivateRuntime>();
beforeEach(() => {
if (process.platform !== "win32") return;
const create = WindowsPrivateRuntime.create;
vi.spyOn(WindowsPrivateRuntime, "create").mockImplementation(
(parent, prefix) => {
const runtime = create(parent, prefix);
windowsRuntimes.add(runtime);
return runtime;
},
);
});
afterEach(async () => {
try {
// A retained workspace keeps its native owner, which blocks rm on Windows.
for (const runtime of windowsRuntimes) {
await runtime.close();
windowsRuntimes.delete(runtime);
}
for (const root of roots.splice(0))
await rm(root, { recursive: true, force: true });
} finally {
vi.restoreAllMocks();
}
});
const fixture = async () => {
const { root, target } = await createIdaTarget();
roots.push(root);
const producer = new RecordingHexRaysIdaMcp(target);
const client = new IdaSessionClient(
{
command: "ida-mcp",
args: ["stdio"],
env: {},
mode: "headless",
protocol: "hexrays",
timeoutMs: 1000,
workspaceRoot: root,
},
target,
producer,
);
return { root, target, producer, client };
};
const resourceScope: RetainedResourceScope = {
retain: () => undefined,
run: (operation) => operation(),
};
/** Private workspaces REA allocated beside the fixture target. */
const workspaces = async (root: string) =>
(await readdir(root)).filter((name) => name.startsWith("rea-ida-"));
describe("Hex-Rays IDA MCP registration", () => {
it("admits only a headless stdio registration", async () => {
const { root } = await createIdaTarget();
roots.push(root);
const path = join(root, "mcp.json");
for (const [input, ok] of [
[
{
command: "uvx",
args: ["ida-mcp", "stdio"],
mode: "headless",
protocol: "hexrays",
},
true,
],
[
{ command: "uvx", args: ["ida-mcp", "stdio"], protocol: "hexrays" },
false,
],
[
{
url: "http://127.0.0.1:8737/mcp",
mode: "headless",
protocol: "hexrays",
},
false,
],
] as const) {
await writeFile(path, JSON.stringify(input));
expect(
(await readIdaConfiguration(path, { resourceScope })).ok,
JSON.stringify(input),
).toBe(ok);
}
});
});
const hasPython = spawnSync("python3", ["--version"]).status === 0;
it.each([1, 500, 1000, 300_000])(
"keeps the Hex-Rays Python deadline inside the %sms MCP deadline",
async (timeoutMs) => {
const producerCall = vi.fn<IdaMcpConnection["call"]>(async () => ({
result: null,
stdout: "",
stderr: "",
}));
await runHexRaysQuery(
{
connect: async () => [],
serverInfo: () => null,
close: async () => undefined,
detach: () => undefined,
call: producerCall,
},
"lease",
"server_health",
{},
timeoutMs,
);
const [tool, args, options] = producerCall.mock.calls[0] ?? [];
expect(tool).toBe("execute_python");
expect(options).toMatchObject({ timeoutMs });
const engineTimeout = Number(args?.timeout) * 1000;
expect(engineTimeout).toBeGreaterThan(0);
expect(engineTimeout).toBeLessThan(timeoutMs);
},
);
describe("Hex-Rays query line", () => {
it.skipIf(!hasPython)(
"delivers caller text to the bridge as data for any string content",
async () => {
const names = [
'a"); __import__("os").system("x") #',
'back\\slash \\N{BULLET} \\x41 """',
"line\nbreak\r\u2028\u2029\u0085\u0000\u001b",
"lone \ud800 surrogate and emoji \u{1f600}",
];
let code = "";
const connection = {
connect: async () => [],
serverInfo: () => null,
close: async () => undefined,
detach: () => undefined,
call: async (
_name: string,
args: Readonly<Record<string, JsonValue>>,
) => {
code = String(args.code);
return { result: null, stdout: "", stderr: "" };
},
};
await runHexRaysQuery(
connection,
"lease",
"lookup_funcs",
{ queries: names },
1000,
);
// Parse only the generated line; evaluating literals runs no code.
const decoded = spawnSync(
"python3",
[
"-I",
"-c",
[
"import ast, json, sys",
"call = ast.parse(sys.stdin.read().rsplit('\\n', 1)[1], mode='eval').body",
"assert isinstance(call, ast.Call) and call.func.id == '_rea_query'",
"tool, arguments = (ast.literal_eval(arg) for arg in call.args)",
"sys.stdout.write(json.dumps([tool, json.loads(arguments)]))",
].join("\n"),
],
{ input: code, encoding: "utf8" },
);
expect(decoded.stderr).toBe("");
expect(JSON.parse(decoded.stdout)).toEqual([
"lookup_funcs",
{ queries: names },
]);
},
);
});
describe("Hex-Rays IDA MCP startup profile", () => {
it("retains the private input after an open tool error and observes a late unleased worker", async () => {
const { producer, client } = await fixture();
producer.openToolError =
"IDA MCP tool failed: timed out waiting for idat worker";
const opened = await client.execute("list_procedures", {});
if (opened.ok) throw new Error("expected startup timeout");
expect(opened.error.message).toContain("timed out waiting for idat worker");
const open = producer.calls.find(({ name }) => name === "open_database");
const path = open?.args.path;
if (typeof path !== "string") throw new Error("missing private input path");
const closing = await client.close();
if (closing.ok)
throw new Error("cleanup accepted an empty startup inventory");
expect(closing.error.cleanupIncomplete).toBe(true);
await access(path);
// Nexus can publish the worker after open_database has returned the error.
const idbPath = path + ".i64";
producer.peers = [
{ path: idbPath, backend: "idat", status: "unavailable" },
];
const retry = await client.close();
if (retry.ok)
throw new Error("expected retained cleanup for the late worker");
expect(projectAnalysisError(retry.error).details).toMatchObject({
diagnostics: {
upstream_sessions: {
state: "unverified",
sessions: [
{ owned: false, input_path: idbPath, hexrays_backend: "idat" },
],
},
},
});
expect(producer.calls.some(({ name }) => name === "close_database")).toBe(
false,
);
await access(path);
});
it("refuses an inconsistent open and inventory backend without querying or closing the worker", async () => {
const { root, producer, client } = await fixture();
producer.openBackend = "idat";
producer.inventoryBackend = "idalib";
const result = await client.execute("list_procedures", {});
if (result.ok) throw new Error("expected inconsistent backend refusal");
expect(projectAnalysisError(result.error).details).toMatchObject({
diagnostics: { identity_check: "owned_worker_binding" },
});
expect((await client.close()).ok).toBe(false);
expect(
producer.calls.some(
({ name }) => name === "execute_python" || name === "close_database",
),
).toBe(false);
expect(await workspaces(root)).toHaveLength(1);
producer.inventoryBackend = undefined;
expect((await client.close()).ok).toBe(true);
expect(await workspaces(root)).toEqual([]);
});
it("names the Hex-Rays profile when the catalog lacks execute_python", async () => {
const { producer, client } = await fixture();
producer.tools = ["open_database", "list_databases", "close_database"];
const result = await client.execute("list_procedures", {});
if (result.ok) throw new Error("expected a profile mismatch");
expect(projectAnalysisError(result.error).details).toMatchObject({
diagnostics: {
mode: "headless",
expected_profile: "hexrays",
missing_tools: ["execute_python"],
},
});
expect(producer.calls).toEqual([]);
});
it("names the Hex-Rays registration when another profile meets its catalog", async () => {
const { root, target } = await createIdaTarget();
roots.push(root);
const producer = new RecordingHexRaysIdaMcp(target);
const client = new IdaSessionClient(
{
command: "ida-mcp",
args: ["stdio"],
env: {},
mode: "headless",
protocol: "modern",
timeoutMs: 1000,
workspaceRoot: root,
},
target,
producer,
);
const result = await client.execute("list_procedures", {});
if (result.ok) throw new Error("expected a profile mismatch");
expect(result.error.userMessage).toContain('"protocol": "hexrays"');
expect(projectAnalysisError(result.error).details).toMatchObject({
diagnostics: {
expected_profile: "database-supervisor",
advertised_tools: [...producer.tools].sort(),
recovery: expect.stringContaining('"protocol": "hexrays"'),
},
});
expect(producer.calls).toEqual([]);
});
});
it.skipIf(!hasPython)(
"reports complete root scan coverage from the Hex-Rays query bridge",
async () => {
const fixturePath = fileURLToPath(
new URL("../../bridge/ida/test_hexrays_queries.py", import.meta.url),
);
const connection = {
connect: async () => [],
serverInfo: () => null,
close: async () => undefined,
detach: () => undefined,
call: async (
_tool: string,
args: Readonly<Record<string, JsonValue>>,
) => {
const result = spawnSync(
"python3",
[
"-I",
"-c",
[
"import json, runpy, sys",
"fixture = runpy.run_path(sys.argv[1])",
"sys.modules.update(fixture['stand_ins']())",
"source, query = sys.stdin.read().rsplit('\\n', 1)",
"namespace = {}",
"exec(source, namespace)",
"print(json.dumps(eval(query, namespace)))",
].join("\n"),
fixturePath,
],
{ input: String(args.code), encoding: "utf8", timeout: 5000 },
);
if (result.status !== 0)
throw new Error("Hex-Rays fixture query failed", {
cause: result.error ?? result.stderr,
});
return { result: JSON.parse(result.stdout), stdout: "", stderr: "" };
},
};
const graph = await readCallGraphCallees(
async (tool, args) =>
(await runHexRaysQuery(connection, "lease", tool, args, 1000)).result,
"0x1000",
);
expect(graph.callees).toEqual([{ address: "0x2000", name: "helper" }]);
expect(graph.coverage).toMatchObject({
status: "complete",
discovery: { callees: { status: "unknown" } },
});
},
);
describe("Hex-Rays IDA MCP evidence", () => {
it.each(["idalib", "idat"])(
"retains the %s backend with completed reads when decompilation fails",
async (backend) => {
const { producer, client } = await fixture();
producer.openBackend = backend;
producer.reads.beforeCall = async (name) => {
if (name === "decompile")
throw new IdaToolRejection("Fixture decompilation failed");
};
try {
const result = await client.execute("procedure_pseudo_code", {
procedure: "main",
});
if (result.ok) throw new Error("expected decompilation failure");
expect(projectAnalysisError(result.error)).toMatchObject({
code: "unreadable_output",
details: {
partial_observation: {
normalized_result: {
status: "partial",
target_binding: { status: "not_verified" },
},
raw_result: {
worker_backend: backend,
observations: [
{
tool: "execute_python",
arguments: { query: "lookup_funcs" },
},
],
},
},
},
});
} finally {
expect((await client.close()).ok).toBe(true);
}
},
);
it("refuses a conflicting IDA input hash even when the private file is unchanged", async () => {
const { target, producer, client } = await fixture();
producer.recordedInputSha256 = target.sha256.toUpperCase();
expect((await client.execute("list_procedures", {})).ok).toBe(true);
producer.recordedInputSha256 = "f".repeat(64);
const result = await client.execute("list_procedures", {});
if (result.ok) throw new Error("expected input identity refusal");
expect(projectAnalysisError(result.error).details).toMatchObject({
diagnostics: { identity_check: "headless_input" },
});
expect((await client.close()).ok).toBe(true);
});
it("refuses an idat database path outside the verified private workspace", async () => {
const { producer, client } = await fixture();
producer.openBackend = "idat";
expect((await client.execute("list_procedures", {})).ok).toBe(true);
producer.reads.idbPath = "/elsewhere/target.i64";
const result = await client.execute("list_procedures", {});
if (result.ok) throw new Error("expected a private database path refusal");
expect(projectAnalysisError(result.error).details).toMatchObject({
diagnostics: { identity_check: "headless_input" },
});
expect((await client.close()).ok).toBe(true);
});
it("keeps the bridge digest and engine output of identity and operation reads", async () => {
const { producer, client } = await fixture();
producer.engineOutput = { stdout: "", stderr: "engine warning" };
const result = await client.execute("list_procedures", {});
if (!result.ok) throw result.error;
const raw = result.value.rawResult as {
health_observations: {
tool: string;
arguments: { query: string; bridge_sha256: string };
output?: { stderr: string };
}[];
observations: { output?: { stderr: string } }[];
};
// One identity read before and one after the operation.
expect(raw.health_observations).toHaveLength(2);
for (const observation of raw.health_observations) {
expect(observation.tool).toBe("execute_python");
expect(observation.arguments.query).toBe("server_health");
expect(observation.arguments.bridge_sha256).toMatch(/^[0-9a-f]{64}$/u);
expect(observation.output?.stderr).toBe("engine warning");
}
expect(raw.observations[0]?.output?.stderr).toBe("engine warning");
expect((await client.close()).ok).toBe(true);
});
});
describe("Hex-Rays IDA MCP session", () => {
it.each(["idalib", "idat"])(
"leases a private %s worker, answers reads through the query bridge, and releases it",
async (backend) => {
const { root, target, producer, client } = await fixture();
producer.openBackend = backend;
const result = await client.execute("analyze_function", {
procedure: "main",
});
if (!result.ok) throw result.error;
const dossier = functionDossierSchema.parse(result.value.result);
expect(dossier.pseudocode).toBe("int main(void) { return 42; }");
expect(dossier.callees.map(({ name }) => name)).toEqual(["puts"]);
const [open] = producer.calls;
expect(open?.name).toBe("open_database");
expect(open?.args.set_current).toBe(false);
expect(open?.args.path).not.toBe(target.path);
expect(String(open?.args.path)).toContain(root);
// Every read is the fixed bridge; no other tool can reach the database.
const reads = producer.calls.filter(
({ name }) => !["open_database", "list_databases"].includes(name),
);
expect(new Set(reads.map(({ name }) => name))).toEqual(
new Set(["execute_python"]),
);
expect(reads.every(({ args }) => args.instance_id === "lease1")).toBe(
true,
);
expect(
reads.every(({ args }) =>
String(args.code).startsWith('"""Read-only REA queries'),
),
).toBe(true);
expect(result.value.rawResult).toMatchObject({ worker_backend: backend });
const raw = result.value.rawResult as {
observations: { tool: string; arguments: { query: string } }[];
};
expect(raw.observations.map(({ tool }) => tool)).toEqual(
raw.observations.map(() => "execute_python"),
);
expect(raw.observations.map(({ arguments: args }) => args.query)).toEqual(
expect.arrayContaining([
"lookup_funcs",
"disasm",
"decompile",
"callees",
]),
);
expect((await client.close()).ok).toBe(true);
expect(producer.calls.at(-2)).toMatchObject({
name: "close_database",
args: { instance_id: "lease1" },
});
expect(producer.calls.at(-1)?.name).toBe("list_databases");
expect(producer.leases.size).toBe(0);
expect(producer.closes).toBe(1);
expect(await workspaces(root)).toEqual([]);
await access(target.path);
},
);
it("refuses a GUI database and retains the workspace it cannot prove released", async () => {
const { root, producer, client } = await fixture();
producer.openBackend = "gui";
const result = await client.execute("list_procedures", {});
expect(result.ok).toBe(false);
if (!result.ok)
expect(result.error.message).toContain(
"instead of a private headless worker",
);
const closed = await client.close();
expect(closed.ok).toBe(false);
expect(await workspaces(root)).toHaveLength(1);
// A GUI database is never REA's to release.
expect(producer.calls.map(({ name }) => name)).not.toContain(
"close_database",
);
});
it("adopts and releases a late lease when the open reply was lost", async () => {
const { root, producer, client } = await fixture();
producer.openBackend = "idat";
producer.loseOpenReply = { leased: true };
expect((await client.execute("list_procedures", {})).ok).toBe(false);
expect((await client.close()).ok).toBe(false);
// The lease is released even though the open itself never completed.
expect(producer.leases.size).toBe(0);
expect(producer.calls.map(({ name }) => name)).toContain("close_database");
expect(await workspaces(root)).toHaveLength(1);
});
it("retains the workspace when a lost open reply left no visible lease", async () => {
const { root, producer, client } = await fixture();
producer.loseOpenReply = { leased: false };
expect((await client.execute("list_procedures", {})).ok).toBe(false);
expect((await client.close()).ok).toBe(false);
expect(producer.calls.map(({ name }) => name)).not.toContain(
"close_database",
);
expect(await workspaces(root)).toHaveLength(1);
});
it("settles a rejected close by the following inventory", async () => {
const released = await fixture();
expect((await released.client.execute("list_procedures", {})).ok).toBe(
true,
);
released.producer.rejectClose = { keepLease: false };
expect((await released.client.close()).ok).toBe(true);
expect(await workspaces(released.root)).toEqual([]);
const retained = await fixture();
expect((await retained.client.execute("list_procedures", {})).ok).toBe(
true,
);
retained.producer.rejectClose = { keepLease: true };
const closed = await retained.client.close();
if (closed.ok) throw new Error("expected retained cleanup");
expect(projectAnalysisError(closed.error).details).toMatchObject({
diagnostics: {
upstream_sessions: {
state: "unverified",
sessions: [{ session_id: "lease1", backend: "worker", owned: true }],
},
},
});
expect(await workspaces(retained.root)).toHaveLength(1);
// An unconfirmed release is retried, not assumed.
retained.producer.rejectClose = undefined;
expect((await retained.client.close()).ok).toBe(true);
expect(
retained.producer.calls.filter(({ name }) => name === "close_database"),
).toHaveLength(2);
expect(await workspaces(retained.root)).toEqual([]);
});
});
describe("Hex-Rays unleased database inventory", () => {
it.each([
["idalib", "available"],
["idat", "unavailable"],
] as const)(
"releases when another client's %s database is not the private copy",
async (backend, status) => {
const { root, producer, client } = await fixture();
producer.peers = [{ path: "/elsewhere/peer.bin", backend, status }];
expect((await client.execute("list_procedures", {})).ok).toBe(true);
expect((await client.close()).ok).toBe(true);
expect(await workspaces(root)).toEqual([]);
},
);
it.each([
["idalib", "available", ""],
["idat", "unavailable", ".i64"],
["idat", "available", ".i64"],
] as const)(
"retains the private workspace while an unleased %s database is %s",
async (backend, status, suffix) => {
const { root, producer, client } = await fixture();
producer.openBackend = backend;
expect((await client.execute("list_procedures", {})).ok).toBe(true);
const path = String(
producer.calls.find(({ name }) => name === "open_database")?.args.path,
);
const listedPath = path + suffix;
producer.peers = [{ path: listedPath, backend, status }];
const closed = await client.close();
expect(closed.ok).toBe(false);
if (closed.ok) throw new Error("expected retained cleanup");
expect(closed.error.cleanupIncomplete).toBe(true);
expect(projectAnalysisError(closed.error).details).toMatchObject({
diagnostics: {
hexrays_close: {
closed: true,
final_lease: status === "unavailable",
idb_path: path + ".i64",
},
upstream_sessions: {
state: "unverified",
sessions: [
{
session_id: "",
backend: "worker",
owned: false,
input_path: listedPath,
is_active: status === "unavailable" ? null : false,
hexrays_status: status,
},
],
},
},
});
expect(producer.leases.size).toBe(0);
expect(await workspaces(root)).toHaveLength(1);
await access(path);
producer.peers = [];
expect((await client.close()).ok).toBe(true);
expect(await workspaces(root)).toEqual([]);
expect(
producer.calls.filter(({ name }) => name === "close_database"),
).toHaveLength(1);
},
);
});
+145
View File
@@ -0,0 +1,145 @@
import { readFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
import { z } from "zod";
import { AnalysisProtocolError } from "../domain/analysisErrorCore.js";
import { sha256Hex } from "../kernel/sha256Hex.js";
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
import type { IdaMcpConnection } from "./IdaMcpConnection.js";
import type { IdaRawObservation } from "./IdaOperationRunner.js";
/** The official Hex-Rays IDA MCP catalog this profile requires. */
export const hexRaysTools = [
"open_database",
"list_databases",
"close_database",
"execute_python",
];
/** Database-supervisor reads that REA's fixed query bridge answers. */
const hexRaysQueries: ReadonlySet<string> = new Set([
"server_health",
"list_funcs",
"lookup_funcs",
"find_regex",
"decompile",
"disasm",
"callees",
"callgraph",
"xrefs_to",
"survey_binary",
]);
const hexRaysBackend = z.enum(["gui", "idalib", "idat"]);
const hexRaysStatus = z.enum([
"available",
"attached",
"current",
"unavailable",
]);
export type HexRaysBackend = z.infer<typeof hexRaysBackend>;
export type HexRaysStatus = z.infer<typeof hexRaysStatus>;
export const hexRaysOpenSchema = z
.object({
instance_id: z.string().min(1),
backend: hexRaysBackend,
status: z.string(),
})
.passthrough();
/**
* Inventory rows. `instance_id` is null when this server holds no lease.
* The row is still a live database owner; null does not mean it has stopped.
* `idat` is a headless owner, distinct from a GUI database.
*/
export const hexRaysListSchema = z
.object({
instances: z.array(
z
.object({
path: z.string(),
backend: hexRaysBackend,
status: hexRaysStatus,
instance_id: z.string().nullable(),
})
.passthrough(),
),
})
.passthrough();
export const hexRaysCloseSchema = z.object({
closed: z.literal(true),
final_lease: z.boolean().optional(),
idb_path: z.string().min(1).optional(),
});
export type HexRaysCloseReceipt = z.infer<typeof hexRaysCloseSchema>;
const executionSchema = z
.object({ result: jsonValueSchema, stdout: z.string(), stderr: z.string() })
.passthrough();
let querySource: { readonly code: string; readonly sha256: string } | undefined;
const queryBridge = () => {
if (querySource !== undefined) return querySource;
const code = readFileSync(
fileURLToPath(
new URL("../../bridge/ida/hexrays_queries.py", import.meta.url),
),
"utf8",
);
querySource = {
code,
sha256: sha256Hex(code),
};
return querySource;
};
/**
* Answer one database-supervisor read through `execute_python` with REA's
* fixed, read-only query bridge. Only the query name and its JSON arguments
* vary; caller text never becomes Python source. The observation records the
* actual upstream tool and the bridge digest instead of the bridge body.
*/
export const runHexRaysQuery = async (
connection: IdaMcpConnection,
instanceId: string,
query: string,
args: Readonly<Record<string, JsonValue>>,
timeoutMs: number,
signal?: AbortSignal,
): Promise<IdaRawObservation> => {
if (!hexRaysQueries.has(query))
throw new AnalysisProtocolError(
`The Hex-Rays IDA MCP profile does not implement ${query}.`,
);
// The lease is selected by instance_id; the supervisor `database` argument has no bridge meaning.
const { database: _database, ...queryArguments } = args;
const bridge = queryBridge();
const timeoutSeconds = timeoutMs / 1000;
const raw = await connection.call(
"execute_python",
{
instance_id: instanceId,
// A JSON string literal is also a valid Python string literal.
code: `${bridge.code}\n_rea_query(${JSON.stringify(query)}, ${JSON.stringify(JSON.stringify(queryArguments))})`,
// Reserve up to five seconds for the reply, including on short budgets.
// Upstream times the initial auto-analysis separately.
timeout: timeoutSeconds - Math.min(5, timeoutSeconds / 2),
},
{ timeoutMs, ...(signal === undefined ? {} : { signal }) },
);
const execution = executionSchema.parse(raw);
return {
tool: "execute_python",
arguments: {
instance_id: instanceId,
query,
query_arguments: queryArguments,
bridge_sha256: bridge.sha256,
},
result: execution.result,
...(execution.stdout === "" && execution.stderr === ""
? {}
: { output: { stdout: execution.stdout, stderr: execution.stderr } }),
};
};
+5 -2
View File
@@ -63,6 +63,9 @@ import {
validateMcpHttpResponse,
} from "../providers/Utf8McpResponse.js";
/** A completed upstream tool reply that reported failure, as opposed to an unreadable or missing reply. */
export class IdaToolRejection extends AnalysisProtocolError {}
/** Injectable MCP boundary used by the provider and transport conformance tests. */
export interface IdaMcpConnection {
connect(): Promise<readonly string[]>;
@@ -200,14 +203,14 @@ const parseIdaTextReply = (text: string): JsonValue => {
*/
export const decodeIdaToolResult = (
input: unknown,
protocol?: "native",
protocol?: "native" | "hexrays",
diagnostic: IdaDiagnosticRedactor = createIdaDiagnosticRedactor(),
): JsonValue => {
const result = toolResultSchema.parse(input);
const blocks = mcpTextBlocks(result.content);
if (result.isError === true) {
const reason = diagnostic.blocks(blocks);
throw new AnalysisProtocolError(
throw new IdaToolRejection(
diagnostic.message("IDA MCP tool failed: ", reason),
{
diagnostics: { reason },
+19 -5
View File
@@ -64,6 +64,8 @@ export interface IdaRawObservation {
readonly tool: string;
readonly arguments: Readonly<Record<string, JsonValue>>;
readonly result: JsonValue;
/** Engine output the upstream reported beside the result, when nonempty. */
readonly output?: { readonly stdout: string; readonly stderr: string };
}
const unknownBody = {
@@ -118,6 +120,11 @@ export class IdaOperationRunner {
readonly surveyAvailable?: boolean;
/** The program identity REA admitted, reported by `list_documents`. */
readonly admittedDocument?: string;
/** Answers modern reads through another upstream tool and reports that actual observation. */
readonly invoke?: (
tool: string,
args: Readonly<Record<string, JsonValue>>,
) => Promise<IdaRawObservation>;
} = {},
) {}
@@ -129,13 +136,20 @@ export class IdaOperationRunner {
throw cancelledBy(tool, this.options.signal);
const scoped =
this.database === undefined ? args : { ...args, database: this.database };
const result = await this.connection.call(tool, scoped, {
signal: this.options.signal,
});
this.raw.push({ tool, arguments: scoped, result });
const observation =
this.options.invoke === undefined
? {
tool,
arguments: scoped,
result: await this.connection.call(tool, scoped, {
signal: this.options.signal,
}),
}
: await this.options.invoke(tool, scoped);
this.raw.push(observation);
if (this.options.signal?.aborted)
throw cancelledBy(tool, this.options.signal);
return result;
return observation.result;
}
async functions(): Promise<IdaFunction[]> {
+4
View File
@@ -49,6 +49,10 @@ export const modernHealthSchema = z
.object({
status: z.literal("ok"),
input_path: z.string().min(1),
input_sha256: z
.string()
.regex(/^[a-f0-9]{64}$/iu)
.nullish(),
idb_path: z.string().nullable(),
imagebase: idaAddressSchema,
auto_analysis_ready: z.boolean().nullable(),
+49 -7
View File
@@ -278,12 +278,28 @@ export class IdaProvider implements AnalysisProviderCandidate {
"IDA does not admit caller-selected GameCube DOL images. Open the target with Ghidra and select format gamecube-dol.",
diagnostics,
};
if (target.kind === "database")
return target.databaseEngine !== "ida"
? {
status: "unsupported",
code: "target_format_unsupported",
reason:
"IDA opens only IDA .idb/.i64 databases. Select the original input binary or an IDA database.",
diagnostics,
}
: {
status: "unknown",
code: null,
reason:
"IDA registration has not been resolved, so whether it can open an existing database is unknown.",
diagnostics,
};
if (target.kind !== "executable")
return {
status: "unsupported",
code: "target_kind_unsupported",
reason:
"IDA MCP integration admits executable inputs, not analysis databases. Select the original input binary.",
"IDA MCP integration admits executable inputs and IDA databases. Select the original input binary.",
diagnostics,
};
if (target.format === "raw-binary")
@@ -321,19 +337,45 @@ export class IdaProvider implements AnalysisProviderCandidate {
options: AnalysisProviderInspectionOptions,
): Promise<ProviderTargetSupport> {
const base = this.inspectTargetSupport(target);
if (base.status === "unsupported" || target.format !== "mach-o-universal")
return base;
// Attached identity is the recorded whole-input digest, which every slice
// of a universal file shares, so it cannot prove the GUI loaded the slice
// admission selected. Headless mode thins that slice into its own input.
// Only IDA databases and universal Mach-O depend on the registration.
if (base.status !== "unknown") return base;
const config = await this.#configuration(options);
if (!config.ok)
return {
status: "unknown",
code: null,
reason: "IDA mode could not be resolved from the registration.",
reason: "IDA registration could not be resolved.",
diagnostics: base.diagnostics,
};
// Only a Hex-Rays lease opens a private database copy; attached GUIs and
// database supervisors have no verified route for an existing database.
if (target.kind === "database") {
if (config.value.protocol !== "hexrays")
return {
status: "unsupported",
code: "target_kind_unsupported",
reason:
'Opening an existing IDA database requires the "hexrays" headless registration. Select the original input binary with this registration.',
diagnostics: base.diagnostics,
};
if (!/\.(?:idb|i64)$/iu.test(target.path))
return {
status: "unsupported",
code: "target_format_unsupported",
reason:
"The Hex-Rays IDA MCP requires a .idb or .i64 filename for a saved database. Select a packed database with its filename suffix.",
diagnostics: base.diagnostics,
};
return {
status: "supported",
code: null,
reason: null,
diagnostics: base.diagnostics,
};
}
// Attached identity is the recorded whole-input digest, which every slice
// of a universal file shares, so it cannot prove the GUI loaded the slice
// admission selected. Headless mode thins that slice into its own input.
if (config.value.mode === "attached")
return {
status: "unsupported",
+3
View File
@@ -42,6 +42,9 @@ export const IDA_LIMITATIONS = Object.freeze([
"Complete function body ranges, typed references, unresolved indirect calls, referenced data, and basic blocks are unavailable in this adapter. Empty unsupported dossier facets are unknown, not observed absence.",
]);
export const IDA_DATABASE_TARGET_LIMITATION =
"Results start from a private copy of the selected IDA database's saved content; unsaved changes held by another IDA session are excluded. The input binary is identified only by the SHA-256 the database records.";
export const IDA_NATIVE_STRING_LIMITATION =
"Native string observations use upstream C-string rendering; other string representations remain unknown.";
+339 -120
View File
@@ -26,14 +26,28 @@ import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
import { err, ok, type Result } from "../domain/result.js";
import type { IdaConfiguration } from "./IdaConfiguration.js";
import { IdaToolRejection, type IdaMcpConnection } from "./IdaMcpConnection.js";
import {
hexRaysCloseSchema,
hexRaysListSchema,
hexRaysOpenSchema,
hexRaysTools,
runHexRaysQuery,
type HexRaysBackend,
type HexRaysCloseReceipt,
type HexRaysStatus,
} from "./IdaHexRaysProtocol.js";
import { idaCompatibilityProfile } from "./IdaConfiguration.js";
import { createIdaDiagnosticRedactor } from "./IdaDiagnosticRedactor.js";
import type { IdaMcpConnection } from "./IdaMcpConnection.js";
import { nativeTools } from "./IdaNativeProtocol.js";
import { readSettledHealth } from "./IdaBusyHealth.js";
import { isX86OnlyTarget } from "./IdaCallGraph.js";
import { IdaOperationRunner } from "./IdaOperationRunner.js";
import {
IdaOperationRunner,
type IdaRawObservation,
} from "./IdaOperationRunner.js";
import {
IDA_DATABASE_TARGET_LIMITATION,
IDA_LIMITATIONS,
idaOperationUnavailableReason,
type IdaOperation,
@@ -106,14 +120,25 @@ interface UpstreamSession {
readonly input_path: string | null;
/** Last inventoried activity; null before upstream reports it. */
readonly is_active: boolean | null;
readonly hexrays_status?: HexRaysStatus;
readonly hexrays_backend?: HexRaysBackend;
}
/** Inventory bindings and protocol-specific evidence used to decide cleanup. */
type InventoriedSession = UpstreamSession & {
readonly owned: boolean;
readonly input_path: string;
readonly referencesWorkspace: boolean;
readonly released: boolean;
};
/** A failed cleanup retains its private workspace and reports the remaining resource. */
class IdaCleanupError extends ProviderAdapterError {
constructor(
path: string,
cause: unknown,
sessions?: readonly UpstreamSession[],
hexRaysClose?: HexRaysCloseReceipt,
) {
super("ida", "close", {
cause,
@@ -133,22 +158,37 @@ class IdaCleanupError extends ProviderAdapterError {
? (cause.diagnostics?.reason ?? cause.message)
: errorMessage(cause),
workspace: path,
...(hexRaysClose === undefined
? {}
: { hexrays_close: jsonValueSchema.parse(hexRaysClose) }),
...(sessions === undefined
? {}
: {
upstream_sessions: {
state: "unverified",
sessions: sessions.map(
({ session_id, backend, owned, input_path, is_active }) => ({
({
session_id,
backend,
owned,
input_path,
is_active,
hexrays_status,
hexrays_backend,
}) => ({
session_id,
backend,
owned,
input_path,
is_active,
...(hexrays_status === undefined ? {} : { hexrays_status }),
...(hexrays_backend === undefined
? {}
: { hexrays_backend }),
}),
),
reason:
"Release of upstream sessions matching the requested session ID or private input was not confirmed; input_path preserves the last observed binding and is null when no inventory has reported it. is_active preserves registry activity and is null when unknown; it does not establish process liveness. A worker outlives its supervisor and may keep running until it finishes and reaches its idle timeout; exiting REA does not stop it. A gui session belongs to an IDA instance REA does not control. An empty session_id means upstream reported none; owned is null when no inventory has reported ownership; an empty list means the requested worker's close was confirmed but no inventory has identified any remaining session.",
"Release of upstream sessions matching the requested session ID or private workspace was not confirmed; input_path preserves the last observed path and is null when no inventory has reported it. is_active preserves registry activity and is null when unknown; it does not establish process liveness. A worker outlives its supervisor and may keep running until it finishes and reaches its idle timeout; exiting REA does not stop it. A gui session belongs to an IDA instance REA does not control. An empty session_id means upstream reported none; owned is null when no inventory has reported ownership; an empty list means the requested worker's close was confirmed but no inventory has identified any remaining session.",
},
}),
},
@@ -168,7 +208,7 @@ class IdaCleanupError extends ProviderAdapterError {
* not control, and the observed teardown shape covers workers only, so a gui
* row keeps blocking release whatever its flags say.
*/
const isReleasedWorkerRow = (entry: {
const isReleasedSupervisorWorker = (entry: {
readonly session_id: string;
readonly owned: boolean;
readonly is_active: boolean;
@@ -267,17 +307,23 @@ export class IdaSessionClient implements AnalysisClient {
#closePromise: Promise<Result<null, AnalysisError>> | undefined;
#workspace: IdaWorkspace | undefined;
#database: string | undefined;
/** The upstream session id this client requested or was assigned; unknown before then. */
#expectedSession: string | undefined;
#hexRaysOpenedBackend: HexRaysBackend | undefined;
#hexRaysCloseReceipt: HexRaysCloseReceipt | undefined;
#databaseCloseCompleted = false;
#openAttempted = false;
#openCompleted = false;
// Only a protocol-defined no-worker reply establishes a rejected open.
#openOutcome: "unverified" | "reply_received" | "no_worker" = "unverified";
#ready = false;
#blockingSessions: readonly UpstreamSession[] | undefined;
#openRejected = false;
#callGraphAdvertised = false;
#surveyAdvertised = false;
#initialIdentity: string | undefined;
#metadata: JsonValue = null;
#lifecycle: JsonValue[] = [];
/** Hex-Rays health reads of the current operation, kept whole beside the parsed metadata. */
#healthObservations: IdaRawObservation[] = [];
constructor(
private readonly config: IdaConfiguration,
@@ -389,6 +435,7 @@ export class IdaSessionClient implements AnalysisClient {
},
]),
);
this.#healthObservations = [];
const failureContext: IdaOperationFailureContext = {
runner: undefined,
metadataBefore: undefined,
@@ -422,13 +469,8 @@ export class IdaSessionClient implements AnalysisClient {
throw cancelledBy(operation, options?.signal);
return ok(
createAnalysisExecution(result, IDA_PROVIDER_IDENTITY, {
rawResult: {
upstream: this.connection.serverInfo(),
metadata_before: before,
metadata_after: after,
observations: jsonValueSchema.parse(runner.raw),
},
limitations: [...IDA_LIMITATIONS, ...runner.limitations],
rawResult: this.#operationRawResult(runner, before, after),
limitations: [...this.#limitations(), ...runner.limitations],
...(runner.relationshipCoverage === undefined
? {}
: { relationshipCoverage: runner.relationshipCoverage }),
@@ -450,11 +492,27 @@ export class IdaSessionClient implements AnalysisClient {
}
#runner(options: ExecutionOptions | undefined): IdaOperationRunner {
const protocol = idaCompatibilityProfile(this.config).protocol;
const database = this.#database;
return new IdaOperationRunner(
this.connection,
idaCompatibilityProfile(this.config).protocol,
this.#database,
// Hex-Rays answers database-supervisor reads through its query bridge.
protocol === "hexrays" ? "modern" : protocol,
database,
{
...(protocol === "hexrays" && database !== undefined
? {
invoke: (tool, args) =>
runHexRaysQuery(
this.connection,
database,
tool,
args,
this.config.timeoutMs,
options?.signal,
),
}
: {}),
regexMatchingDeadline: this.regexSettings?.regexMatchingDeadline,
regexWorkerHeapRequest: this.regexSettings?.regexWorkerHeapRequest,
signal: options?.signal,
@@ -467,6 +525,12 @@ export class IdaSessionClient implements AnalysisClient {
);
}
#limitations(): readonly string[] {
return this.target.kind === "database"
? [...IDA_LIMITATIONS, IDA_DATABASE_TARGET_LIMITATION]
: IDA_LIMITATIONS;
}
#health(metadata: JsonValue) {
return ok(
createAnalysisExecution(
@@ -480,7 +544,7 @@ export class IdaSessionClient implements AnalysisClient {
},
IDA_PROVIDER_IDENTITY,
{
limitations: IDA_LIMITATIONS,
limitations: this.#limitations(),
...(this.profile === undefined
? {}
: { analysisProfile: this.profile }),
@@ -554,8 +618,11 @@ export class IdaSessionClient implements AnalysisClient {
runner.raw.length > 0 &&
metadataBefore !== undefined
) {
const observations = jsonValueSchema.parse(runner.raw);
const upstream = this.connection.serverInfo();
const rawResult = this.#operationRawResult(
runner,
metadataBefore,
metadataAfter,
);
const binding =
context.postOperationIdentityCheck !== "verified"
? {
@@ -574,7 +641,7 @@ export class IdaSessionClient implements AnalysisClient {
result: {
status: "partial",
failed_operation: operation,
observations,
observations: rawResult.observations,
metadata_before: metadataBefore,
target_binding: binding,
...(metadataAfter === undefined
@@ -582,18 +649,13 @@ export class IdaSessionClient implements AnalysisClient {
: { metadata_after: metadataAfter }),
},
rawResult: {
upstream,
observations,
metadata_before: metadataBefore,
...(metadataAfter === undefined
? {}
: { metadata_after: metadataAfter }),
...rawResult,
post_operation_identity_check: context.postOperationIdentityCheck,
},
confidence: "observed",
authority: "external-service",
limitations: [
...IDA_LIMITATIONS,
...this.#limitations(),
...runner.limitations,
"The requested IDA operation failed after these completed upstream replies; the partial Evidence does not establish a complete result.",
"Replies are bound to the selected target only by the pre-operation identity check unless post_operation_identity_check is verified.",
@@ -645,17 +707,32 @@ export class IdaSessionClient implements AnalysisClient {
}
async #initialize(): Promise<void> {
const tools = new Set(await this.connection.connect());
this.#callGraphAdvertised = tools.has("callgraph");
this.#surveyAdvertised = tools.has("survey_binary");
const profile = idaCompatibilityProfile(this.config);
const tools = new Set(await this.connection.connect());
const protocol = profile.protocol;
// REA's query bridge implements both reads for the Hex-Rays profile.
this.#callGraphAdvertised =
protocol === "hexrays" || tools.has("callgraph");
this.#surveyAdvertised =
protocol === "hexrays" || tools.has("survey_binary");
const expected = {
native: nativeTools,
modern: modernTools,
}[profile.protocol];
hexrays: hexRaysTools,
}[protocol];
const missing = expected.filter((name) => !tools.has(name));
if (missing.length > 0) {
const summary = `IDA MCP ${profile.diagnosticLabel} compatibility profile is missing tools: ${missing.join(", ")}. Attached mode requires the native IDA MCP tool catalog; headless mode requires the database supervisor profile. See docs/providers/ida-provider.md.`;
// A registration for another profile can still point at the official
// server; name the registration that fits instead of a reinstall.
const servesHexRays =
protocol !== "hexrays" && hexRaysTools.every((name) => tools.has(name));
const hexRaysHint = servesHexRays
? ' This server serves the Hex-Rays IDA MCP catalog; register it with "mode": "headless" and "protocol": "hexrays".'
: "";
const summary =
protocol === "hexrays"
? `IDA MCP Hex-Rays compatibility profile is missing tools: ${missing.join(", ")}. The Hex-Rays profile requires the official Hex-Rays IDA MCP tool catalog. See docs/providers/ida-provider.md.`
: `IDA MCP ${profile.diagnosticLabel} compatibility profile is missing tools: ${missing.join(", ")}. Attached mode requires the native IDA MCP tool catalog; headless mode requires the database supervisor profile.${hexRaysHint} See docs/providers/ida-provider.md.`;
// The caller cannot act on a profile mismatch it never sees, so the
// missing names travel as adapter diagnostics rather than a bare message.
throw new ProviderAdapterError("ida", "initialize", {
@@ -665,8 +742,10 @@ export class IdaSessionClient implements AnalysisClient {
mode: this.config.mode,
expected_profile: profile.diagnosticIdentity,
missing_tools: [...missing],
recovery:
"Install an IDA MCP build that serves the selected profile; see docs/providers/ida-provider.md.",
advertised_tools: [...tools].sort(),
recovery: servesHexRays
? 'Set "mode": "headless" and "protocol": "hexrays" in the registration; see docs/providers/ida-provider.md.'
: "Install an IDA MCP build that serves the selected profile; see docs/providers/ida-provider.md.",
},
});
}
@@ -676,66 +755,174 @@ export class IdaSessionClient implements AnalysisClient {
this.config.workspaceRoot,
);
await this.#workspace.copyInput();
this.#openAttempted = true;
const raw = await this.connection.call("idb_open", {
input_path: this.#workspace.inputPath,
mode: "force_headless",
run_auto_analysis: true,
build_caches: true,
init_hexrays: true,
preferred_session_id: this.#workspace.sessionId,
});
this.#openCompleted = true;
// A completed but malformed/positive open may still own a live Worker.
// Only an explicit producer rejection keeps the old no-worker branch.
this.#openRejected = rejectedOpenDatabaseSchema.safeParse(raw).success;
this.#lifecycle.push(raw);
const opened = openDatabaseSchema.parse(raw);
if (
!sameIdaHostPath(opened.session.input_path, this.#workspace.inputPath)
)
throw new IdaIdentityRefusal(
"IDA opened a different input than the private admitted target copy.",
"Check the selected input and upstream worker binding. Retry only after retained private-worker cleanup is confirmed.",
"opened_input",
);
if (opened.session.session_id !== this.#workspace.sessionId)
throw new IdaIdentityRefusal(
"IDA returned an adopted or unexpected session instead of the requested private worker.",
"Use an IDA supervisor that honors the requested private worker session ID. Confirm retained cleanup before reopening the target.",
"worker_session",
);
const inventory = databaseListSchema.parse(
await this.connection.call("idb_list", {}),
);
this.#lifecycle.push(jsonValueSchema.parse(inventory));
const workspace = this.#workspace;
this.#openAttempted = true;
const session =
protocol === "hexrays"
? await this.#openHexRays(workspace)
: await this.#openSupervisor(workspace);
const inventory = await this.#inventory(workspace);
this.#lifecycle.push(inventory.raw);
this.#recordBlockingSessions(
inventory.sessions.filter(
(entry) =>
entry.session_id === workspace.sessionId ||
sameIdaHostPath(entry.input_path, workspace.inputPath),
(entry) => entry.session_id === session || entry.referencesWorkspace,
),
);
const entry = inventory.sessions.find(
({ session_id }) => session_id === opened.session.session_id,
({ session_id }) => session_id === session,
);
if (
entry?.owned !== true ||
entry.backend !== "worker" ||
(protocol === "hexrays" &&
entry.hexrays_backend !== this.#hexRaysOpenedBackend) ||
entry.is_active !== true ||
!sameIdaHostPath(entry.input_path, this.#workspace.inputPath)
!sameIdaHostPath(entry.input_path, workspace.inputPath)
)
throw new IdaIdentityRefusal(
"IDA did not return an active owned headless worker for the private input copy.",
"Configure the supervisor to return an active owned worker for the private input. Confirm retained cleanup before reopening the target.",
"Configure the server to report the same owned worker for the private input in its open and inventory replies. Confirm retained cleanup before reopening the target.",
"owned_worker_binding",
);
this.#database = opened.session.session_id;
this.#database = session;
}
this.#ready = true;
}
/** Request the private worker from a database supervisor; returns its session id. */
async #openSupervisor(workspace: IdaWorkspace): Promise<string> {
this.#expectedSession = workspace.sessionId;
const raw = await this.connection.call("idb_open", {
input_path: workspace.inputPath,
mode: "force_headless",
run_auto_analysis: true,
build_caches: true,
init_hexrays: true,
preferred_session_id: workspace.sessionId,
});
this.#openOutcome = rejectedOpenDatabaseSchema.safeParse(raw).success
? "no_worker"
: "reply_received";
this.#lifecycle.push(raw);
const opened = openDatabaseSchema.parse(raw);
if (!sameIdaHostPath(opened.session.input_path, workspace.inputPath))
throw new IdaIdentityRefusal(
"IDA opened a different input than the private admitted target copy.",
"Check the selected input and upstream worker binding. Retry only after retained private-worker cleanup is confirmed.",
"opened_input",
);
if (opened.session.session_id !== workspace.sessionId)
throw new IdaIdentityRefusal(
"IDA returned an adopted or unexpected session instead of the requested private worker.",
"Use an IDA supervisor that honors the requested private worker session ID. Confirm retained cleanup before reopening the target.",
"worker_session",
);
return opened.session.session_id;
}
/**
* Lease a headless worker for the private input copy. Hex-Rays assigns the
* instance id, so the binding is the returned id plus its inventory row.
*/
async #openHexRays(workspace: IdaWorkspace): Promise<string> {
// The MCP tool error only reports that the request failed. Nexus can
// return a startup error while a worker is still starting.
const raw = await this.connection.call("open_database", {
path: workspace.inputPath,
set_current: false,
});
this.#openOutcome = "reply_received";
this.#lifecycle.push(raw);
const opened = hexRaysOpenSchema.parse(raw);
this.#expectedSession = opened.instance_id;
this.#hexRaysOpenedBackend = opened.backend;
if (opened.backend === "gui")
throw new AnalysisProtocolError(
"IDA attached a GUI database instead of a private headless worker for the private input copy.",
);
return opened.instance_id;
}
/** Normalize upstream inventory and derive the path scope for release checks. */
async #inventory(workspace: IdaWorkspace): Promise<{
readonly raw: JsonValue;
readonly sessions: readonly InventoriedSession[];
}> {
if (idaCompatibilityProfile(this.config).protocol !== "hexrays") {
const raw = await this.connection.call("idb_list", {});
return {
raw,
sessions: databaseListSchema.parse(raw).sessions.map((entry) => ({
...entry,
referencesWorkspace: sameIdaHostPath(
entry.input_path,
workspace.inputPath,
),
released: isReleasedSupervisorWorker(entry),
})),
};
}
const raw = await this.connection.call("list_databases", {});
return {
raw,
sessions: hexRaysListSchema.parse(raw).instances.map((entry) => ({
session_id: entry.instance_id ?? "",
backend: entry.backend === "gui" ? "gui" : "worker",
owned: entry.instance_id !== null,
input_path: entry.path,
is_active:
entry.status === "unavailable"
? null
: entry.status === "current" || entry.status === "attached",
hexrays_status: entry.status,
hexrays_backend: entry.backend,
// Nexus may list the private database path in place of the input.
referencesWorkspace: workspace.containsPath(entry.path),
// Every listed workspace path blocks release, including unleased rows.
released: false,
})),
};
}
async #readHexRaysHealth(
database: string,
signal?: AbortSignal,
): Promise<JsonValue> {
const observation = await runHexRaysQuery(
this.connection,
database,
"server_health",
{},
this.config.timeoutMs,
signal,
);
this.#healthObservations.push(observation);
return observation.result;
}
#operationRawResult(
runner: IdaOperationRunner,
metadataBefore: JsonValue,
metadataAfter: JsonValue | undefined,
) {
return {
upstream: this.connection.serverInfo(),
metadata_before: metadataBefore,
...(metadataAfter === undefined ? {} : { metadata_after: metadataAfter }),
observations: jsonValueSchema.parse(runner.raw),
...(this.#hexRaysOpenedBackend === undefined
? {}
: { worker_backend: this.#hexRaysOpenedBackend }),
...(this.#healthObservations.length === 0
? {}
: {
health_observations: jsonValueSchema.parse(
this.#healthObservations,
),
}),
};
}
async #nativeMetadata(signal?: AbortSignal): Promise<JsonValue> {
if (this.connection.readResource === undefined)
throw new AnalysisProtocolError(
@@ -772,18 +959,34 @@ export class IdaSessionClient implements AnalysisClient {
"Close the REA analysis session and reopen the selected target using the configured headless supervisor.",
"database_binding",
);
const raw = await readSettledHealth(this.connection, {
database: this.#database,
timeoutMs: this.config.timeoutMs,
signal: options?.signal,
});
// Hex-Rays execute_python waits for initial auto-analysis before running.
const raw =
idaCompatibilityProfile(this.config).protocol === "hexrays"
? await this.#readHexRaysHealth(this.#database, options?.signal)
: await readSettledHealth(this.connection, {
database: this.#database,
timeoutMs: this.config.timeoutMs,
signal: options?.signal,
});
const metadata = modernHealthSchema.parse(raw);
this.#metadata = raw;
onObserved?.(raw);
// A database records the input it was created from and is rewritten by
// its worker, so the private copy is bound by the opened database path;
// copyInput already verified the bytes it admitted.
if (
!sameIdaHostPath(metadata.input_path, this.#workspace.inputPath) ||
(await idaFileDigest(this.#workspace.inputPath)) !==
this.#workspace.inputSha256
this.target.kind === "database"
? metadata.idb_path === null ||
!sameIdaHostPath(metadata.idb_path, this.#workspace.inputPath)
: !sameIdaHostPath(metadata.input_path, this.#workspace.inputPath) ||
(this.#hexRaysOpenedBackend === "idat" &&
(metadata.idb_path === null ||
!this.#workspace.containsPath(metadata.idb_path))) ||
(metadata.input_sha256 != null &&
metadata.input_sha256.toLowerCase() !==
this.#workspace.inputSha256) ||
(await idaFileDigest(this.#workspace.inputPath)) !==
this.#workspace.inputSha256
)
throw new IdaIdentityRefusal(
"IDA headless input identity changed after target admission.",
@@ -847,14 +1050,14 @@ export class IdaSessionClient implements AnalysisClient {
if (
!this.#openAttempted ||
this.#workspace === undefined ||
this.#openRejected
this.#openOutcome === "no_worker"
)
return undefined;
return this.#databaseCloseCompleted
? []
: [
{
session_id: this.#workspace.sessionId,
session_id: this.#expectedSession ?? "",
backend: "worker",
owned: null,
input_path: null,
@@ -876,22 +1079,27 @@ export class IdaSessionClient implements AnalysisClient {
#recordBlockingSessions(
entries: readonly (UpstreamSession & { readonly owned: boolean })[],
): boolean {
this.#blockingSessions =
entries.length > 0
? entries.map(
({ session_id, backend, owned, input_path, is_active }) => ({
session_id,
backend,
owned,
input_path,
is_active,
}),
)
: undefined;
this.#blockingSessions = entries.length > 0 ? entries : undefined;
return entries.length > 0;
}
async #closeDatabase(database: string): Promise<void> {
/** Release the session; false when upstream rejected the release and only inventory can settle it. */
async #closeDatabase(database: string): Promise<boolean> {
if (idaCompatibilityProfile(this.config).protocol === "hexrays") {
try {
this.#hexRaysCloseReceipt = hexRaysCloseSchema.parse(
await this.connection.call("close_database", {
instance_id: database,
}),
);
return true;
} catch (cause: unknown) {
// A rejected release, such as an already reaped or busy lease, is
// settled by the inventory read that follows and retried otherwise.
if (!(cause instanceof IdaToolRejection)) throw cause;
return false;
}
}
const response = await this.connection.call("idb_close", {
database,
save: false,
@@ -900,7 +1108,7 @@ export class IdaSessionClient implements AnalysisClient {
if (!closed.success) {
if (!absentDatabaseCloseSchema(database).safeParse(response).success)
throw closed.error;
return;
return true;
}
if (
closed.data.session_id !== database ||
@@ -911,6 +1119,7 @@ export class IdaSessionClient implements AnalysisClient {
throw new AnalysisProtocolError(
"IDA database close did not confirm the requested owned, unsaved session release.",
);
return true;
}
async #closeOnce(): Promise<Result<null, AnalysisError>> {
@@ -918,17 +1127,23 @@ export class IdaSessionClient implements AnalysisClient {
await this.#tail;
if (this.#closed) return ok(null);
try {
if (this.#workspace !== undefined && this.#openAttempted) {
const workspace = this.#workspace;
if (workspace !== undefined && this.#openAttempted) {
if (this.#database === undefined) {
const inventory = databaseListSchema.parse(
await this.connection.call("idb_list", {}),
);
const workspace = this.#workspace;
const inventory = await this.#inventory(workspace);
const expected = this.#expectedSession;
// REA's own Hex-Rays stdio server leases only what REA opened, so a
// late lease on the private input is REA's even without a reply id.
const adoptByPath =
expected === undefined &&
idaCompatibilityProfile(this.config).protocol === "hexrays";
this.#database = inventory.sessions.find(
(entry) =>
entry.owned &&
entry.backend === "worker" &&
entry.session_id === workspace.sessionId &&
(this.#hexRaysOpenedBackend === undefined ||
entry.hexrays_backend === this.#hexRaysOpenedBackend) &&
(entry.session_id === expected || adoptByPath) &&
sameIdaHostPath(entry.input_path, workspace.inputPath),
)?.session_id;
// Every same-input session and any entry under the requested ID,
@@ -937,8 +1152,7 @@ export class IdaSessionClient implements AnalysisClient {
const blocked = this.#recordBlockingSessions(
inventory.sessions.filter(
(entry) =>
entry.session_id === workspace.sessionId ||
sameIdaHostPath(entry.input_path, workspace.inputPath),
entry.session_id === expected || entry.referencesWorkspace,
),
);
if (this.#database === undefined && blocked)
@@ -947,40 +1161,44 @@ export class IdaSessionClient implements AnalysisClient {
);
if (
this.#database === undefined &&
this.#openCompleted &&
!this.#openRejected
this.#openOutcome === "reply_received"
)
throw new AnalysisProtocolError(
"IDA open returned without a verified private worker binding. An empty session inventory does not prove that its Worker exited; the private workspace was retained.",
);
}
if (this.#database !== undefined) {
if (!this.#databaseCloseCompleted) {
await this.#closeDatabase(this.#database);
if (
!this.#databaseCloseCompleted &&
(await this.#closeDatabase(this.#database))
) {
this.#databaseCloseCompleted = true;
this.#forgetReleasedSession(this.#database);
}
const inventory = databaseListSchema.parse(
await this.connection.call("idb_list", {}),
);
const inventory = await this.#inventory(workspace);
const remaining = inventory.sessions.filter(
(entry) =>
!isReleasedWorkerRow(entry) &&
!entry.released &&
(entry.session_id === this.#database ||
sameIdaHostPath(
entry.input_path,
this.#workspace?.inputPath ?? "",
)),
entry.referencesWorkspace),
);
if (this.#recordBlockingSessions(remaining))
throw new AnalysisProtocolError(
"IDA worker remains registered after close.",
);
// An unconfirmed close is settled once inventory shows the release.
this.#databaseCloseCompleted = true;
this.#database = undefined;
}
if (!this.#openCompleted)
if (this.#openOutcome === "unverified")
throw new AnalysisProtocolError(
"IDA database open did not return a completed response. Worker inventory cannot prove that the request has stopped; the private workspace was retained.",
"IDA worker startup remains unverified. A worker may still be starting even when inventory is empty. The private workspace was retained.",
{
diagnostics: {
recovery:
"Check the upstream IDA worker and confirm it has stopped before manually removing the retained workspace. See docs/providers/ida-provider.md.",
},
},
);
this.#openAttempted = false;
}
@@ -995,6 +1213,7 @@ export class IdaSessionClient implements AnalysisClient {
path,
cause,
this.#unreleasedSessions(),
this.#hexRaysCloseReceipt,
);
const client = this;
// The failure reads this client's later successful close.
+17 -2
View File
@@ -5,7 +5,11 @@ import { HOST_PLATFORM } from "../platform/HostPlatform.js";
import { open, realpath, stat, type FileHandle } from "node:fs/promises";
import { tmpdir } from "node:os";
import { basename, isAbsolute, join, normalize } from "node:path";
import { absoluteCallerPath } from "../filesystem/callerPath.js";
import {
absoluteCallerPath,
isQualifiedCallerPath,
} from "../filesystem/callerPath.js";
import { isPathWithinRoot } from "../domain/localPath.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import { AnalysisProtocolError } from "../domain/analysisErrorCore.js";
import { ConfigurationError } from "../domain/configurationErrors.js";
@@ -42,7 +46,11 @@ export const resolveIdaWorkspaceParent = async (
return realpath(root);
};
/** Private input copy isolates upstream database and sidecar writes from the original. */
/**
* Private input copy isolates upstream database and sidecar writes from the
* original. An IDA database target is copied whole, so the worker unpacks and
* releases only the copy; the selected database is never opened for writing.
*/
export class IdaWorkspace {
readonly sessionId = `rea-${randomUUID()}`;
#inputSha256: string | undefined;
@@ -59,6 +67,13 @@ export class IdaWorkspace {
}
/** SHA-256 of the private input bytes copyInput admitted; undefined until prepared. */
/** Upstream publishes absolute, canonical host paths for its databases. */
containsPath(path: string): boolean {
return (
isQualifiedCallerPath(path) && isPathWithinRoot(this.directory, path)
);
}
get inputSha256(): string | undefined {
return this.#inputSha256;
}
+38 -1
View File
@@ -1157,7 +1157,7 @@ describe("app bundle canonical containment", () => {
);
});
describe("binary target I/O: explicit kinds and executable headers", () => {
describe("binary target I/O: explicit kinds and database identity", () => {
it("honors an explicit database kind without relying on the file suffix", async () => {
const directory = await createTestTempDirectory("rea-target-");
await writeFile(join(directory, "saved-analysis"), "database");
@@ -1169,9 +1169,46 @@ describe("binary target I/O: explicit kinds and executable headers", () => {
expect(result.ok && result.value).toMatchObject({
kind: "database",
format: "analysis-database",
databaseEngine: null,
});
});
it("identifies IDA databases by signature and Hopper databases by suffix", async () => {
const directory = await createTestTempDirectory("rea-target-");
const header = (magic: string) =>
Buffer.concat([Buffer.from(magic, "latin1"), Buffer.alloc(28)]);
await writeFile(join(directory, "renamed.bin"), header("IDA2"));
await writeFile(join(directory, "legacy.idb"), header("IDA1"));
await writeFile(join(directory, "sample.hop"), header("IDA9"));
await writeFile(join(directory, "spoofed.i64"), header("IDA9"));
const parse = (name: string) =>
parseBinaryTarget(name, { cwd: directory, hostArchitecture: "arm64" });
for (const [name, databaseEngine] of [
["renamed.bin", "ida"],
["legacy.idb", "ida"],
["sample.hop", "hopper"],
] as const)
expect(await parse(name)).toMatchObject({
ok: true,
value: {
kind: "database",
format: "analysis-database",
databaseEngine,
},
});
// A suffix alone does not make an IDA database.
expect((await parse("spoofed.i64")).ok).toBe(false);
// An explicit executable kind is not overridden by the signature.
expect(
await parseBinaryTarget("renamed.bin", {
cwd: directory,
targetKind: "executable",
}),
).toMatchObject({ ok: false });
});
});
describe("binary target I/O: executable headers", () => {
it("reads a PE header beyond the initial probe", async () => {
const directory = await createTestTempDirectory("rea-target-");
const path = join(directory, "delayed.exe");
@@ -106,7 +106,12 @@ const targets: readonly BinaryTarget[] = [
entryPoint: 0x80003100,
},
},
{ ...identity, kind: "database", format: "analysis-database" },
{
...identity,
kind: "database",
format: "analysis-database",
databaseEngine: null,
},
...([...ZIP_PACKAGE_FORMATS, "asar", "godot-pck", "dmg", "pkg"] as const).map(
(format) => ({ ...identity, kind: "archive" as const, format }),
),
@@ -18,6 +18,7 @@ const bridge = "package/bridge/hopper_bridge.py";
const members = [
bridge,
"package/bridge/cutter/rea_bridge.py",
"package/bridge/ida/hexrays_queries.py",
"package/bridge/agentenv/capture.py",
"package/bridge/agentenv/computer.py",
"package/bridge/agentenv/solve.py",
@@ -32,6 +32,7 @@ const exec = promisify(execFile);
const packedFiles = [
"package/bridge/hopper_bridge.py",
"package/bridge/cutter/rea_bridge.py",
"package/bridge/ida/hexrays_queries.py",
"package/bridge/agentenv/capture.py",
"package/bridge/agentenv/computer.py",
"package/bridge/agentenv/solve.py",
@@ -0,0 +1,24 @@
import { expect, it } from "vitest";
import { privateIdaInput } from "../../../../scripts/lib/ida-private-input.mjs";
const target = "/samples/target.exe.i64";
const metadata = {
// A database saved beside its executable still records that executable.
input_path: "/samples/target.exe",
idb_path: "/tmp/rea-ida-1/target.exe.i64",
};
it("binds a database target's private copy by its opened database", () => {
expect(privateIdaInput(metadata, target, true)).toBe(metadata.idb_path);
expect(() =>
privateIdaInput({ ...metadata, idb_path: null }, target, true),
).toThrow();
});
it("binds an executable target's private copy by its input", () => {
const input = { input_path: "/tmp/rea-ida-1/target.exe", idb_path: null };
expect(privateIdaInput(input, "/samples/target.exe", false)).toBe(
input.input_path,
);
expect(() => privateIdaInput(input, input.input_path, false)).toThrow();
});
@@ -583,6 +583,7 @@ describe("observe_native_calls failures", () => {
sha256: target.sha256,
kind: "database",
format: "analysis-database",
databaseEngine: null,
})
.execute("observe_native_calls", { breakpoints: [] });
expect(!database.ok && database.error).toBeInstanceOf(
@@ -22,6 +22,7 @@ const target: BinaryTarget = {
path: "/fixture",
kind: "database",
format: "analysis-database",
databaseEngine: null,
sha256: "0".repeat(64),
};
+149 -7
View File
@@ -1,4 +1,5 @@
import { rm, writeFile } from "node:fs/promises";
import { createHash } from "node:crypto";
import { readdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
import { snapshotExecution } from "../../src/domain/analysisSnapshot.fixture.js";
import { join } from "node:path";
import { afterEach, describe, expect, it } from "vitest";
@@ -16,6 +17,9 @@ import { createEvidence } from "../../src/domain/evidence.js";
import { createEvidenceBundle } from "../../src/domain/evidenceBundle.js";
import { createAnalysisExecution } from "../../src/ports/AnalysisProvider.js";
import { EnhancedTools } from "../../src/application/EnhancedTools.js";
import { IDA_DATABASE_TARGET_LIMITATION } from "../../src/ida/IdaProviderCapabilities.js";
import type { BinaryTarget } from "../../src/domain/binaryTargetTypes.js";
import { RecordingHexRaysIdaMcp } from "../fixtures/idaHexRaysMcp.js";
import { IDA_PROVIDER_IDENTITY } from "../../src/ida/IdaProviderMetadata.js";
import { parseBinaryTarget } from "../../src/application/BinaryTargetResolver.js";
import { fat } from "../../src/domain/binaryTarget.fixture.js";
@@ -158,12 +162,16 @@ describe("IDA provider composition", () => {
const producer = new RecordingIdaMcp(target);
const provider = new IdaProvider(config.value, {}, () => producer);
expect(
provider.inspectTargetSupport({
path: target.path,
sha256: target.sha256,
kind: "database",
format: "analysis-database",
}),
await provider.inspectTargetSupportWithOptions(
{
path: target.path,
sha256: target.sha256,
kind: "database",
format: "analysis-database",
databaseEngine: "ida",
},
{},
),
).toMatchObject({ status: "unsupported", code: "target_kind_unsupported" });
const session = createTestBinarySession(provider);
expect((await session.open(target.path)).ok).toBe(true);
@@ -404,3 +412,137 @@ describe("IDA binary_overview execution", () => {
expect((await session.close()).ok).toBe(true);
});
});
describe("IDA database targets", () => {
const hexRaysSession = async () => {
const { root } = await createIdaTarget();
roots.push(root);
const registration = join(root, "registration.json");
await writeFile(
registration,
JSON.stringify({
command: "uvx",
args: ["ida-mcp", "stdio"],
mode: "headless",
protocol: "hexrays",
workspaceRoot: root,
}),
);
const config = parseConfig({ REA_IDA_MCP_CONFIG: registration });
if (!config.ok) throw config.error;
const bytes = Buffer.concat([
Buffer.from("IDA2", "latin1"),
Buffer.alloc(60, 7),
]);
const path = await realpath(root).then((dir) =>
join(dir, "target.exe.i64"),
);
await writeFile(path, bytes);
const target: BinaryTarget = {
path,
sha256: createHash("sha256").update(bytes).digest("hex"),
kind: "database",
format: "analysis-database",
databaseEngine: "ida",
};
const producer = new RecordingHexRaysIdaMcp(target);
producer.recordedInputPath = "/original/target.exe";
const provider = new IdaProvider(config.value, {}, () => producer);
return {
root,
path,
bytes,
target,
producer,
provider,
session: new BinarySession(
SessionProviderRouter.selectable(
new AnalysisProviderRegistry([provider]),
[],
),
),
};
};
it("analyzes a private database copy through idat and leaves the selected database unchanged", async () => {
const { root, path, bytes, target, producer, provider, session } =
await hexRaysSession();
producer.openBackend = "idat";
expect(
provider.inspectTargetSupport({
path: join(root, "sample.hop"),
sha256: "a".repeat(64),
kind: "database",
format: "analysis-database",
databaseEngine: "hopper",
}),
).toMatchObject({
status: "unsupported",
code: "target_format_unsupported",
});
// The registration protocol decides database support, so only the
// registration-aware check can admit an IDA database.
expect(provider.inspectTargetSupport(target)).toMatchObject({
status: "unknown",
});
expect(
await provider.inspectTargetSupportWithOptions(target, {}),
).toMatchObject({ status: "supported" });
const opened = await session.open(path, { providerId: "ida" });
expect(opened).toMatchObject({
ok: true,
value: { kind: "database", databaseEngine: "ida" },
});
const listed = await session.execute("list_procedures", {});
if (!listed.ok) throw listed.error;
expect(listed.value.limitations).toContain(IDA_DATABASE_TARGET_LIMITATION);
const open = producer.calls.find(({ name }) => name === "open_database");
expect(open?.args.path).not.toBe(path);
expect(String(open?.args.path).replaceAll("\\", "/")).toMatch(
/rea-ida-[^/]+\/target\.exe\.i64$/u,
);
expect((await session.close()).ok).toBe(true);
// The worker repacked only its private copy, which REA then removed.
expect(producer.leases.size).toBe(0);
expect((await readFile(path)).equals(bytes)).toBe(true);
expect(
(await readdir(root)).filter((name) => name.startsWith("rea-ida-")),
).toEqual([]);
});
it("refuses a signature-recognized database without the upstream filename suffix before opening it", async () => {
const { root, bytes, producer, session } = await hexRaysSession();
const path = join(root, "saved-database");
await writeFile(path, bytes);
const opened = await session.open(path, { providerId: "ida" });
expect(opened).toMatchObject({
ok: false,
error: {
_tag: "ProviderSelectionError",
rejections: [
{
providerId: "ida",
code: "target_format_unsupported",
reason: expect.stringContaining(".idb or .i64"),
},
],
},
});
expect(producer.calls).toEqual([]);
});
it("binds the database by its opened path, not the input it records", async () => {
const { path, producer, session } = await hexRaysSession();
expect((await session.open(path, { providerId: "ida" })).ok).toBe(true);
expect((await session.execute("list_procedures", {})).ok).toBe(true);
producer.reads.idbPath = "/elsewhere/other.i64";
const moved = await session.execute("list_procedures", {});
expect(moved.ok).toBe(false);
if (!moved.ok)
expect(moved.error.message).toContain("input identity changed");
await session.close();
});
});
+173
View File
@@ -0,0 +1,173 @@
import { appendFile } from "node:fs/promises";
import { z } from "zod";
import type { BinaryTarget } from "../../src/domain/binaryTargetTypes.js";
import { jsonValueSchema, type JsonValue } from "../../src/domain/jsonValue.js";
import {
IdaToolRejection,
type IdaMcpConnection,
} from "../../src/ida/IdaMcpConnection.js";
import { RecordingIdaMcp } from "./idaMcp.js";
const QUERY_LINE = /\n_rea_query\(("[^"\n]*"), ("(?:[^"\\\n]|\\.)*")\)$/u;
/**
* Stateful Hex-Rays IDA MCP fixture at the real connection seam. Leases are
* tracked like the official server; `execute_python` decodes REA's trailing
* query line and answers through the database-supervisor fixture's reads.
*/
export class RecordingHexRaysIdaMcp implements IdaMcpConnection {
readonly calls: {
name: string;
args: Readonly<Record<string, JsonValue>>;
}[] = [];
readonly reads: RecordingIdaMcp;
/** Leases this server holds, keyed by instance id. */
readonly leases = new Map<string, { path: string; backend: string }>();
/** Databases other clients hold; listed without an instance id. */
peers: {
path: string;
backend: string;
status?: "available" | "attached" | "current" | "unavailable";
}[] = [];
tools = [
"open_database",
"list_databases",
"close_database",
"execute_python",
"reference",
"save_database",
];
openBackend = "idalib";
inventoryBackend: string | undefined;
openToolError: string | undefined;
/** Lose the open reply in transport, optionally after the lease exists. */
loseOpenReply: { leased: boolean } | undefined;
/** Reject close_database; `keepLease` leaves the worker registered. */
rejectClose: { keepLease: boolean } | undefined;
/**
* Input path an opened database records. When set, an open is treated as an
* existing database: health reports this input and the opened path as the
* database, and releasing the lease repacks the opened file like idalib.
*/
recordedInputPath: string | undefined;
recordedInputSha256: string | null = null;
/** Engine output reported beside every execute_python result. */
engineOutput = { stdout: "", stderr: "" };
closes = 0;
detaches = 0;
#nextId = 0;
constructor(readonly target: BinaryTarget) {
this.reads = new RecordingIdaMcp(target, "headless");
}
async connect() {
return this.tools;
}
serverInfo() {
return { name: "ida-mcp", version: "fixture" };
}
async close() {
this.closes += 1;
}
detach() {
this.detaches += 1;
}
async call(
name: string,
args: Readonly<Record<string, JsonValue>>,
): Promise<JsonValue> {
this.calls.push({ name, args: structuredClone(args) });
switch (name) {
case "open_database": {
if (this.openToolError !== undefined)
throw new IdaToolRejection(this.openToolError);
const path = z.string().parse(args.path);
const instance_id = `lease${(this.#nextId += 1)}`;
if (this.loseOpenReply?.leased !== false)
this.leases.set(instance_id, { path, backend: this.openBackend });
this.reads.inputPath = this.recordedInputPath ?? path;
this.reads.idbPath =
this.recordedInputPath === undefined ? undefined : path;
if (this.loseOpenReply !== undefined)
throw new Error("Fixture transport lost the open reply");
return {
instance_id,
backend: this.openBackend,
status: "attached",
recovery: "none",
};
}
case "list_databases":
return {
instances: [
...[...this.leases].map(([instance_id, lease]) => ({
path: lease.path,
backend: this.inventoryBackend ?? lease.backend,
status: "attached",
instance_id,
error: null,
})),
...this.peers.map((peer) => ({
path: peer.path,
backend: peer.backend,
status: peer.status ?? "available",
instance_id: null,
error: null,
})),
],
};
case "close_database": {
const id = z.string().parse(args.instance_id);
if (this.rejectClose !== undefined) {
if (!this.rejectClose.keepLease) this.leases.delete(id);
throw new IdaToolRejection(
`IDA MCP tool failed: unknown database instance: ${id}`,
);
}
const lease = this.leases.get(id);
if (lease === undefined || !this.leases.delete(id))
throw new IdaToolRejection(
`IDA MCP tool failed: unknown database instance: ${id}`,
);
if (this.recordedInputPath !== undefined)
await appendFile(lease.path, "repacked");
const idbPath = this.reads.idbPath ?? lease.path + ".i64";
return {
closed: true,
final_lease: !this.peers.some(
({ path, status }) =>
(path === lease.path || path === idbPath) &&
status !== "unavailable",
),
idb_path: idbPath,
};
}
case "execute_python": {
const id = z.string().parse(args.instance_id);
if (!this.leases.has(id))
throw new IdaToolRejection(
`IDA MCP tool failed: unknown database instance: ${id}`,
);
const match = QUERY_LINE.exec(z.string().parse(args.code));
if (match === null) throw new Error("Unrecognized fixture Python");
const tool = z.string().parse(JSON.parse(match[1] ?? ""));
const query = z
.record(z.string(), jsonValueSchema)
.parse(JSON.parse(z.string().parse(JSON.parse(match[2] ?? ""))));
const result = await this.reads.call(tool, { ...query, database: id });
return {
result:
tool === "server_health" &&
result !== null &&
typeof result === "object" &&
!Array.isArray(result)
? { ...result, input_sha256: this.recordedInputSha256 }
: result,
...this.engineOutput,
};
}
default:
throw new Error(`Unimplemented producer tool ${name}`);
}
}
}
+3 -1
View File
@@ -72,6 +72,8 @@ export class RecordingIdaMcp implements IdaMcpConnection {
detaches = 0;
inputSha256: string;
inputPath: string;
/** Opened database path; defaults to the input path's sibling database. */
idbPath: string | undefined;
imageBase = "0x1000";
pseudocode = "int main(void) { return 42; }";
owned = true;
@@ -268,7 +270,7 @@ export class RecordingIdaMcp implements IdaMcpConnection {
return {
status: "ok",
input_path: this.inputPath,
idb_path: `${this.inputPath}.i64`,
idb_path: this.idbPath ?? `${this.inputPath}.i64`,
module: "target.elf",
imagebase: this.imageBase,
auto_analysis_ready: true,
+12 -3
View File
@@ -7,6 +7,15 @@ import { registerHooks } from "node:module";
import { idaCleanupState } from "./idaVerifierCleanupMock.mjs";
const mockUrl = new URL("./idaVerifierCleanupMock.mjs", import.meta.url).href;
const mockedBuiltModules = new Set(
[
"contracts/toolContracts.js",
"domain/evidence.js",
"domain/native/functionDossier.js",
"ida/IdaConfiguration.js",
"ida/IdaMcpConnection.js",
].map((module) => new URL(`../../dist/${module}`, import.meta.url).href),
);
registerHooks({
resolve(specifier, context, next) {
const parent = context.parentURL ? new URL(context.parentURL).pathname : "";
@@ -22,7 +31,7 @@ registerHooks({
specifier.endsWith("/owned-mcp-stdio.mjs") ||
specifier.endsWith("/verify-commands.mjs") ||
specifier.endsWith("/verifier-file-resources.mjs") ||
specifier.includes("/dist/")
mockedBuiltModules.has(specifier)
)
return { shortCircuit: true, url: mockUrl };
return next(specifier, context);
@@ -56,14 +65,14 @@ try {
const report = JSON.parse(await fs.readFile(reportPath, "utf8"));
assert.equal(output.passed, false);
assert.equal(process.exitCode, 1);
assert.equal(idaCleanupState.events.includes("client.close"), true);
assert.equal(idaCleanupState.events.includes("transport.close"), true);
if (failClose)
assert.deepEqual(report.failure.causes, [
idaCleanupState.primary.message,
idaCleanupState.cleanup.message,
]);
else assert.equal(report.failure.message, idaCleanupState.primary.message);
assert.equal(idaCleanupState.events.includes("client.close"), true);
assert.equal(idaCleanupState.events.includes("transport.close"), true);
write(
JSON.stringify({
failClose,