Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
d8b802b
test(mcp): expect trace_feature to report references the provider tru…
nikolay-dementiev Oct 12, 2026
41708b0
fix(mcp): report references a provider truncated in trace_feature
nikolay-dementiev Oct 12, 2026
5c01da3
refactor(ida): report reference truncation whenever the runner observ…
nikolay-dementiev Oct 12, 2026
6160b6e
test(mcp): cover session forwarding, per-target state, native reports…
nikolay-dementiev Oct 12, 2026
142f8ad
test(mcp): format the session forwarding test
nikolay-dementiev Oct 12, 2026
bfcb5af
test(ida): expect headless IDA to resolve containing procedures from …
nikolay-dementiev Oct 12, 2026
99ff05d
test(ida): expect feature tracing and address context to work on head…
nikolay-dementiev Oct 12, 2026
64701e8
test(mcp): expect trace_feature availability to follow the search ope…
nikolay-dementiev Oct 12, 2026
a88a9ea
fix(mcp): derive trace_feature availability from the search operation…
nikolay-dementiev Oct 12, 2026
6c46908
feat(ida): resolve containing procedures and report the admitted prog…
nikolay-dementiev Oct 12, 2026
4c5e944
docs(ida): describe containing procedures, the admitted document and …
nikolay-dementiev Oct 12, 2026
4c315fe
test(ida): verify containing procedures, the admitted document and fe…
nikolay-dementiev Oct 12, 2026
5ebae47
docs(testing): list the headless IDA workflows the real lane verifies
nikolay-dementiev Oct 12, 2026
29b72eb
test(ida): make each survey failure case isolate a single defect
nikolay-dementiev Oct 12, 2026
aea084d
test(ida): pin large addresses, segment order, document identity, att…
nikolay-dementiev Oct 12, 2026
48e012d
test(mcp): expect a repeated reference source to be resolved once in …
nikolay-dementiev Oct 12, 2026
72f12e1
fix(mcp): resolve the containing procedure of a repeated reference so…
nikolay-dementiev Oct 12, 2026
0d68088
test(ida): trace the fixture procedure and derive probe addresses fro…
nikolay-dementiev Oct 12, 2026
56a1f6f
Merge remote-tracking branch 'upstream/main' into feat/trace-feature-…
nikolay-dementiev Oct 13, 2026
86bec61
test(process): format processCaptureLifecycle.test.ts after the merge
nikolay-dementiev Oct 13, 2026
b39c768
test(ida): declare the alignment each synthetic universal slice offse…
nikolay-dementiev Oct 13, 2026
fa24661
Merge branch 'feat/trace-feature-xref-coverage' into feat/ida-contain…
nikolay-dementiev Oct 13, 2026
172464e
Merge remote-tracking branch 'upstream/main' into feat/ida-containing…
nikolay-dementiev Oct 13, 2026
d3507f5
refactor(ida): move the real lane's feature trace assertions into a h…
nikolay-dementiev Oct 13, 2026
a7b1fe3
test(ida): expect the real lane's feature trace check to accept refer…
nikolay-dementiev Oct 13, 2026
b472d51
fix(ida): check each trace reference against its own matched address …
nikolay-dementiev Oct 13, 2026
e34afbf
test(ida): pin that the new operations reject a document other than t…
nikolay-dementiev Oct 13, 2026
2808af0
Merge remote-tracking branch 'upstream/main' into feat/trace-feature-…
nikolay-dementiev Oct 13, 2026
4bcef24
Merge branch 'feat/trace-feature-xref-coverage' into feat/ida-contain…
nikolay-dementiev Oct 13, 2026
a66eaef
Merge remote-tracking branch 'upstream/main' into feat/ida-containing…
nikolay-dementiev Oct 13, 2026
b4fc393
refactor(ida): move the real lane's mapped non-function probe into a …
nikolay-dementiev Oct 13, 2026
51c3832
test(ida): expect the real lane's mapped data probe to skip strings i…
nikolay-dementiev Oct 13, 2026
f82873c
fix(ida): try the target's strings in order for the mapped non-functi…
nikolay-dementiev Oct 13, 2026
5856c17
test(ida): declare the real lane helper types for the verifier tests
nikolay-dementiev Oct 13, 2026
6d0ba6e
test(ida): expect the real lane to reject a listed string that resolv…
nikolay-dementiev Oct 13, 2026
1bc928a
fix(ida): fail the real lane when a listed string resolves as unmapped
nikolay-dementiev Oct 13, 2026
a7948f3
Merge remote-tracking branch 'upstream/main' into feat/trace-feature-…
nikolay-dementiev Oct 13, 2026
36d990c
Merge branch 'feat/trace-feature-xref-coverage' into feat/ida-contain…
nikolay-dementiev Oct 13, 2026
cbbee5a
Merge branch 'main' of https://github.com/morluto/rea into feat/trace…
nikolay-dementiev Oct 13, 2026
23cac82
Merge branch 'feat/trace-feature-xref-coverage' into feat/ida-contain…
nikolay-dementiev Oct 13, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/ida-provider.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,6 +126,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.
Expand Down
4 changes: 3 additions & 1 deletion docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -661,7 +661,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.
Expand Down
9 changes: 9 additions & 0 deletions scripts/lib/ida-feature-trace.d.mts
Original file line number Diff line number Diff line change
@@ -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 changes: 52 additions & 0 deletions scripts/lib/ida-feature-trace.mjs
Original file line number Diff line number Diff line change
@@ -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;
}
61 changes: 60 additions & 1 deletion scripts/verify-real-ida.mjs
Original file line number Diff line number Diff line change
@@ -1,12 +1,16 @@
#!/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";
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";
Expand Down Expand Up @@ -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.",
Expand Down
11 changes: 11 additions & 0 deletions src/application/AnalysisProvider.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
}
Expand All @@ -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;
}
Expand Down Expand Up @@ -103,6 +111,9 @@ export function createAnalysisExecution(
options.relationshipCoverage,
),
}),
...(options.referencesTruncated === undefined
? {}
: { referencesTruncated: options.referencesTruncated }),
locations: [...(options.locations ?? [])],
subject: options.subject ?? null,
};
Expand Down
68 changes: 68 additions & 0 deletions src/application/CapabilityInventory.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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" });
});
});
4 changes: 2 additions & 2 deletions src/application/CapabilityInventory.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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",
],
Expand Down
Loading
Loading