Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(ida): report missing tools when a compatibility profile mismatches (#2307)
vtxbeca34f52258
diff --git a/docs/ida-provider.md b/docs/ida-provider.mdindex fbf67c8a2..012f75bfb 100644--- a/docs/ida-provider.md+++ b/docs/ida-provider.md@@ -4,6 +4,15 @@ REA adapts an existing IDA MCP server into its native analysis tools. Existing IChoose one lifecycle mode in an upstream MCP JSON registration. 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++Each mode accepts one upstream tool profile, checked against `tools/list` before any analysis runs. Upstream's `main` branch has since moved to 2.0.0, which renamed the GUI tools and dropped `idb_close`, so it serves neither profile. Installing from that branch fails at startup with the missing tool names in the error diagnostics.++| Mode | Upstream profile | Known working |+| -------- | ------------------- | ------------------------------------------------------ |+| attached | legacy GUI tools | 1.4.0 |+| headless | database supervisor | builds serving `idb_open`, `idb_list`, and `idb_close` |+## Analyze an already-open GUI targetThe attached profile supports upstream **1.4.0 legacy tools**, including `get_metadata`, `list_functions`, and `decompile_function`. Copy the upstream registration's `command`, `args`, and optional `env` into a JSON file. An existing `mcpServers` object with an `ida-pro-mcp` entry is also accepted. For example:diff --git a/src/ida/IdaSessionClient.test.ts b/src/ida/IdaSessionClient.test.tsindex 7fa366bce..0ae4002d2 100644--- a/src/ida/IdaSessionClient.test.ts+++ b/src/ida/IdaSessionClient.test.ts@@ -31,6 +31,7 @@ const LIVE_PEER = {const fixture = async (mode: "attached" | "headless" = "attached",timeoutMs = 1000,+ protocol?: "native",) => {const { root, target } = await createIdaTarget();roots.push(root);@@ -41,6 +42,7 @@ const fixture = async (args: [],env: {},mode,+ ...(protocol === undefined ? {} : { protocol }),timeoutMs,workspaceRoot: root,},@@ -709,6 +711,74 @@ describe("headless IDA non-busy health payloads", () => {});});+describe("IDA compatibility profile mismatch", () => {+ it("reports the native profile for an incompatible catalog", async () => {+ const { producer, client } = await fixture("attached", 1000, "native");+ producer.tools = [];+ const result = await client.execute("health", {});+ expect(result.ok).toBe(false);+ if (result.ok) throw new Error("Expected incompatible native catalog");+ expect(projectAnalysisError(result.error).details).toMatchObject({+ diagnostics: {+ mode: "attached",+ expected_profile: "native",+ missing_tools: expect.arrayContaining(["decompile"]),+ },+ });+ expect(producer.calls).toEqual([]);+ expect((await client.close()).ok).toBe(true);+ });++ it("names every missing tool so the caller can identify the upstream profile", async () => {+ const { producer, client } = await fixture("headless");+ producer.tools = [+ "idb_open",+ "idb_list",+ "server_health",+ "list_funcs",+ "lookup_funcs",+ "find_regex",+ "decompile",+ "disasm",+ "callees",+ "xrefs_to",+ ];+ const result = await client.execute("health", {});+ expect(result.ok, "an incomplete profile cannot serve analysis").toBe(+ false,+ );+ if (result.ok) return;+ const projected = projectAnalysisError(result.error);+ expect(+ projected.details,+ "the absent tool and the expected profile are both reported",+ ).toMatchObject({+ provider_id: "ida",+ diagnostics: {+ mode: "headless",+ expected_profile: "database-supervisor",+ missing_tools: ["idb_close"],+ },+ });+ });++ it("reports the legacy profile when an attached producer serves modern tools", async () => {+ const { producer, client } = await fixture("attached");+ producer.tools = ["server_health", "lookup_funcs", "decompile", "disasm"];+ const result = await client.execute("health", {});+ expect(result.ok, "an incomplete profile cannot serve analysis").toBe(+ false,+ );+ if (result.ok) return;+ expect(+ projectAnalysisError(result.error).details,+ "attached mode names the legacy profile it expected",+ ).toMatchObject({+ diagnostics: { mode: "attached", expected_profile: "legacy-1.4" },+ });+ });+});+describe("headless IDA lifecycle boundaries", () => {it("never closes an unowned worker even when open echoes the requested private identity", async () => {const { producer, client } = await fixture("headless");diff --git a/src/ida/IdaSessionClient.ts b/src/ida/IdaSessionClient.tsindex dc0ae5d6f..70d4fc365 100644--- a/src/ida/IdaSessionClient.ts+++ b/src/ida/IdaSessionClient.ts@@ -483,10 +483,27 @@ export class IdaSessionClient implements AnalysisClient {? legacyTools: modernTools;const missing = expected.filter((name) => !tools.has(name));- if (missing.length > 0)- throw new AnalysisProtocolError(- `IDA MCP ${this.config.protocol === "native" ? "native attached" : this.config.mode} compatibility profile is missing tools: ${missing.join(", ")}. Native attached mode requires the native IDA MCP tool catalog; legacy attached mode requires the legacy 1.4 profile; headless mode requires the database supervisor profile. See docs/ida-provider.md.`,- );+ if (missing.length > 0) {+ const summary = `IDA MCP ${this.config.protocol === "native" ? "native attached" : this.config.mode} compatibility profile is missing tools: ${missing.join(", ")}. Native attached mode requires the native IDA MCP tool catalog; legacy attached mode requires the legacy 1.4 profile; headless mode requires the database supervisor profile. See docs/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", {+ userMessage: summary,+ diagnostics: {+ reason: summary,+ mode: this.config.mode,+ expected_profile:+ this.config.protocol === "native"+ ? "native"+ : this.config.mode === "attached"+ ? "legacy-1.4"+ : "database-supervisor",+ missing_tools: [...missing],+ recovery:+ "Install an IDA MCP build that serves the selected profile; see docs/ida-provider.md.",+ },+ });+ }if (this.config.mode === "headless") {this.#workspace = await IdaWorkspace.allocate(this.target,diff --git a/tests/composition/idaProvider.test.ts b/tests/composition/idaProvider.test.tsindex 9a702bb45..f6dd1dd0d 100644--- a/tests/composition/idaProvider.test.ts+++ b/tests/composition/idaProvider.test.ts@@ -1,6 +1,7 @@import { rm, writeFile } from "node:fs/promises";import { join } from "node:path";import { afterEach, describe, expect, it } from "vitest";+import { projectAnalysisError } from "../../src/domain/analysisErrorProjection.js";import { IdaProvider } from "../../src/ida/IdaProvider.js";import { createIdaTarget, RecordingIdaMcp } from "../fixtures/idaMcp.js";import { createTestBinarySession } from "../fixtures/binarySession.js";@@ -157,12 +158,21 @@ describe("IDA provider composition", () => {expect(analyzed).toMatchObject({ok: false,error: {- _tag: "AnalysisProtocolError",- message: expect.stringContaining(+ _tag: "ProviderAdapterError",+ userMessage: expect.stringContaining("headless compatibility profile is missing tools: idb_open",),},});+ if (analyzed.ok) throw new Error("Expected incompatible IDA profile");+ expect(projectAnalysisError(analyzed.error).details).toMatchObject({+ provider_id: "ida",+ diagnostics: {+ mode: "headless",+ expected_profile: "database-supervisor",+ missing_tools: expect.arrayContaining(["idb_open"]),+ },+ });expect(producer.connects).toBe(1);expect((await session.close()).ok).toBe(true);expect(producer.closes).toBe(1);