Files
rea/src/ida/IdaSessionClient.test.ts
T

446 lines
17 KiB
TypeScript

import { readFile, readdir, rm } from "node:fs/promises";
import { afterEach, describe, expect, it } from "vitest";
import { z } from "zod";
import {
createIdaTarget,
RecordingIdaMcp,
} from "../../tests/fixtures/idaMcp.js";
import { IdaSessionClient } from "./IdaSessionClient.js";
import { functionDossierSchema } from "../domain/hopperValues.js";
import { jsonValueSchema } from "../domain/jsonValue.js";
const roots: string[] = [];
afterEach(async () => {
for (const root of roots.splice(0))
await rm(root, { recursive: true, force: true });
});
const fixture = async (mode: "attached" | "headless" = "attached") => {
const { root, target } = await createIdaTarget();
roots.push(root);
const producer = new RecordingIdaMcp(target, mode);
const client = new IdaSessionClient(
{
command: "fixture",
args: [],
env: {},
mode,
timeoutMs: 1000,
workspaceRoot: root,
},
target,
producer,
);
return { root, target, producer, client };
};
describe("headless IDA producer pagination", () => {
it("follows reported cursors for modern inventories, pseudocode, and bare-hex assembly without losing pages", async () => {
const { producer, client } = await fixture("headless");
producer.overrideCall = (name, args) => {
const first = args.offset === 0;
const cursor = first ? { next: 1 } : { done: true };
if (name === "decompile")
return { code: first ? "first line" : "second line", cursor };
if (name === "disasm")
return {
asm: {
name: "main",
start_ea: "0x1000",
lines: [
{
addr: first ? "1000" : "1001",
instruction: first ? "push rbp" : "ret",
},
],
},
cursor,
};
if (name === "find_regex")
return {
matches: [
{
addr: first ? "0x3000" : "0x3002",
string: first ? "a.b" : "a+b",
},
],
cursor,
};
if (name === "list_funcs") {
const page = z
.object({ offset: z.number() })
.parse(args.queries).offset;
return [
{
data: [
{
addr: page === 0 ? "0x1000" : "0x2000",
name: page === 0 ? "main" : "other",
size: "0x20",
},
],
next_offset: page === 0 ? 1 : null,
},
];
}
return undefined;
};
const inventory = await client.execute("list_procedures", {});
expect(inventory.ok && inventory.value.result).toHaveLength(2);
const strings = await client.execute("list_strings", {});
expect(strings.ok && strings.value.result).toHaveLength(2);
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("first line\nsecond line");
expect(dossier.assembly).toEqual(["0x1000: push rbp", "0x1001: ret"]);
await client.close();
});
});
describe("attached IDA observation semantics", () => {
it("rejects an unrelated document before connecting or opening a provider", async () => {
const { producer, client } = await fixture();
const result = await client.execute("list_procedures", {
document: "/unrelated/input",
});
expect(result.ok).toBe(false);
if (!result.ok) {
expect(result.error._tag).toBe("AnalysisInputError");
expect(result.error.message).toContain("list_procedures");
}
expect(producer.connects).toBe(0);
expect(producer.calls).toEqual([]);
await client.close();
});
it("preserves hexadecimal-looking function names as names unless the caller uses an explicit 0x address", async () => {
const { producer, client } = await fixture();
producer.overrideCall = (name, args) =>
name === "get_function_by_name" && args.name === "f"
? { address: "0x1000", name: "f", size: "0x20" }
: undefined;
const found = await client.execute("procedure_address", { procedure: "f" });
expect(found.ok && found.value.result).toBe("0x1000");
expect(
producer.calls.some(({ name }) => name === "get_function_by_address"),
).toBe(false);
await client.close();
});
it("accepts MCP's null projection for omitted optional fields without accepting null required fields", async () => {
const { producer, client } = await fixture();
expect(
(await client.execute("list_procedures", { document: null })).ok,
).toBe(true);
expect(
(await client.execute("list_strings", { document: null, address: null }))
.ok,
).toBe(true);
expect(
(
await client.execute("procedure_pseudo_code", {
document: null,
procedure: "main",
})
).ok,
).toBe(true);
const required = await client.execute("procedure_pseudo_code", {
document: null,
procedure: null,
});
expect(required.ok).toBe(false);
if (!required.ok) expect(required.error._tag).toBe("AnalysisInputError");
expect(
producer.calls.filter(({ name }) => name === "decompile_function"),
).toHaveLength(1);
await client.close();
});
});
describe("attached IDA function observations", () => {
it("resolves interior addresses and call sites to canonical entries, preserves externals, and reports unknown body evidence", async () => {
const { producer, client } = await fixture();
const result = await client.execute("analyze_function", {
procedure: "0x1004",
});
expect(result.ok).toBe(true);
if (!result.ok) throw result.error;
const dossier = functionDossierSchema.parse(result.value.result);
expect(dossier.procedure.address).toBe("0x1000");
expect(dossier.callers.map((caller) => caller.address)).toEqual(["0x1000"]);
expect(dossier.callees.map((callee) => callee.address)).toEqual(["0x2000"]);
expect(dossier.procedure.body.available).toBe(false);
expect(dossier.comments).toEqual([]);
expect(result.value.rawResult).toMatchObject({
observations: expect.arrayContaining([
expect.objectContaining({ tool: "get_callers" }),
]),
});
expect(result.value.provider.version).toBe("1");
expect(producer.serverInfo()).toMatchObject({
version: "sdk-version-is-not-ida",
});
await client.close();
expect(producer.calls.some(({ name }) => name.startsWith("idb_"))).toBe(
false,
);
});
it("returns complete paged inventory and distinguishes literal from regex search", async () => {
const { producer, client } = await fixture();
producer.overrideCall = (name, args) =>
name === "list_functions"
? {
data: [
{
address: args.offset === 0 ? "0x1000" : "0x2000",
name: "main",
size: "0x10",
},
],
next_offset: args.offset === 0 ? 100 : null,
}
: undefined;
const inventory = await client.execute("list_procedures", {});
expect(inventory.ok && inventory.value.result).toHaveLength(2);
for (const [pattern, mode, count] of [
["a.b", "literal", 1],
["a+b", "literal", 0],
["a.b", "regex", 1],
] as const) {
const found = await client.execute("search_strings", { pattern, mode });
expect(found.ok && found.value.result).toHaveLength(count);
}
expect(
(await client.execute("search_strings", { pattern: "[", mode: "regex" }))
.ok,
).toBe(false);
await client.close();
});
it("rejects mismatched identities and target switches rather than returning a successful observation", async () => {
const { producer, client, target } = await fixture();
producer.inputSha256 = "a".repeat(64);
const mismatch = await client.execute("health", {});
expect(mismatch.ok).toBe(false);
if (!mismatch.ok) expect(mismatch.error.message).toContain("SHA-256");
producer.inputSha256 = target.sha256;
producer.beforeCall = async (name) => {
if (name === "decompile_function") producer.imageBase = "0x2000";
};
const changed = await client.execute("procedure_pseudo_code", {
procedure: "main",
});
expect(changed.ok).toBe(false);
if (!changed.ok) expect(changed.error.message).toContain("changed");
await client.close();
});
it("rejects malformed producer data, non-advancing cursors, unsupported mutation, and missing explicit addresses", async () => {
const { producer, client } = await fixture();
expect(
(
await client.execute("set_address_name", {
address: "0x1000",
name: "changed",
})
).ok,
).toBe(false);
expect(producer.connects).toBe(0);
expect((await client.execute("xrefs", {})).ok).toBe(false);
const invalidAddress = await client.execute("xrefs", {
address: "not-an-address",
});
expect(invalidAddress.ok).toBe(false);
if (!invalidAddress.ok)
expect(invalidAddress.error._tag).toBe("AnalysisInputError");
expect(producer.connects).toBe(0);
producer.overrideCall = (name) =>
name === "list_functions" ? { data: [], next_offset: 0 } : undefined;
expect((await client.execute("list_procedures", {})).ok).toBe(false);
producer.overrideCall = (name) =>
name === "decompile_function" ? { unexpected: true } : undefined;
const malformed = await client.execute("procedure_pseudo_code", {
procedure: "main",
});
expect(malformed.ok).toBe(false);
if (!malformed.ok) expect(malformed.error._tag).toBe("AnalysisOutputError");
await client.close();
});
it("drains in-flight read-only work on cancellation before closing its proxy", async () => {
const { producer, client } = await fixture();
await client.execute("health", {});
let release: (() => void) | undefined;
let notify: (() => void) | undefined;
const started = new Promise<void>((resolve) => {
notify = resolve;
});
producer.beforeCall = async (name) => {
if (name === "decompile_function") {
notify?.();
await new Promise<void>((resolve) => {
release = resolve;
});
}
};
const controller = new AbortController();
const call = client.execute(
"procedure_pseudo_code",
{ procedure: "main" },
{ signal: controller.signal },
);
await started;
controller.abort();
const close = client.closeWithOutcome();
expect(producer.closes).toBe(0);
release?.();
const result = await call;
expect(result.ok).toBe(false);
if (!result.ok) expect(result.error._tag).toBe("AnalysisCancelledError");
expect((await close).ok).toBe(true);
expect(producer.closes).toBe(1);
});
});
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");
producer.owned = false;
expect((await client.execute("health", {})).ok).toBe(false);
const closed = await client.closeWithOutcome();
expect(closed.ok).toBe(false);
if (!closed.ok) expect(closed.error.cleanupIncomplete).toBe(true);
expect(producer.calls.some(({ name }) => name === "idb_close")).toBe(false);
});
});
describe("headless IDA session ownership and cleanup", () => {
it("shares an in-flight close across concurrent cleanup callers", async () => {
const { producer, client } = await fixture("headless");
expect((await client.execute("health", {})).ok).toBe(true);
let release: (() => void) | undefined;
let notify: (() => void) | undefined;
const closeStarted = new Promise<void>((resolve) => {
notify = resolve;
});
producer.beforeCall = async (name) => {
if (name !== "idb_close") return;
notify?.();
await new Promise<void>((resolve) => {
release = resolve;
});
};
const first = client.closeWithOutcome();
await closeStarted;
const second = client.closeWithOutcome();
release?.();
const results = await Promise.all([first, second]);
expect(results.every((result) => result.ok)).toBe(true);
expect(
producer.calls.filter(({ name }) => name === "idb_close"),
).toHaveLength(1);
expect(producer.closes).toBe(1);
});
it("retains the workspace after an unconfirmed open, even when inventory is empty, and never retries startup implicitly", async () => {
const { producer, client, root } = await fixture("headless");
producer.beforeCall = async (name) => {
if (name === "idb_open")
throw new Error("Timed out while the worker may still be opening");
};
expect((await client.execute("health", {})).ok).toBe(false);
expect((await client.execute("health", {})).ok).toBe(false);
expect(
producer.calls.filter(({ name }) => name === "idb_open"),
).toHaveLength(1);
const closed = await client.closeWithOutcome();
expect(closed.ok).toBe(false);
if (!closed.ok) expect(closed.error.cleanupIncomplete).toBe(true);
expect(
(await readdir(root)).some((name) => name.startsWith("rea-ida-")),
).toBe(true);
expect(producer.closes).toBe(1);
});
it("opens a private digest-verified copy, scopes requests, closes without saving, and removes only its workspace", async () => {
const { producer, client, root, target } = await fixture("headless");
const original = await readFile(target.path);
const result = await client.execute("analyze_function", {
procedure: "main",
});
expect(result.ok).toBe(true);
if (!result.ok) throw result.error;
expect(producer.inputPath).not.toBe(target.path);
expect(await readFile(producer.inputPath)).toEqual(original);
expect(
functionDossierSchema
.parse(result.value.result)
.limitations.some((value) => value.includes("Direct callers")),
).toBe(true);
const open = producer.calls.find(({ name }) => name === "idb_open");
expect(open?.args).toMatchObject({
mode: "force_headless",
run_auto_analysis: true,
});
for (const call of producer.calls.filter(
({ name }) => !["idb_open", "idb_list"].includes(name),
))
expect(call.args.database).toBe(producer.database);
expect((await client.closeWithOutcome()).ok).toBe(true);
expect(
producer.calls.find(({ name }) => name === "idb_close")?.args.save,
).toBe(false);
expect(await readdir(root)).toEqual(["target.elf"]);
expect(await readFile(target.path)).toEqual(original);
});
it("retains the private workspace and reports cleanup failure when worker release is unverified", async () => {
const { producer, client, root } = await fixture("headless");
await client.execute("health", {});
producer.failClose = true;
const result = await client.closeWithOutcome();
expect(result.ok).toBe(false);
if (!result.ok) expect(result.error.cleanupIncomplete).toBe(true);
expect(
(await readdir(root)).some((name) => name.startsWith("rea-ida-")),
).toBe(true);
});
it("never closes an unrelated database when startup returns a different input identity", async () => {
const { producer, client, root } = await fixture("headless");
producer.overrideCall = (name) =>
name === "idb_open"
? {
success: true,
session: {
session_id: "user-database",
input_path: "/unrelated/input",
},
}
: undefined;
expect((await client.execute("health", {})).ok).toBe(false);
expect((await client.closeWithOutcome()).ok).toBe(true);
expect(producer.calls.some(({ name }) => name === "idb_close")).toBe(false);
expect(await readdir(root)).toEqual(["target.elf"]);
});
it("releases a privately owned worker after malformed open output using verified session inventory", async () => {
const { producer, client, root } = await fixture("headless");
producer.beforeCall = async (name, args) => {
if (name === "idb_open") {
producer.database = z.string().parse(args.preferred_session_id);
producer.inputPath = z.string().parse(args.input_path);
}
};
producer.overrideCall = (name) =>
name === "idb_open"
? jsonValueSchema.parse({
success: true,
session: { session_id: producer.database },
})
: undefined;
expect((await client.execute("health", {})).ok).toBe(false);
expect((await client.closeWithOutcome()).ok).toBe(true);
expect(
producer.calls.find(({ name }) => name === "idb_close")?.args.database,
).toMatch(/^rea-/u);
expect(await readdir(root)).toEqual(["target.elf"]);
});
});