Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(ghidra): expose terminal-call boundary assumptions
morluto69a8b3a954a8
diff --git a/bridge/ghidra/ReaGhidraBridge.java b/bridge/ghidra/ReaGhidraBridge.javaindex 5da3e1374..498a99e00 100644--- a/bridge/ghidra/ReaGhidraBridge.java+++ b/bridge/ghidra/ReaGhidraBridge.java@@ -377,7 +377,10 @@ public final class ReaGhidraBridge extends HeadlessScript {case "inspect_native_instruction" -> inspectNativeInstruction(request.params);case "resolve_native_call_targets" -> resolveNativeCallTargets(request.params);case "xrefs" -> xrefs(request.params);- case "analyze_function" -> analyzeFunction(request.params);+ case "analyze_function" -> {+ FunctionAnalysisObservation observation = analyzeFunctionObservation(request.params);+ yield functionObservation(observation.dossier(), observation.limitations());+ }case "set_address_name", "set_addresses_names" -> {if (!descriptor.transport.equals("unix-socket"))throw new RequestFailure("method_unavailable", "Windows P0 does not admit database mutation");@@ -652,10 +655,14 @@ public final class ReaGhidraBridge extends HeadlessScript {private JsonElement procedurePseudocode(JsonObject params) throws Exception {requireKeys(params, Set.of("document", "procedure"));requireDocument(params);- String value = decompiledText(- decompile(resolveProcedure(requireString(params, "procedure")))+ Function function = resolveProcedure(requireString(params, "procedure"));+ String value = decompiledText(decompile(function));+ return functionObservation(+ value == null ? JsonNull.INSTANCE : GSON.toJsonTree(value),+ noReturnCallLimitations(+ currentProgram.getListing().getInstructions(function.getBody(), true)+ ));- return value == null ? JsonNull.INSTANCE : GSON.toJsonTree(value);}private JsonElement procedureAssembly(JsonObject params) throws Exception {@@ -663,7 +670,10 @@ public final class ReaGhidraBridge extends HeadlessScript {requireDocument(params);Function function = resolveProcedure(requireString(params, "procedure"));InstructionScan scan = scanInstructions(function, Integer.MAX_VALUE);- return GSON.toJsonTree(renderAssembly(scan.instructions));+ return functionObservation(+ GSON.toJsonTree(renderAssembly(scan.instructions)),+ noReturnCallLimitations(scan.instructions)+ );}private JsonObject readFunctionInstructions(JsonObject params) throws Exception {@@ -681,11 +691,13 @@ public final class ReaGhidraBridge extends HeadlessScript {limitations.add("The fast path does not invoke the decompiler or scan whole-program names and strings.");+ List<String> boundaryLimitations = noReturnCallLimitations(scan.instructions);+ for (String limitation : boundaryLimitations) limitations.add(limitation);JsonObject result = new JsonObject();result.add("procedure", procedureIdentity(function));result.add("instructions", items);result.add("limitations", limitations);- return result;+ return functionObservation(result, boundaryLimitations);}private JsonArray procedureCalls(JsonObject params, boolean callers) throws Exception {@@ -718,7 +730,12 @@ public final class ReaGhidraBridge extends HeadlessScript {result.addProperty("signature", function.getPrototypeString(false, true));result.add("locals", functionLocals(function));result.add("classification", functionClassification(function));- return result;+ return functionObservation(+ result,+ noReturnCallLimitations(+ currentProgram.getListing().getInstructions(function.getBody(), true)+ )+ );}private JsonObject procedureReferences(JsonObject params) throws Exception {@@ -1130,6 +1147,10 @@ public final class ReaGhidraBridge extends HeadlessScript {}private JsonObject analyzeFunction(JsonObject params) throws Exception {+ return analyzeFunctionObservation(params).dossier();+ }++ private FunctionAnalysisObservation analyzeFunctionObservation(JsonObject params) throws Exception {requireKeys(params, Set.of("procedure"));Function function = resolveProcedure(requireString(params, "procedure"));InstructionScan scan = scanInstructions(function, Integer.MAX_VALUE);@@ -1187,12 +1208,16 @@ public final class ReaGhidraBridge extends HeadlessScript {limitations.add("Synthetic Ghidra entry-point references without actionable memory sources are omitted.");+ List<String> boundaryLimitations = noReturnCallLimitations(scan.instructions);+ for (String limitation : boundaryLimitations) {+ limitations.add(limitation);+ }if (decompilation != null && decompilation.getErrorMessage() != null &&!decompilation.getErrorMessage().isBlank()) {limitations.add("Ghidra decompiler diagnostic: " + decompilation.getErrorMessage());}result.add("limitations", limitations);- return result;+ return new FunctionAnalysisObservation(result, boundaryLimitations);}private JsonObject nativeValueFlow(DecompileResults decompilation) throws Exception {@@ -2654,6 +2679,63 @@ public final class ReaGhidraBridge extends HeadlessScript {return new InstructionScan(List.copyOf(instructions), iterator.hasNext());}+ private JsonObject functionObservation(+ JsonElement value,+ List<String> limitations) {+ JsonObject result = new JsonObject();+ result.add("value", value);+ result.add("limitations", GSON.toJsonTree(limitations));+ return result;+ }++ private List<String> noReturnCallLimitations(Iterable<Instruction> instructions)+ throws Exception {+ List<String> limitations = new ArrayList<>();+ for (Instruction instruction : instructions) {+ monitor.checkCancelled();+ if (!instruction.getFlowType().isCall() || !instruction.getFlowType().isTerminal()) {+ continue;+ }+ Address[] destinations = instruction.getFlows();+ StringBuilder limitation = new StringBuilder();+ limitation.append("Ghidra Listing reports a terminal call at ")+ .append(canonicalAddress(instruction.getAddress()));+ if (destinations.length == 0) {+ limitation.append(" with no resolved callee; its no-return basis is unknown.");+ }+ else {+ limitation.append(" to ");+ for (int index = 0; index < destinations.length; index++) {+ if (index > 0) limitation.append(", ");+ Address destination = destinations[index];+ limitation.append(canonicalAddress(destination));+ Function target = currentProgram.getFunctionManager().getFunctionAt(destination);+ if (target == null) {+ limitation.append(" (callee identity unknown)");+ }+ else {+ limitation.append(" ").append(procedureName(target));+ limitation.append(" (external=").append(target.isExternal());+ limitation.append(", thunk=").append(target.isThunk());+ limitation.append(", hasNoReturn=").append(target.hasNoReturn()).append(")");+ }+ }+ limitation.append("; fallthrough is excluded by Ghidra's flow model.");+ Function target = destinations.length == 1+ ? currentProgram.getFunctionManager().getFunctionAt(destinations[0])+ : null;+ if (target != null && target.hasNoReturn()) {+ limitation.append(" This records Ghidra's FunctionManager flag, not an independent verification that the callee cannot return.");+ }+ else {+ limitation.append(" The reason for the terminal flow is not established by this observation.");+ }+ }+ limitations.add(limitation.toString());+ }+ return limitations;+ }+private static String renderAssembly(List<Instruction> instructions) {return String.join("\n", renderAssemblyLines(instructions));}@@ -3483,6 +3565,7 @@ public final class ReaGhidraBridge extends HeadlessScript {private record InventoryItem(Address address, String value, JsonObject facts) {}private record FunctionEntry(Function function, InventoryItem item) {}+ private record FunctionAnalysisObservation(JsonObject dossier, List<String> limitations) {}private record InstructionScan(List<Instruction> instructions, boolean truncated) {}private record SessionDescriptor(String transport,diff --git a/docs/ghidra-provider.md b/docs/ghidra-provider.mdindex af95d0ab4..cdb9e1336 100644--- a/docs/ghidra-provider.md+++ b/docs/ghidra-provider.md@@ -52,6 +52,17 @@ bytes and references.| P-code value flow | Function dossiers include up to 3,000 high-p-code operations, at most 64 inputs per operation, and 12,000 def-use edges. Results identify memory reads/writes, branches, and calls by p-code opcode, and mark decompiler-dead operations. Large results report truncation, an omitted-operation lower bound, and known omitted-input/edge counts. The dossier is an intra-function graph; `trace_native_values` composes derived parameter/argument and return/output dependencies across resolved calls. It does not resolve memory aliasing, call side effects, runtime behavior, persistent state, or business meaning. || Result extent | Function instruction scans and native API boundary observations remain complete. P-code flow is the explicit bounded exception; its count fields distinguish exact retained counts from lower-bound or known-omitted counts. Caller cancellation and provider failures remain distinct. |+Function extents and instruction completeness refer to Ghidra's analyzed body.+An inferred no-return call can terminate that body before subsequent bytes.+Pseudocode, assembly, procedure info, instruction windows, and dossiers report+observed terminal call sites in Evidence limitations, including resolved callee+names, addresses, and FunctionManager flags when available. Instruction windows+and dossiers also retain these warnings in their result limitations. An+unresolved callee or unestablished terminal-flow basis remains explicit. These+observations qualify the analysis; they do not prove that a no-return flag is+incorrect or recover excluded code. Analysis profiles version this observation+contract so older snapshots cannot replay unqualified results.+`npm run verify:ghidra` compiles the versioned C oracle into debug and strippedhost-native targets (x86-64/AArch64 ELF on Linux or Mach-O on macOS), plus a nativeDWARF 4 type-layout object. It proves the admitted operations, external functions, resolved thunks, exports, stripped-namediff --git a/scripts/lib/real-ghidra-large-results.mjs b/scripts/lib/real-ghidra-large-results.mjsindex 5617a1b4a..fa1c5115f 100644--- a/scripts/lib/real-ghidra-large-results.mjs+++ b/scripts/lib/real-ghidra-large-results.mjs@@ -183,7 +183,9 @@ export async function verifyGhidraLargeResults({assert.equal(dossier.procedure.name, "rea_frame_probe");assert.ok(dossier.comments.some(({ text }) => text === comment));assert.ok(- dossierRecord.raw_result.comments.some(({ text }) => text === comment),+ dossierRecord.raw_result.value.comments.some(+ ({ text }) => text === comment,+ ),);const { stdout } = await exec(process.execPath,diff --git a/scripts/verify-real-ghidra-function.mjs b/scripts/verify-real-ghidra-function.mjsindex b9d9c299e..16bb172b6 100644--- a/scripts/verify-real-ghidra-function.mjs+++ b/scripts/verify-real-ghidra-function.mjs@@ -21,6 +21,10 @@ import {} from "./verify-real-ghidra-assertions.mjs";async function functionCall(client, operation, parameters) {+ return (await functionObservationCall(client, operation, parameters)).value;+}++async function functionObservationCall(client, operation, parameters) {const input = parseGhidraFunctionInput(operation, parameters);if (!input.ok) throw input.error;const called = await client.callTool(operation, input.value);@@ -153,6 +157,57 @@ export async function verifyDebugFunctionOperations(const denseSwitchDossier = await functionCall(client, "analyze_function", {procedure: denseSwitchProcedure.address,});+ const terminalProcedure = requireProcedure(+ procedures,+ "rea_ghidra_inventory_terminal_call",+ );+ const terminalObservations = await Promise.all(+ [+ "procedure_info",+ "procedure_assembly",+ "read_function_instructions",+ "procedure_pseudo_code",+ "analyze_function",+ ].map((operation) =>+ functionObservationCall(client, operation, {+ ...(operation === "analyze_function" ? {} : { document: null }),+ procedure: terminalProcedure.address,+ }),+ ),+ );+ const terminalLimitations = terminalObservations.map((result) =>+ result.limitations.find(+ (limitation) =>+ /terminal call at 0x[0-9a-f]+/i.test(limitation) &&+ / to 0x[0-9a-f]+/i.test(limitation) &&+ limitation.includes("abort") &&+ limitation.includes("hasNoReturn=true"),+ ),+ );+ if (+ terminalLimitations.some((limitation) => limitation === undefined) ||+ terminalLimitations.some(+ (limitation) =>+ !limitation.includes("external=") ||+ !limitation.includes("thunk=") ||+ !limitation.includes("fallthrough is excluded") ||+ !limitation.includes("not an independent verification"),+ )+ )+ throw new Error(+ `Ghidra no-return boundary evidence was missing callee, address, or flag provenance: ${JSON.stringify(terminalObservations.map(({ limitations }) => limitations))}`,+ );+ const returningObservation = await functionObservationCall(+ client,+ "procedure_info",+ { document: null, procedure: leaf.address },+ );+ if (+ returningObservation.limitations.some((limitation) =>+ limitation.includes("puts"),+ )+ )+ throw new Error("Ghidra marked an ordinary returning call as terminal");// The debug fixture is compiled -O0, and GCC 16 and later lower dense// switches to compare chains at -O0, so this dossier asserts only its// complete shape; the optimized jump-table variant proves dense jump-table@@ -179,6 +234,8 @@ export async function verifyDebugFunctionOperations(instruction_window: {returned: instructionWindow.instructions.length,},+ terminal_call_limitations: terminalLimitations,+ returning_call_limitations: returningObservation.limitations,cancellation,timeout,concurrency: concurrent,diff --git a/scripts/verify-real-ghidra-windows.mjs b/scripts/verify-real-ghidra-windows.mjsindex 6eb501437..d2bbb511b 100644--- a/scripts/verify-real-ghidra-windows.mjs+++ b/scripts/verify-real-ghidra-windows.mjs@@ -322,7 +322,7 @@ async function functionOperation(operation, parameters) {const result = parseGhidraFunctionResult(operation, called.value);if (!result.ok) throw result.error;observed.add(operation);- return result.value;+ return result.value.value;}function assertSession(session, targetSha256, profileDigest) {diff --git a/src/contracts/functionWorkflowToolContracts.ts b/src/contracts/functionWorkflowToolContracts.tsindex 5ef3f82f2..c738b7927 100644--- a/src/contracts/functionWorkflowToolContracts.ts+++ b/src/contracts/functionWorkflowToolContracts.ts@@ -36,7 +36,7 @@ const functionWorkflow = <Name extends FunctionWorkflowName>(export const FUNCTION_WORKFLOW_TOOL_CONTRACTS = [functionWorkflow("analyze_function",- "Build a dossier for one native function identified by symbol or provider-returned address. Returns identity with complete inclusive body ranges or explicit unknown, provider-specific pseudocode and assembly, comments, calls, references, referenced strings/names, local CFG blocks, and available native API boundary observations.",+ "Build a dossier for one native function identified by symbol or provider-returned address. Returns identity with complete inclusive analyzed body ranges or explicit unknown, provider-specific pseudocode and assembly, comments, calls, references, referenced strings/names, local CFG blocks, and available native API boundary observations. Ghidra terminal-call assumptions that may cut the analyzed body are reported in limitations with available callee identities.",),functionWorkflow("inspect_native_api",diff --git a/src/contracts/officialToolContracts.ts b/src/contracts/officialToolContracts.tsindex 811b66c90..0838e105e 100644--- a/src/contracts/officialToolContracts.ts+++ b/src/contracts/officialToolContracts.ts@@ -144,7 +144,7 @@ export const OFFICIAL_TOOL_CONTRACTS = [),official("procedure_assembly",- "Return assembly for one analyzed procedure identified by symbol or hexadecimal address. Use when pseudocode loses calling-convention or instruction-level detail; output is currently returned as one unpaginated string.",+ "Return assembly for one analyzed procedure identified by symbol or hexadecimal address. Use when pseudocode loses calling-convention or instruction-level detail; output is currently returned as one unpaginated string. Ghidra terminal-call assumptions that may cut the analyzed body are reported in Evidence limitations.",z.object({ procedure, document }),),official(@@ -159,12 +159,12 @@ export const OFFICIAL_TOOL_CONTRACTS = [),official("procedure_info",- "Return provider metadata for one procedure identified by symbol or address: entrypoint, signature, locals, size, block count, and complete inclusive body ranges when observed. Hopper locals preserve observed names and signed stack displacements; source types remain unknown. Body byte count and enclosing span remain distinct; unavailable extent is explicit.",+ "Return provider metadata for one procedure identified by symbol or address: entrypoint, signature, locals, size, block count, and complete inclusive body ranges when observed. Extents reflect the provider's analyzed body; Ghidra terminal-call assumptions that may cut it are reported in Evidence limitations. Hopper locals preserve observed names and signed stack displacements; source types remain unknown. Body byte count and enclosing span remain distinct; unavailable extent is explicit.",z.object({ procedure, document }),),official("read_function_instructions",- "Return every raw instruction for one analyzed procedure. Instruction text is provider-specific.",+ "Return every raw instruction for one analyzed procedure. Instruction text and body extent are provider-specific. Ghidra terminal-call assumptions that may cut the analyzed body are reported in limitations.",functionInstructionInputSchema,),...HOPPER_MEMORY_TOOL_DEFINITIONS.map(({ name, description, inputSchema }) =>@@ -181,7 +181,7 @@ export const OFFICIAL_TOOL_CONTRACTS = [),official("procedure_pseudo_code",- "Decompile one analyzed procedure by symbol name or provider-normalized address. Returns provider-specific pseudocode, never original source or cross-provider text equivalence, and may return null; request procedure_assembly when instruction precision matters.",+ "Decompile one analyzed procedure by symbol name or provider-normalized address. Returns provider-specific pseudocode, never original source or cross-provider text equivalence, and may return null; request procedure_assembly when instruction precision matters. Ghidra no-return assumptions may cut the analyzed body; Evidence limitations report observed terminal calls and available callee identities.",z.object({ procedure, document }),),official(diff --git a/src/ghidra/GhidraAnalysisProfile.ts b/src/ghidra/GhidraAnalysisProfile.tsindex 59113b3b8..36b7d32eb 100644--- a/src/ghidra/GhidraAnalysisProfile.ts+++ b/src/ghidra/GhidraAnalysisProfile.ts@@ -70,6 +70,7 @@ export const resolveGhidraAnalysisProfile = (string_inventory_evidence: "defined-data-coverage-v1",location_resolution: "explicit-address-exact-entry-symbol-first-v3",instruction_flow_evidence: "decoded-return-pcode-v1",+ function_boundary_observations: "ghidra-terminal-call-limitations-v1",process_launch:installation.platform === "win32"? "official-headless-script-v1"diff --git a/src/ghidra/GhidraFunctionValues.test.ts b/src/ghidra/GhidraFunctionValues.test.tsindex a99d304a7..f868d65a0 100644--- a/src/ghidra/GhidraFunctionValues.test.ts+++ b/src/ghidra/GhidraFunctionValues.test.ts@@ -20,7 +20,55 @@ import {ghidraReferenceEdge,} from "../domain/ghidraValues.fixture.js";+const observationOperations: ReadonlySet<GhidraFunctionOperation> = new Set([+ "analyze_function",+ "procedure_assembly",+ "procedure_info",+ "procedure_pseudo_code",+ "read_function_instructions",+]);++// Existing assertions focus on the value schema; this helper builds the current+// bridge envelope and returns its normalized value for those assertions.+const parseFunctionValueFixture = (+ operation: GhidraFunctionOperation,+ value: JsonValue,+) => {+ const wireValue = observationOperations.has(operation)+ ? { value, limitations: [] }+ : value;+ const parsed = parseGhidraFunctionResult(operation, wireValue);+ return parsed.ok ? { ok: true as const, value: parsed.value.value } : parsed;+};+describe("Ghidra function-analysis result values", () => {+ it.each([...observationOperations])(+ "requires the function-observation limitations envelope for %s",+ (operation) => {+ expect(parseGhidraFunctionResult(operation, null)).toMatchObject({+ ok: false,+ error: { _tag: "AnalysisOutputError" },+ });+ },+ );++ it("preserves a named function-observation limitation", () => {+ expect(+ parseGhidraFunctionResult("procedure_pseudo_code", "void f() {}"),+ ).toMatchObject({ ok: false, error: { _tag: "AnalysisOutputError" } });+ const limitation =+ "Ghidra marks a call to external __tls_get_addr terminal; return behavior is not independently verified.";+ expect(+ parseGhidraFunctionResult("procedure_pseudo_code", {+ value: "void f() {}",+ limitations: [limitation],+ }),+ ).toEqual({+ ok: true,+ value: { value: "void f() {}", limitations: [limitation] },+ });+ });+it.each(["reference_kinds_available", "unresolved_calls"])("rejects omitted %s instead of inventing complete reference observations",(field) => {@@ -35,10 +83,10 @@ describe("Ghidra function-analysis result values", () => {Object.entries(output).filter(([key]) => key !== field),);expect(- parseGhidraFunctionResult("procedure_references", output),+ parseFunctionValueFixture("procedure_references", output),).toMatchObject({ ok: true });expect(- parseGhidraFunctionResult("procedure_references", incomplete),+ parseFunctionValueFixture("procedure_references", incomplete),).toMatchObject({ ok: false, error: { _tag: "AnalysisOutputError" } });},);@@ -80,7 +128,7 @@ describe("Ghidra function-analysis result values", () => {);expect(- parseGhidraFunctionResult(+ parseFunctionValueFixture("analyze_function",jsonValueSchema.parse({...dossier,@@ -103,7 +151,7 @@ describe("Ghidra function-analysis result values", () => {if (typeof flow !== "object" || flow === null || Array.isArray(flow))throw new TypeError("Ghidra p-code fixture is invalid");expect(- parseGhidraFunctionResult("analyze_function", {+ parseFunctionValueFixture("analyze_function", {...dossier,native_value_flow: {...flow,@@ -159,7 +207,7 @@ describe("Ghidra compact reference provenance", () => {};for (const reference of [complete, legacy, unknown]) {const expected = output([reference]);- const parsed = parseGhidraFunctionResult(operation, expected);+ const parsed = parseFunctionValueFixture(operation, expected);if (!parsed.ok) throw parsed.error;expect(parsed.value).toEqual(expected);}@@ -179,7 +227,7 @@ describe("Ghidra compact reference provenance", () => {["source", false],] as const) {expect(- parseGhidraFunctionResult(+ parseFunctionValueFixture(operation,output([{ ...compactReference(), [field]: value }]),),@@ -215,7 +263,7 @@ describe("Ghidra jump-table mapping contract", () => {],},];- const parsed = parseGhidraFunctionResult("analyze_function", {+ const parsed = parseFunctionValueFixture("analyze_function", {...dossier,native_api: {...boundary,@@ -255,7 +303,7 @@ describe("Ghidra jump-table mapping contract", () => {throw new TypeError("Ghidra jump-table fixture is unavailable");const { default_targets: omittedDefaults, ...withoutDefaults } = table;expect(omittedDefaults).toHaveLength(1);- const parsed = parseGhidraFunctionResult("analyze_function", {+ const parsed = parseFunctionValueFixture("analyze_function", {...dossier,native_api: {...boundary,@@ -288,7 +336,7 @@ describe("Ghidra jump-table mapping contract", () => {{ target_address: "0x401020", confidence: "high", evidence: [] },]) {expect(- parseGhidraFunctionResult("analyze_function", {+ parseFunctionValueFixture("analyze_function", {...dossier,native_api: {...boundary,@@ -304,7 +352,7 @@ describe("Ghidra function-analysis malformed results", () => {it.each(malformedOutputs())("rejects malformed %s output",(_name, operation, value) => {- expect(parseGhidraFunctionResult(operation, value)).toMatchObject({+ expect(parseFunctionValueFixture(operation, value)).toMatchObject({ok: false,error: { _tag: "AnalysisOutputError" },});@@ -438,7 +486,7 @@ describe("complete Ghidra function body range evidence", () => {body: body(),});it("preserves inclusive disjoint ranges and distinguishes owned bytes from enclosing span", () => {- expect(parseGhidraFunctionResult("procedure_info", info())).toMatchObject({+ expect(parseFunctionValueFixture("procedure_info", info())).toMatchObject({ok: true,value: { body: body(), length: 5 },});@@ -446,7 +494,7 @@ describe("complete Ghidra function body range evidence", () => {it("rejects omitted body evidence instead of accepting a length as complete coverage", () => {const { body: omitted, ...withoutBody } = info();expect(omitted.total_bytes).toBe(5);- expect(parseGhidraFunctionResult("procedure_info", withoutBody).ok).toBe(+ expect(parseFunctionValueFixture("procedure_info", withoutBody).ok).toBe(false,);});@@ -460,14 +508,14 @@ describe("complete Ghidra function body range evidence", () => {contains_entry: false,};expect(- parseGhidraFunctionResult("procedure_info", {+ parseFunctionValueFixture("procedure_info", {...info(),body: empty,length: 0,}).ok,).toBe(false);expect(- parseGhidraFunctionResult("procedure_info", {+ parseFunctionValueFixture("procedure_info", {...info(),classification: { ...ghidraFunctionClassification(), external: true },body: empty,@@ -480,7 +528,7 @@ describe("complete Ghidra function body range evidence", () => {const { body: omitted, ...identity } = ghidraFunctionIdentity();expect(omitted.total_bytes).toBe(6);expect(- parseGhidraFunctionResult("analyze_function", {+ parseFunctionValueFixture("analyze_function", {...dossier,callers: [identity],}).ok,@@ -488,10 +536,10 @@ describe("complete Ghidra function body range evidence", () => {});it("requires body length and Ghidra-specific body provenance", () => {expect(- parseGhidraFunctionResult("procedure_info", { ...info(), length: 18 }).ok,+ parseFunctionValueFixture("procedure_info", { ...info(), length: 18 }).ok,).toBe(false);expect(- parseGhidraFunctionResult("procedure_info", {+ parseFunctionValueFixture("procedure_info", {...info(),body: { ...body(), provenance: "unreviewed" },}).ok,@@ -511,7 +559,7 @@ describe("complete Ghidra function body range evidence", () => {{ ranges: [{ start: "0x401002", end: "0x401000" }] },])("rejects contradictory complete body facts %j", (change) => {expect(- parseGhidraFunctionResult("procedure_info", {+ parseFunctionValueFixture("procedure_info", {...info(),body: { ...body(), ...change },}).ok,diff --git a/src/ghidra/GhidraFunctionValues.ts b/src/ghidra/GhidraFunctionValues.tsindex e56f043f5..8876e31ae 100644--- a/src/ghidra/GhidraFunctionValues.ts+++ b/src/ghidra/GhidraFunctionValues.ts@@ -387,14 +387,54 @@ const resultSchemas = {xrefs: z.array(ghidraCanonicalAddressSchema),} satisfies Readonly<Record<GhidraFunctionOperation, z.ZodType>>;+const functionBoundaryObservationOperations: ReadonlySet<GhidraFunctionOperation> =+ new Set([+ "analyze_function",+ "procedure_assembly",+ "procedure_info",+ "procedure_pseudo_code",+ "read_function_instructions",+ ]);++const functionObservationEnvelope = z.strictObject({+ value: z.unknown(),+ limitations: z.array(z.string()),+});++export interface ParsedGhidraFunctionResult {+ readonly value: JsonValue;+ readonly limitations: readonly string[];+}+/** Require exact, bounded Java-bridge function output before creating Evidence. */export const parseGhidraFunctionResult = (operation: GhidraFunctionOperation,value: JsonValue,-): Result<JsonValue, AnalysisOutputError> => {- const parsed = resultSchemas[operation].safeParse(value);+): Result<ParsedGhidraFunctionResult, AnalysisOutputError> => {+ let observation: {+ readonly value: unknown;+ readonly limitations: readonly string[];+ };+ if (functionBoundaryObservationOperations.has(operation)) {+ const envelope = functionObservationEnvelope.safeParse(value);+ if (!envelope.success)+ return err(+ new AnalysisOutputError(+ operation,+ "Ghidra bridge omitted the function observation envelope",+ { cause: envelope.error },+ ),+ );+ observation = envelope.data;+ } else {+ observation = { value, limitations: [] };+ }+ const parsed = resultSchemas[operation].safeParse(observation.value);return parsed.success- ? ok(jsonValueSchema.parse(parsed.data))+ ? ok({+ value: jsonValueSchema.parse(parsed.data),+ limitations: observation.limitations,+ }): err(new AnalysisOutputError(operation,diff --git a/src/ghidra/GhidraProvider.behavior.test.ts b/src/ghidra/GhidraProvider.behavior.test.tsindex cd623a236..fd0a3f5f0 100644--- a/src/ghidra/GhidraProvider.behavior.test.ts+++ b/src/ghidra/GhidraProvider.behavior.test.ts@@ -562,6 +562,31 @@ describe("Ghidra result projection", () => {});});+ it("projects terminal-call facts from the function bridge into execution limitations", async () => {+ const limitation =+ "Ghidra Listing reports a terminal call at 0x401020 to 0x7f001000 __tls_get_addr (external=true, thunk=false, hasNoReturn=true); fallthrough is excluded by Ghidra's flow model. This records Ghidra's FunctionManager flag, not an independent verification that the callee cannot return.";+ const ghidra = provider(installationHost(), () => ({+ start: () => Promise.resolve(ok(sessionInfo())),+ callTool: () =>+ Promise.resolve(+ ok({ value: "void main() {}", limitations: [limitation] }),+ ),+ close: () => Promise.resolve(ok(null)),+ }));+ const client = await createElfClient(ghidra);+ const execution = await client.execute("procedure_pseudo_code", {+ procedure: "main",+ });+ if (!execution.ok) throw execution.error;+ expect(execution.value.result).toBe("void main() {}");+ expect(execution.value.limitations).toContain(limitation);+ expect(execution.value.rawResult).toEqual({+ value: "void main() {}",+ limitations: [limitation],+ });+ await client.close();+ });+it.each([["invalid_request", "AnalysisInputError"],["not_found", "AnalysisInputError"],diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.tsindex 0af34b380..f659eb12c 100644--- a/src/ghidra/GhidraProviderClient.ts+++ b/src/ghidra/GhidraProviderClient.ts@@ -8,6 +8,7 @@ import {type AnalysisOperation,} from "../application/AnalysisProvider.js";import type { AppConfig } from "../config/types.js";+import type { JsonValue } from "../domain/jsonValue.js";import type { AnalysisProfileCommitment } from "../domain/analysisProfile.js";import type { BinaryTarget } from "../domain/binaryTargetTypes.js";import {@@ -263,16 +264,23 @@ export const createGhidraProviderClient = (input: {config.ghidraStartupTimeoutMs,),);- const result = isGhidraFunctionOperation(operation)- ? parseGhidraFunctionResult(operation, called.value)- : parseGhidraInventoryResult(operation, called.value);- if (!result.ok) return result;- let normalized = result.value;+ let normalized: JsonValue;+ let observationLimitations: readonly string[] = [];+ if (isGhidraFunctionOperation(operation)) {+ const result = parseGhidraFunctionResult(operation, called.value);+ if (!result.ok) return result;+ normalized = result.value.value;+ observationLimitations = result.value.limitations;+ } else {+ const result = parseGhidraInventoryResult(operation, called.value);+ if (!result.ok) return result;+ normalized = result.value;+ }if (operation === "inspect_native_load_image") {const attested = await attestGhidraNativeLoadImage(target,operation,- result.value,+ normalized,client,(failure) =>projectSessionError(@@ -288,7 +296,11 @@ export const createGhidraProviderClient = (input: {createAnalysisExecution(normalized, committedProfile.provider, {rawResult: called.value,analysisProfile: committedProfile,- limitations: [...limitationsFor(operation), ...sessionLimitations],+ limitations: [+ ...limitationsFor(operation),+ ...observationLimitations,+ ...sessionLimitations,+ ],}),);},diff --git a/src/ghidra/GhidraSnapshotCache.test.ts b/src/ghidra/GhidraSnapshotCache.test.tsindex 19f903ea4..a7f30f196 100644--- a/src/ghidra/GhidraSnapshotCache.test.ts+++ b/src/ghidra/GhidraSnapshotCache.test.ts@@ -104,8 +104,13 @@ const fixture = (version = "12.1.4") => {persists_after_close: false,},});+ const value =+ operation === "procedure_pseudo_code" ? dossier.pseudocode : dossier;return ok(- operation === "procedure_pseudo_code" ? dossier.pseudocode : dossier,+ operation === "procedure_pseudo_code" ||+ operation === "analyze_function"+ ? { value, limitations: [] }+ : value,);},close: async () => ok(null),diff --git a/tests/boundary/mcp/ghidraEvidenceMcp.test.ts b/tests/boundary/mcp/ghidraEvidenceMcp.test.tsindex 9fa1f3b97..c28fcca39 100644--- a/tests/boundary/mcp/ghidraEvidenceMcp.test.ts+++ b/tests/boundary/mcp/ghidraEvidenceMcp.test.ts@@ -4,8 +4,98 @@ import { EnhancedTools } from "../../../src/application/EnhancedTools.js";import { connectGhidraMcp, sessionEvidence } from "./ghidraMcpHarness.js";import { functionDossierSchema } from "../../../src/domain/hopperValues.js";import { ghidraFunctionDossier } from "../../../src/domain/ghidraValues.fixture.js";-import { jsonValueSchema } from "../../../src/domain/jsonValue.js";+import {+ jsonValueSchema,+ type JsonValue,+} from "../../../src/domain/jsonValue.js";import { ok } from "../../../src/domain/result.js";+import {+ isGhidraFunctionOperation,+ type GhidraFunctionOperation,+} from "../../../src/ghidra/GhidraFunctionValues.js";++it("retains terminal-call qualifications across function views and snapshot replay", async () => {+ const limitation =+ "Ghidra Listing reports a terminal call at 0x401000 to EXTERNAL:0x20 __tls_get_addr (external=true, thunk=false, hasNoReturn=true); fallthrough is excluded by Ghidra's flow model. This records Ghidra's FunctionManager flag, not an independent verification that the callee cannot return.";+ const dossier = functionDossierSchema.parse(ghidraFunctionDossier());+ dossier.limitations.push(limitation);+ const { signature, locals, ...identity } = dossier.procedure;+ if (!identity.body.available)+ throw new Error("The function fixture must include its analyzed body");+ const values = new Map<GhidraFunctionOperation, JsonValue>([+ ["procedure_pseudo_code", dossier.pseudocode],+ ["procedure_assembly", dossier.assembly.join("\n")],+ [+ "procedure_info",+ {+ name: identity.name,+ entrypoint: identity.address,+ signature,+ locals,+ basicblock_count: dossier.basic_blocks.length,+ length: identity.body.total_bytes,+ classification: identity.classification,+ body: identity.body,+ },+ ],+ [+ "read_function_instructions",+ {+ procedure: identity,+ instructions: dossier.assembly,+ limitations: [limitation],+ },+ ],+ ["analyze_function", jsonValueSchema.parse(dossier)],+ ]);+ const harness = await connectGhidraMcp(+ "ghidra-terminal-call-evidence",+ (operation) => {+ if (!isGhidraFunctionOperation(operation))+ throw new Error(`Unexpected operation: ${operation}`);+ const value = values.get(operation);+ if (value === undefined)+ throw new Error(`Unexpected operation: ${operation}`);+ return Promise.resolve(ok({ value, limitations: [limitation] }));+ },+ );+ try {+ for (const [name, value] of values) {+ const request = {+ name,+ arguments:+ name === "analyze_function"+ ? { procedure: identity.address }+ : { procedure: identity.address, document: "fixture" },+ };+ const reply = await harness.mcp.callTool(request);+ expect(reply.isError, name).not.toBe(true);+ const evidence = sessionEvidence(+ harness.session,+ reply.structuredContent,+ );+ expect(evidence.normalized_result, name).toEqual(value);+ expect(evidence.raw_result, name).toEqual({+ value,+ limitations: [limitation],+ });+ expect(evidence.limitations, name).toContain(limitation);+ expect(evidence.analysis_profile?.parameters).toMatchObject({+ function_boundary_observations: "ghidra-terminal-call-limitations-v1",+ });+ const replay = await harness.session.execute(name, evidence.parameters);+ if (!replay.ok) throw replay.error;+ expect(replay.value.result, name).toEqual(value);+ expect(replay.value.limitations, name).toContain(limitation);+ expect(replay.value.limitations, name).toContainEqual(+ expect.stringContaining("Loaded from a local REA analysis snapshot"),+ );+ }+ expect(harness.calls).toEqual([...values.keys()]);+ } finally {+ await harness.close();+ }+});it("rejects contradictory annotation readback across the provider and MCP boundaries", async () => {const dossier = functionDossierSchema.parse(ghidraFunctionDossier());diff --git a/tests/boundary/mcp/ghidraMcpHarness.ts b/tests/boundary/mcp/ghidraMcpHarness.tsindex cbfbb7019..7e2c3ae73 100644--- a/tests/boundary/mcp/ghidraMcpHarness.ts+++ b/tests/boundary/mcp/ghidraMcpHarness.ts@@ -206,15 +206,19 @@ const resultBuilders = new Map<GhidraOperation, GhidraResultBuilder>([["procedure_callers", () => []],["procedure_info",- () => ({- name: "fixture_main",- entrypoint: "0x401000",- basicblock_count: 1,- length: 6,- signature: "int fixture_main(void)",- locals: [],- classification: ghidraFunctionClassification(),- }),+ () => {+ const identity = ghidraFunctionIdentity();+ return {+ name: "fixture_main",+ entrypoint: "0x401000",+ basicblock_count: 1,+ length: 6,+ signature: "int fixture_main(void)",+ locals: [],+ classification: ghidraFunctionClassification(),+ body: identity.body,+ };+ },],["procedure_pseudo_code", () => "int fixture_main(void) { return 42; }"],[@@ -247,9 +251,23 @@ const resultFor = (const builder = resultBuilders.get(operation);if (builder === undefined)throw new TypeError(`Unexpected Ghidra operation: ${operation}`);- return builder(input, typeof input.limit === "number" ? input.limit : 100);+ const value = builder(+ input,+ typeof input.limit === "number" ? input.limit : 100,+ );+ return functionObservationOperations.has(operation)+ ? { value, limitations: [] }+ : value;};+const functionObservationOperations: ReadonlySet<GhidraOperation> = new Set([+ "analyze_function",+ "procedure_assembly",+ "procedure_info",+ "procedure_pseudo_code",+ "read_function_instructions",+]);+const stringItem = (address: string, value: string): JsonValue => ({address,value,diff --git a/tests/conformance/ghidra/inventory.c b/tests/conformance/ghidra/inventory.cindex 8b57aa1ce..e82c7d9dd 100644--- a/tests/conformance/ghidra/inventory.c+++ b/tests/conformance/ghidra/inventory.c@@ -1,4 +1,5 @@#include <stdio.h>+#include <stdlib.h>volatile int rea_ghidra_inventory_global = 7;@@ -43,6 +44,15 @@ __attribute__((noinline, used)) int rea_ghidra_inventory_leaf(int value) {return value + rea_ghidra_inventory_global;}+// Ghidra's no-return analysis recognizes abort; this function provides a real+// terminal-call boundary while retaining a returning path.+__attribute__((noinline, used)) int rea_ghidra_inventory_terminal_call(+ int should_abort) {+ if (should_abort) abort();+ puts("REA_GHIDRA_TERMINAL_CALL_RETURNED");+ return should_abort;+}+// A reference into the function body can land inside an instruction.__attribute__((used)) const unsigned char *volatile rea_ghidra_interior_pointer =(const unsigned char *)(void *)rea_ghidra_inventory_leaf + 1;