From 2b72592f8942aeb072900c9ea7d808c87aa32f5e Mon Sep 17 00:00:00 2001 From: N0zoM1z0 <161784452+N0zoM1z0@users.noreply.github.com> Date: Tue, 13 Oct 2026 02:14:25 +0800 Subject: [PATCH] perf(ida): batch native lookups and narrow literal search Bind each lookup reply to its query, batch unique native callees, and fetch conservative literal string candidates while preserving Unicode, case, pagination, and raw source Evidence. Preserve explicit native search failures and describe unknown string representations. Verified with Windows IDA Pro 9.3 and the native MCP plugin built from c9d15d98e8a143fc74f6e14037c48f63889b6d6c with a loopback listener. Production CLI/MCP parity and two-function switching passed on the public fixture; equivalent tasks passed on Windows whoami.exe. Windows IDA Free was not used. No personal paths or license registration information are included. Validation: 182 focused tests, static checks, architecture guards, test discovery, and docs checks passed. Same-main measurements show warm task time 675 to 317 ms and estimated response tokens 16618 to 11509; cold-start, overall CPU, and memory improvement were not established. Detailed scope and measurements are in experiments/analysis-efficiency/ida-native-windows.md. --- docs/ida-provider.md | 10 +- docs/testing.md | 9 +- .../analysis-efficiency/ida-native-windows.md | 97 ++++++ src/ida/IdaConfiguration.ts | 2 +- src/ida/IdaNativeProtocol.test.ts | 298 +++++++++++++++++- src/ida/IdaNativeProtocol.ts | 35 ++ src/ida/IdaOperationRunner.ts | 147 ++++++--- src/ida/IdaProviderCapabilities.ts | 8 +- tests/conformance/ida/inventory.c | 6 +- tests/fixtures/idaMcp.ts | 21 +- 10 files changed, 568 insertions(+), 65 deletions(-) create mode 100644 experiments/analysis-efficiency/ida-native-windows.md diff --git a/docs/ida-provider.md b/docs/ida-provider.md index 60851d53c..5ba3d0912 100644 --- a/docs/ida-provider.md +++ b/docs/ida-provider.md @@ -34,7 +34,7 @@ REA's close operation releases its MCP connection or proxy. It never saves or cl ## Optional native IDA MCP bridge -IDA Pro and IDA Free can use the separate [ida-free-mcp native plugin](https://github.com/0xshlomil/ida-free-mcp) through an explicit attached registration. Install and start that plugin using its upstream instructions, open the original binary in the IDA GUI, and wait for analysis. Native MCP 1.1.2 binds `0.0.0.0` without a listen-address setting. Restrict inbound access with the host firewall or use an upstream build that binds only to loopback before starting it. REA's loopback URL restriction does not change the plugin's listener. REA does not install IDA, build the plugin, activate a license, or launch the GUI. +IDA Pro and IDA Free can use the separate [ida-free-mcp native plugin](https://github.com/0xshlomil/ida-free-mcp) through an explicit attached registration. Install and start that plugin using its upstream instructions, open the original binary in the IDA GUI, and wait for analysis. The native MCP 1.1.2 release binds `0.0.0.0` without a listen-address setting. Restrict inbound access with the host firewall or use an upstream build that binds only to loopback before starting it. REA's loopback URL restriction does not change the plugin's listener. REA does not install IDA, build the plugin, activate a license, or launch the GUI. ```json { @@ -48,9 +48,13 @@ Set `REA_IDA_MCP_CONFIG` to this file and select `ida` using the same CLI/MCP co This experimental profile provides function/string inventory and search, function lookup, assembly, GUI pseudocode, callees, address xrefs, instruction windows, and function dossiers. Direct callers remain unavailable: native code/data xref labels do not prove call edges. It requires neither IDAPython nor idalib. Native headless registrations are rejected. +Native string observations use upstream C-string rendering; other representations remain unknown. Literal searches request conservative candidates and apply REA's original case and Unicode matching rules. Regex searches retain the full scan because native byte-oriented regex semantics cannot replace REA's Unicode regex semantics. All candidate pages are examined, and upstream search errors remain failures. + +Native callee resolution batches unique queries and checks each reply's query identity. Results remain live: a recorded input hash does not establish database revision, so cross-request analysis caches cannot prove freshness. For focused questions, use pseudocode, callees, or instruction-window tools; a function dossier requests additional facets and returns more Evidence. + IDA Free's cloud decompiler needs network access and may request consent. Follow its licensing and supported architecture limits; see [IDA Free](https://hex-rays.com/ida-free). Decompilation moves GUI focus and the upstream plugin closes existing pseudocode tabs before requesting fresh output. REA advertises UI/network effects and closes only its MCP connection, preserving the open database. Rendered pseudocode has upstream traversal limits and does not prove complete source recovery. Cloud/widget failures remain explicit failures; retry after the GUI finishes or dismiss its prompt. -Native MCP 1.1.2 can navigate in the previously focused pseudocode tab when switching functions. Its producing navigation order must be fixed to focus the disassembly view **before** jumping to the requested entry. This REA profile does not repair stale GUI output. Verification must include two different functions before claiming reliable function switching. Reliable function switching requires that upstream correction. The initial Linux verification uses a locally corrected native plugin. +The native MCP 1.1.2 release can navigate in the previously focused pseudocode tab when switching functions. Its producing navigation order must focus the disassembly view **before** jumping to the requested entry. Use a build including [upstream #7](https://github.com/0xshlomil/ida-free-mcp/pull/7), merged in `6adf2c615a2a03661059673e9c136ef28d0dc778`, or a release containing that correction. REA does not repair stale GUI output. Verify two different functions before claiming reliable switching. The initial Linux verification used a local version of this upstream correction. Native tool observations retain actual tool names and complete JSON text. Upstream `structuredContent` can be a shortened preview even while text contains the full result. REA reads the full native representation and rejects missing/malformed text instead of treating previews as complete observations. @@ -135,3 +139,5 @@ Run `npm run verify:ida -- --target /absolute/path/to/program --procedure main` To verify GUI function switching, add `--second-procedure other_function --second-marker unique_second_body_text`. 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 initial real workflows use stdio registrations for the 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. + +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/main/experiments/analysis-efficiency/ida-native-windows.md). This follow-up did not run Windows IDA Free or native macOS. diff --git a/docs/testing.md b/docs/testing.md index bbad3f77e..a9b20695f 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -620,8 +620,9 @@ Python package, or compiler. The target must already be open in the GUI for the legacy or native attached profile; the database-supervisor headless profile opens a digest-verified private copy. A caller-supplied fixture keeps prerequisites limited to the selected engine and host. `tests/conformance/ida/inventory.c` -provides an optional small native fixture source with an exported -`rea_fixture_add` function. +provides an optional small native fixture source with exported +`rea_fixture_add` and `rea_fixture_subtract` functions. For their switching check, +use `--second-procedure rea_fixture_subtract --second-marker='- 13'`. The lane invokes the production CLI dispatcher and connects the pinned MCP client SDK to the production REA server. It verifies function Evidence and @@ -649,7 +650,9 @@ failed intermittently on that host. Linux headless, modern attached GUI tools, other engine versions and architectures remain unverified; see the [provider guide](ida-provider.md). -Native IDA MCP verification uses `"protocol": "native"` with an already-running native plugin. Add `--second-procedure other_function --second-marker unique_second_body_text` to exercise GUI function switching and a return to the first function. The literal marker must appear in the second function's pseudocode and be absent from the first. Native cloud/widget failures are reported without hidden retries. Local validation covers Linux x64 IDA Free 9.4 with native MCP 1.1.2 and a corrected upstream navigation order; stock 1.1.2 switching and native Windows/macOS workflows are not established by that run. See the [optional native bridge prerequisites](ida-provider.md#optional-native-ida-mcp-bridge). +Native IDA MCP verification uses `"protocol": "native"` with an already-running native plugin. Add `--second-procedure other_function --second-marker unique_second_body_text` to exercise GUI function switching and a return to the first function. The literal marker must appear in the second function's pseudocode and be absent from the first. Native cloud/widget failures are reported without hidden retries. + +The initial Linux x64 IDA Free 9.4 run used native MCP 1.1.2 with a local navigation correction. Windows x64 verification uses **IDA Pro 9.3**, the two-function public fixture, and the shipped Windows `whoami.exe` application. The native plugin was built from upstream `c9d15d98e8a143fc74f6e14037c48f63889b6d6c`, including the merged navigation fix, with a local loopback-listener change. Production CLI/MCP parity, switching, identity and cleanup passed. Correctness and performance measurements are recorded in the [Windows native verification notes](https://github.com/morluto/rea/blob/main/experiments/analysis-efficiency/ida-native-windows.md). Stock 1.1.2 switching, native macOS, and Windows IDA Free remain unverified. See the [native bridge prerequisites](ida-provider.md#optional-native-ida-mcp-bridge). ## DOS Ghidra analysis diff --git a/experiments/analysis-efficiency/ida-native-windows.md b/experiments/analysis-efficiency/ida-native-windows.md new file mode 100644 index 000000000..c055f446e --- /dev/null +++ b/experiments/analysis-efficiency/ida-native-windows.md @@ -0,0 +1,97 @@ +# Native IDA MCP verification on Windows + +Verification date: 2026-10-13. These runs used **IDA Pro 9.3** (executable +product version `9.3.26.0213`), not Windows IDA Free. Personal paths, raw +observations, and license registration information are excluded. + +The native plugin was built from upstream +[`c9d15d98e8a143fc74f6e14037c48f63889b6d6c`](https://github.com/0xshlomil/ida-free-mcp/commit/c9d15d98e8a143fc74f6e14037c48f63889b6d6c) +with MinGW GCC 13 and its pinned public SDK. The only local source change +bound the listener to `127.0.0.1`; the upstream function-navigation fix was +already present. This does not verify the stock 1.1.2 release listener or +its older navigation order. + +## Correctness and authority + +The public [IDA fixture](../../tests/conformance/ida/inventory.c) contains +two exported functions with distinct bodies. Production CLI/MCP verification +checks matching function Evidence, assembly, a unique second-function marker, +return to the first function, original-input identity, invalid requests, and +connection cleanup. It preserves the attached GUI database. + +The real application was a digest-verified, unchanged copy of Windows +`whoami.exe`: 94,208 bytes, 243 recognized functions, and 314 upstream +C-string observations. The selected 1,741-byte function had 20 resolved +callees. Before and after, the task returned identical pseudocode, callee +addresses, and its one `whoami` string match. The executable was never run. +Other string representations remain unknown in the native profile. + +A Windows C++ producer golden checked 24 literal/case combinations and +408 candidate comparisons, including metacharacters, Kelvin sign, dotted I, +sigma, supplementary characters, and null bytes. Adapter tests additionally +cover malformed UTF-16 fallback, candidate pagination, explicit search errors, +and reordered, missing, duplicate, unrelated, or failed lookup replies. +These checks do not establish IDA recognition of every Unicode string format. + +## Equivalent completed tasks + +Both builds used main `59be86671`. The baseline was `fb34ccbec`, before +the native performance edits; the comparison build added those edits. +Schemas were identical. Each run opened the same analyzed binary, read the +specified function's pseudocode and callees, searched literal `whoami`, and +closed the REA session. The task then repeated on the same MCP connection. + +There were two runs per build on a shared host. Node 24.18.0 and IDA were +restricted to one logical CPU with below-normal priority; each Node process +had a 768 MiB heap ceiling. The attached database was already analyzed. +Node compile caching was disabled for the primary comparison. + +| Measurement | Before | After | +| --------------------------------------------------- | -----------: | -----------: | +| Task response text | 49,139 bytes | 32,546 bytes | +| Task response token estimate | 16,618 | 11,509 | +| Callee lookup calls, including selector | 17 | 2 | +| String-search pages | 4 | 1 | +| String-search Evidence | 19,022 bytes | 3,344 bytes | +| Mean task time, warm MCP connection | 675 ms | 317 ms | +| Mean task time, fresh MCP process and catalog | 19.72 s | 20.86 s | +| Mean Node family CPU, fresh and warm tasks together | 17.72 s | 18.62 s | +| Largest Node family peak-RSS upper bound | 776.8 MiB | 780.0 MiB | +| Mean attached IDA CPU during both tasks | 226.6 ms | 171.9 ms | + +The warm task was about 53% faster and its response estimate about 31% +smaller. Fresh-start, overall CPU, and memory improvements were not +established. Startup and full catalog conversion dominate the fresh task. +Two samples do not establish a general performance guarantee. + +Token counts use local `cl100k_base` tokenization of complete serialized +MCP response text and request arguments; they are estimates, not model usage. +Requests added 99 estimated tokens per task. The unchanged full schema +catalog contained 2,422,229 bytes and 613,965 estimated tokens. Including it +once gives first-task estimates of 630,682 before and 625,573 after. A host +may select schemas lazily; actual host injection, prompts, reasoning tokens, +and model-side costs were not measured. No retries were needed. + +Node CPU counters were captured at shutdown. The memory figure sums the +two processes' individual OS peak RSS values: an upper bound, not a +simultaneous family peak. Attached IDA is outside that process family; its +unchanged lifetime peak working set was 376.9 MiB, including initial analysis. +Measurement overhead and whole-machine resource use were not measured. + +## Reuse and cleanup + +Callee queries are deduplicated and batched within an operation. Literal +search fetches a conservative candidate set, including non-ASCII text when +needed, and preserves REA's final Unicode predicate. It examines all candidate +pages and retains full source observations. Regex searches keep the full scan. + +Cross-request analysis results remain live because an input digest does not +establish database revision or freshness. An exploratory caller-selected +[Node compile cache](https://nodejs.org/download/release/v24.16.0/docs/api/module.html#module-compile-cache) +did not demonstrate startup improvement: empty-cache and cache-hit MCP starts +were 7.35 s and 7.56 s. It occupied 6.7 MiB and was limited to this experiment; +no new default cache or installation behavior was introduced. + +Temporary source, SDK, build, portable runtime, cache, and raw measurement +outputs are test-owned cleanup targets. Attached GUI databases are retained; +REA never saves or closes them. diff --git a/src/ida/IdaConfiguration.ts b/src/ida/IdaConfiguration.ts index d44850bb2..9f971610a 100644 --- a/src/ida/IdaConfiguration.ts +++ b/src/ida/IdaConfiguration.ts @@ -43,7 +43,7 @@ const registrationSchema = z ]) .refine( (config) => config.protocol !== "native" || config.mode === "attached", - "The native IDA Free protocol requires attached mode", + "The native IDA MCP protocol requires attached mode", ); /** An upstream MCP registration plus REA's database lifecycle selection. */ diff --git a/src/ida/IdaNativeProtocol.test.ts b/src/ida/IdaNativeProtocol.test.ts index a2ade45df..dfe409e38 100644 --- a/src/ida/IdaNativeProtocol.test.ts +++ b/src/ida/IdaNativeProtocol.test.ts @@ -6,6 +6,10 @@ import { RecordingIdaMcp, } from "../../tests/fixtures/idaMcp.js"; import type { JsonValue } from "../domain/jsonValue.js"; +import { + AnalysisInputError, + AnalysisProtocolError, +} from "../domain/analysisErrorCore.js"; import { readIdaConfiguration } from "./IdaConfiguration.js"; import { decodeIdaToolResult, @@ -101,7 +105,7 @@ const fixture = async () => { return { producer, client, target, resources, root }; }; -describe("native IDA Free attached protocol", () => { +describe("native IDA attached protocol", () => { it("requires explicit opt-in and rejects native headless registrations", async () => { const { root } = await fixture(); const path = join(root, "native.json"); @@ -191,7 +195,7 @@ describe("native IDA Free attached protocol", () => { }); }); -describe("native IDA Free provider observations", () => { +describe("native IDA provider observations", () => { it("retains native tool provenance, reads recorded metadata, and closes only its connection", async () => { const { client, producer, resources } = await fixture(); for (const operation of [ @@ -276,7 +280,295 @@ describe("native IDA Free provider observations", () => { }); }); -describe("native IDA Free malformed observations", () => { +describe("native IDA callee lookup batches", () => { + it("batches unique callees and binds reordered replies to their source queries", async () => { + const { client, producer } = await fixture(); + const previous = producer.overrideCall; + producer.overrideCall = (name, args) => { + if (name === "callees") + return [ + { + callees: [ + { addr: "0x2004", name: "first", type: "internal" }, + { addr: "0x2004", name: "first", type: "internal" }, + { addr: "0x3000", name: "second", type: "internal" }, + { addr: "0x4000", name: "import", type: "external" }, + ], + more: false, + error: null, + }, + ]; + if ( + name === "lookup_funcs" && + Array.isArray(args.queries) && + args.queries.length > 1 + ) + return [ + { + query: "0x3000", + fn: { addr: "0x3000", name: "second", size: "0x20" }, + error: null, + }, + { + query: "0x2004", + fn: { addr: "0x2000", name: "first", size: "0x20" }, + error: null, + }, + ]; + return previous?.(name, args); + }; + try { + const result = await client.execute("procedure_callees", { + procedure: "main", + }); + if (!result.ok) throw result.error; + expect(result.value.result).toEqual(["0x4000", "0x2000", "0x3000"]); + expect( + producer.calls + .filter(({ name }) => name === "lookup_funcs") + .map(({ args }) => args.queries), + ).toEqual([["main"], ["0x2004", "0x3000"]]); + expect(result.value.rawResult).toMatchObject({ + observations: expect.arrayContaining([ + expect.objectContaining({ + tool: "lookup_funcs", + arguments: { queries: ["0x2004", "0x3000"] }, + result: [ + expect.objectContaining({ query: "0x3000" }), + expect.objectContaining({ query: "0x2004" }), + ], + }), + ]), + }); + } finally { + await client.close(); + } + }); + + it("rejects missing, duplicate, unrelated, and failed callee lookup rows as provider faults", async () => { + const { client, producer } = await fixture(); + const previous = producer.overrideCall; + const first = { + query: "0x2000", + fn: { addr: "0x2000", name: "first", size: "0x20" }, + error: null, + }; + const second = { + query: "0x3000", + fn: { addr: "0x3000", name: "second", size: "0x20" }, + error: null, + }; + let rows: JsonValue = []; + producer.overrideCall = (name, args) => { + if (name === "callees") + return [ + { + callees: [ + { addr: "0x2000", name: "first", type: "internal" }, + { addr: "0x3000", name: "second", type: "internal" }, + ], + more: false, + error: null, + }, + ]; + if ( + name === "lookup_funcs" && + Array.isArray(args.queries) && + args.queries.length > 1 + ) + return rows; + return previous?.(name, args); + }; + try { + for (const reply of [ + [first], + [first, first], + [first, { ...second, query: "unrequested" }], + [first, { query: "0x3000", fn: null, error: "Not found" }], + ]) { + rows = reply; + const result = await client.execute("procedure_callees", { + procedure: "main", + }); + expect(result.ok).toBe(false); + if (!result.ok) + expect(result.error).toBeInstanceOf(AnalysisProtocolError); + } + } finally { + await client.close(); + } + }); +}); + +describe("native IDA literal matching", () => { + it("retains literal, Unicode, case, and regex semantics while narrowing native candidates", async () => { + const { client, producer } = await fixture(); + const values = [ + "A.B", + "axb", + "Kelvin", + "İstanbul", + "σ", + "ς", + "literal[bracket", + "a\\b", + "🧪", + ]; + producer.overrideCall = (name, args) => { + if (name !== "find_regex") return undefined; + if (typeof args.pattern !== "string") + throw new Error("Invalid fixture pattern"); + // Exercise a byte-oriented producer seam, including Unicode candidates + // whose final matching semantics belong to REA, not the upstream regex. + const regex = new RegExp( + Buffer.from(args.pattern).toString("latin1"), + "i", + ); + return { + matches: values.flatMap((value, i) => + regex.test(Buffer.from(value).toString("latin1")) + ? [{ addr: `0x${(0x3000 + i).toString(16)}`, string: value }] + : [], + ), + cursor: { done: true }, + }; + }; + const cases = [ + { + pattern: "a.b", + mode: "literal", + case_sensitive: false, + expected: ["A.B"], + }, + { pattern: "a.b", mode: "literal", case_sensitive: true, expected: [] }, + { + pattern: "kelvin", + mode: "literal", + case_sensitive: false, + expected: ["Kelvin"], + }, + { + pattern: "İ", + mode: "literal", + case_sensitive: false, + expected: ["İstanbul"], + }, + { pattern: "σ", mode: "literal", case_sensitive: false, expected: ["σ"] }, + { + pattern: "σ", + mode: "regex", + case_sensitive: false, + expected: ["σ", "ς"], + }, + { + pattern: "[", + mode: "literal", + case_sensitive: false, + expected: ["literal[bracket"], + }, + { + pattern: "\\", + mode: "literal", + case_sensitive: true, + expected: ["a\\b"], + }, + { + pattern: "\ud800", + mode: "literal", + case_sensitive: false, + expected: [], + }, + { + pattern: "🧪", + mode: "literal", + case_sensitive: true, + expected: ["🧪"], + }, + ]; + try { + for (const { expected, ...query } of cases) { + const before = producer.calls.length; + const result = await client.execute("search_strings", query); + if (!result.ok) throw result.error; + expect(result.value.result).toEqual( + expected.map((value) => ({ + address: `0x${(0x3000 + values.indexOf(value)).toString(16)}`, + value, + })), + ); + const reads = producer.calls + .slice(before) + .filter(({ name }) => name === "find_regex"); + expect(reads).toHaveLength(1); + if (query.mode === "regex" || query.pattern === "\ud800") + expect(reads[0]?.args.pattern).toBe("[\\s\\S]*"); + else expect(reads[0]?.args.pattern).not.toBe("[\\s\\S]*"); + } + const before = producer.calls.length; + const invalid = await client.execute("search_strings", { + pattern: "[", + mode: "regex", + }); + expect(invalid.ok).toBe(false); + if (!invalid.ok) expect(invalid.error).toBeInstanceOf(AnalysisInputError); + expect( + producer.calls.slice(before).some(({ name }) => name === "find_regex"), + ).toBe(false); + } finally { + await client.close(); + } + }); +}); + +describe("native IDA string pagination and failures", () => { + it("reads all candidate pages and reports native search failures explicitly", async () => { + const { client, producer } = await fixture(); + producer.overrideCall = (name, args) => + name === "find_regex" + ? { + matches: [ + { + addr: args.offset === 0 ? "0x3000" : "0x3001", + string: args.offset === 0 ? "σ" : "needle", + }, + ], + cursor: args.offset === 0 ? { next: 1 } : { done: true }, + } + : undefined; + try { + const found = await client.execute("search_strings", { + pattern: "needle", + }); + if (!found.ok) throw found.error; + expect(found.value.result).toEqual([ + { address: "0x3001", value: "needle" }, + ]); + const reads = producer.calls.filter(({ name }) => name === "find_regex"); + expect(reads.map(({ args }) => args.offset)).toEqual([0, 1]); + expect(new Set(reads.map(({ args }) => args.pattern)).size).toBe(1); + producer.overrideCall = (name) => + name === "find_regex" + ? { + matches: [], + cursor: { done: true }, + error: "Regex resource failure", + } + : undefined; + const failed = await client.execute("search_strings", { + pattern: "needle", + }); + expect(failed.ok).toBe(false); + if (!failed.ok) { + expect(failed.error).toBeInstanceOf(AnalysisProtocolError); + expect(failed.error.message).toContain("Regex resource failure"); + } + } finally { + await client.close(); + } + }); +}); + +describe("native IDA malformed observations", () => { it("rejects wrong-function pseudocode, upstream cloud failures, and malformed assembly", async () => { const { client, producer } = await fixture(); for (const value of [ diff --git a/src/ida/IdaNativeProtocol.ts b/src/ida/IdaNativeProtocol.ts index 0f44751b5..711383f8e 100644 --- a/src/ida/IdaNativeProtocol.ts +++ b/src/ida/IdaNativeProtocol.ts @@ -5,6 +5,7 @@ import { disassemblySchema, idaAddressSchema, modernCalleesSchema, + modernStringsSchema, modernXrefsSchema, } from "./IdaProtocolValues.js"; @@ -68,6 +69,40 @@ export const nativeXrefsSchema = z .array(modernXrefsSchema.element.extend({ error: nativeErrorSchema })) .length(1); +/** Native regex failures carry an empty page, which must not imply absence. */ +export const nativeStringsSchema = modernStringsSchema + .extend({ error: z.string().optional() }) + .transform((page) => { + if (page.error !== undefined) + throw new AnalysisProtocolError( + `Native IDA string search failed: ${page.error}`, + ); + return page; + }); + +/** + * Native regexes fold bytes, while REA's insensitive literal search folds + * Unicode strings. Include every non-ASCII value as a candidate, then apply + * REA's exact predicate. Ill-formed UTF-16 cannot cross upstream JSON/UTF-8. + */ +export const nativeLiteralSearchPattern = ( + pattern: string, + caseSensitive: boolean, +): string | undefined => { + if (/[\uD800-\uDFFF]/u.test(pattern)) return undefined; + let literal = (caseSensitive ? pattern : pattern.toLowerCase()).replace( + /[.*+?^${}()|[\]\\]/gu, + "\\$&", + ); + // Spell ASCII variants explicitly rather than depending on an upstream locale. + if (!caseSensitive) + literal = literal.replace( + /[a-z]/gu, + (char) => `[${char}${char.toUpperCase()}]`, + ); + return caseSensitive ? literal : `(?:${literal})|[\\x80-\\xff]`; +}; + /** Read-only tools required from the native bridge; GUI lifecycle tools are excluded. */ export const nativeTools = [ "list_funcs", diff --git a/src/ida/IdaOperationRunner.ts b/src/ida/IdaOperationRunner.ts index 638b2f015..650af64dc 100644 --- a/src/ida/IdaOperationRunner.ts +++ b/src/ida/IdaOperationRunner.ts @@ -4,6 +4,8 @@ import { nativeDisassemblySchema, nativeCalleesSchema, nativeXrefsSchema, + nativeLiteralSearchPattern, + nativeStringsSchema, } from "./IdaNativeProtocol.js"; import { analysisSearchInput } from "../contracts/analysisSearchContract.js"; import { @@ -20,7 +22,10 @@ import type { RelationshipCoverage } from "../domain/relationshipCoverage.js"; import { readCallGraphCallees, unavailableCallGraph } from "./IdaCallGraph.js"; import type { IdaMcpConnection } from "./IdaMcpConnection.js"; import type { IdaOperation } from "./IdaProviderCapabilities.js"; -import { IDA_LIMITATIONS } from "./IdaProviderCapabilities.js"; +import { + IDA_LIMITATIONS, + IDA_NATIVE_STRING_LIMITATION, +} from "./IdaProviderCapabilities.js"; import type { EvidenceLocation } from "../domain/evidence.js"; import { disassemblySchema, @@ -34,6 +39,7 @@ import { modernDecompileSchema, modernDisassemblySchema, modernLookupSchema, + modernLookupBatchSchema, modernPageSchema, modernStringsSchema, modernXrefsSchema, @@ -66,6 +72,7 @@ const MISSING_PROCEDURE_ANSWERS: ReadonlySet = new Set([ ]); const lines = (asm: IdaDisassembly) => asm.lines.map(({ address, instruction }) => `${address}: ${instruction}`); +const searchQuerySchema = z.object(analysisSearchInput); /** Translate explicit analyst questions into a closed set of read-only upstream requests. */ export class IdaOperationRunner { @@ -141,33 +148,7 @@ export class IdaOperationRunner { const item = modernLookupSchema.parse( await this.call("lookup_funcs", { queries: [query] }), )[0]; - if ( - requestedBy !== undefined && - item?.query === query && - item.fn === null && - item.error !== null && - MISSING_PROCEDURE_ANSWERS.has(item.error) - ) - throw new AnalysisInputError( - requestedBy, - { - cause: new AnalysisProtocolError( - `IDA function lookup failed for ${query}: ${item.error}`, - ), - }, - [ - { - path: [], - reason: "invalid_value", - message: `IDA could not resolve procedure ${JSON.stringify(query)}: ${item.error}.`, - }, - ], - ); - if (item?.fn == null || item.error !== null) - throw new AnalysisProtocolError( - `IDA function lookup failed for ${query}: ${item?.error ?? "missing function"}`, - ); - return item.fn; + return this.lookupFunction(query, item, requestedBy); } const address = idaAddressSchema.safeParse( /^0x/iu.test(query) ? query : undefined, @@ -190,6 +171,43 @@ export class IdaOperationRunner { return entry; } + private lookupFunction( + query: string, + item: z.infer[number] | undefined, + requestedBy?: string, + ): IdaFunction { + if (item?.query !== query) + throw new AnalysisProtocolError( + `IDA function lookup omitted or contradicted query ${JSON.stringify(query)}.`, + ); + if ( + requestedBy !== undefined && + item.fn === null && + item.error !== null && + MISSING_PROCEDURE_ANSWERS.has(item.error) + ) + throw new AnalysisInputError( + requestedBy, + { + cause: new AnalysisProtocolError( + `IDA function lookup failed for ${query}: ${item.error}`, + ), + }, + [ + { + path: [], + reason: "invalid_value", + message: `IDA could not resolve procedure ${JSON.stringify(query)}: ${item.error}.`, + }, + ], + ); + if (item.fn === null || item.error !== null) + throw new AnalysisProtocolError( + `IDA function lookup failed for ${query}: ${item.error ?? "missing function"}`, + ); + return item.fn; + } + /** True only for modern callee reads on targets not proven x86-only; x86 reads never reach the graph code. */ private readsCallGraph(direction: "callers" | "callees"): boolean { return ( @@ -218,7 +236,11 @@ export class IdaOperationRunner { result.set(callee.address, identity({ ...callee, size: "unknown" })); } - async strings(): Promise<{ address: string; value: string }[]> { + async strings( + nativePattern?: string, + ): Promise<{ address: string; value: string }[]> { + if (this.protocol === "native") + this.limitations.push(IDA_NATIVE_STRING_LIMITATION); const result: { address: string; value: string }[] = []; let offset: number | null = 0; while (offset !== null) { @@ -235,9 +257,14 @@ export class IdaOperationRunner { ); offset = page.next_offset; } else { - const page = modernStringsSchema.parse( + const page = ( + this.protocol === "native" ? nativeStringsSchema : modernStringsSchema + ).parse( await this.call("find_regex", { - pattern: this.protocol === "native" ? "[\\s\\S]*" : "(?s).*", + pattern: + this.protocol === "native" + ? (nativePattern ?? "[\\s\\S]*") + : "(?s).*", offset, limit: 100, }), @@ -433,9 +460,31 @@ export class IdaOperationRunner { else queries.push(item.addr); } } - for (const query of new Set(queries)) { - const resolved = identity(await this.resolve(query)); - result.set(resolved.address, resolved); + const querySet = new Set(queries); + if (this.protocol === "native" && querySet.size > 0) { + const rows = modernLookupBatchSchema.parse( + await this.call("lookup_funcs", { queries: [...querySet] }), + ); + const byQuery = new Map(rows.map((row) => [row.query, row])); + if ( + rows.length !== querySet.size || + byQuery.size !== rows.length || + rows.some((row) => !querySet.has(row.query)) + ) + throw new AnalysisProtocolError( + "Native IDA returned an inconsistent callee lookup batch.", + ); + for (const query of querySet) { + const resolved = identity( + this.lookupFunction(query, byQuery.get(query)), + ); + result.set(resolved.address, resolved); + } + } else { + for (const query of querySet) { + const resolved = identity(await this.resolve(query)); + result.set(resolved.address, resolved); + } } if (this.relationshipCoverage === undefined) this.relationshipCoverage = { @@ -449,19 +498,29 @@ export class IdaOperationRunner { operation: IdaOperation, parameters: Readonly>, ): Promise { + const query = + operation === "search_procedures" || operation === "search_strings" + ? searchQuerySchema.parse(parameters) + : undefined; + const matches = + query === undefined ? undefined : this.searchPredicate(query); if (operation === "list_procedures" || operation === "search_procedures") { const items = (await this.functions()).map((fn) => ({ address: fn.address, value: fn.name, })); - return operation === "list_procedures" + return matches === undefined ? items - : this.search(items, parameters); + : items.filter(({ value }) => matches(value)); } if (operation === "list_strings" || operation === "search_strings") { - const items = await this.strings(); - return operation === "search_strings" - ? this.search(items, parameters) + const nativePattern = + this.protocol === "native" && query?.mode === "literal" + ? nativeLiteralSearchPattern(query.pattern, query.case_sensitive) + : undefined; + const items = await this.strings(nativePattern); + return matches !== undefined + ? items.filter(({ value }) => matches(value)) : parameters.address === undefined ? items : items.filter( @@ -509,11 +568,9 @@ export class IdaOperationRunner { } } - private search( - items: { address: string; value: string }[], - input: Readonly>, - ): JsonValue { - const query = z.object(analysisSearchInput).parse(input); + private searchPredicate( + query: z.infer, + ): (value: string) => boolean { let matches: (value: string) => boolean; if (query.mode === "regex") { try { @@ -532,7 +589,7 @@ export class IdaOperationRunner { matches = (value) => (query.case_sensitive ? value : value.toLowerCase()).includes(needle); } - return items.filter(({ value }) => matches(value)); + return matches; } private async dossier(fn: IdaFunction): Promise { diff --git a/src/ida/IdaProviderCapabilities.ts b/src/ida/IdaProviderCapabilities.ts index 74a49c9c0..d52c949e0 100644 --- a/src/ida/IdaProviderCapabilities.ts +++ b/src/ida/IdaProviderCapabilities.ts @@ -37,6 +37,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_NATIVE_STRING_LIMITATION = + "Native string observations use upstream C-string rendering; other string representations remain unknown."; + /** * Attached mode requires the legacy 1.4 profile, whose `disassemble_function` * jumps to the function and whose `decompile_function` opens or reuses a @@ -81,5 +84,8 @@ export const idaCapabilities = ( changesPermissions: false, requiresRoot: false, }, - limitations: IDA_LIMITATIONS, + limitations: + native && (operation === "list_strings" || operation === "search_strings") + ? [...IDA_LIMITATIONS, IDA_NATIVE_STRING_LIMITATION] + : IDA_LIMITATIONS, })); diff --git a/tests/conformance/ida/inventory.c b/tests/conformance/ida/inventory.c index 83dc5ef2c..d5367fb81 100644 --- a/tests/conformance/ida/inventory.c +++ b/tests/conformance/ida/inventory.c @@ -10,6 +10,10 @@ REA_EXPORT REA_NOINLINE int rea_fixture_add(int left, int right) { return left + right + 7; } +REA_EXPORT REA_NOINLINE int rea_fixture_subtract(int left, int right) { + return left - right - 13; +} + int main(void) { - return rea_fixture_add(11, 24); + return rea_fixture_add(11, 24) + rea_fixture_subtract(24, 11); } diff --git a/tests/fixtures/idaMcp.ts b/tests/fixtures/idaMcp.ts index 00202208d..04bdb5f16 100644 --- a/tests/fixtures/idaMcp.ts +++ b/tests/fixtures/idaMcp.ts @@ -113,10 +113,13 @@ export class RecordingIdaMcp implements IdaMcpConnection { if (overridden !== undefined) return overridden; if (["idb_open", "idb_list", "idb_close", "server_health"].includes(name)) return this.lifecycle(name, args); - return this.read(name); + return this.read(name, args); } - private read(name: string): JsonValue { + private read( + name: string, + args: Readonly>, + ): JsonValue { const fn = { address: "0x1000", name: "main", size: "0x20" }; const asm = { name: "main", @@ -153,13 +156,13 @@ export class RecordingIdaMcp implements IdaMcpConnection { case "get_function_by_name": return fn; case "lookup_funcs": - return [ - { - query: "main", - fn: { addr: fn.address, name: fn.name, size: fn.size }, - error: null, - }, - ]; + if (!Array.isArray(args.queries)) + throw new Error("Invalid fixture lookup queries"); + return args.queries.map((query) => ({ + query, + fn: { addr: fn.address, name: fn.name, size: fn.size }, + error: null, + })); case "decompile_function": return this.pseudocode; case "decompile":