Files
reverse-engineering-anything/tests/composition/idaProvider.test.ts
T
morluto ff0176256a feat(snapshots)!: persist the target identity as the snapshot target (#11551)
* feat(snapshots)!: persist the target identity as the snapshot target

The snapshot target is now `{ kind, identity }`, where `identity` is the
FileTargetIdentity that `binaryTargetIdentity` produces and `kind` is the
binary kind query IDs commit to. The per-format target projection and
`snapshotTargetIdentity` are deleted; the schema checks the format's
selection, architecture and kind instead of keeping one union arm per format.

Entry execution subjects use the Evidence subject shape (file or explicit
unknown), so a snapshot entry commits to the same identity, including the
selection, as its Evidence record. Workflow entries take the subject of the
workflow's own Evidence. Replay no longer re-derives the selection from the
open target.

`FileTargetSelection` gains `universal-slice` (`offset`, `size`, and the FAT
`cpu_type`/`cpu_subtype` when target admission supplied the FAT table, else
null). `binaryTargetIdentity` produces it for `mach-o-universal` targets, so
Evidence and snapshots for different slices of one container no longer share
an identity.

Refs #11417

BREAKING CHANGE: analysis snapshot files change shape: `target` is
`{ kind, identity: { kind: "file", sha256, format, architecture, selection } }`
and entry `execution.subject` is the Evidence subject
(`{ identity, name, local_path }`, never null). Snapshot binding mismatch
details report `target.snapshot`/`target.selected` in the same shape. Evidence
IDs of universal Mach-O targets change because their subject identity now
carries the selected slice. Recreate saved snapshots and Evidence bundles of
universal Mach-O targets.

* docs(evidence): name the universal Mach-O slice selection in the subject contract

* fix(snapshots): read the snapshot target identity in the Ghidra verification scripts

The real Ghidra snapshot checks (lifecycle, RISC-V, MIPS, PowerPC) read
snapshot.target.sha256 and .architecture, which moved under
snapshot.target.identity, so they would fail after saving a valid snapshot.

* feat(evidence)!: name live browser page Evidence by its page URL (#11559)

Browser page observations (inspect_web_page, analyze_web_bundle,
observe_web_session, discover_webmcp_tools, capture_web_screenshot,
observe_web_execution, inspect_web_event_listeners) named an unknown
(`not-observed`) subject although the provider reports the page URL.

`TargetIdentity` gains a `url` kind: the reported URL with userinfo removed
and its origin (`null` for an opaque origin). The schema refuses a URL that
carries userinfo or an origin the URL does not have.
`browserUrlTargetIdentity` in the browser URL owner builds it from the
provider's reported URL; a withheld or unparseable URL stays unknown
(`not-observed`). Target lists and comparisons still name no single
document. Analysis views keep their parent's URL subject, as they already
keep a file subject.

BREAKING CHANGE: Evidence IDs of live browser page observations and their
analysis views change, and their subject is
`{ "kind": "url", "url", "origin" }` with `name` and `local_path` null.
Recreate stored Evidence for these tools. This lands inside Evidence format
revision 2 under the release hold (#11417); no `evidence_format` bump.
2026-11-16 07:04:34 +08:00

407 lines
15 KiB
TypeScript

import { 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";
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";
import { parseConfig } from "../../src/config/parseConfig.js";
import {
createAnalysisSnapshotEntry,
snapshotBinding,
snapshotTarget,
} from "../../src/domain/analysisSnapshot.js";
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_PROVIDER_IDENTITY } from "../../src/ida/IdaProviderMetadata.js";
import { parseBinaryTarget } from "../../src/application/BinaryTargetResolver.js";
import { fat } from "../../src/domain/binaryTarget.fixture.js";
import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js";
import { BinarySession } from "../../src/application/binary/BinarySession.js";
import { SessionProviderRouter } from "../../src/application/binary/SessionProviderRouter.js";
import { AnalysisProviderRegistry } from "../../src/application/binary/AnalysisProviderRegistry.js";
const roots: string[] = [];
afterEach(async () => {
for (const root of roots.splice(0))
await rm(root, { recursive: true, force: true });
});
const reobservesExternallyMutableState = async (): Promise<void> => {
const { root, target } = await createIdaTarget();
roots.push(root);
const path = join(root, "registration.json");
await writeFile(
path,
JSON.stringify({ command: "fixture", protocol: "legacy" }),
);
const config = parseConfig({ REA_IDA_MCP_CONFIG: path });
if (!config.ok) throw config.error;
const producer = new RecordingIdaMcp(target);
const session = createTestBinarySession(
new IdaProvider(config.value, {}, () => producer),
);
expect((await session.open(target.path)).ok).toBe(true);
const query = { procedure: "main", document: target.path };
const first = await session.execute("procedure_pseudo_code", query);
expect(first.ok && first.value.result).toContain("42");
const snapshot = session.exportAnalysisSnapshot();
if (!snapshot.ok) throw snapshot.error;
expect(snapshot.value.entries).toEqual([]);
const profile = session.analysisProfile();
if (profile === undefined) throw new Error("Missing profile");
const cached = createAnalysisExecution(
"stale output",
IDA_PROVIDER_IDENTITY,
{
analysisProfile: profile,
subject: {
path: target.path,
sha256: target.sha256,
format: target.format,
...(target.architecture === undefined
? {}
: { architecture: target.architecture }),
},
},
);
snapshot.value.entries.push(
createAnalysisSnapshotEntry({
target: snapshotTarget(target),
binding: snapshotBinding(profile),
operation: "procedure_pseudo_code",
parameters: query,
execution: snapshotExecution(cached),
}),
);
snapshot.value.evidence_bundle = createEvidenceBundle([
...snapshot.value.evidence_bundle.records,
createEvidence(target, IDA_PROVIDER_IDENTITY, {
operation: "procedure_pseudo_code",
parameters: query,
result: cached.result,
rawResult: cached.rawResult,
analysisProfile: profile,
}),
]);
expect(session.importAnalysisSnapshot(snapshot.value).ok).toBe(true);
expect(session.allowsSnapshotReplay("procedure_pseudo_code")).toBe(false);
expect(session.allowsSnapshotReplay("binary_overview")).toBe(false);
producer.pseudocode = "int main(void) { return 99; }";
const second = await session.execute("procedure_pseudo_code", query);
expect(second.ok && second.value.result).toContain("99");
expect(
producer.calls.filter(({ name }) => name === "decompile_function"),
).toHaveLength(2);
await session.close();
expect(producer.closes).toBe(1);
};
describe("IDA provider composition", () => {
it("discovers without launching and commits adapter semantics without persisting credentials", async () => {
const { root, target } = await createIdaTarget();
roots.push(root);
const path = join(root, "registration.json");
await writeFile(
path,
JSON.stringify({
url: "http://127.0.0.1:8745/mcp",
headers: { Authorization: "Bearer private-fixture-token" },
mode: "headless",
}),
);
const config = parseConfig({ REA_IDA_MCP_CONFIG: path });
if (!config.ok) throw config.error;
const producer = new RecordingIdaMcp(target, "headless");
const provider = new IdaProvider(config.value, {}, () => producer);
expect(await provider.inspectAvailability()).toMatchObject({
status: "available",
diagnostics: { live_connection_probed: false },
});
const resolution = await provider.resolveAnalysisProfile(target);
if (!resolution.ok) throw resolution.error;
expect(resolution.value.profile.parameters).toMatchObject({
engine_version: null,
upstream_distribution_version: null,
cache_policy: "live",
version_scope: "rea-ida-adapter",
});
expect(JSON.stringify(resolution)).not.toContain("private-fixture-token");
expect(producer.connects).toBe(0);
expect(
(await provider.inspectReadinessSnapshot()).capabilities.find(
({ operation }) => operation === "procedure_callers",
)?.available,
).toBe(false);
});
it(
"re-observes externally mutable state even when a document is explicit and a snapshot is imported",
reobservesExternallyMutableState,
);
it("rejects unsupported target kinds and reports incomplete upstream profiles on first analysis", async () => {
const { root, target } = await createIdaTarget();
roots.push(root);
const path = join(root, "registration.json");
await writeFile(
path,
JSON.stringify({
command: "fixture",
mode: "headless",
workspaceRoot: root,
}),
);
const config = parseConfig({ REA_IDA_MCP_CONFIG: path });
if (!config.ok) throw config.error;
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",
}),
).toMatchObject({ status: "unsupported", code: "target_kind_unsupported" });
const session = createTestBinarySession(provider);
expect((await session.open(target.path)).ok).toBe(true);
expect(producer.connects).toBe(0);
const analyzed = await session.execute("procedure_pseudo_code", {
procedure: "main",
});
expect(analyzed).toMatchObject({
ok: false,
error: {
_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);
});
});
describe("IDA provider selection cancellation", () => {
it("restores a cancelled replacement through the prior selected registration binding", async () => {
const first = await createIdaTarget();
const second = await createIdaTarget();
roots.push(first.root, second.root);
const path = join(first.root, "registration.json");
await writeFile(
path,
JSON.stringify({ command: "first-server", protocol: "legacy" }),
);
const config = parseConfig({ REA_IDA_MCP_CONFIG: path });
if (!config.ok) throw config.error;
const factorySelections: string[] = [];
const controller = new AbortController();
const cancellationReason = new Error(
"cancel after retiring previous IDA client",
);
let cancelWhenPreviousCloses = false;
const provider = new IdaProvider(config.value, {}, (registration) => {
const command =
"command" in registration ? registration.command : registration.url;
factorySelections.push(command);
const producer = new RecordingIdaMcp(first.target, "attached");
if (factorySelections.length === 1) {
const close = producer.close.bind(producer);
producer.close = async () => {
await close();
if (cancelWhenPreviousCloses) controller.abort(cancellationReason);
};
}
return producer;
});
const session = createTestBinarySession(provider);
expect((await session.open(first.target.path)).ok).toBe(true);
expect(
(await session.execute("procedure_pseudo_code", { procedure: "main" }))
.ok,
).toBe(true);
await writeFile(
path,
JSON.stringify({ command: "replacement-server", protocol: "legacy" }),
);
cancelWhenPreviousCloses = true;
const replacement = await session.open(second.target.path, {
signal: controller.signal,
});
expect(replacement.ok).toBe(false);
expect(replacement).toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError", cause: cancellationReason },
});
if (replacement.ok) throw new Error("Expected cancellation");
expect(replacement.error.cause).toBe(cancellationReason);
expect(session.activeTarget()?.sha256).toBe(first.target.sha256);
expect(
(await session.execute("procedure_pseudo_code", { procedure: "main" }))
.ok,
).toBe(true);
expect(factorySelections).toEqual(["first-server", "first-server"]);
expect((await session.close()).ok).toBe(true);
});
it("preserves an already-aborted profile signal without reading registration", async () => {
const { root, target } = await createIdaTarget();
roots.push(root);
const config = parseConfig({
REA_IDA_MCP_CONFIG: join(root, "registration-that-must-not-be-read.json"),
});
if (!config.ok) throw config.error;
const reason = new Error("cancel before IDA profile inspection");
const controller = new AbortController();
controller.abort(reason);
let runCalls = 0;
const profile = await new IdaProvider(
config.value,
{},
).resolveAnalysisProfile(target, {
signal: controller.signal,
resourceScope: {
retain: () => undefined,
run: async (operation) => {
runCalls += 1;
return operation();
},
},
});
expect(profile).toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError", cause: reason },
});
if (profile.ok) throw new Error("Expected cancellation");
expect(profile.error.cause).toBe(reason);
expect(runCalls).toBe(0);
});
});
describe("IDA universal Mach-O target identity", () => {
const openUniversal = async (registration: Record<string, unknown>) => {
const root = await createTestTempDirectory("rea-ida-universal-");
const input = join(root, "universal");
// x86_64 and arm64 slices share one whole-file digest.
await writeFile(input, fat([0x01000007, 0x0100000c]));
const resolved = await parseBinaryTarget(input);
if (!resolved.ok) throw resolved.error;
const path = join(root, "registration.json");
await writeFile(
path,
JSON.stringify({ ...registration, workspaceRoot: root }),
);
const config = parseConfig({ REA_IDA_MCP_CONFIG: path });
if (!config.ok) throw config.error;
const producer = new RecordingIdaMcp(
resolved.value,
registration.mode === "headless" ? "headless" : "attached",
);
// The production registry consults IDA's own target admission.
const session = new BinarySession(
SessionProviderRouter.selectable(
new AnalysisProviderRegistry([
new IdaProvider(config.value, {}, () => producer),
]),
[],
),
);
return {
producer,
session,
opened: await session.open(input, { providerId: "ida" }),
};
};
it.each([
{
profile: "legacy attached",
registration: { command: "fixture", protocol: "legacy" },
},
{
profile: "native attached",
registration: {
url: "http://127.0.0.1:13337/mcp",
mode: "attached",
protocol: "native",
},
},
])(
"refuses $profile analysis whose recorded whole-file digest cannot identify the loaded slice",
async ({ registration }) => {
const { producer, session, opened } = await openUniversal(registration);
expect(opened).toMatchObject({
ok: false,
error: {
_tag: "ProviderSelectionError",
reason: "target_unsupported",
rejections: [
{
providerId: "ida",
code: "target_format_unsupported",
reason: expect.stringContaining("lipo -thin"),
},
],
},
});
expect(producer.connects).toBe(0);
expect((await session.close()).ok).toBe(true);
},
);
it("keeps admitting headless analysis, which thins the selected slice", async () => {
const { session, opened } = await openUniversal({
command: "fixture",
mode: "headless",
});
expect(opened.ok).toBe(true);
expect((await session.close()).ok).toBe(true);
});
});
describe("IDA binary_overview execution", () => {
it("uses the bound IDA document and omits unsupported segment coverage", async () => {
const { root, target } = await createIdaTarget();
roots.push(root);
const path = join(root, "registration.json");
await writeFile(
path,
JSON.stringify({ command: "fixture", protocol: "legacy" }),
);
const config = parseConfig({ REA_IDA_MCP_CONFIG: path });
if (!config.ok) throw config.error;
const producer = new RecordingIdaMcp(target);
const session = createTestBinarySession(
new IdaProvider(config.value, {}, () => producer),
);
expect((await session.open(target.path)).ok).toBe(true);
const tools = new EnhancedTools(session);
const overview = await tools.execute("binary_overview", {});
expect(overview.ok).toBe(true);
if (overview.ok) {
expect(overview.value).toMatchObject({
document: target.path,
procedure_count: 1,
string_count: 1,
});
expect(overview.value).not.toHaveProperty("segments");
expect(overview.value).not.toHaveProperty("segment_count");
}
const procedures = await session.execute("list_procedures", {});
expect(procedures.ok).toBe(true);
expect((await session.close()).ok).toBe(true);
});
});