Files
reverse-engineering-anything/bridge/ida/hexrays_queries.py
T
6822ebe1f3 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>
2026-11-20 17:58:27 -05:00

337 lines
11 KiB
Python

"""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))