chore(docs): merge captured main into documentation continuation

This commit is contained in:
morluto
2026-10-13 21:07:53 +08:00
48 changed files with 2473 additions and 123 deletions
+3 -1
View File
@@ -682,7 +682,9 @@ 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
CLI/MCP parity, inventory/search, pseudocode, instructions, xrefs, malformed
input, original-input preservation, and lifecycle cleanup. For headless
input, original-input preservation, and lifecycle cleanup. The headless
profile also checks containing procedures, the admitted program as the
document, address context, and feature tracing. For headless
analysis it confirms that the owned database IDs disappear from upstream
discovery and private workspaces are removed. For attached analysis it confirms
the existing GUI target remains reachable with the same input identity.
+4
View File
@@ -88,6 +88,8 @@ REA copies the admitted binary into a private temporary directory, checks its di
One REA session owns one database. Stdio registrations default `IDA_MCP_MAX_WORKERS` to `1`; the explicit upstream `--max-workers 1` also bounds a supervisor. Database size and engine memory depend on the target and upstream; REA does not impose an engine memory limit. The original binary is never executed or overwritten. Optional `workspaceRoot` selects an existing absolute temporary-directory parent on the REA host. Ensure it has space for the input copy and IDA working files.
When a completed `idb_open` response reports success or is otherwise ambiguous, but no active owned private worker can be verified, REA retains the private workspace even if `idb_list` appears empty. A later close can retry verification if the original owned worker becomes discoverable. A completed explicit `idb_open` rejection retains the existing no-worker cleanup path. This is a local admission/ownership safeguard and **does not** provide a process-termination receipt or change the legacy reaped-worker protocol.
Headless cleanup uses the upstream database lifecycle. Abruptly terminating REA, its proxy, or the supervisor does not establish worker release. Prefer `close_binary` for MCP sessions; after an interrupted process, inspect upstream session inventory and retained workspace diagnostics before removing working files. This adapter does not claim Windows Job Object containment for the upstream detached workers.
## Connect an agent once
@@ -126,6 +128,8 @@ For guided registration, set `REA_IDA_MCP_CONFIG` before `rea setup --client <cl
All profiles support procedure/string inventory and literal or regex search, procedure resolution, pseudocode, assembly, raw function instructions, resolved callees, incoming address references, and a function dossier. Inventories and modern pseudocode/assembly follow upstream pagination. Upstream limits on modern xrefs and callees are retained as explicit truncation limitations. In the modern headless profile, targets that are not proven x86-only use processor-neutral `callgraph` edges instead of the x86 instruction checks in upstream `callees` (mrexodia/ida-pro-mcp#549). REA requests depth zero: the pinned upstream emits the root's outgoing edges without scanning child functions, then REA batches function-name lookup for those addresses. The graph covers recognized function destinations only; imports and other non-function targets remain unknown. A server without `callgraph` returns an empty relationship list with an explicit coverage limitation. Graph and path workflows retain those limitations alongside observed edges. A failed or inconsistent graph reply remains an error. A transport-level truncated preview is rejected rather than reported as complete evidence; the error preserves upstream retrieval guidance.
The modern headless profile also supports `resolve_containing_procedure` and `list_documents`. An address resolves through upstream `lookup_funcs` to the canonical entry of the function that contains it; the body stays unavailable like other IDA identities. When no function contains it, REA reads the database-scoped minimal `survey_binary` and reports `not_in_procedure` for an address inside one of its segments (ends are exclusive) and `outside_segments` otherwise. A missing, truncated or inconsistent survey fails the read instead of guessing a reason. `list_documents` returns the single admitted program path, so `inspect_address_context` and `trace_feature` need no explicit document. `trace_feature` marks a trace truncated, with a residual unknown for that address, when upstream caps the references it returned. The legacy and native profiles do not declare these operations.
The legacy profile additionally supports direct callers. Its producer may report call-site or interior addresses; REA resolves the reported function symbol to its canonical entry. The modern and native profiles do not prove direct callers from its code/data xref labels, so that capability is unavailable and the dossier marks it unknown.
Complete body ranges, typed reference edges, CFG, referenced data, source locals, comment kinds, and database revision are unavailable. Empty unsupported dossier facets mean **unknown**, not observed absence. `binary_overview`, whole-symbol inventory, mutation, debugging, arbitrary Python forwarding, and requested GUI navigation are outside this adapter's coverage. Check session availability before composing a workflow that needs those facets.
+9
View File
@@ -0,0 +1,9 @@
export function assertFeatureTrace(
trace: unknown,
procedure: { readonly address: string },
): void;
export function findMappedNonFunction(
strings: readonly { readonly address: string }[],
resolveAt: (address: string) => Promise<unknown>,
): Promise<string | undefined>;
+52
View File
@@ -0,0 +1,52 @@
import assert from "node:assert/strict";
const NEGATIVE_REASONS = new Set(["not_in_procedure", "outside_segments"]);
/**
* Assert the `trace_feature` result of the real IDA lane for one selected
* procedure. The query is a substring search, so the trace may also match other
* procedures and strings; each reference is checked against its own matched
* target, and a source outside every function (a data reference) is valid.
*/
export function assertFeatureTrace(trace, procedure) {
assert.ok(
trace.matches.some(
({ type, address }) =>
type === "procedure" && address === procedure.address,
),
"The trace omitted the selected procedure's match.",
);
assert.equal(typeof trace.truncated, "boolean");
const matched = new Set(trace.matches.map(({ address }) => address));
for (const reference of trace.references) {
assert.ok(
matched.has(reference.target_address),
`A reference targets ${reference.target_address}, which is not a match.`,
);
const { containing_procedure: containing } = reference;
if (containing.found)
assert.equal(typeof containing.procedure.address, "string");
else assert.ok(NEGATIVE_REASONS.has(containing.reason));
}
}
/**
* Find a string that IDA maps outside every function. A string inside a
* function chunk (inline data in code) is valid and skipped, so the strings are
* tried in order. Any other answer must be "not in a procedure": IDA lists only
* mapped strings, so an unmapped answer is a containment defect and fails the
* lane. Returns the address, or undefined when every string is inside a function.
*/
export async function findMappedNonFunction(strings, resolveAt) {
for (const { address } of strings) {
const resolved = await resolveAt(address);
if (resolved.found) continue;
assert.equal(
resolved.reason,
"not_in_procedure",
`The listed string at ${address} resolved as ${resolved.reason}.`,
);
return address;
}
return undefined;
}
+60 -1
View File
@@ -1,4 +1,8 @@
#!/usr/bin/env node
import {
assertFeatureTrace,
findMappedNonFunction,
} from "./lib/ida-feature-trace.mjs";
import { requireMcpToolError } from "./lib/mcp-verifier-results.mjs";
import assert from "node:assert/strict";
@@ -6,7 +10,7 @@ import { execFile } from "node:child_process";
import { createHash } from "node:crypto";
import { createReadStream } from "node:fs";
import { access, writeFile } from "node:fs/promises";
import { dirname, join, resolve } from "node:path";
import { basename, dirname, join, resolve } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { parseArgs, promisify } from "node:util";
import { Client } from "@modelcontextprotocol/client";
@@ -261,6 +265,61 @@ const mcp = async (cliDossier) => {
break;
}
}
if (config.mode === "headless") {
const documents = observe(await call("list_documents", {}));
assert.equal(documents.length, 1);
assert.equal(basename(documents[0]), basename(target));
assert.ok(
!workspaces.has(dirname(documents[0])),
"list_documents reported the private workspace copy.",
);
const resolveAt = async (address) =>
observe(await call("resolve_containing_procedure", { address }));
const instructionAddresses = dossier.assembly
.map((line) => /^(0x[0-9a-f]+)/iu.exec(line)?.[1])
.filter((address) => address !== undefined);
const queries = [
dossier.procedure.address,
...instructionAddresses.slice(1, 2),
];
for (const queried of queries) {
const containing = await resolveAt(queried);
assert.equal(containing.found, true);
assert.equal(containing.procedure.address, dossier.procedure.address);
assert.equal(containing.procedure.name, dossier.procedure.name);
}
const unmapped = await resolveAt("0xffffffffffffff00");
assert.equal(unmapped.found, false);
assert.equal(unmapped.reason, "outside_segments");
const strings = observe(await call("list_strings", {}));
const mappedString = await findMappedNonFunction(strings, resolveAt);
if (mappedString === undefined)
report.unverified.push(
"Mapped non-function containment: no string of the target is mapped outside every function.",
);
const context = await client.callTool({
name: "inspect_address_context",
arguments: { address: dossier.procedure.address },
});
assert.notEqual(context.isError, true);
const contextResult = context.structuredContent.result;
assert.equal(contextResult.document, documents[0]);
assert.equal(contextResult.procedure.state, "available");
assert.equal(
contextResult.procedure.value.procedure.address,
dossier.procedure.address,
);
const traced = await client.callTool({
name: "trace_feature",
arguments: { query: dossier.procedure.name },
});
assert.notEqual(traced.isError, true);
const trace = traced.structuredContent.normalized_result;
assertFeatureTrace(trace, dossier.procedure);
report.checks.push(
"headless containing procedures, the admitted program as the document, address context, and the procedure match and references of feature tracing",
);
}
if (values["expected-string"] === undefined)
report.unverified.push(
"String inventory/search correctness: no independent expected literal supplied.",
+2 -2
View File
@@ -27,9 +27,9 @@ if (
);
const offset = bytes.length >= 64 ? bytes.readUInt32LE(0x3c) : bytes.length;
if (
bytes.toString("ascii", 0, 2) !== "MZ" ||
bytes.toString("latin1", 0, 2) !== "MZ" ||
offset > bytes.length - 26 ||
bytes.toString("ascii", offset, offset + 4) !== "PE\0\0" ||
bytes.toString("latin1", offset, offset + 4) !== "PE\0\0" ||
bytes.readUInt16LE(offset + 4) !== 0x8664 ||
bytes.readUInt16LE(offset + 24) !== 0x20b
)
+30
View File
@@ -810,6 +810,36 @@ exit 1`,
expect(result.error.message).toContain("overwrite");
});
it.each([
["offline", false, "error: device offline"],
["unauthorized", false, "error: device unauthorized"],
["offline", true, "error: device offline"],
] as const)(
"reports the %s device state when the push existence probe cannot run (overwrite %s)",
async (state, overwrite, stderr) => {
const { binary, root } = await writeAdbStub(
(stubRoot) => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi
if [ "$1" = "-s" ]; then printf '%s\\n' "$3" >> "${stubRoot}/calls"; printf '%s\\n' "${stderr}" >&2; exit 1; fi`,
);
const localFile = join(root, "payload.bin");
await writeFile(localFile, "x");
const projected = await refusedBy(providerOver(binary), {
operation: "push_adb_file",
input: {
serial: "emulator-5554",
local_path: localFile,
device_path: "/data/local/tmp/payload.bin",
overwrite,
},
});
// Existence is unknown, so nothing is claimed about the path and no push runs.
expect(projected).toMatchObject({ code: "unsupported_target" });
expect(projected.message).toContain(state);
expect(projected.message).not.toContain("already exists");
expect(await readFile(join(root, "calls"), "utf8")).toBe("shell\n");
},
);
it("reports a local push source that does not exist", async () => {
const { binary } = await writeAdbStub(
() => `if [ "$1" = "version" ]; then ${VERSION_BLOCK}; exit 0; fi
+8 -10
View File
@@ -1623,17 +1623,15 @@ export class AdbProvider {
{ timeoutMs: SETTINGS_TIMEOUT_MS, maxOutputBytes: 1024 },
signal,
);
let deviceExists: boolean;
if (existsProbe.ok) deviceExists = true;
else if (existsProbe.error instanceof AnalysisProtocolError)
deviceExists = false;
else if (existsProbe.error instanceof AnalysisTimeoutError)
// `test -e` exits nonzero with no adb diagnosis when the path is absent.
// Any other probe failure leaves existence unknown, so it is reported as
// is rather than read as an existing path or followed by a push.
if (
!existsProbe.ok &&
!(existsProbe.error instanceof AnalysisProtocolError)
)
return existsProbe;
else if (existsProbe.error instanceof AnalysisCancelledError)
return existsProbe;
else if (existsProbe.error instanceof AnalysisResourceConstraintError)
return existsProbe;
else deviceExists = true; // authorization/refusal states surface on push instead
const deviceExists = existsProbe.ok;
if (deviceExists && !input.overwrite)
return err(
new AnalysisOutputError(
+11
View File
@@ -50,6 +50,13 @@ export interface AnalysisExecution {
readonly limitations: readonly string[];
/** Provider-owned completeness assessment for caller/callee observations. */
readonly relationshipCoverage?: RelationshipCoverage;
/**
* Whether the provider capped an `xrefs` read: true when it reported a
* truncation, false when it explicitly reported none. Absent when it reports
* nothing, which is not a completeness claim. Never part of Evidence or tool
* output.
*/
readonly referencesTruncated?: boolean;
readonly locations: readonly EvidenceLocation[];
readonly subject: EvidenceSubjectTarget | null;
}
@@ -59,6 +66,7 @@ interface CreateAnalysisExecutionOptions {
readonly analysisProfile?: AnalysisProfileCommitment;
readonly limitations?: readonly string[];
readonly relationshipCoverage?: RelationshipCoverage;
readonly referencesTruncated?: boolean;
readonly locations?: readonly EvidenceLocation[];
readonly subject?: EvidenceSubjectTarget;
}
@@ -103,6 +111,9 @@ export function createAnalysisExecution(
options.relationshipCoverage,
),
}),
...(options.referencesTruncated === undefined
? {}
: { referencesTruncated: options.referencesTruncated }),
locations: [...(options.locations ?? [])],
subject: options.subject ?? null,
};
@@ -497,3 +497,71 @@ it("reports host denial before target mismatch but keeps composed workflow prere
).reason,
).toBe("target_required");
});
describe("trace_feature requirements", () => {
const capabilities = (operations: readonly string[]) =>
operations.map((operation) => ({
operation,
available: true,
reason: null,
}));
it("needs the search operations the workflow actually calls", () => {
expect(
entry(
"trace_feature",
status({
open: true,
kind: "executable",
capabilities: capabilities([
"search_strings",
"search_procedures",
"xrefs",
"resolve_containing_procedure",
]),
}),
),
).toMatchObject({ available: true, reason: "available" });
});
it.each(["search_strings", "search_procedures"])(
"is unavailable without %s",
(missing) => {
const operations = [
"search_strings",
"search_procedures",
"xrefs",
"resolve_containing_procedure",
].filter((operation) => operation !== missing);
expect(
entry(
"trace_feature",
status({
open: true,
kind: "executable",
capabilities: capabilities(operations),
}),
),
).toMatchObject({ available: false, reason: "provider_missing" });
},
);
it("is unavailable when only the list operations exist", () => {
expect(
entry(
"trace_feature",
status({
open: true,
kind: "executable",
capabilities: capabilities([
"list_strings",
"list_procedures",
"xrefs",
"resolve_containing_procedure",
]),
}),
),
).toMatchObject({ available: false, reason: "provider_missing" });
});
});
+2 -2
View File
@@ -121,8 +121,8 @@ const ENHANCED_REQUIREMENTS: Readonly<Record<string, readonly string[]>> = {
analyze_function: ["analyze_function"],
inspect_native_api: ["analyze_function"],
trace_feature: [
"list_strings",
"list_procedures",
"search_strings",
"search_procedures",
"xrefs",
"resolve_containing_procedure",
],
+47 -17
View File
@@ -1,5 +1,8 @@
import { z } from "zod";
import type { AnalysisOperation } from "./AnalysisProvider.js";
import type {
AnalysisExecution,
AnalysisOperation,
} from "./AnalysisProvider.js";
import { AnalysisOutputError } from "../domain/analysisErrorCore.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import type { JsonValue } from "../domain/jsonValue.js";
@@ -16,6 +19,12 @@ type AnalysisCall = (
signal?: AbortSignal,
) => Promise<Result<JsonValue, AnalysisError>>;
type ObserveCall = (
name: AnalysisOperation,
arguments_: Readonly<Record<string, JsonValue>>,
signal?: AbortSignal,
) => Promise<Result<AnalysisExecution, AnalysisError>>;
type LiteralSearchSource = readonly [
"search_strings" | "search_procedures",
"string" | "procedure",
@@ -39,6 +48,7 @@ export interface LiteralTraceInput {
/** Trace matching strings and procedures through provider xrefs. */
export const traceLiteralFeature = async (
call: AnalysisCall,
observe: ObserveCall,
input: LiteralTraceInput,
signal?: AbortSignal,
): EnhancedResult => {
@@ -49,7 +59,7 @@ export const traceLiteralFeature = async (
signal,
);
if (!searched.ok) return searched;
const traced = await traceReferences(call, {
const traced = await traceReferences(call, observe, {
matches: searched.value.matches,
...(signal === undefined ? {} : { signal }),
});
@@ -59,8 +69,8 @@ export const traceLiteralFeature = async (
search_mode: "literal",
matches: searched.value.matches,
references: traced.value.references,
truncated: false,
residual_unknowns: [],
truncated: traced.value.residual.length > 0,
residual_unknowns: traced.value.residual,
});
};
@@ -126,24 +136,39 @@ const addPageMatches = (input: {
const traceReferences = async (
call: AnalysisCall,
observe: ObserveCall,
request: ReferenceTraceRequest,
): Promise<Result<{ references: TraceReference[] }, AnalysisError>> => {
): Promise<
Result<{ references: TraceReference[]; residual: string[] }, AnalysisError>
> => {
const references: TraceReference[] = [];
const residual: string[] = [];
// A source address is resolved once however many matches reference it.
const containing = new Map<string, JsonValue>();
for (const match of request.matches) {
const xrefs = await call(
const observed = await observe(
"xrefs",
{ address: match.address },
request.signal,
);
if (!xrefs.ok) return xrefs;
if (!Array.isArray(xrefs.value))
if (!observed.ok) return observed;
// Only an explicit producer report of truncation is a coverage gap; a
// provider that reports nothing keeps its previous, unqualified result.
const unknown = `References to ${match.address} were truncated by the provider; additional references may exist.`;
if (
observed.value.referencesTruncated === true &&
!residual.includes(unknown)
)
residual.push(unknown);
const sources = observed.value.result;
if (!Array.isArray(sources))
return err(
new AnalysisOutputError(
"xrefs",
"provider returned a non-array result",
),
);
for (const source of xrefs.value) {
for (const source of sources) {
if (typeof source !== "string")
return err(
new AnalysisOutputError(
@@ -151,18 +176,23 @@ const traceReferences = async (
"provider returned a non-address value",
),
);
const resolved = await call(
"resolve_containing_procedure",
{ address: source },
request.signal,
);
if (!resolved.ok) return resolved;
let containingProcedure = containing.get(source);
if (containingProcedure === undefined) {
const resolved = await call(
"resolve_containing_procedure",
{ address: source },
request.signal,
);
if (!resolved.ok) return resolved;
containingProcedure = resolved.value;
containing.set(source, containingProcedure);
}
references.push({
target_address: match.address,
source_address: source,
containing_procedure: resolved.value,
containing_procedure: containingProcedure,
});
}
}
return ok({ references });
return ok({ references, residual });
};
+2
View File
@@ -163,6 +163,8 @@ export class EnhancedTools {
return traceLiteralFeature(
(name, arguments_, operationSignal) =>
this.#call(name, arguments_, operationSignal),
(name, arguments_, operationSignal) =>
this.#observe(name, arguments_, operationSignal),
call.input,
signal,
);
+3 -1
View File
@@ -20,7 +20,9 @@ export const workflowAnalysisProfile = (
upstream_analysis_profile: upstream,
...(operation === "binary_overview"
? { workflow_revision: 3 }
: operation === "batch_decompile" || operation === "get_call_graph"
: operation === "batch_decompile" ||
operation === "get_call_graph" ||
operation === "trace_feature"
? { workflow_revision: 2 }
: {}),
});
@@ -661,3 +661,52 @@ it("does not replay pre-envelope call graphs under the revised workflow profile"
}).success,
).toBe(false);
});
describe("executions that report truncated references", () => {
const record = (referencesTruncated: boolean | undefined) => {
const cache = new AnalysisSnapshotCache();
const parameters = { address: "0x1000", document: "fixture" };
cache.record({
target: ANALYSIS_SNAPSHOT_TARGET,
profile: ANALYSIS_SNAPSHOT_PROFILE,
operation: "xrefs",
parameters,
execution: createAnalysisExecution(
["0x2000"],
ANALYSIS_SNAPSHOT_PROVIDER,
{
subject: ANALYSIS_SNAPSHOT_TARGET,
analysisProfile: ANALYSIS_SNAPSHOT_PROFILE,
...(referencesTruncated === undefined ? {} : { referencesTruncated }),
},
),
});
return cache.lookup(
ANALYSIS_SNAPSHOT_TARGET,
ANALYSIS_SNAPSHOT_PROFILE,
"xrefs",
parameters,
);
};
it("are not replayed, because a replay would lose the truncation", () => {
expect(record(true)).toBeUndefined();
});
it("do not stop an execution that is complete or silent from being replayed", () => {
expect(record(false)?.result).toEqual(["0x2000"]);
expect(record(undefined)?.result).toEqual(["0x2000"]);
});
});
it("revises the trace_feature workflow profile so earlier results are not replayed", () => {
const profile = ANALYSIS_SNAPSHOT_PROFILE;
expect(workflowAnalysisProfile(profile, "trace_feature")).not.toEqual(
workflowAnalysisProfile(profile),
);
expect(
workflowAnalysisProfile(profile, "trace_call_path"),
"other workflows keep their profile",
).toEqual(workflowAnalysisProfile(profile));
});
@@ -337,6 +337,9 @@ export class AnalysisSnapshotCache {
}): void {
const { target, profile, operation, parameters, execution } = input;
this.select(target, profile);
// The snapshot format does not carry reference truncation; a replay would
// present a capped read as complete, so it is not recorded.
if (execution.referencesTruncated === true) return;
const queryId = analysisQueryId(
snapshotTarget(target),
snapshotBinding(profile),
+6 -2
View File
@@ -278,8 +278,12 @@ export const parsePeRecord = (
record.toString("binary", 0, 4) !== "PE\u0000\u0000"
)
return err("invalid or truncated PE header");
const machine = decodePeMachine(record.readUInt16LE(4));
if (machine === undefined) return err("unsupported PE architecture");
const machineType = record.readUInt16LE(4);
const machine = decodePeMachine(machineType);
if (machine === undefined)
return err(
`unsupported PE architecture (COFF machine 0x${machineType.toString(16).padStart(4, "0")})`,
);
const { architecture } = machine;
const optionalHeaderSize = record.readUInt16LE(20);
if (optionalHeaderSize > 4096 || record.length < 24 + optionalHeaderSize)
+19
View File
@@ -159,3 +159,22 @@ describe("read-only NativeAOT PE parser", () => {
});
});
});
describe("NativeAOT PE signature admission", () => {
it.each([
["MZ", "Not a PE image"],
["PE", "Invalid PE signature"],
])(
"rejects a high-bit lookalike of the %s signature",
(signature, reason) => {
const bytes = nativeAotPeFixture();
const offset = signature === "MZ" ? 0 : bytes.readUInt32LE(0x3c);
for (const position of [offset, offset + 1])
bytes.writeUInt8(bytes.readUInt8(position) | 0x80, position);
expect(
parseNativeAotPe(bytes, nativeAotPeDigest(bytes), SUMMARY_BUDGET)
.summary,
).toMatchObject({ status: "not_applicable", reason });
},
);
});
+2 -2
View File
@@ -384,11 +384,11 @@ class PeImage {
constructor(bytes: Buffer) {
this.#bytes = bytes;
if (bytes.length < 0x40 || bytes.toString("ascii", 0, 2) !== "MZ")
if (bytes.length < 0x40 || bytes.toString("latin1", 0, 2) !== "MZ")
throw new Error("Not a PE image");
const peOffset = this.#u32(0x3c);
this.#range(peOffset, 24);
if (bytes.toString("ascii", peOffset, peOffset + 4) !== "PE\0\0")
if (bytes.toString("latin1", peOffset, peOffset + 4) !== "PE\0\0")
throw new Error("Invalid PE signature");
this.#machine = this.#u16(peOffset + 4);
const count = this.#u16(peOffset + 6);
+10 -1
View File
@@ -72,6 +72,15 @@ const NATIVE_ARCHITECTURES: readonly {
/** Bound installation discovery reads; larger headers remain unknown. */
const EXECUTABLE_HEADER_PROBE_BYTES = 4096;
/**
* Bound the Java version probe so a chatty or hostile JVM cannot force an
* unbounded in-memory capture. Well-behaved JVMs print a few kilobytes for
* `-XshowSettings:properties`; the same 1 MiB budget used for other Java
* listings leaves ample headroom. A probe that exceeds the budget yields no
* observation and is reported through the existing failed-probe path.
*/
const JAVA_PROBE_MAX_OUTPUT_BYTES = 1024 * 1024;
/** Compatibility of one present native decompiler with the inspected host. */
type NativeDecompilerCompatibility =
| {
@@ -763,7 +772,7 @@ const systemGhidraInstallationHost = (): GhidraInstallationHost => ({
encoding: "utf8",
env: environment,
timeout: 5_000,
maxBuffer: Number.POSITIVE_INFINITY,
maxBuffer: JAVA_PROBE_MAX_OUTPUT_BYTES,
windowsHide: true,
},
);
+48 -2
View File
@@ -1,3 +1,4 @@
import { parseGhidraJavaProperties } from "./GhidraJavaProperties.js";
import {
GHIDRA_SEED_SCRIPT,
snapshotGhidraAnalysisSeeds,
@@ -5,7 +6,7 @@ import {
} from "./GhidraAnalysisSeeds.js";
import type { GhidraLanguageOverride } from "../config/ghidraLanguageOverride.js";
import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
import { mkdir, realpath } from "node:fs/promises";
import { mkdir, readFile, realpath } from "node:fs/promises";
import { basename, dirname, join, posix, win32 } from "node:path";
import writeFileAtomic from "write-file-atomic";
@@ -219,7 +220,11 @@ export class GhidraHeadlessLauncher implements GhidraLauncher {
"Installed Allegrex content changed since profile resolution; reopen the target to resolve a fresh profile.",
);
}
await createGhidraRuntimeDirectories(paths, platform);
await createGhidraRuntimeDirectories(
paths,
platform,
await ghidraConfigReleaseDirectory(this.options.analyzeHeadlessPath),
);
const seedPath =
this.options.analysisSeeds === undefined
? undefined
@@ -721,9 +726,44 @@ const ghidraRuntimePaths = (runtimeRoot: string) => ({
scriptLogPath: join(runtimeRoot, "script.log"),
});
/**
* Ghidra's launch support resolves its JDK before the headless run and then
* persists that choice under `<config>/ghidra/<release directory>`. Inside
* REA's Windows private runtime a child JVM cannot create those directories
* itself, so startup aborted with "Failed to create directory" and reported
* that no supported JDK was found. Create the release directory while this
* process still owns the runtime, leaving Ghidra only a file write inside it.
*/
const ghidraConfigReleaseDirectory = async (
analyzeHeadlessPath: string,
): Promise<string> => {
const installRoot = dirname(dirname(analyzeHeadlessPath));
try {
const properties = await readFile(
join(installRoot, "Ghidra", "application.properties"),
"latin1",
);
const parsed = parseGhidraJavaProperties(properties);
if (!parsed.ok) return basename(installRoot);
const version = parsed.value.get("application.version");
const release = parsed.value.get("application.release.name");
return version === undefined ||
release === undefined ||
release.length === 0
? basename(installRoot)
: `ghidra_${version}_${release}`;
} catch (cause: unknown) {
// An unreadable properties file leaves the release coordinate unknown; the
// conventional extraction directory carries the same name.
void cause;
return basename(installRoot);
}
};
const createGhidraRuntimeDirectories = async (
paths: ReturnType<typeof ghidraRuntimePaths>,
platform: NodeJS.Platform,
configReleaseDirectory: string,
): Promise<void> => {
if (platform === "win32") {
const runtime = windowsPrivateRuntime(dirname(paths.projectRoot));
@@ -736,6 +776,11 @@ const createGhidraRuntimeDirectories = async (
paths.dataRoot,
])
runtime.mkdir(basename(path));
// Each level needs its parent first: the native owner opens every existing
// component and creates only the final one.
const configRoot = basename(paths.configRoot);
runtime.mkdir(win32.join(configRoot, "ghidra"));
runtime.mkdir(win32.join(configRoot, "ghidra", configReleaseDirectory));
return;
}
await Promise.all(
@@ -746,6 +791,7 @@ const createGhidraRuntimeDirectories = async (
paths.cacheRoot,
paths.configRoot,
paths.dataRoot,
join(paths.configRoot, "ghidra", configReleaseDirectory),
].map((path) => mkdir(path, { recursive: true, mode: 0o700 })),
);
};
+623
View File
@@ -0,0 +1,623 @@
import { rm } from "node:fs/promises";
import { afterEach, describe, expect, it } from "vitest";
import type { JsonValue } from "../domain/jsonValue.js";
import {
createIdaTarget,
RecordingIdaMcp,
} from "../../tests/fixtures/idaMcp.js";
import { decodeIdaToolResult } from "./IdaMcpConnection.js";
import { idaCapabilities } from "./IdaProviderCapabilities.js";
import { IdaSessionClient } from "./IdaSessionClient.js";
const roots: string[] = [];
afterEach(async () => {
for (const root of roots.splice(0))
await rm(root, { recursive: true, force: true });
});
const segment = (name: string, start: string, end: string) => ({
name,
start,
end,
size: `0x${(BigInt(end) - BigInt(start)).toString(16)}`,
permissions: "r--",
});
/** Adjacent .text and .data, a gap, then a segment above 2^53. */
const SEGMENTS = [
segment(".text", "0x1000", "0x2000"),
segment(".data", "0x2000", "0x3000"),
segment(".far", "0x5000", "0x6000"),
segment(".huge", "0x20000000000001", "0x20000000000002"),
];
/** The same segments in descending order, which a scan may not rely on. */
const UNSORTED = [...SEGMENTS].reverse();
const survey = (segments: JsonValue = SEGMENTS) => ({
metadata: { path: "/db/target.i64", module: "target", arch: "metapc" },
statistics: { total_segments: Array.isArray(segments) ? segments.length : 0 },
segments,
entrypoints: [],
});
const function_ = { addr: "0x1000", name: "main", size: "0x20" };
const MODERN_WITHOUT_SURVEY = [
"idb_open",
"idb_list",
"idb_close",
"server_health",
"list_funcs",
"lookup_funcs",
"find_regex",
"decompile",
"disasm",
"callees",
"xrefs_to",
];
interface Upstream {
/** Answer for the lookup of the queried address; default is "Not a function". */
readonly lookup?: (query: string) => JsonValue;
readonly survey?: JsonValue;
readonly tools?: readonly string[];
readonly surveyFailure?: "error" | "preview";
/** A distinct source alias of the admitted target, as for an app bundle. */
readonly sourcePath?: string;
/** Report a different input from the second health read on. */
readonly identityChangesAfterOperation?: boolean;
}
const session = async (
upstream: Upstream = {},
mode: "headless" | "attached" = "headless",
) => {
const created = await createIdaTarget("x86_64");
const { root } = created;
const target =
upstream.sourcePath === undefined
? created.target
: { ...created.target, sourcePath: upstream.sourcePath };
roots.push(root);
const producer = new RecordingIdaMcp(target, mode);
if (upstream.tools !== undefined) producer.tools = upstream.tools;
producer.beforeCall = async (name) => {
if (name !== "survey_binary") return;
if (upstream.surveyFailure === "error")
decodeIdaToolResult({
content: [{ type: "text", text: "survey failed" }],
isError: true,
});
if (upstream.surveyFailure === "preview")
decodeIdaToolResult({
content: [{ type: "text", text: "preview" }],
_meta: { ida_mcp: { output_truncated: true } },
});
};
let healthReads = 0;
producer.overrideCall = (name, args) => {
if (name === "server_health" && upstream.identityChangesAfterOperation) {
healthReads += 1;
if (healthReads === 2)
return {
status: "ok",
input_path: "/different/target.elf",
idb_path: "/different/target.elf.i64",
module: "target.elf",
imagebase: "0x1000",
auto_analysis_ready: true,
};
}
if (name === "lookup_funcs") {
const queries = Array.isArray(args.queries) ? args.queries : [];
return queries.map((query) =>
upstream.lookup === undefined
? { query, fn: null, error: "Not a function" }
: upstream.lookup(String(query)),
);
}
if (name === "survey_binary") return upstream.survey ?? survey();
return undefined;
};
const client = new IdaSessionClient(
{
command: "fixture",
args: [],
env: {},
mode,
timeoutMs: 1000,
workspaceRoot: root,
},
target,
producer,
);
return { client, producer, target };
};
const containing = async (
client: IdaSessionClient,
address: string,
options?: Parameters<IdaSessionClient["execute"]>[2],
) => client.execute("resolve_containing_procedure", { address }, options);
const found = (query: string, fn: typeof function_) => ({
query,
fn,
error: null,
});
describe("IDA containment capabilities", () => {
it("declares both operations for the headless profile only", () => {
const declared = (mode: "attached" | "headless", native = false) =>
idaCapabilities(mode, false, native)
.map(({ operation }) => operation)
.filter(
(operation) =>
operation === "resolve_containing_procedure" ||
operation === "list_documents",
);
expect(
idaCapabilities("headless", false)
.filter(
({ operation }) =>
operation === "resolve_containing_procedure" ||
operation === "list_documents",
)
.map(({ available }) => available),
"both are declared available, not merely listed",
).toEqual([true, true]);
expect(declared("headless")).toEqual([
"resolve_containing_procedure",
"list_documents",
]);
expect(declared("attached")).toEqual([]);
expect(declared("attached", true)).toEqual([]);
expect(
idaCapabilities("attached", false).map(({ operation }) => operation),
"attached profiles do not even declare them",
).not.toContain("list_documents");
});
it.each(["resolve_containing_procedure", "list_documents"] as const)(
"refuses %s on the legacy attached profile without calling upstream",
async (operation) => {
const { client, producer } = await session({}, "attached");
try {
const result = await client.execute(
operation,
operation === "list_documents" ? {} : { address: "0x1000" },
);
expect(result.ok).toBe(false);
if (!result.ok)
expect(result.error._tag).toBe("AnalysisCapabilityUnavailableError");
expect(producer.calls.some(({ name }) => name === "lookup_funcs")).toBe(
false,
);
} finally {
expect((await client.close()).ok).toBe(true);
}
},
);
});
describe("headless IDA containing procedure", () => {
it("returns the canonical entry for an interior address without reading segments", async () => {
const { client, producer } = await session({
lookup: (query) => found(query, function_),
});
try {
const result = await containing(client, "1ffe");
if (!result.ok) throw result.error;
expect(result.value.result).toEqual({
query_address: "0x1ffe",
found: true,
procedure: {
address: "0x1000",
name: "main",
classification: null,
body: {
available: false,
reason: "IDA MCP does not report complete function body ranges.",
},
},
});
expect(
producer.calls.filter(({ name }) => name === "lookup_funcs"),
"the normalized address is the only query",
).toMatchObject([{ args: { queries: ["0x1ffe"] } }]);
expect(
producer.calls.some(({ name }) => name === "survey_binary"),
"a positive answer needs no segment facts",
).toBe(false);
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it.each([
["inside the first segment", "0x1000", "not_in_procedure"],
["inside an adjacent segment", "0x2000", "not_in_procedure"],
[
"at the exclusive end of the last adjacent segment",
"0x3000",
"outside_segments",
],
["in the gap between segments", "0x4000", "outside_segments"],
["one below a segment start", "0xfff", "outside_segments"],
["the last byte of a segment", "0x5fff", "not_in_procedure"],
["above every segment", "0x6000", "outside_segments"],
[
"inside a one-byte segment above 2^53",
"0x20000000000001",
"not_in_procedure",
],
[
"one below that segment, which a rounded number cannot tell apart",
"0x20000000000000",
"outside_segments",
],
[
"at the exclusive end of that segment",
"0x20000000000002",
"outside_segments",
],
] as const)(
"reports an address that is not a function %s as %s",
async (_description, address, reason) => {
const { client, producer } = await session();
try {
const result = await containing(client, address);
if (!result.ok) throw result.error;
expect(result.value.result).toEqual({
query_address: address,
found: false,
procedure: null,
reason,
});
expect(
producer.calls.find(({ name }) => name === "survey_binary")?.args,
"the minimal survey is the only segment source",
).toMatchObject({ detail_level: "minimal" });
expect(
producer.calls.filter(({ name }) => name === "survey_binary"),
).toHaveLength(1);
} finally {
expect((await client.close()).ok).toBe(true);
}
},
);
});
describe("headless IDA containment failures", () => {
it.each([
["no segments field", { metadata: {}, statistics: {} }],
["segments that are null", survey(null)],
["an empty segment list", survey([])],
[
"a row with a malformed address",
survey([
{
name: ".x",
start: "0xzz",
end: "0x2000",
size: "0x1000",
permissions: "r--",
},
]),
],
[
"a reversed segment",
survey([
{ name: ".x", start: "0x2000", end: "0x1000", permissions: "r--" },
]),
],
[
"a size that disagrees with the bounds",
survey([{ ...segment(".x", "0x1000", "0x2000"), size: "0x10" }]),
],
[
"a total that disagrees with the rows",
{ ...survey(), statistics: { total_segments: 9 } },
],
["a malformed row after valid ones", survey([...SEGMENTS, { name: ".y" }])],
] as const)(
"fails instead of guessing a reason when the survey has %s",
async (_description, reply) => {
const { client } = await session({ survey: reply as JsonValue });
try {
const result = await containing(client, "0x4000");
expect(result.ok).toBe(false);
if (!result.ok) expect(result.error._tag).toBe("AnalysisOutputError");
} finally {
expect((await client.close()).ok).toBe(true);
}
},
);
it.each(["error", "preview"] as const)(
"fails when the survey tool reports %s",
async (surveyFailure) => {
const { client } = await session({ surveyFailure });
try {
const result = await containing(client, "0x4000");
expect(result.ok).toBe(false);
} finally {
expect((await client.close()).ok).toBe(true);
}
},
);
it("fails without a segment source when the server does not advertise the survey", async () => {
const { client, producer } = await session({
tools: MODERN_WITHOUT_SURVEY,
});
try {
const negative = await containing(client, "0x4000");
expect(negative.ok).toBe(false);
expect(
producer.calls.some(({ name }) => name === "survey_binary"),
"an unadvertised tool is never requested",
).toBe(false);
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it("still answers a positive lookup when the server does not advertise the survey", async () => {
const { client } = await session({
lookup: (query) => found(query, function_),
tools: MODERN_WITHOUT_SURVEY,
});
try {
const result = await containing(client, "0x1010");
expect(result.ok).toBe(true);
} finally {
expect((await client.close()).ok).toBe(true);
}
});
});
describe("headless IDA containment lookup failures", () => {
it.each([
["an answer for another query", () => found("0x9999", function_)],
[
"a function together with an error",
(query: string) => ({ query, fn: function_, error: "Not found" }),
],
[
"neither a function nor an error",
(query: string) => ({ query, fn: null, error: null }),
],
[
"an unknown error text",
(query: string) => ({ query, fn: null, error: "boom" }),
],
[
"a padded missing answer",
(query: string) => ({ query, fn: null, error: " Not a function" }),
],
] as const)(
"treats %s as a producer failure and reads no segments",
async (_description, lookup) => {
const { client, producer } = await session({ lookup });
try {
const result = await containing(client, "0x4000");
expect(result.ok).toBe(false);
if (!result.ok) expect(result.error._tag).toBe("AnalysisProtocolError");
expect(
producer.calls.some(({ name }) => name === "survey_binary"),
).toBe(false);
} finally {
expect((await client.close()).ok).toBe(true);
}
},
);
it('treats "Not found" for an address like any expected missing answer', async () => {
const { client } = await session({
lookup: (query) => ({ query, fn: null, error: "Not found" }),
});
try {
const result = await containing(client, "0x4000");
if (!result.ok) throw result.error;
expect(result.value.result).toMatchObject({
found: false,
reason: "outside_segments",
});
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it("stops before the survey when the request is cancelled after the lookup", async () => {
const controller = new AbortController();
const { client, producer } = await session();
const inner = producer.beforeCall;
producer.beforeCall = async (name, args) => {
await inner?.(name, args);
if (name === "lookup_funcs") controller.abort();
};
try {
const result = await containing(client, "0x4000", {
signal: controller.signal,
});
expect(result.ok).toBe(false);
if (!result.ok) expect(result.error._tag).toBe("AnalysisCancelledError");
expect(
producer.calls.some(({ name }) => name === "survey_binary"),
"nothing is dispatched after cancellation",
).toBe(false);
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it("does not depend on the order of the surveyed segments", async () => {
const { client } = await session({ survey: survey(UNSORTED) });
try {
const inside = await containing(client, "0x1000");
const gap = await containing(client, "0x4000");
if (!inside.ok) throw inside.error;
if (!gap.ok) throw gap.error;
expect(inside.value.result).toMatchObject({ reason: "not_in_procedure" });
expect(gap.value.result).toMatchObject({ reason: "outside_segments" });
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it("retains the completed replies when the survey is rejected", async () => {
const { client } = await session({
survey: survey([
{ name: ".x", start: "0x2000", end: "0x1000", permissions: "r--" },
]),
});
try {
const result = await containing(client, "0x4000");
expect(result.ok).toBe(false);
if (!result.ok)
expect(result.error.partialObservation).toMatchObject({
normalized_result: {
status: "partial",
observations: [
expect.objectContaining({ tool: "lookup_funcs" }),
expect.objectContaining({ tool: "survey_binary" }),
],
},
});
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it("rejects an address that is not hexadecimal and a document that is not the admitted target", async () => {
const { client, producer } = await session();
try {
const badAddress = await containing(client, "main");
const badDocument = await client.execute("resolve_containing_procedure", {
address: "0x1000",
document: "/somewhere/else",
});
for (const result of [badAddress, badDocument]) {
expect(result.ok).toBe(false);
if (!result.ok) expect(result.error._tag).toBe("AnalysisInputError");
}
expect(
producer.calls.some(({ name }) => name === "lookup_funcs"),
"invalid input never reaches upstream",
).toBe(false);
} finally {
expect((await client.close()).ok).toBe(true);
}
});
});
describe("headless IDA document identity", () => {
it("accepts an explicit admitted document and rejects an unknown one for the same operations", async () => {
const { client, target, producer } = await session();
try {
const admitted = await client.execute("resolve_containing_procedure", {
address: "0x4000",
document: target.path,
});
const unknownContainment = await client.execute(
"resolve_containing_procedure",
{ address: "0x4000", document: "/somewhere/else" },
);
const unknownListing = await client.execute("list_documents", {
document: "/somewhere/else",
});
expect(admitted.ok, "the admitted program is accepted").toBe(true);
for (const rejected of [unknownContainment, unknownListing]) {
expect(rejected.ok).toBe(false);
if (!rejected.ok)
expect(rejected.error._tag).toBe("AnalysisInputError");
}
expect(
producer.calls.filter(({ name }) => name === "lookup_funcs"),
"only the admitted request reached upstream",
).toHaveLength(1);
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it("lists the admitted path, not its source alias or the private copy", async () => {
const { client, target, producer } = await session({
sourcePath: "/Applications/Fixture.app",
});
try {
const result = await client.execute("list_documents", {});
if (!result.ok) throw result.error;
expect(result.value.result).toEqual([target.path]);
expect(
producer.calls.filter(({ name }) => name === "server_health"),
"the target identity is checked before and after the local answer",
).toHaveLength(2);
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it("fails when the target identity changes during the operation", async () => {
const { client } = await session({ identityChangesAfterOperation: true });
try {
const result = await client.execute("list_documents", {});
expect(result.ok).toBe(false);
if (!result.ok) {
expect(result.error.message).toContain("identity changed");
}
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it("stops without dispatching when the request is already cancelled", async () => {
const controller = new AbortController();
controller.abort();
const { client, producer } = await session();
try {
const result = await client.execute(
"list_documents",
{},
{ signal: controller.signal },
);
expect(result.ok).toBe(false);
if (!result.ok) expect(result.error._tag).toBe("AnalysisCancelledError");
expect(producer.calls).toEqual([]);
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it("lists exactly the admitted program", async () => {
const { client, target } = await session();
try {
const result = await client.execute("list_documents", {});
if (!result.ok) throw result.error;
expect(result.value.result).toEqual([target.path]);
} finally {
expect((await client.close()).ok).toBe(true);
}
});
});
+30
View File
@@ -758,3 +758,33 @@ describe("native IDA malformed observations", () => {
await client.close();
});
});
describe("native IDA attached operation admission", () => {
it("forwards the native producer's explicit reference cap flag", async () => {
const { client } = await fixture();
const result = await client.execute("xrefs", { address: "0x1000" });
if (!result.ok) throw result.error;
expect(result.value.referencesTruncated).toBe(false);
await client.close();
});
it("does not admit the headless-only containment and document operations", async () => {
const { client, producer } = await fixture();
for (const [operation, parameters] of [
["resolve_containing_procedure", { address: "0x1000" }],
["list_documents", {}],
] as const) {
const result = await client.execute(operation, parameters);
expect(result.ok).toBe(false);
if (!result.ok)
expect(result.error._tag).toBe("AnalysisCapabilityUnavailableError");
}
expect(
producer.calls.some(({ name }) => name === "lookup_funcs"),
"nothing is dispatched upstream",
).toBe(false);
await client.close();
});
});
+86 -20
View File
@@ -45,6 +45,7 @@ import {
modernStringsSchema,
modernXrefsSchema,
nextOffset,
surveySegmentsSchema,
type IdaDisassembly,
type IdaFunction,
} from "./IdaProtocolValues.js";
@@ -86,6 +87,8 @@ export class IdaOperationRunner {
readonly locations: EvidenceLocation[] = [];
readonly limitations: string[] = [];
relationshipCoverage: RelationshipCoverage | undefined;
/** The upstream cap flag of the last `xrefs_to` read, when the producer reported one. */
referencesTruncated: boolean | undefined;
constructor(
private readonly connection: IdaMcpConnection,
private readonly protocol: "legacy" | "modern" | "native",
@@ -97,6 +100,10 @@ export class IdaOperationRunner {
readonly x86Only?: boolean;
/** False when the upstream server does not advertise `callgraph`. */
readonly callGraphAvailable?: boolean;
/** False when the upstream server does not advertise `survey_binary`. */
readonly surveyAvailable?: boolean;
/** The program identity REA admitted, reported by `list_documents`. */
readonly admittedDocument?: string;
} = {},
) {}
@@ -177,41 +184,89 @@ export class IdaOperationRunner {
return entry;
}
private lookupFunction(
/** Parse one lookup row: a function, an expected "missing" answer, or a producer failure. */
private lookupOutcome(
query: string,
item: z.infer<typeof modernLookupBatchSchema>[number] | undefined,
requestedBy?: string,
): IdaFunction {
): { readonly fn: IdaFunction } | { readonly missing: string } {
if (item?.query !== query)
throw new AnalysisProtocolError(
`IDA function lookup answered for a different query than ${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}.`,
},
],
);
return { missing: 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 { fn: item.fn };
}
private lookupFunction(
query: string,
item: z.infer<typeof modernLookupBatchSchema>[number] | undefined,
requestedBy?: string,
): IdaFunction {
const outcome = this.lookupOutcome(query, item);
if ("fn" in outcome) return outcome.fn;
if (requestedBy === undefined)
throw new AnalysisProtocolError(
`IDA function lookup failed for ${query}: ${outcome.missing}`,
);
throw new AnalysisInputError(
requestedBy,
{
cause: new AnalysisProtocolError(
`IDA function lookup failed for ${query}: ${outcome.missing}`,
),
},
[
{
path: [],
reason: "invalid_value",
message: `IDA could not resolve procedure ${JSON.stringify(query)}: ${outcome.missing}.`,
},
],
);
}
/** The containing function of an address, or why none contains it. */
private async containingProcedure(address: string): Promise<JsonValue> {
const item = modernLookupSchema.parse(
await this.call("lookup_funcs", { queries: [address] }),
)[0];
const outcome = this.lookupOutcome(address, item);
if ("fn" in outcome)
return {
query_address: address,
found: true,
procedure: identity(outcome.fn),
};
return {
query_address: address,
found: false,
procedure: null,
reason: (await this.addressInSegment(address))
? "not_in_procedure"
: "outside_segments",
};
}
/** Segment membership from the database-scoped minimal survey; a missing fact is a failure. */
private async addressInSegment(address: string): Promise<boolean> {
if (this.options.surveyAvailable === false)
throw new AnalysisProtocolError(
"The upstream server does not advertise survey_binary, so segment membership cannot be established.",
);
const { segments } = surveySegmentsSchema.parse(
await this.call("survey_binary", { detail_level: "minimal" }),
);
const value = BigInt(address);
return segments.some(({ start, end }) => start <= value && value < end);
}
/** True only for modern callee reads on targets not proven x86-only; x86 reads never reach the graph code. */
@@ -390,6 +445,7 @@ export class IdaOperationRunner {
throw new AnalysisProtocolError(
`IDA xrefs failed: ${page?.error ?? "missing references"}`,
);
if (page.more !== undefined) this.referencesTruncated = page.more;
if (page.more === true)
this.limitations.push(
"Upstream xrefs_to capped results at 1000 references; additional references remain unknown.",
@@ -536,6 +592,16 @@ export class IdaOperationRunner {
address === idaAddressSchema.parse(parameters.address),
);
}
if (operation === "list_documents") {
if (this.options.admittedDocument === undefined)
throw new AnalysisProtocolError("The admitted IDA program is unknown.");
return [this.options.admittedDocument];
}
if (operation === "resolve_containing_procedure") {
const queried = idaAddressSchema.parse(parameters.address);
this.locations.push({ kind: "address", address: queried });
return this.containingProcedure(queried);
}
if (operation === "xrefs") {
const inspectedAddress = idaAddressSchema.parse(parameters.address);
this.locations.push({ kind: "address", address: inspectedAddress });
+58
View File
@@ -218,6 +218,14 @@ export const openDatabaseSchema = z
.passthrough(),
})
.passthrough();
/** Only an explicit completed rejection preserves legacy no-worker cleanup. */
export const rejectedOpenDatabaseSchema = z
.object({
error: z.string().min(1),
success: z.never().optional(),
})
.passthrough();
export const databaseListSchema = z
.object({
sessions: z.array(
@@ -247,3 +255,53 @@ export const absentDatabaseCloseSchema = (sessionId: string) =>
z
.object({ error: z.literal(`Session not found: ${sessionId}`) })
.passthrough();
// Piped, so a malformed coordinate is a schema issue and never reaches BigInt.
const hexCoordinate = z
.string()
.regex(/^0x[0-9a-f]+$/iu)
.pipe(z.transform((value) => BigInt(value)));
/**
* The minimal `survey_binary` reply, reduced to validated segment intervals
* (exclusive ends). Any malformed, reversed or inconsistent fact rejects the
* whole reply, because a membership answer needs every segment.
*/
export const surveySegmentsSchema = z
.object({
statistics: z
.object({ total_segments: z.number().int().nonnegative().optional() })
.passthrough()
.optional(),
segments: z
.array(
z
.object({
start: hexCoordinate,
end: hexCoordinate,
size: hexCoordinate.optional(),
})
.passthrough(),
)
.min(1),
})
.passthrough()
.superRefine(({ statistics, segments }, context) => {
if (
statistics?.total_segments !== undefined &&
statistics.total_segments !== segments.length
)
context.addIssue({
code: "custom",
message: "survey segment count disagrees with its statistics",
});
for (const { start, end, size } of segments) {
// A malformed row has already reported its own issue; refinements still run.
if (typeof start !== "bigint" || typeof end !== "bigint") continue;
if (start >= end || (size !== undefined && size !== end - start))
context.addIssue({
code: "custom",
message: "survey segment bounds are reversed or inconsistent",
});
}
});
+48 -31
View File
@@ -24,9 +24,23 @@ export const IDA_OPERATIONS = Object.freeze([
"read_function_instructions",
"xrefs",
"analyze_function",
"resolve_containing_procedure",
"list_documents",
] as const satisfies readonly Exclude<AnalysisOperation, "health">[]);
export type IdaOperation = (typeof IDA_OPERATIONS)[number];
/** Operations only the modern headless profile implements. */
const HEADLESS_ONLY_OPERATIONS: ReadonlySet<IdaOperation> = new Set([
"resolve_containing_procedure",
"list_documents",
]);
/** Whether the configured profile admits an operation. */
export const idaProfileAdmits = (
operation: IdaOperation,
mode: "attached" | "headless",
): boolean => mode === "headless" || !HEADLESS_ONLY_OPERATIONS.has(operation);
/** Shared limitations of observations from an externally mutable analysis database. */
export const IDA_LIMITATIONS = Object.freeze([
"Provider version identifies the REA IDA adapter. IDA engine and upstream distribution versions are unknown unless separately observed; MCP serverInfo is reported independently.",
@@ -58,34 +72,37 @@ export const idaCapabilities = (
stdio: boolean,
native = false,
): readonly CapabilityDescriptor[] =>
IDA_OPERATIONS.map((operation) => ({
provider: IDA_PROVIDER_IDENTITY,
operation,
...((mode === "headless" || native) && operation === "procedure_callers"
? ({
available: false,
reason: native
? "The native upstream profile reports code references without proving direct call edges."
: "The modern upstream profile reports code references without proving direct call edges.",
} as const)
: ({ available: true, reason: null } as const)),
cachePolicy: "live",
effects: {
mutatesArtifact: false,
launchesProcess: stdio || mode === "headless",
mayShowUi:
mode === "attached" &&
(native
? operation === "procedure_pseudo_code" ||
operation === "analyze_function"
: ATTACHED_GUI_NAVIGATION_OPERATIONS.has(operation)),
mayAccessNetwork: true,
mayWriteFilesystem: stdio || mode === "headless",
changesPermissions: false,
requiresRoot: false,
},
limitations:
native && (operation === "list_strings" || operation === "search_strings")
? [...IDA_LIMITATIONS, IDA_NATIVE_STRING_LIMITATION]
: IDA_LIMITATIONS,
}));
IDA_OPERATIONS.filter((operation) => idaProfileAdmits(operation, mode)).map(
(operation) => ({
provider: IDA_PROVIDER_IDENTITY,
operation,
...((mode === "headless" || native) && operation === "procedure_callers"
? ({
available: false,
reason: native
? "The native upstream profile reports code references without proving direct call edges."
: "The modern upstream profile reports code references without proving direct call edges.",
} as const)
: ({ available: true, reason: null } as const)),
cachePolicy: "live",
effects: {
mutatesArtifact: false,
launchesProcess: stdio || mode === "headless",
mayShowUi:
mode === "attached" &&
(native
? operation === "procedure_pseudo_code" ||
operation === "analyze_function"
: ATTACHED_GUI_NAVIGATION_OPERATIONS.has(operation)),
mayAccessNetwork: true,
mayWriteFilesystem: stdio || mode === "headless",
changesPermissions: false,
requiresRoot: false,
},
limitations:
native &&
(operation === "list_strings" || operation === "search_strings")
? [...IDA_LIMITATIONS, IDA_NATIVE_STRING_LIMITATION]
: IDA_LIMITATIONS,
}),
);
+96
View File
@@ -0,0 +1,96 @@
import { rm } from "node:fs/promises";
import { afterEach, describe, expect, it } from "vitest";
import {
createIdaTarget,
RecordingIdaMcp,
} from "../../tests/fixtures/idaMcp.js";
import {
callGraphSession as session,
removeCallGraphSessions,
} from "../../tests/fixtures/idaCallGraph.js";
import { IdaSessionClient } from "./IdaSessionClient.js";
const attachedRoots: string[] = [];
afterEach(async () => {
await removeCallGraphSessions();
for (const root of attachedRoots.splice(0))
await rm(root, { recursive: true, force: true });
});
const xrefs = async (more: boolean | undefined) => {
const { client, producer } = await session({ callees: [] }, "x86_64");
const inner = producer.overrideCall;
producer.overrideCall = (name, args) =>
name === "xrefs_to"
? [{ xrefs: [], ...(more === undefined ? {} : { more }) }]
: inner?.(name, args);
try {
const result = await client.execute("xrefs", { address: "0x1000" });
if (!result.ok) throw result.error;
return result.value;
} finally {
expect((await client.close()).ok).toBe(true);
}
};
describe("headless IDA reference coverage", () => {
it("reports a capped xrefs read as truncated", async () => {
const execution = await xrefs(true);
expect(execution.referencesTruncated).toBe(true);
expect(
execution.limitations,
"the diagnostic limitation is still reported",
).toContain(
"Upstream xrefs_to capped results at 1000 references; additional references remain unknown.",
);
});
it("reports an explicitly uncapped xrefs read as not truncated", async () => {
expect((await xrefs(false)).referencesTruncated).toBe(false);
});
it("reports nothing when the producer does not say whether the read was capped", async () => {
expect((await xrefs(undefined)).referencesTruncated).toBeUndefined();
});
it("does not report reference coverage for other operations", async () => {
const { client } = await session({ callees: [] }, "x86_64");
try {
const result = await client.execute("procedure_callees", {
procedure: "main",
});
if (!result.ok) throw result.error;
expect(result.value.referencesTruncated).toBeUndefined();
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it("reports nothing for the legacy profile, whose producer has no cap flag", async () => {
const { root, target } = await createIdaTarget("x86_64");
attachedRoots.push(root);
const client = new IdaSessionClient(
{
command: "fixture",
args: [],
env: {},
mode: "attached",
timeoutMs: 1000,
workspaceRoot: root,
},
target,
new RecordingIdaMcp(target, "attached"),
);
try {
const result = await client.execute("xrefs", { address: "0x1000" });
if (!result.ok) throw result.error;
expect(result.value.referencesTruncated).toBeUndefined();
} finally {
expect((await client.close()).ok).toBe(true);
}
});
});
+80 -18
View File
@@ -515,7 +515,7 @@ describe("headless IDA transient busy health", () => {
});
it.each([
["free-form text", "token=abc123 /private/home/user secret"],
["free-form text", "token=abc123 /private<home> secret"],
["an over-long name", "x".repeat(200)],
])(
"reports %s from the worker as unknown instead of echoing it",
@@ -899,6 +899,85 @@ describe("headless IDA reaped worker cleanup", () => {
});
});
/** A completed open response is not proof that its private Worker was ever released. */
describe("headless IDA unresolved successful-open ownership", () => {
it.each(["matching", "foreign-input", "malformed"] as const)(
"retains the private input after %s success with incomplete initial discovery",
async (kind) => {
const { producer, client, root } = await fixture("headless");
let hidden = true;
let ownedId: string | undefined;
let privateInput: string | undefined;
producer.beforeCall = async (name, args) => {
if (name !== "idb_open") return;
ownedId = z.string().parse(args.preferred_session_id);
privateInput = z.string().parse(args.input_path);
producer.database = ownedId;
producer.inputPath = privateInput;
};
producer.overrideCall = (name) => {
if (name === "idb_open") {
const originalId = z.string().parse(ownedId);
const originalInput = z.string().parse(privateInput);
if (kind === "foreign-input")
return {
success: true,
session: {
session_id: "foreign-session",
input_path: "/foreign/input",
},
};
if (kind === "malformed")
return { success: true, session: { session_id: originalId } };
return {
success: true,
session: { session_id: originalId, input_path: originalInput },
};
}
if (name === "idb_list" && hidden) return { sessions: [] };
return undefined;
};
expect((await client.execute("health", {})).ok).toBe(false);
const incomplete = await client.close();
expect(incomplete.ok).toBe(false);
if (!incomplete.ok) expect(incomplete.error.cleanupIncomplete).toBe(true);
expect(producer.closes).toBe(0);
expect(producer.database).toBe(ownedId);
expect(
(await readdir(root)).some((name) => name.startsWith("rea-ida-")),
).toBe(true);
expect(producer.calls.some(({ name }) => name === "idb_close")).toBe(
false,
);
// A later positive private ownership record permits ordinary save=false
// cleanup, without ever adopting the foreign open-response identity.
hidden = false;
expect((await client.close()).ok).toBe(true);
expect(producer.calls.filter(({ name }) => name === "idb_close")).toEqual(
[{ name: "idb_close", args: { database: ownedId, save: false } }],
);
expect(producer.closes).toBe(1);
expect(await readdir(root)).toEqual(["target.elf"]);
},
);
it("preserves cleanup after a completed, explicit idb_open rejection", async () => {
const { producer, client, root } = await fixture("headless");
producer.overrideCall = (name) =>
name === "idb_open"
? { error: "Input was rejected before creating a session" }
: undefined;
expect((await client.execute("health", {})).ok).toBe(false);
expect((await client.close()).ok).toBe(true);
expect(producer.calls.some(({ name }) => name === "idb_close")).toBe(false);
expect(producer.closes).toBe(1);
expect(await readdir(root)).toEqual(["target.elf"]);
});
});
describe("headless IDA cleanup verification", () => {
it("retries failed worker release through the retained connection before removing its workspace", async () => {
const { producer, client, root } = await fixture("headless");
@@ -943,23 +1022,6 @@ describe("headless IDA cleanup verification", () => {
).toHaveLength(1);
expect(await readdir(root)).toEqual(["target.elf"]);
});
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.close()).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) => {
+32
View File
@@ -33,6 +33,7 @@ import {
IDA_LIMITATIONS,
IDA_OPERATIONS,
IDA_PROVIDER_IDENTITY,
idaProfileAdmits,
type IdaOperation,
} from "./IdaProviderCapabilities.js";
import {
@@ -42,6 +43,7 @@ import {
legacyMetadataSchema,
modernHealthSchema,
openDatabaseSchema,
rejectedOpenDatabaseSchema,
} from "./IdaProtocolValues.js";
import {
idaFileDigest,
@@ -121,7 +123,9 @@ export class IdaSessionClient implements AnalysisClient {
#databaseCloseCompleted = false;
#openAttempted = false;
#openCompleted = false;
#openRejected = false;
#callGraphAdvertised = false;
#surveyAdvertised = false;
#initialIdentity: string | undefined;
#metadata: JsonValue = null;
#lifecycle: JsonValue[] = [];
@@ -194,6 +198,17 @@ export class IdaSessionClient implements AnalysisClient {
"This integration admits read-only analysis operations only.",
),
);
if (
operation !== "health" &&
!idaProfileAdmits(operation, this.config.mode)
)
return err(
new AnalysisCapabilityUnavailableError(
"ida",
operation,
"This operation is available for the modern headless profile only.",
),
);
if (
operation === "procedure_callers" &&
idaProtocol(this.config) !== "legacy"
@@ -269,6 +284,9 @@ export class IdaSessionClient implements AnalysisClient {
...(runner.relationshipCoverage === undefined
? {}
: { relationshipCoverage: runner.relationshipCoverage }),
...(runner.referencesTruncated !== undefined
? { referencesTruncated: runner.referencesTruncated }
: {}),
locations: [
{ kind: "artifact-path", path: this.target.path },
...runner.locations,
@@ -293,6 +311,8 @@ export class IdaSessionClient implements AnalysisClient {
selectorOrigin: options?.selectorOrigin,
x86Only: isX86OnlyTarget(this.target),
callGraphAvailable: this.#callGraphAdvertised,
surveyAvailable: this.#surveyAdvertised,
admittedDocument: this.target.path,
},
);
}
@@ -423,6 +443,7 @@ export class IdaSessionClient implements AnalysisClient {
async #initialize(): Promise<void> {
const tools = new Set(await this.connection.connect());
this.#callGraphAdvertised = tools.has("callgraph");
this.#surveyAdvertised = tools.has("survey_binary");
const expected =
this.config.protocol === "native"
? nativeTools
@@ -450,6 +471,9 @@ export class IdaSessionClient implements AnalysisClient {
preferred_session_id: this.#workspace.sessionId,
});
this.#openCompleted = true;
// A completed but malformed/positive open may still own a live Worker.
// Only an explicit producer rejection keeps the old no-worker branch.
this.#openRejected = rejectedOpenDatabaseSchema.safeParse(raw).success;
this.#lifecycle.push(raw);
const opened = openDatabaseSchema.parse(raw);
if (
@@ -614,6 +638,14 @@ export class IdaSessionClient implements AnalysisClient {
throw new AnalysisProtocolError(
"An unowned worker still uses the private workspace; it was retained.",
);
if (
this.#database === undefined &&
this.#openCompleted &&
!this.#openRejected
)
throw new AnalysisProtocolError(
"IDA open returned without a verified private worker binding. An empty session inventory does not prove that its Worker exited; the private workspace was retained.",
);
}
if (this.#database !== undefined) {
if (!this.#databaseCloseCompleted) {
@@ -17,6 +17,28 @@ import {
resolveProcessScenarioRuntimePaths,
} from "./ProcessScenarioRuntimeValidation.js";
import { parseProcessScenario } from "../../domain/process/processScenario.js";
import { createTestTempDirectory } from "../../../tests/fixtures/temporaryDirectory.js";
it.skipIf(process.platform === "win32")(
"resolves a literal backslash in a POSIX executable basename through PATH",
async () => {
const root = await createTestTempDirectory("rea-process-posix-basename-");
const bin = join(root, "bin");
await mkdir(bin);
const command = "selected\\node";
const selected = join(bin, command);
await symlink(process.execPath, selected);
await expect(resolveExecutable(command, root, bin)).resolves.toBe(selected);
const resolved = await resolveProcessScenarioRuntimePaths(
parseProcessScenario({
executable: command,
working_directory: root,
environment: { PATH: bin },
}),
);
expect(resolved.executable).toBe(selected);
},
);
it("preserves the caller-selected executable symlink for process invocation", async () => {
const root = await mkdtemp(join(tmpdir(), "rea-process-executable-alias-"));
@@ -1,6 +1,6 @@
import { constants as fsConstants } from "node:fs";
import { access, realpath, stat } from "node:fs/promises";
import { delimiter, isAbsolute, join, resolve } from "node:path";
import { delimiter, isAbsolute, join, resolve, sep } from "node:path";
import type { ProcessScenario } from "../../domain/process/processScenario.js";
import { AnalysisInputError } from "../../domain/analysisErrorCore.js";
@@ -71,7 +71,9 @@ export const resolveExecutable = async (
: resolve(workingDirectory, directory),
);
const candidates =
isAbsolute(command) || command.includes("/") || command.includes("\\")
isAbsolute(command) ||
command.includes("/") ||
(sep === "\\" && command.includes("\\"))
? [resolve(workingDirectory, command)]
: directories.map((directory) => join(directory, command));
const failures: string[] = [];
+1 -1
View File
@@ -394,7 +394,7 @@ const readRows = (
for (const name of columns)
if (!available.has(name))
throw new SqliteInspectionFailure(
"selection",
"column-selection",
`Selected column does not exist with that exact name in table ${input.table}: ${name}`,
);
const projection = columns
+1
View File
@@ -12,6 +12,7 @@ export class SqliteInspectionFailure extends Error {
readonly reason:
| "format"
| "selection"
| "column-selection"
| "unsupported"
| "unavailable"
| "output-limit"
+10 -1
View File
@@ -36,6 +36,7 @@ const replySchema = z.discriminatedUnion("ok", [
reason: z.enum([
"format",
"selection",
"column-selection",
"unsupported",
"unavailable",
"output-limit",
@@ -49,6 +50,14 @@ export type SqliteWorkerLauncher = NonNullable<
Parameters<typeof runOwnedCommand>[2]
>["launcher"];
// Each input rejection names the caller argument that requires correction.
const rejectedArgument = {
format: "path",
unsupported: "path",
selection: "table",
"column-selection": "columns",
} as const;
const rejectedReply = (
reply: z.output<typeof replySchema> & { ok: false },
capturedOutput: AnalysisCapturedOutput,
@@ -83,7 +92,7 @@ const rejectedReply = (
);
return new AnalysisInputError(operation, { capturedOutput }, [
{
path: [reply.reason === "selection" ? "table" : "path"],
path: [rejectedArgument[reply.reason]],
reason: "invalid_format",
message: reply.message,
},
+16
View File
@@ -143,6 +143,22 @@ describe("packaged Windows native admission", () => {
},
);
it.each([
{ signature: "MZ", offset: 0 },
{ signature: "PE", offset: 64 },
])(
"rejects digest-valid high-bit $signature lookalikes before loading",
({ offset }) => {
const value = fixture();
value.bytes[offset] = (value.bytes[offset] ?? 0) | 0x80;
value.manifest.artifactSha256 = createHash("sha256")
.update(value.bytes)
.digest("hex");
expect(loadWindowsNativeAuthority(value.host).available).toBe(false);
expect(value.loads()).toBe(0);
},
);
it("rejects a digest-valid artifact for another machine", () => {
const value = fixture();
value.bytes.writeUInt16LE(0xaa64, 68);
+2 -2
View File
@@ -132,12 +132,12 @@ export const loadWindowsNativeAuthority = (
};
const assertWindowsX64Artifact = (bytes: Buffer): void => {
if (bytes.length < 64 || bytes.toString("ascii", 0, 2) !== "MZ")
if (bytes.length < 64 || bytes.toString("latin1", 0, 2) !== "MZ")
throw new Error("Windows native artifact is not a PE image");
const offset = bytes.readUInt32LE(0x3c);
if (
offset > bytes.length - 26 ||
bytes.toString("ascii", offset, offset + 4) !== "PE\0\0" ||
bytes.toString("latin1", offset, offset + 4) !== "PE\0\0" ||
bytes.readUInt16LE(offset + 4) !== 0x8664 ||
bytes.readUInt16LE(offset + 24) !== 0x20b
)
@@ -87,3 +87,43 @@ it.each([
);
},
);
it("bounds the Java version probe and reports an over-budget probe as a failed Java check", async () => {
const root = await createTestTempDirectory("rea-java-probe-bound-");
const configuredHome = join(root, "selected-jdk");
const installDir = join(root, "ghidra");
await mkdir(join(installDir, "Ghidra"), { recursive: true });
await writeFile(
join(installDir, "Ghidra", "application.properties"),
`application.version=${SUPPORTED_GHIDRA_VERSION}\napplication.java.min=17\n`,
);
// A chatty or hostile JVM that overruns the capture budget: spawnSync reports
// ENOBUFS, which the probe already treats as a failed observation.
mockSpawnSync.mockReturnValue({
stdout: "",
stderr: "java.version = 21.0.11\n",
status: null,
error: Object.assign(new Error("spawnSync /java ENOBUFS"), {
code: "ENOBUFS",
}),
});
const inspection = inspectGhidraInstallation({
environment: {},
installDir,
javaHome: configuredHome,
});
const [, , options] = mockSpawnSync.mock.calls[0] as [
string,
readonly string[],
{ readonly maxBuffer?: number },
];
expect(options.maxBuffer).toBe(1024 * 1024);
expect(inspection.javaVersion).toBeNull();
expect(inspection.javaHome).toBe(configuredHome);
expect(inspection.checks.find(({ name }) => name === "java")).toMatchObject({
status: "failed",
code: "runtime_missing",
});
});
@@ -4,9 +4,35 @@ import { describe, expect, it } from "vitest";
import { systemDoctorHost } from "../../../src/application/Doctor.js";
import { parseBinaryTarget } from "../../../src/application/BinaryTargetResolver.js";
import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";
import { pe } from "../../../src/domain/binaryTarget.fixture.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
describe("executable format refusal diagnostics", () => {
it.each([
[0x01a6, "0x01a6"],
[0x0000, "0x0000"],
[0xffff, "0xffff"],
] as const)(
"retains unsupported PE machine %i in the refusal",
async (machine, expectedMachine) => {
const directory = await createTestTempDirectory("rea-target-pe-machine-");
const path = join(directory, "unsupported.exe");
const bytes = pe(0x014c);
bytes.writeUInt16LE(machine, 0x44);
await writeFile(path, bytes);
const result = await parseBinaryTarget(path);
if (result.ok) throw new Error("unsupported PE target was admitted");
const reason = `unsupported PE architecture (COFF machine ${expectedMachine})`;
expect(projectAnalysisError(result.error)).toMatchObject({
code: "target_unavailable",
category: "unsupported_target",
message: `Cannot open artifact: ${reason}.`,
details: { reason, constraint: "file_format_rejected" },
});
},
);
it.each(["NE", "LE", "LX"] as const)(
"reports unsupported %s executables without path advice",
async (signature) => {
@@ -0,0 +1,249 @@
import { afterEach, describe, expect, it } from "vitest";
import type { AnalysisOperationPort } from "../../../src/application/AnalysisProvider.js";
import { createAnalysisExecution } from "../../../src/application/AnalysisProvider.js";
import { EnhancedTools } from "../../../src/application/EnhancedTools.js";
import { AnalysisOutputError } from "../../../src/domain/analysisErrorCore.js";
import { err, ok } from "../../../src/domain/result.js";
import { closeEnhancedToolResources, connect } from "./enhancedToolsHarness.js";
afterEach(closeEnhancedToolResources);
const PROVIDER = {
id: "fixture",
name: "Fixture analysis provider",
version: "1",
} as const;
type Coverage = boolean | undefined;
interface Behavior {
/** What the provider reports for the references of each match address. */
readonly coverage?: Readonly<Record<string, Coverage>>;
readonly limitations?: readonly string[];
/** Also report the first string match as a procedure match. */
readonly duplicateProcedure?: boolean;
/** Fail the references read of this address. */
readonly failXrefsOf?: string;
readonly calls?: string[];
}
const containing = (address: string) => ({
query_address: address,
found: false,
procedure: null,
reason: "not_in_procedure",
});
/**
* A provider with two string matches (0x10 and 0x11), each referenced from
* one address (0x20 and 0x21).
*/
const provider = (behavior: Behavior = {}): AnalysisOperationPort => ({
execute: async (name, arguments_) => {
const address = String(arguments_.address);
behavior.calls?.push(`${name}:${address}`);
switch (name) {
case "search_strings":
return ok(
createAnalysisExecution(
[
{ address: "0x10", value: "hello" },
{ address: "0x11", value: "hello again" },
],
PROVIDER,
),
);
case "search_procedures":
return ok(
createAnalysisExecution(
behavior.duplicateProcedure === true
? [{ address: "0x10", value: "hello" }]
: [],
PROVIDER,
),
);
case "xrefs": {
if (address === behavior.failXrefsOf)
return err(new AnalysisOutputError("xrefs", "provider failed"));
const reported = behavior.coverage?.[address];
return ok(
createAnalysisExecution(
[address === "0x10" ? "0x20" : "0x21"],
PROVIDER,
{
limitations: behavior.limitations ?? [],
...(reported === undefined
? {}
: { referencesTruncated: reported }),
},
),
);
}
case "resolve_containing_procedure":
return ok(createAnalysisExecution(containing(address), PROVIDER));
default:
throw new Error(`Unexpected operation: ${name}`);
}
},
});
const expectedTrace = (
residual: readonly string[],
extraMatches: readonly object[] = [],
) => ({
query: "hello",
search_mode: "literal",
matches: [
{ type: "string", address: "0x10", value: "hello" },
{ type: "string", address: "0x11", value: "hello again" },
...extraMatches,
],
references: [
{
target_address: "0x10",
source_address: "0x20",
containing_procedure: containing("0x20"),
},
{
target_address: "0x11",
source_address: "0x21",
containing_procedure: containing("0x21"),
},
...extraMatches.map(() => ({
target_address: "0x10",
source_address: "0x20",
containing_procedure: containing("0x20"),
})),
],
truncated: residual.length > 0,
residual_unknowns: residual,
});
const unknownFor = (address: string) =>
`References to ${address} were truncated by the provider; additional references may exist.`;
const trace = async (analysis: AnalysisOperationPort) => {
const client = await connect(analysis);
const result = await client.callTool({
name: "trace_feature",
arguments: { query: "hello" },
});
expect(result.isError).not.toBe(true);
return result.structuredContent as { normalized_result: unknown };
};
describe("trace_feature reference coverage", () => {
it("marks the trace truncated for the target whose references the provider capped", async () => {
const output = await trace(
provider({ coverage: { "0x10": true, "0x11": false } }),
);
expect(
output.normalized_result,
"the received references are kept and only the capped target is a residual unknown",
).toEqual(expectedTrace([unknownFor("0x10")]));
});
it("does not carry a truncation over to the next target that reports nothing", async () => {
const output = await trace(provider({ coverage: { "0x10": true } }));
expect(output.normalized_result).toEqual(
expectedTrace([unknownFor("0x10")]),
);
});
it("reports a capped target once when it is matched twice", async () => {
const output = await trace(
provider({ coverage: { "0x10": true }, duplicateProcedure: true }),
);
expect(output.normalized_result).toEqual(
expectedTrace(
[unknownFor("0x10")],
[{ type: "procedure", address: "0x10", value: "hello" }],
),
);
});
it("resolves the containing procedure of a repeated reference source once", async () => {
const calls: string[] = [];
const output = await trace(provider({ duplicateProcedure: true, calls }));
expect(
calls.filter((call) => call.startsWith("resolve_containing_procedure:")),
"the source 0x20 is referenced by two matches of the same address and resolved once",
).toEqual([
"resolve_containing_procedure:0x20",
"resolve_containing_procedure:0x21",
]);
expect(
output.normalized_result,
"every reference is still reported with its containing procedure",
).toEqual(
expectedTrace(
[],
[{ type: "procedure", address: "0x10", value: "hello" }],
),
);
});
it("keeps the trace complete when the provider explicitly reports no cap", async () => {
const output = await trace(
provider({ coverage: { "0x10": false, "0x11": false } }),
);
expect(output.normalized_result).toEqual(expectedTrace([]));
});
it("does not change the trace of a provider that reports no coverage", async () => {
const output = await trace(
provider({
limitations: ["Upstream xrefs_to capped results at 1000 references."],
}),
);
expect(
output.normalized_result,
"a limitation text alone never truncates, and an absent field keeps the previous result",
).toEqual(expectedTrace([]));
});
it("never exposes the coverage field in the tool output", async () => {
const output = await trace(
provider({ coverage: { "0x10": true, "0x11": false } }),
);
expect(JSON.stringify(output)).not.toMatch(
/referencesTruncated|references_truncated/,
);
});
it("fails the trace when a references read fails and reads nothing further", async () => {
const calls: string[] = [];
const result = await new EnhancedTools(
provider({ failXrefsOf: "0x10", calls }),
).execute("trace_feature", { query: "hello" });
expect(result.ok).toBe(false);
expect(
calls.filter((call) => call.startsWith("xrefs:")),
"the next target is not read after the failure",
).toEqual(["xrefs:0x10"]);
});
it("stops without reading references when the trace is cancelled", async () => {
const calls: string[] = [];
const controller = new AbortController();
controller.abort();
const result = await new EnhancedTools(provider({ calls })).execute(
"trace_feature",
{ query: "hello" },
controller.signal,
);
expect(result.ok).toBe(false);
expect(calls.filter((call) => call.startsWith("xrefs:"))).toEqual([]);
});
});
@@ -196,9 +196,9 @@ itWithCaptureCapability(
result.value.frames.map(({ at_ms }) => at_ms),
"capture-relative frame times stay ordered and nonnegative",
).toEqual(
[...result.value.frames.map(({ at_ms }) => at_ms)].sort(
(left, right) => left - right,
),
result.value.frames
.map(({ at_ms }) => at_ms)
.sort((left, right) => left - right),
);
expect(result.value.frames.every(({ at_ms }) => at_ms >= 0)).toBe(true);
expect(result.value.exit.reason).toBe("exited");
@@ -28,6 +28,35 @@ const identitySchema = z.object({
const itWithLinuxCaptureCapability =
process.platform === "linux" ? itWithCaptureCapability : it.skip;
itWithCaptureCapability(
"captures a POSIX PATH executable with a literal backslash in its basename",
async () => {
const root = await createTestTempDirectory("rea-process-backslash-name-");
const bin = join(root, "bin");
await mkdir(bin);
const command = "selected\\node";
const selected = join(bin, command);
await symlink(process.execPath, selected);
const scenario = parseProcessScenario({
executable: command,
working_directory: root,
environment: { PATH: bin },
arguments: ["-e", 'process.stdout.write("selected executable")'],
settle_ms: 100,
});
const result = await captureProcessScenario(scenario);
if (!result.ok) throw result.error;
expect(result.value.frames.map(({ data }) => data).join("")).toBe(
"selected executable",
);
expect(result.value.exit).toMatchObject({ code: 0, reason: "exited" });
expect(result.value.cleanup).toMatchObject({
owned_process_group: "verified",
temporary_root: "removed",
});
},
);
itWithCaptureCapability(
"preserves numeric reports and original normalized PTY text in Evidence",
async () => {
@@ -1,4 +1,11 @@
import { access, chmod, readFile, stat } from "node:fs/promises";
import {
access,
chmod,
mkdir,
readFile,
stat,
writeFile,
} from "node:fs/promises";
import { join, posix, win32 } from "node:path";
import { fileURLToPath } from "node:url";
@@ -480,6 +487,64 @@ describe("Ghidra Windows launcher", () => {
).toThrow(/metacharacters/u);
});
it.skipIf(process.platform !== "win32").each([
{
properties:
"application.version=12.1.4\napplication.release.name=PUBLIC\n",
release: "ghidra_12.1.4_PUBLIC",
},
{ properties: undefined, release: "renamed-install" },
{ properties: "application.version=12.1.4\n", release: "renamed-install" },
])(
"prepares the release directory through the Windows runtime ($release)",
async ({ properties, release }) => {
const parent = await createTestTempDirectory("rea-launch-config-");
const installRoot = join(parent, "renamed-install");
if (properties !== undefined) {
await mkdir(join(installRoot, "Ghidra"), { recursive: true });
await writeFile(
join(installRoot, "Ghidra", "application.properties"),
properties,
);
}
const runtime = await createGhidraTestRuntime(parent);
runtimes.push(runtime);
const spawnProcess = vi.fn(async () => {
throw new Error("fixture stops before process creation");
});
const launcher = new GhidraHeadlessLauncher({
environment: process.env,
platform: "win32",
analyzeHeadlessPath: join(
installRoot,
"support",
"analyzeHeadless.bat",
),
javaHome: "C:\\Java\\jdk-21",
bridgeScriptPath: join(parent, "ReaGhidraBridge.java"),
spawnProcess,
});
const launched = await launcher.launch({
runtimeRoot: runtime.path,
transport: "unix-socket",
endpointPath: join(runtime.path, "bridge.sock"),
token: "fixture-token",
runId: "d6fcbb66-e829-4ff6-a535-0035aec63139",
targetPath: join(parent, "fixture.exe"),
targetSha256: "b".repeat(64),
providerVersion: "12.1.4",
profileDigest: "a".repeat(64),
});
expect(launched.ok).toBe(false);
expect(spawnProcess).toHaveBeenCalledOnce();
expect(
(
await stat(join(runtime.path, "config", "ghidra", release))
).isDirectory(),
).toBe(true);
},
);
it.skipIf(process.platform !== "win32")(
"keeps authority in a private descriptor and isolates Ghidra state through the batch launcher",
async () => {
@@ -0,0 +1,144 @@
import { rm } from "node:fs/promises";
import { afterEach, describe, expect, it } from "vitest";
import { inspectAddressContext } from "../../../../src/application/AnalysisContextQueries.js";
import { EnhancedTools } from "../../../../src/application/EnhancedTools.js";
import { IdaSessionClient } from "../../../../src/ida/IdaSessionClient.js";
import { createIdaTarget, RecordingIdaMcp } from "../../../fixtures/idaMcp.js";
const roots: string[] = [];
afterEach(async () => {
for (const root of roots.splice(0))
await rm(root, { recursive: true, force: true });
});
const session = async (cappedReferences = false) => {
const { root, target } = await createIdaTarget("arm64");
roots.push(root);
const producer = new RecordingIdaMcp(target, "headless");
if (cappedReferences) {
const inner = producer.overrideCall;
producer.overrideCall = (name, args) =>
name === "xrefs_to"
? [
{
xrefs: [
{
addr: "0x1004",
type: "code",
fn: { addr: "0x1000", name: "main", size: "0x20" },
},
],
more: true,
},
]
: inner?.(name, args);
}
const client = new IdaSessionClient(
{
command: "fixture",
args: [],
env: {},
mode: "headless",
timeoutMs: 1000,
workspaceRoot: root,
},
target,
producer,
);
return { client, target };
};
const MAIN = {
found: true,
procedure: { address: "0x1000", name: "main" },
};
describe("trace_feature on headless IDA", () => {
it("attributes a reference to its containing procedure", async () => {
const { client } = await session();
try {
const result = await new EnhancedTools(client).execute("trace_feature", {
query: "a.b",
});
if (!result.ok) throw result.error;
expect(result.value).toMatchObject({
matches: [{ type: "string", address: "0x3000" }],
references: [
{
target_address: "0x3000",
source_address: "0x1004",
containing_procedure: MAIN,
},
],
truncated: false,
residual_unknowns: [],
});
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it("keeps an upstream reference cap visible once containment makes the trace run", async () => {
const { client } = await session(true);
try {
const result = await new EnhancedTools(client).execute("trace_feature", {
query: "a.b",
});
if (!result.ok) throw result.error;
expect(result.value).toMatchObject({
references: [{ source_address: "0x1004", containing_procedure: MAIN }],
truncated: true,
residual_unknowns: [
"References to 0x3000 were truncated by the provider; additional references may exist.",
],
});
} finally {
expect((await client.close()).ok).toBe(true);
}
});
});
describe("inspect_address_context on headless IDA", () => {
it("resolves the admitted program as the document and reports the containing procedure", async () => {
const { client, target } = await session();
try {
const result = await inspectAddressContext(client, {
address: "0x1004",
});
if (!result.ok) throw result.error;
expect(result.value).toMatchObject({
address: "0x1004",
document: target.path,
procedure: { state: "available", value: MAIN },
name: { state: "unavailable" },
comment: { state: "unavailable" },
inline_comment: { state: "unavailable" },
bookmarks: { state: "unavailable" },
});
} finally {
expect((await client.close()).ok).toBe(true);
}
});
it("answers the same way for an explicit admitted document", async () => {
const { client, target } = await session();
try {
const implicit = await inspectAddressContext(client, {
address: "0x1004",
});
const explicit = await inspectAddressContext(client, {
address: "0x1004",
document: target.path,
});
if (!implicit.ok) throw implicit.error;
if (!explicit.ok) throw explicit.error;
expect(explicit.value).toEqual(implicit.value);
} finally {
expect((await client.close()).ok).toBe(true);
}
});
});
@@ -0,0 +1,212 @@
import { describe, expect, it } from "vitest";
import {
assertFeatureTrace,
findMappedNonFunction,
} from "../../../../scripts/lib/ida-feature-trace.mjs";
const procedure = { address: "0x1000", name: "main" };
const containing = (found: boolean) =>
found
? {
query_address: "0x1004",
found: true,
procedure: { address: "0x1000", name: "main" },
}
: {
query_address: "0x3010",
found: false,
procedure: null,
reason: "not_in_procedure",
};
const trace = (
matches: readonly { type: string; address: string }[],
references: readonly {
target_address: string;
containing_procedure: unknown;
}[],
) => ({
query: "main",
search_mode: "literal",
matches,
references,
truncated: false,
residual_unknowns: [],
});
const SELECTED = { type: "procedure", address: "0x1000" };
const SUBSTRING = { type: "procedure", address: "0x2000" };
const STRING = { type: "string", address: "0x3000" };
describe("the real IDA lane's feature trace assertions", () => {
it("accepts references to every matched address, whoever contains the source", () => {
expect(() =>
assertFeatureTrace(
trace(
[SELECTED, SUBSTRING, STRING],
[
{
target_address: "0x1000",
containing_procedure: containing(true),
},
// A substring match such as main_helper, referenced from code.
{
target_address: "0x2000",
containing_procedure: containing(true),
},
// A string containing the query, referenced from data outside functions.
{
target_address: "0x3000",
containing_procedure: containing(false),
},
],
),
procedure,
),
).not.toThrow();
});
it("accepts a reference to the selected procedure from data outside functions", () => {
expect(() =>
assertFeatureTrace(
trace(
[SELECTED],
[
{
target_address: "0x1000",
containing_procedure: containing(false),
},
],
),
procedure,
),
).not.toThrow();
});
it("rejects a reference whose target is not one of the matches", () => {
expect(() =>
assertFeatureTrace(
trace(
[SELECTED],
[
{
target_address: "0x9999",
containing_procedure: containing(true),
},
],
),
procedure,
),
).toThrow();
});
it("rejects a trace without the selected procedure's match", () => {
expect(() => assertFeatureTrace(trace([STRING], []), procedure)).toThrow();
});
it("rejects a containment answer that is neither found nor a known reason", () => {
expect(() =>
assertFeatureTrace(
trace(
[SELECTED],
[
{
target_address: "0x1000",
containing_procedure: {
query_address: "0x1004",
found: false,
procedure: null,
reason: "unknown",
},
},
],
),
procedure,
),
).toThrow();
});
it("rejects a trace that does not say whether it was truncated", () => {
expect(() =>
assertFeatureTrace(
{ ...trace([SELECTED], []), truncated: undefined },
procedure,
),
).toThrow();
});
});
describe("the real IDA lane's mapped non-function probe", () => {
const inFunction = {
query_address: "0x1100",
found: true,
procedure: { address: "0x1000", name: "main" },
};
const data = {
query_address: "0x3000",
found: false,
procedure: null,
reason: "not_in_procedure",
};
const resolver =
(answers: Readonly<Record<string, unknown>>, asked: string[] = []) =>
async (address: string) => {
asked.push(address);
return answers[address];
};
it("skips a string inside a function chunk and uses the next one", async () => {
const asked: string[] = [];
await expect(
findMappedNonFunction(
[{ address: "0x1100" }, { address: "0x3000" }],
resolver({ "0x1100": inFunction, "0x3000": data }, asked),
),
).resolves.toBe("0x3000");
expect(asked, "strings are tried in order until one qualifies").toEqual([
"0x1100",
"0x3000",
]);
});
it("stops at the first string that qualifies", async () => {
const asked: string[] = [];
await expect(
findMappedNonFunction(
[{ address: "0x3000" }, { address: "0x3100" }],
resolver({ "0x3000": data, "0x3100": data }, asked),
),
).resolves.toBe("0x3000");
expect(asked).toEqual(["0x3000"]);
});
it("reports no qualifying string when every string is inside a function", async () => {
await expect(
findMappedNonFunction(
[{ address: "0x1100" }, { address: "0x1200" }],
resolver({ "0x1100": inFunction, "0x1200": inFunction }),
),
).resolves.toBeUndefined();
});
it("reports no qualifying string when the target has no strings", async () => {
await expect(
findMappedNonFunction([], resolver({})),
).resolves.toBeUndefined();
});
it("rejects a listed string that resolves as unmapped, since IDA cannot list an unmapped address", async () => {
await expect(
findMappedNonFunction(
[{ address: "0x4000" }, { address: "0x3000" }],
resolver({
"0x4000": { ...data, reason: "outside_segments" },
"0x3000": data,
}),
),
).rejects.toThrow();
});
});
@@ -5,6 +5,7 @@ import { DatabaseSync } from "node:sqlite";
import { promisify } from "node:util";
import { fileURLToPath } from "node:url";
import { expect, it as nativeTest, onTestFinished } from "vitest";
import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";
import { SqliteDatabaseProvider } from "../../../src/sqlite/SqliteDatabaseProvider.js";
import { spawnOwnedProviderProcess } from "../../../src/process/ProviderProcess.js";
import { PrivateRuntimeRoot } from "../../../src/process/PrivateRuntimeRoot.js";
@@ -356,6 +357,49 @@ it("does not execute views when selecting rows", async () => {
});
});
it("attributes table and column selection failures to their own arguments", async () => {
const { database } = await createFixture();
const provider = createProvider();
onTestFinished(() => provider.close());
const projection = async (selection: {
table: string;
columns?: string[];
}) => {
const result = await provider.inspect({
path: database.path,
row_limit: 1,
...selection,
});
if (result.ok) throw new Error("Expected a rejected selection");
return projectAnalysisError(result.error);
};
expect(
await projection({ table: "records", columns: ["nope"] }),
).toMatchObject({
details: {
issues: [
{
path: ["columns"],
reason: "invalid_format",
message:
"Selected column does not exist with that exact name in table records: nope",
},
],
},
});
expect(await projection({ table: "absent" })).toMatchObject({
details: { issues: [{ path: ["table"] }] },
});
const selected = await provider.inspect({
path: database.path,
table: "records",
columns: ["id"],
row_limit: 1,
});
if (!selected.ok) throw selected.error;
expect(selected.value.result).toMatchObject({ rows: { columns: ["id"] } });
});
it("rejects malformed databases without altering the selected file", async () => {
const workspace = await createTestWorkspace("rea-sqlite-invalid-");
onTestFinished(() => removeTestWorkspace(workspace.root));
@@ -1278,3 +1278,102 @@ describe("selector origin forwarding", () => {
).toEqual(["provider", "provider", undefined]);
});
});
describe("reference truncation forwarding", () => {
const referenceProvider = (
referencesTruncated: boolean | undefined,
calls: string[],
): AnalysisProvider => {
const identity = {
id: "fixture",
name: "Fixture analysis provider",
version: "1",
} as const;
return {
identity: () => identity,
resolveAnalysisProfile: () =>
Promise.resolve(
resultOk({
profile: createAnalysisProfile(identity, { fixture: true }),
}),
),
capabilities: () => [
{
provider: identity,
operation: "xrefs",
available: true,
reason: null,
effects: {
mutatesArtifact: false,
launchesProcess: false,
mayShowUi: false,
mayAccessNetwork: false,
mayWriteFilesystem: false,
changesPermissions: false,
requiresRoot: false,
},
limitations: [],
},
],
createClient: () => ({
execute: (operation) => {
calls.push(operation);
return Promise.resolve(
resultOk(
createAnalysisExecution(
["0x2000"],
identity,
referencesTruncated === undefined
? {}
: { referencesTruncated },
),
),
);
},
close: () => Promise.resolve(resultOk(null)),
}),
};
};
const parameters = { address: "0x1000", document: "fixture" };
it("forwards a truncation on both execution paths and never replays it from the snapshot", async () => {
const [first] = await createBinarySessionTargets();
const calls: string[] = [];
const session = createTestBinarySession(referenceProvider(true, calls));
expect((await session.open(first)).ok).toBe(true);
calls.length = 0;
const direct = await session.execute("xrefs", parameters);
const admitted = await session.withAdmittedAnalysis(
"trace_feature",
undefined,
(analysis) => analysis.execute("xrefs", parameters),
);
expect(direct.ok && direct.value.referencesTruncated).toBe(true);
if (!admitted.ok) throw admitted.error;
expect(admitted.value.ok && admitted.value.value.referencesTruncated).toBe(
true,
);
expect(
calls,
"a truncated read is not recorded, so every call reaches the provider",
).toEqual(["xrefs", "xrefs"]);
});
it("keeps an explicit complete report out of the way of snapshot replay", async () => {
const [first] = await createBinarySessionTargets();
const calls: string[] = [];
const session = createTestBinarySession(referenceProvider(false, calls));
expect((await session.open(first)).ok).toBe(true);
calls.length = 0;
const live = await session.execute("xrefs", parameters);
await session.execute("xrefs", parameters);
expect(live.ok && live.value.referencesTruncated).toBe(false);
expect(calls, "the complete read is recorded and replayed").toEqual([
"xrefs",
]);
});
});
@@ -29,15 +29,25 @@ const parametersFor = (
operation: string,
): Readonly<Record<string, JsonValue>> => {
if (operation.startsWith("search_")) return { pattern: "a.b" };
if (operation === "xrefs") return { address: "0x1000" };
if (operation === "xrefs" || operation === "resolve_containing_procedure")
return { address: "0x1000" };
if (operation.startsWith("list_")) return {};
return { procedure: "main" };
};
/** Operations only the headless profile declares. */
const HEADLESS_ONLY: ReadonlySet<string> = new Set([
"resolve_containing_procedure",
"list_documents",
]);
describe.each(["attached", "headless"] as const)(
"IDA %s caller-visible contracts",
(mode) => {
it.each(IDA_OPERATIONS)(
const operations = IDA_OPERATIONS.filter(
(operation) => mode === "headless" || !HEADLESS_ONLY.has(operation),
);
it.each(operations)(
"declares %s UI effects matching the upstream tools it reaches",
async (operation) => {
const { root, target } = await createIdaTarget();
@@ -69,7 +79,7 @@ describe.each(["attached", "headless"] as const)(
},
);
it.each(IDA_OPERATIONS)(
it.each(operations)(
"serializes %s against its named advertised output contract",
async (operation) => {
const { root, target } = await createIdaTarget();
+1
View File
@@ -57,6 +57,7 @@ const modernNames = [
"callees",
"xrefs_to",
"callgraph",
"survey_binary",
];
/** Stateful producer fixture at the real connection seam; no module mocking. */