diff --git a/bridge/ghidra/ReaGhidraBridge.java b/bridge/ghidra/ReaGhidraBridge.java index f91f003e4..e184dc206 100644 --- a/bridge/ghidra/ReaGhidraBridge.java +++ b/bridge/ghidra/ReaGhidraBridge.java @@ -81,6 +81,7 @@ import ghidra.program.model.listing.Function; import ghidra.program.model.listing.FunctionIterator; import ghidra.program.model.listing.Instruction; import ghidra.program.model.listing.InstructionIterator; +import ghidra.program.model.listing.Listing; import ghidra.program.model.listing.Variable; import ghidra.program.model.mem.MemoryBlock; import ghidra.program.model.mem.MemoryBlockSourceInfo; @@ -405,7 +406,9 @@ public final class ReaGhidraBridge extends HeadlessScript { case "xrefs" -> xrefs(request.params); case "analyze_function" -> { FunctionAnalysisObservation observation = analyzeFunctionObservation(request.params); - yield functionObservation(observation.dossier(), observation.limitations()); + JsonObject result = functionObservation(observation.dossier(), observation.limitations()); + result.add("relationship_coverage", observation.relationshipCoverage()); + yield result; } case "set_address_name", "set_addresses_names" -> { if (!descriptor.transport.equals("unix-socket")) @@ -1016,12 +1019,19 @@ public final class ReaGhidraBridge extends HeadlessScript { for (Function item : ordered) { result.add(canonicalAddress(item.getEntryPoint())); } - return functionObservation( - result, - noReturnCallLimitations( + if (callers) { + JsonObject observation = functionObservation(result, noReturnCallLimitations( currentProgram.getListing().getInstructions(function.getBody(), true) - ) + )); + observation.add("relationship_coverage", callRelationshipCoverage(null, + unrepresentedIncomingCalls(function, observed))); + monitor.checkCancelled(); + return observation; + } + CallBoundaryObservation calls = callBoundaryObservation( + function, currentProgram.getListing().getInstructions(function.getBody(), true), observed, false, null ); + return callRelationshipObservation(result, calls); } private JsonObject procedureInfo(JsonObject params) throws Exception { @@ -1071,18 +1081,10 @@ public final class ReaGhidraBridge extends HeadlessScript { result.addProperty("direction", direction); result.add("references", edges); result.addProperty("reference_kinds_available", true); - JsonArray unresolvedCalls = new JsonArray(); - if (direction.equals("outgoing")) for (Instruction instruction : scanInstructions(function, Integer.MAX_VALUE).instructions) { - if (!instruction.getFlowType().isCall()) continue; - boolean resolved = false; - for (Reference reference : instruction.getReferencesFrom()) if (reference.getReferenceType().isCall()) resolved = true; - if (!resolved) { - JsonObject site = new JsonObject(); - site.addProperty("address", canonicalAddress(instruction.getAddress())); - site.addProperty("reason", "Instruction decoder identifies a call but ReferenceManager supplies no call destination"); - unresolvedCalls.add(site); - } - } + JsonArray unresolvedCalls = direction.equals("outgoing") + ? callBoundaryObservation( + function, currentProgram.getListing().getInstructions(function.getBody(), true), null, true, references + ).unresolvedCalls() : new JsonArray(); result.add("unresolved_calls", unresolvedCalls); return result; } @@ -1490,16 +1492,28 @@ public final class ReaGhidraBridge extends HeadlessScript { InstructionScan scan = scanInstructions(function, Integer.MAX_VALUE); DecompileResults decompilation = decompile(function); String pseudocode = decompiledText(decompilation); - List incomingReferences = collectReferences(function, "incoming") - .stream() + JsonObject availability = new JsonObject(); + availability.add("pseudocode", facetAvailability( + pseudocode != null, + function.isExternal() ? "Ghidra does not decompile external functions." + : function.getBody().isEmpty() ? "Ghidra has no function body to decompile." + : "Ghidra completed decompilation without returning pseudocode." + )); + if (pseudocode == null) { + pseudocode = ""; + } + List bodyIncoming = collectReferences(function, "incoming"); + List incomingReferences = bodyIncoming.stream() .filter(reference -> !function.getBody().contains(reference.getFromAddress())) .toList(); List outgoingReferences = collectReferences(function, "outgoing"); JsonArray incoming = referenceEdges(incomingReferences); JsonArray outgoing = referenceEdges(outgoingReferences); - JsonArray comments = comments(scan.instructions); - JsonArray callers = procedureIdentities(function.getCallingFunctions(monitor)); - JsonArray callees = procedureIdentities(function.getCalledFunctions(monitor)); + JsonArray comments = comments(function); + Set callerFunctions = function.getCallingFunctions(monitor); + JsonArray callers = procedureIdentities(callerFunctions); + Set calleeFunctions = function.getCalledFunctions(monitor); + JsonArray callees = procedureIdentities(calleeFunctions); JsonArray referencedStrings = referencedStrings(outgoingReferences); JsonArray referencedNames = referencedNames(outgoingReferences); JsonArray blocks = basicBlockValues(function); @@ -1511,7 +1525,7 @@ public final class ReaGhidraBridge extends HeadlessScript { procedure.add("locals", functionLocals(function)); JsonObject result = new JsonObject(); result.add("procedure", procedure); - result.addProperty("pseudocode", pseudocode == null ? "" : pseudocode); + result.addProperty("pseudocode", pseudocode); result.add("assembly", assembly); result.add("comments", comments); result.add("callers", callers); @@ -1520,20 +1534,6 @@ public final class ReaGhidraBridge extends HeadlessScript { result.add("outgoing_references", outgoing); result.add("referenced_strings", referencedStrings); result.add("referenced_names", referencedNames); - JsonObject facets = new JsonObject(); - JsonObject pseudocodeAvailability = new JsonObject(); - pseudocodeAvailability.addProperty("available", pseudocode != null); - if (pseudocode == null) { - pseudocodeAvailability.addProperty("reason", "Ghidra did not supply pseudocode."); - } - facets.add("pseudocode", pseudocodeAvailability); - for (String facet : List.of("assembly", "comments", "callers", "callees", - "references", "strings_names", "cfg")) { - JsonObject available = new JsonObject(); - available.addProperty("available", true); - facets.add(facet, available); - } - result.add("facet_availability", facets); boolean swift = swiftProgram(); boolean aarch64 = currentProgram.getLanguageID().getIdAsString().startsWith("AARCH64:"); SwiftStringLiteralDecode swiftLiterals = swift && aarch64 ? swiftStringLiterals(function) : null; @@ -1547,6 +1547,15 @@ public final class ReaGhidraBridge extends HeadlessScript { nativeApiBoundary(function, decompilation) ); result.add("native_value_flow", nativeValueFlow(decompilation)); + // Successful full queries distinguish collected empty sets from missing facts. + // Availability does not claim that Ghidra resolved every runtime relationship. + for (String facet : List.of("comments", "callers", "callees", "references", "strings_names", "cfg")) { + availability.add(facet, facetAvailability(true, null)); + } + availability.add("assembly", facetAvailability( + !scan.truncated(), "The function instruction scan was truncated." + )); + result.add("facet_availability", availability); JsonArray limitations = new JsonArray(); limitations.add( "Unresolved computed or indirect flows without target addresses are not represented as reference edges." @@ -1574,8 +1583,10 @@ public final class ReaGhidraBridge extends HeadlessScript { "Swift String literal decoding is implemented for AArch64 register pairs only; no Swift literals were decoded for this architecture." ); } - List boundaryLimitations = noReturnCallLimitations(scan.instructions); - for (String limitation : boundaryLimitations) { + CallBoundaryObservation calls = callBoundaryObservation( + function, scan.instructions, calleeFunctions, true, outgoingReferences); + result.add("unresolved_calls", calls.unresolvedCalls()); + for (String limitation : calls.limitations()) { limitations.add(limitation); } if (decompilation != null && decompilation.getErrorMessage() != null && @@ -1583,7 +1594,14 @@ public final class ReaGhidraBridge extends HeadlessScript { limitations.add("Ghidra decompiler diagnostic: " + decompilation.getErrorMessage()); } result.add("limitations", limitations); - return new FunctionAnalysisObservation(result, boundaryLimitations); + monitor.checkCancelled(); + int missingCallers = 0; + for (Reference reference : bodyIncoming) { + monitor.checkCancelled(); + if (unrepresentedCaller(reference, callerFunctions)) missingCallers++; + } + return new FunctionAnalysisObservation(result, calls.limitations(), + callRelationshipCoverage(calls, missingCallers)); } private JsonObject nativeValueFlow(DecompileResults decompilation) throws Exception { @@ -3287,54 +3305,202 @@ public final class ReaGhidraBridge extends HeadlessScript { return result; } + private static JsonObject facetAvailability(boolean available, String reason) { + JsonObject result = new JsonObject(); + result.addProperty("available", available); + if (!available) result.addProperty("reason", reason); + return result; + } + + private JsonObject callRelationshipObservation(JsonElement value, CallBoundaryObservation calls) + throws Exception { + monitor.checkCancelled(); + JsonObject result = functionObservation(value, calls.limitations()); + result.add("relationship_coverage", callRelationshipCoverage(calls, null)); + return result; + } + + private static JsonObject callRelationshipCoverage( + CallBoundaryObservation calls, Integer missingCallers) { + JsonObject coverage = completeResolvedCallCoverage(); + Integer omitted = calls == null ? null : calls.unrepresentedCalleeCalls(); + JsonArray directions = new JsonArray(); + if (missingCallers != null && missingCallers > 0) directions.add("callers"); + String callerLimitation = missingCallers != null && missingCallers > 0 + ? "Ghidra's caller inventory omits sources of " + missingCallers + + " call reference(s) into this function's body." : null; + if ((calls != null && omitted == null) || (calls == null && missingCallers == null)) { + coverage.addProperty("status", "unknown"); + String reason = calls == null ? "No call inventory was examined." + : "The callee inventory was not examined alongside decoded call targets."; + coverage.addProperty("reason", reason + (callerLimitation == null ? "" : " " + callerLimitation)); + if (calls == null && missingCallers == null) directions.add("callers"); + directions.add("callees"); + coverage.add("limited_directions", directions); + return coverage; + } + JsonArray limitations = new JsonArray(); + if (callerLimitation != null) limitations.add(callerLimitation); + if (omitted != null && omitted > 0) { + limitations.add("Ghidra's callee inventory omits targets of " + omitted + + " call reference(s) or decoded call(s) without destinations."); + directions.add("callees"); + } + if (!limitations.isEmpty()) { + coverage.addProperty("status", "partial"); + coverage.add("limitations", limitations); + coverage.add("limited_directions", directions); + } + return coverage; + } + + private static JsonObject completeResolvedCallCoverage() { + JsonObject coverage = new JsonObject(); + coverage.addProperty("status", "complete"); + JsonArray diagnostics = new JsonArray(); + diagnostics.add( + "Only resolved Ghidra call references are returned; unresolved computed or indirect calls remain unknown, while function classifications distinguish thunks and externals." + ); + coverage.add("diagnostics", diagnostics); + return coverage; + } + + private boolean unrepresentedCaller(Reference reference, Set callers) { + if (!reference.getReferenceType().isCall()) return false; + Function caller = containingFunction(reference.getFromAddress()); + return caller == null || !callers.contains(caller); + } + + private int unrepresentedIncomingCalls(Function function, Set callers) + throws Exception { + int[] omitted = { 0 }; + visitReferences(function, "incoming", reference -> { + if (unrepresentedCaller(reference, callers)) omitted[0]++; + }); + return omitted[0]; + } + private List noReturnCallLimitations(Iterable instructions) throws Exception { List 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()); + String limitation = terminalCallLimitation(instruction); + if (limitation != null) limitations.add(limitation); } return limitations; } + private CallBoundaryObservation callBoundaryObservation( + Function function, Iterable instructions, Set returnedCallees, + boolean includeUnresolvedSites, List observedReferences) + throws Exception { + List limitations = new ArrayList<>(); + CallBoundaryReferences calls = new CallBoundaryReferences(returnedCallees, includeUnresolvedSites); + if (observedReferences == null) visitReferences(function, "outgoing", calls::observe); + else for (Reference reference : observedReferences) { + monitor.checkCancelled(); + calls.observe(reference); + } + for (Instruction instruction : instructions) { + monitor.checkCancelled(); + String limitation = terminalCallLimitation(instruction); + if (limitation != null) limitations.add(limitation); + if (!instruction.getFlowType().isCall()) continue; + boolean destination = false; + for (Reference reference : instruction.getReferencesFrom()) { + if (!reference.getReferenceType().isCall()) continue; + destination = true; + break; + } + if (!destination) { + calls.unrepresented++; + calls.unresolved(instruction.getAddress(), + "Instruction decoder identifies a call but ReferenceManager supplies no call destination"); + } + } + return new CallBoundaryObservation(List.copyOf(limitations), + returnedCallees == null ? null : calls.unrepresented, calls.unresolvedCalls()); + } + + private final class CallBoundaryReferences { + private final Set returnedCallees; + private final TreeMap unresolved; + private int unrepresented; + + CallBoundaryReferences(Set returnedCallees, boolean includeUnresolvedSites) { + this.returnedCallees = returnedCallees; + unresolved = includeUnresolvedSites ? new TreeMap<>() : null; + } + + void observe(Reference reference) { + if (!reference.getReferenceType().isCall()) return; + // Reference identity follows the same containing-function owner as referenceEdge. + Function target = containingFunction(reference.getToAddress()); + if (returnedCallees != null && (target == null || !returnedCallees.contains(target))) + unrepresented++; + if (target == null) unresolved(reference.getFromAddress(), + "A call destination has no known containing Ghidra procedure"); + } + + void unresolved(Address address, String reason) { + if (unresolved != null) unresolved.put(address, reason); + } + + JsonArray unresolvedCalls() { + if (unresolved == null) return null; + JsonArray result = new JsonArray(); + for (var item : unresolved.entrySet()) { + JsonObject site = new JsonObject(); + site.addProperty("address", canonicalAddress(item.getKey())); + site.addProperty("reason", item.getValue()); + result.add(site); + } + return result; + } + } + + private String terminalCallLimitation(Instruction instruction) { + if (!instruction.getFlowType().isCall() || !instruction.getFlowType().isTerminal()) + return null; + 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."); + } + } + return limitation.toString(); + } + private static String renderAssembly(List instructions) { return String.join("\n", renderAssemblyLines(instructions)); } @@ -3358,15 +3524,27 @@ public final class ReaGhidraBridge extends HeadlessScript { private List collectReferences( Function function, String direction) throws Exception { + TreeMap observed = new TreeMap<>(); + visitReferences(function, direction, reference -> addReference(observed, reference)); + List result = new ArrayList<>(observed.values()); + result.sort(REFERENCE_ORDER); + return result; + } + + @FunctionalInterface + private interface ReferenceVisitor { + void accept(Reference reference) throws Exception; + } + + private void visitReferences(Function function, String direction, ReferenceVisitor visitor) + throws Exception { // References can target instruction interiors or originate in embedded // data. Use actual body ownership, including an external's exact entry. - AddressSet scope = new AddressSet(function.getBody()); - scope.add(function.getEntryPoint()); + AddressSet scope = functionObservationScope(function); boolean outgoing = direction.equals("outgoing"); AddressIterator addresses = outgoing ? currentProgram.getReferenceManager().getReferenceSourceIterator(scope, true) : currentProgram.getReferenceManager().getReferenceDestinationIterator(scope, true); - TreeMap observed = new TreeMap<>(); while (addresses.hasNext()) { monitor.checkCancelled(); Address address = addresses.next(); @@ -3374,7 +3552,7 @@ public final class ReaGhidraBridge extends HeadlessScript { for (Reference reference : currentProgram.getReferenceManager() .getReferencesFrom(address)) { monitor.checkCancelled(); - addReference(observed, reference); + if (!reference.isEntryPointReference()) visitor.accept(reference); } } else { @@ -3382,19 +3560,14 @@ public final class ReaGhidraBridge extends HeadlessScript { .getReferencesTo(address); while (iterator.hasNext()) { monitor.checkCancelled(); - addReference(observed, iterator.next()); + Reference reference = iterator.next(); + if (!reference.isEntryPointReference()) visitor.accept(reference); } } } - List result = new ArrayList<>(observed.values()); - result.sort(REFERENCE_ORDER); - return result; } private static void addReference(TreeMap observed, Reference reference) { - if (reference.isEntryPointReference()) { - return; - } String key = canonicalAddress(reference.getFromAddress()) + "\u0000" + canonicalAddress(reference.getToAddress()) + "\u0000" + reference.getReferenceType().getName() + "\u0000" + @@ -3403,6 +3576,12 @@ public final class ReaGhidraBridge extends HeadlessScript { observed.putIfAbsent(key, reference); } + private static AddressSet functionObservationScope(Function function) { + AddressSet scope = new AddressSet(function.getBody()); + scope.add(function.getEntryPoint()); + return scope; + } + private JsonArray referenceEdges(List references) { JsonArray result = new JsonArray(); for (Reference reference : references) { @@ -3556,23 +3735,28 @@ public final class ReaGhidraBridge extends HeadlessScript { return result; } - private static JsonArray comments(List instructions) { + private JsonArray comments(Function function) throws Exception { + Listing listing = currentProgram.getListing(); + AddressSet scope = functionObservationScope(function); + AddressIterator addresses = listing.getCommentAddressIterator(scope, true); TreeMap observed = new TreeMap<>(); - for (Instruction instruction : instructions) { + while (addresses.hasNext()) { + monitor.checkCancelled(); + Address address = addresses.next(); for (CommentType type : CommentType.values()) { - String text = instruction.getComment(type); + String text = listing.getComment(type, address); if (text == null || text.isEmpty()) { continue; } String kind = type == CommentType.EOL ? "inline" : "comment"; JsonObject item = new JsonObject(); - item.addProperty("address", canonicalAddress(instruction.getAddress())); + item.addProperty("address", canonicalAddress(address)); item.addProperty("kind", kind); item.addProperty("text", text); - String key = canonicalAddress(instruction.getAddress()) + "\u0000" + + String key = canonicalAddress(address) + "\u0000" + kind + "\u0000" + type.name() + "\u0000" + text; observed.put(key, item); - } + } } JsonArray result = new JsonArray(); observed.values().forEach(result::add); @@ -4508,7 +4692,8 @@ public final class ReaGhidraBridge extends HeadlessScript { private record InventoryItem(Address address, String value, JsonObject facts) {} private record AddressNameRequest(String inputAddress, Address address, String name) {} private record FunctionEntry(Function function, InventoryItem item) {} - private record FunctionAnalysisObservation(JsonObject dossier, List limitations) {} + private record FunctionAnalysisObservation(JsonObject dossier, List limitations, JsonObject relationshipCoverage) {} + private record CallBoundaryObservation(List limitations, Integer unrepresentedCalleeCalls, JsonArray unresolvedCalls) {} private record SwiftStringLiteralDecode(JsonArray literals, JsonArray omissions) {} private record SwiftLiteralLayout( String representation, diff --git a/scripts/lib/native-value-e2e.mjs b/scripts/lib/native-value-e2e.mjs index d329bc822..916533a87 100644 --- a/scripts/lib/native-value-e2e.mjs +++ b/scripts/lib/native-value-e2e.mjs @@ -215,6 +215,27 @@ async function verifyNativeValueAdapters( const functionEvidence = parseEvidence(analyzed.structuredContent); assert.equal(functionEvidence.operation, "analyze_function"); assert.equal(functionEvidence.provider.id, "ghidra"); + assert.deepEqual( + functionEvidence.normalized_result.facet_availability, + Object.fromEntries( + [ + "pseudocode", + "assembly", + "comments", + "callers", + "callees", + "references", + "strings_names", + "cfg", + ].map((facet) => [facet, { available: true }]), + ), + ); + assert.equal(functionEvidence.relationship_coverage?.status, "complete"); + assert.ok( + functionEvidence.relationship_coverage.diagnostics.some((diagnostic) => + diagnostic.includes("indirect calls remain unknown"), + ), + ); const functionProfile = analysisProfileSchema.parse( functionEvidence.analysis_profile, ); @@ -247,6 +268,7 @@ async function verifyNativeValueAdapters( assert.ok( comparisonEvidence.evidence_links.includes(functionEvidence.evidence_id), ); + await verifyUnresolvedCallEvidence(client); const bundle = await client.callTool({ name: "get_evidence_bundle", arguments: {}, @@ -307,3 +329,63 @@ async function verifyNativeValueAdapters( unknowns: cliGraph.unknowns.length, }; } + +async function verifyUnresolvedCallEvidence(client) { + const inventory = await client.callTool({ + name: "list_procedures", + arguments: {}, + }); + assert.notEqual(inventory.isError, true, JSON.stringify(inventory)); + const procedures = parseEvidence( + inventory.structuredContent, + ).normalized_result; + const indirect = procedures.find((item) => + item.value.endsWith("rea_ghidra_inventory_indirect"), + ); + const leaf = procedures.find((item) => + item.value.endsWith("rea_ghidra_inventory_leaf"), + ); + assert.ok( + indirect && leaf, + "Source fixture lacks the unresolved callback and its possible target", + ); + const analyzed = await client.callTool( + { name: "analyze_function", arguments: { procedure: indirect.address } }, + { timeout: 180000 }, + ); + assert.notEqual(analyzed.isError, true, JSON.stringify(analyzed)); + const evidence = parseEvidence(analyzed.structuredContent); + assert.equal(evidence.relationship_coverage?.status, "partial"); + assert.ok(evidence.normalized_result.unresolved_calls.length > 0); + const traced = await client.callTool( + { + name: "trace_call_path", + arguments: { + start: indirect.address, + goal: leaf.address, + direction: "forward", + }, + }, + { timeout: 180000 }, + ); + assert.notEqual(traced.isError, true, JSON.stringify(traced)); + const trace = parseEvidence(traced.structuredContent).normalized_result; + assert.equal(trace.goal_status, "unknown"); + assert.equal(trace.truncated, true); + assert.ok(trace.residual_unknowns.length > 0); + const compared = await client.callTool( + { + name: "compare_functions", + arguments: { + left: analyzed.structuredContent, + right: analyzed.structuredContent, + }, + }, + { timeout: 180000 }, + ); + assert.notEqual(compared.isError, true, JSON.stringify(compared)); + assert.equal( + parseEvidence(compared.structuredContent).normalized_result.status, + "unknown", + ); +} diff --git a/scripts/lib/real-ghidra-boundaries.mjs b/scripts/lib/real-ghidra-boundaries.mjs index c2347dde1..54376c389 100644 --- a/scripts/lib/real-ghidra-boundaries.mjs +++ b/scripts/lib/real-ghidra-boundaries.mjs @@ -136,7 +136,7 @@ export async function verifyGhidraBoundaries( assert.deepEqual(externalDossier.callees, []); assert.deepEqual(externalDossier.facet_availability.pseudocode, { available: false, - reason: "Ghidra did not supply pseudocode.", + reason: "Ghidra does not decompile external functions.", }); for (const facet of [ "assembly", diff --git a/src/domain/callPath.test.ts b/src/domain/callPath.test.ts index 80a260ac3..048cb63b4 100644 --- a/src/domain/callPath.test.ts +++ b/src/domain/callPath.test.ts @@ -337,6 +337,42 @@ describe("call path topology and capacity", () => { }); }); +describe("directional call relationship coverage", () => { + it.each([ + { + directions: ["callers"] as ["callers"], + status: "not_found", + exhaustive: true, + }, + { + directions: ["callees"] as ["callees"], + status: "unknown", + exhaustive: false, + }, + { + directions: ["callers", "callees"] as ["callers", "callees"], + status: "unknown", + exhaustive: false, + }, + ])( + "uses $directions coverage for the forward search", + ({ directions, status, exhaustive }) => { + const limitation = "The inventory omitted a reference."; + const relationshipCoverage: RelationshipCoverage = { + status: "partial", + limitations: [limitation], + limited_directions: directions, + }; + const result = run([ + observe("0x1000", ["0x2000"], "rea-workflow", { relationshipCoverage }), + observe("0x2000", [], "rea-workflow", { relationshipCoverage }), + ]); + expect(result).toMatchObject({ status, search_scope: { exhaustive } }); + expect(result.limitations).toContain(limitation); + }, + ); +}); + describe("explicit call relationship coverage", () => { it("accumulates 150,000 partial reasons without argument-stack exhaustion", () => { const result = run([ diff --git a/src/domain/callPath.ts b/src/domain/callPath.ts index 3ffbc2356..65524fbc2 100644 --- a/src/domain/callPath.ts +++ b/src/domain/callPath.ts @@ -10,7 +10,7 @@ import { parseFunctionEvidence, type FunctionSnapshot, } from "./functionDossierEvidence.js"; -import { isCallerOnlyUnknownCoverage } from "./functionCallCoverage.js"; +import { isCallerOnlyIncompleteCoverage } from "./functionCallCoverage.js"; import { compareUnicodeCodePoints } from "./unicodeCodePointOrder.js"; /** Minimal directed caller-to-callee adjacency for call-path search. */ @@ -268,7 +268,7 @@ const inspectSearch = ({ coverage === null ? snapshot.limitations.length > 0 : coverage.status !== "complete" && - !isCallerOnlyUnknownCoverage(coverage) + !isCallerOnlyIncompleteCoverage(coverage) ) incompleteExpandedCoverage = true; } else if (node === goal) { diff --git a/src/domain/functionCallCoverage.test.ts b/src/domain/functionCallCoverage.test.ts index 6fd3fb045..543f6ca92 100644 --- a/src/domain/functionCallCoverage.test.ts +++ b/src/domain/functionCallCoverage.test.ts @@ -2,7 +2,7 @@ import { describe, expect, it } from "vitest"; import { combineFunctionRelationshipCoverage, - isCallerOnlyUnknownCoverage, + isCallerOnlyIncompleteCoverage, } from "./functionCallCoverage.js"; import type { RelationshipCoverage } from "./relationshipCoverage.js"; @@ -22,14 +22,14 @@ const cappedCallees: RelationshipCoverage = { }; const complete: RelationshipCoverage = { status: "complete" }; -describe("isCallerOnlyUnknownCoverage", () => { +describe("isCallerOnlyIncompleteCoverage", () => { it("detects unknown callers beside complete callees", () => { const combined = combineFunctionRelationshipCoverage( unknownCallers, complete, ); expect(combined.status).toBe("unknown"); - expect(isCallerOnlyUnknownCoverage(combined)).toBe(true); + expect(isCallerOnlyIncompleteCoverage(combined)).toBe(true); }); it("rejects unknown callees beside complete callers", () => { @@ -37,7 +37,7 @@ describe("isCallerOnlyUnknownCoverage", () => { complete, unknownCallees, ); - expect(isCallerOnlyUnknownCoverage(combined)).toBe(false); + expect(isCallerOnlyIncompleteCoverage(combined)).toBe(false); }); it("rejects unknown coverage on both sides", () => { @@ -45,7 +45,7 @@ describe("isCallerOnlyUnknownCoverage", () => { unknownCallers, unknownCallees, ); - expect(isCallerOnlyUnknownCoverage(combined)).toBe(false); + expect(isCallerOnlyIncompleteCoverage(combined)).toBe(false); }); it("rejects unknown callers beside IDA-capped callees", () => { @@ -54,11 +54,37 @@ describe("isCallerOnlyUnknownCoverage", () => { cappedCallees, ); expect(combined.status).toBe("unknown"); - expect(isCallerOnlyUnknownCoverage(combined)).toBe(false); + expect(isCallerOnlyIncompleteCoverage(combined)).toBe(false); }); it("rejects complete coverage", () => { const combined = combineFunctionRelationshipCoverage(complete, complete); - expect(isCallerOnlyUnknownCoverage(combined)).toBe(false); + expect(isCallerOnlyIncompleteCoverage(combined)).toBe(false); + }); + + it("retains caller-only partial coverage without relying on limitation wording", () => { + const combined = combineFunctionRelationshipCoverage( + { status: "partial", limitations: ["Missing incoming references."] }, + complete, + ); + expect(combined).toMatchObject({ limited_directions: ["callers"] }); + expect(isCallerOnlyIncompleteCoverage(combined)).toBe(true); + }); + + it("uses explicit directions even when explanation text contains direction labels", () => { + expect( + isCallerOnlyIncompleteCoverage({ + status: "unknown", + reason: "Callers: unavailable. Callees: diagnostic text.", + limited_directions: ["callers"], + }), + ).toBe(true); + expect( + isCallerOnlyIncompleteCoverage({ + status: "unknown", + reason: "Callers: unavailable.", + limited_directions: ["callees"], + }), + ).toBe(false); }); }); diff --git a/src/domain/functionCallCoverage.ts b/src/domain/functionCallCoverage.ts index b64e78cd6..ce3798c4f 100644 --- a/src/domain/functionCallCoverage.ts +++ b/src/domain/functionCallCoverage.ts @@ -22,6 +22,16 @@ export const combineFunctionRelationshipCoverage = ( ), ); const details = diagnostics.length > 0 ? { diagnostics } : {}; + const callersLimited = callers?.status !== "complete"; + const calleesLimited = callees?.status !== "complete"; + const limited_directions: Extract< + RelationshipCoverage, + { status: "partial" } + >["limited_directions"] = callersLimited + ? calleesLimited + ? ["callers", "callees"] + : ["callers"] + : ["callees"]; const reasons = reads.flatMap(({ direction, coverage }) => { const label = direction === "callers" ? callerCoveragePrefix : calleeCoveragePrefix; @@ -43,30 +53,37 @@ export const combineFunctionRelationshipCoverage = ( return { status: "unknown", reason: uniqueSorted(reasons).join(" "), + limited_directions, ...details, }; if (reasons.length > 0) return { status: "partial", limitations: uniqueSorted(reasons), + limited_directions, ...details, }; return { status: "complete", ...details }; }; /** - * Whether combined relationship coverage is unknown only on the caller side. - * The combine helper above prefixes each direction's reasons, so a reason - * that carries the caller prefix and no callee prefix records observed - * callees with unobservable callers. Forward (callee-edge) searches stay - * exhaustive under that caveat; the caller reason remains a limitation. + * Forward searches depend on callee coverage. Preserve the historical + * unknown-reason encoding when reading observations without explicit directions. */ -export const isCallerOnlyUnknownCoverage = ( +export const isCallerOnlyIncompleteCoverage = ( coverage: RelationshipCoverage, -): boolean => - coverage.status === "unknown" && - coverage.reason.startsWith(callerCoveragePrefix) && - !coverage.reason.includes(calleeCoveragePrefix); +): boolean => { + if (coverage.status === "complete") return false; + if (coverage.limited_directions !== undefined) + return !coverage.limited_directions.some( + (direction) => direction === "callees", + ); + return ( + coverage.status === "unknown" && + coverage.reason.startsWith(callerCoveragePrefix) && + !coverage.reason.includes(calleeCoveragePrefix) + ); +}; /** Explain why two resolved call sets cannot establish call-set equality. */ export const functionCallCoverageLimitations = ( diff --git a/src/domain/relationshipCoverage.ts b/src/domain/relationshipCoverage.ts index 1de973669..4dd4e0c40 100644 --- a/src/domain/relationshipCoverage.ts +++ b/src/domain/relationshipCoverage.ts @@ -1,24 +1,35 @@ import { z } from "zod"; -const diagnostics = z.array(z.string().min(1)).min(1); -const completeCoverage = z.strictObject({ status: z.literal("complete") }); +const diagnostics = z.array(z.string().min(1)).min(1).exactOptional(); +const completeCoverage = z.strictObject({ + status: z.literal("complete"), + diagnostics, +}); +const limitedDirections = z.union([ + z.tuple([z.literal("callers")]).check(z.minLength(1), z.maxLength(1)), + z.tuple([z.literal("callees")]).check(z.minLength(1), z.maxLength(1)), + z + .tuple([z.literal("callers"), z.literal("callees")]) + .check(z.minLength(2), z.maxLength(2)), +]); const partialCoverage = z.strictObject({ status: z.literal("partial"), limitations: z.array(z.string().min(1)).min(1), + limited_directions: limitedDirections.exactOptional(), + diagnostics, }); const unknownCoverage = z.strictObject({ status: z.literal("unknown"), reason: z.string().min(1), + limited_directions: limitedDirections.exactOptional(), + diagnostics, }); /** Explicit coverage state for a provider's observed caller/callee set. */ -export const relationshipCoverageSchema = z.union([ +export const relationshipCoverageSchema = z.discriminatedUnion("status", [ completeCoverage, - completeCoverage.extend({ diagnostics }), partialCoverage, - partialCoverage.extend({ diagnostics }), unknownCoverage, - unknownCoverage.extend({ diagnostics }), ]); export type RelationshipCoverage = z.infer; diff --git a/src/ghidra/GhidraAnalysisProfile.ts b/src/ghidra/GhidraAnalysisProfile.ts index da39ce53c..cc1d5eefb 100644 --- a/src/ghidra/GhidraAnalysisProfile.ts +++ b/src/ghidra/GhidraAnalysisProfile.ts @@ -40,6 +40,8 @@ import { NATIVE_AOT_PROFILE_CONTRACT_REVISION, } from "../domain/native/nativeAotPe.js"; +const callRelationshipCoverage = "function-body-call-coverage-v5"; + /** * The processor language REA pins for this target, or undefined when Ghidra may * select from the header. The committed profile and the session readback both @@ -125,7 +127,7 @@ export const resolveGhidraAnalysisProfile = async ( load_image_observations: "source-mappings-entry-context-v2", function_body_evidence: "complete-inclusive-ranges-v1", function_references: "complete-body-and-entry-reference-manager-v2", - call_relationship_coverage: "resolved-call-reference-diagnostics-v1", + call_relationship_coverage: callRelationshipCoverage, function_dossier_coverage: "observed-facets-and-call-relationships-v1", string_inventory_evidence: "defined-data-coverage-v1", @@ -222,7 +224,7 @@ export const resolveGhidraAnalysisProfile = async ( load_image_observations: "source-mappings-entry-context-v2", function_body_evidence: "complete-inclusive-ranges-v1", function_references: "complete-body-and-entry-reference-manager-v2", - call_relationship_coverage: "resolved-call-reference-diagnostics-v1", + call_relationship_coverage: callRelationshipCoverage, function_dossier_coverage: "observed-facets-and-call-relationships-v1", string_inventory_evidence: "defined-data-coverage-v1", location_resolution: "explicit-address-exact-entry-symbol-first-v3", diff --git a/src/ghidra/GhidraFunctionValues.test.ts b/src/ghidra/GhidraFunctionValues.test.ts index e7e5d8e9d..6ec7ad34e 100644 --- a/src/ghidra/GhidraFunctionValues.test.ts +++ b/src/ghidra/GhidraFunctionValues.test.ts @@ -43,7 +43,120 @@ const parseFunctionValueFixture = ( return parsed.ok ? { ok: true as const, value: parsed.value.value } : parsed; }; +describe("Ghidra unresolved call locations", () => { + it("rejects a noncanonical unresolved call site rather than retaining unverifiable location evidence", () => { + expect( + parseGhidraFunctionResult("analyze_function", { + value: { + ...functionDossierSchema.parse(ghidraFunctionDossier()), + unresolved_calls: [ + { address: "not-an-address", reason: "No call destination." }, + ], + }, + limitations: [], + relationship_coverage: { + status: "partial", + limitations: ["An unresolved call remains."], + }, + }), + ).toMatchObject({ ok: false, error: { _tag: "AnalysisOutputError" } }); + }); +}); + describe("Ghidra function-analysis result values", () => { + it("retains unavailable pseudocode instead of treating its empty representation as observed source", () => { + const availability = { + pseudocode: { + available: false, + reason: "Ghidra does not decompile external functions.", + }, + comments: { available: true }, + }; + const parsed = parseGhidraFunctionResult("analyze_function", { + value: { + ...functionDossierSchema.parse(ghidraFunctionDossier()), + pseudocode: "", + facet_availability: availability, + }, + limitations: [], + }); + expect(parsed).toMatchObject({ + ok: true, + value: { value: { pseudocode: "", facet_availability: availability } }, + }); + }); + it.each([ + { status: "complete", diagnostics: ["Resolved static references only."] }, + { + status: "partial", + limitations: ["Only the first instruction range was examined."], + }, + { status: "unknown", reason: "Relationship inventory was unavailable." }, + { + status: "partial", + limitations: ["Missing callers."], + limited_directions: ["callers"], + }, + { + status: "unknown", + reason: "Missing callees.", + limited_directions: ["callees"], + }, + ])("preserves observed $status relationship coverage", (coverage) => { + const parsed = parseGhidraFunctionResult("analyze_function", { + value: ghidraFunctionDossier(), + limitations: [], + relationship_coverage: coverage, + }); + expect(parsed).toMatchObject({ + ok: true, + value: { relationshipCoverage: coverage }, + }); + }); + + it("preserves omitted relationship coverage for legacy observations", () => { + const parsed = parseGhidraFunctionResult("analyze_function", { + value: ghidraFunctionDossier(), + limitations: [], + }); + if (!parsed.ok) throw parsed.error; + expect(parsed.value).not.toHaveProperty("relationshipCoverage"); + }); +}); + +describe("Ghidra relationship metadata validation", () => { + it.each([ + { status: "partial", limitations: [] }, + { status: "unknown", reason: "" }, + { status: "complete", limitations: ["Truncated."] }, + { status: "partial", limitations: ["Truncated."], limited_directions: [] }, + { + status: "partial", + limitations: ["Truncated."], + limited_directions: ["callers", "callers"], + }, + { status: "unknown", reason: "Missing.", limited_directions: ["incoming"] }, + { status: "complete", limited_directions: ["callers"] }, + ])("rejects malformed relationship coverage %j", (coverage) => { + expect( + parseGhidraFunctionResult("analyze_function", { + value: ghidraFunctionDossier(), + limitations: [], + relationship_coverage: coverage, + }), + ).toMatchObject({ ok: false, error: { _tag: "AnalysisOutputError" } }); + }); + + it("rejects relationship metadata on unrelated function operations", () => { + expect( + parseGhidraFunctionResult("procedure_assembly", { + value: "ret", + limitations: [], + relationship_coverage: { status: "complete" }, + }), + ).toMatchObject({ ok: false, error: { _tag: "AnalysisOutputError" } }); + }); + it("preserves file-offset resolution in Evidence locations and rejects inexact offsets", () => { const selection = { file_offset: 0x210, diff --git a/src/ghidra/GhidraFunctionValues.ts b/src/ghidra/GhidraFunctionValues.ts index a6e62c93c..d038ac82e 100644 --- a/src/ghidra/GhidraFunctionValues.ts +++ b/src/ghidra/GhidraFunctionValues.ts @@ -27,6 +27,10 @@ import { import { nativeApiBoundarySchema } from "../domain/native/nativeApiBoundary.js"; import { nativeValueFlowSchema } from "../domain/native/nativeValueFlow.js"; import type { EvidenceLocation } from "../domain/evidence.js"; +import { + relationshipCoverageSchema, + type RelationshipCoverage, +} from "../domain/relationshipCoverage.js"; import { err, ok, type Result } from "../domain/result.js"; import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js"; import { @@ -307,6 +311,7 @@ const ghidraFunctionDossier = functionDossierSchema ...value.comments.map(({ address }) => address), ...value.callers.map(({ address }) => address), ...value.callees.map(({ address }) => address), + ...(value.unresolved_calls ?? []).map(({ address }) => address), ...value.incoming_references.flatMap(referenceAddresses), ...value.outgoing_references.flatMap(referenceAddresses), ...value.referenced_strings.flatMap(({ address, source_address }) => [ @@ -419,6 +424,7 @@ const functionBoundaryObservationOperations: ReadonlySet["selection"]; @@ -450,13 +458,17 @@ export const parseGhidraFunctionResult = ( const envelope = functionObservationEnvelope.safeParse(value); if ( !envelope.success || + (operation !== "analyze_function" && + operation !== "procedure_callers" && + operation !== "procedure_callees" && + envelope.data.relationship_coverage !== undefined) || (operation !== "procedure_pseudo_code" && envelope.data.selection !== undefined) ) return err( new AnalysisOutputError( operation, - "Ghidra bridge omitted the function observation envelope", + "Ghidra bridge returned an invalid function observation envelope for this operation", envelope.success ? undefined : { cause: envelope.error }, ), ); @@ -469,6 +481,9 @@ export const parseGhidraFunctionResult = ( ? ok({ value: jsonValueSchema.parse(parsed.data), limitations: observation.limitations, + ...(observation.relationship_coverage === undefined + ? {} + : { relationshipCoverage: observation.relationship_coverage }), ...(observation.selection === undefined ? {} : { diff --git a/src/ghidra/GhidraProvider.behavior.test.ts b/src/ghidra/GhidraProvider.behavior.test.ts index c69c83bd9..018116b82 100644 --- a/src/ghidra/GhidraProvider.behavior.test.ts +++ b/src/ghidra/GhidraProvider.behavior.test.ts @@ -633,7 +633,7 @@ describe("Ghidra client projection", () => { expect(resolved.value.profile.parameters).toMatchObject({ language_id: "auto-from-header", compiler_spec_id: "auto-default", - call_relationship_coverage: "resolved-call-reference-diagnostics-v1", + call_relationship_coverage: "function-body-call-coverage-v5", function_dossier_coverage: "observed-facets-and-call-relationships-v1", }); @@ -870,7 +870,16 @@ describe("Ghidra relationship coverage", () => { Promise.resolve( ok( operation === "procedure_callees" - ? { value: ["0x2000"], limitations: [] } + ? { + value: ["0x2000"], + limitations: [], + relationship_coverage: { + status: "complete", + diagnostics: [ + "Only resolved Ghidra call references are returned; unresolved computed or indirect calls remain unknown, while function classifications distinguish thunks and externals.", + ], + }, + } : { value: [], limitations: [] }, ), ), diff --git a/src/ghidra/GhidraProviderCapabilities.ts b/src/ghidra/GhidraProviderCapabilities.ts index f4bff8d9c..909fbcea3 100644 --- a/src/ghidra/GhidraProviderCapabilities.ts +++ b/src/ghidra/GhidraProviderCapabilities.ts @@ -2,7 +2,6 @@ import type { CapabilityDescriptor, ProviderIdentity, } from "../application/AnalysisProvider.js"; -import type { RelationshipCoverage } from "../domain/relationshipCoverage.js"; import { hasWindowsNativeAuthority, windowsNativeAuthorityUnavailableReason, @@ -44,22 +43,6 @@ const stringInventoryLimitation = const searchLimitation = "Regex mode uses Java Pattern semantics. Matcher or compiler stack exhaustion returns a resource constraint without closing the session; literal mode avoids regex recursion and returns complete matching values."; -const resolvedCallReferenceLimitation = - "Only resolved Ghidra call references are returned; unresolved computed or indirect calls remain unknown, while function classifications distinguish thunks and externals."; - -/** Relationship-only caveats belong to each observed caller/callee result. */ -export const relationshipCoverageFor = ( - operation: string, -): RelationshipCoverage | undefined => - operation === "procedure_callers" || - operation === "procedure_callees" || - operation === "analyze_function" - ? { - status: "complete", - diagnostics: [resolvedCallReferenceLimitation], - } - : undefined; - /** Limitation text for one admitted operation, including the common base. */ export const limitationsFor = (operation: string): readonly string[] => { const common = [ diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.ts index 9db1b0c5f..dd95849c8 100644 --- a/src/ghidra/GhidraProviderClient.ts +++ b/src/ghidra/GhidraProviderClient.ts @@ -34,6 +34,7 @@ import { } from "../domain/analysisErrorCore.js"; import type { AnalysisError } from "../domain/analysisErrorBase.js"; import type { EvidenceLocation } from "../domain/evidence.js"; +import type { RelationshipCoverage } from "../domain/relationshipCoverage.js"; import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; import { err, ok, type Result } from "../domain/result.js"; @@ -86,7 +87,6 @@ import { healthLimitations, windowsP0Limitations, limitationsFor, - relationshipCoverageFor, } from "./GhidraProviderCapabilities.js"; import type { GhidraSessionError } from "./GhidraSessionError.js"; import { @@ -733,8 +733,8 @@ export const createGhidraProviderClient = (input: { rawResult: JsonValue, observationLimitations: readonly string[] = [], locations: readonly EvidenceLocation[] = [], + relationshipCoverage?: RelationshipCoverage, ) => { - const relationshipCoverage = relationshipCoverageFor(operation); return createAnalysisExecution(normalized, committedProfile.provider, { rawResult, locations, @@ -838,12 +838,14 @@ export const createGhidraProviderClient = (input: { let normalized: JsonValue; let observationLimitations: readonly string[] = []; let observationLocations: readonly EvidenceLocation[] = []; + let relationshipCoverage: RelationshipCoverage | undefined; if (isGhidraFunctionOperation(operation)) { const result = parseGhidraFunctionResult(operation, called.value); if (!result.ok) return result; normalized = result.value.value; observationLimitations = result.value.limitations; observationLocations = result.value.locations ?? []; + relationshipCoverage = result.value.relationshipCoverage; } else { const result = parseGhidraInventoryResult(operation, called.value); if (!result.ok) return result; @@ -939,6 +941,7 @@ export const createGhidraProviderClient = (input: { called.value, observationLimitations, observationLocations, + relationshipCoverage, ), ); }, diff --git a/src/ghidra/GhidraSnapshotCache.test.ts b/src/ghidra/GhidraSnapshotCache.test.ts index 83d293aa2..fa7b35c22 100644 --- a/src/ghidra/GhidraSnapshotCache.test.ts +++ b/src/ghidra/GhidraSnapshotCache.test.ts @@ -11,6 +11,7 @@ import { silentLogger } from "../logger.js"; import { GhidraProvider } from "./GhidraProvider.js"; import { GhidraSessionError } from "./GhidraSessionError.js"; import { GHIDRA_SESSION_CAPABILITIES } from "./GhidraSessionValues.js"; +import type { RelationshipCoverage } from "../domain/relationshipCoverage.js"; const TARGET: BinaryTarget = { path: "/tmp/ghidra-cache-fixture", @@ -23,7 +24,7 @@ const TARGET: BinaryTarget = { // Exercise the real provider descriptors, profile, input/output projection and // session cache; only the installed Ghidra process is replaced at its seam. -const fixture = (version = "12.1.4") => { +const fixture = (version = "12.1.4", coverage?: RelationshipCoverage) => { const config = parseConfig({ GHIDRA_INSTALL_DIR: "/opt/ghidra" }); if (!config.ok) throw config.error; const calls: string[] = []; @@ -113,7 +114,13 @@ const fixture = (version = "12.1.4") => { return ok( operation === "procedure_pseudo_code" || operation === "analyze_function" - ? { value, limitations: [] } + ? { + value, + limitations: [], + ...(operation === "analyze_function" && coverage !== undefined + ? { relationship_coverage: coverage } + : {}), + } : value, ); }, @@ -133,42 +140,119 @@ const open = async (session: ReturnType["session"]) => { expect((await session.openResolvedTarget(preview.value)).ok).toBe(true); }; -describe("Ghidra snapshot cache", () => { - it("refuses snapshots whose profile predates typed incoming references", async () => { - const initial = fixture(); - await open(initial.session); - const snapshot = initial.session.exportAnalysisSnapshot(); - if (!snapshot.ok) throw snapshot.error; - await initial.session.close(); - const profile = snapshot.value.binding.analysis_profile; - expect(profile.parameters.instruction_references).toBe( - "exact-address-incoming-v1", - ); - const legacy = { - ...snapshot.value, - binding: { - ...snapshot.value.binding, - analysis_profile: createAnalysisProfile( - profile.provider, - Object.fromEntries( - Object.entries(profile.parameters).filter( - ([key]) => key !== "instruction_references", - ), - ), - ), - }, - }; - const replay = fixture(); - const imported = replay.session.importAnalysisSnapshot(legacy); - if (!imported.ok) throw imported.error; - expect(await replay.session.previewTarget(TARGET)).toMatchObject({ - ok: false, - error: { _tag: "EvidenceIntegrityError" }, - }); - expect(replay.calls).toEqual([]); - await replay.session.close(); - }); +describe("Ghidra relationship coverage replay", () => { + it.each([ + undefined, + { status: "complete", diagnostics: ["Resolved static references only."] }, + { status: "partial", limitations: ["Instruction coverage was truncated."] }, + { status: "unknown", reason: "Relationship inventory was unavailable." }, + { + status: "partial", + limitations: ["Missing callers."], + limited_directions: ["callers"], + }, + ] satisfies (RelationshipCoverage | undefined)[])( + "preserves relationship coverage %j through live execution, cache and snapshot replay", + async (coverage) => { + const initial = fixture("12.1.4", coverage); + await open(initial.session); + const parameters = { procedure: "0x1000" }; + for (let i = 0; i < 2; i++) { + const execution = await initial.session.execute( + "analyze_function", + parameters, + ); + if (!execution.ok) throw execution.error; + expect(execution.value.relationshipCoverage).toEqual(coverage); + } + expect(initial.calls).toEqual(["analyze_function"]); + const snapshot = initial.session.exportAnalysisSnapshot(); + if (!snapshot.ok) throw snapshot.error; + await initial.session.close(); + const replay = fixture(); + expect(replay.session.importAnalysisSnapshot(snapshot.value).ok).toBe( + true, + ); + await open(replay.session); + const execution = await replay.session.execute( + "analyze_function", + parameters, + ); + if (!execution.ok) throw execution.error; + expect(execution.value.relationshipCoverage ?? undefined).toEqual( + coverage, + ); + expect(replay.calls).toEqual([]); + await replay.session.close(); + }, + ); +}); +describe("Ghidra snapshot profile admission", () => { + it.each([ + { + parameter: "instruction_references", + current: "exact-address-incoming-v1", + legacy: undefined, + }, + { + parameter: "call_relationship_coverage", + current: "function-body-call-coverage-v5", + legacy: "resolved-call-reference-diagnostics-v1", + }, + { + parameter: "call_relationship_coverage", + current: "function-body-call-coverage-v5", + legacy: "decoded-call-target-coverage-v2", + }, + { + parameter: "call_relationship_coverage", + current: "function-body-call-coverage-v5", + legacy: "decoded-call-target-coverage-v3", + }, + { + parameter: "call_relationship_coverage", + current: "function-body-call-coverage-v5", + legacy: "function-body-call-coverage-v4", + }, + ])( + "refuses snapshots with outdated $parameter semantics", + async ({ parameter, current, legacy: prior }) => { + const initial = fixture(); + await open(initial.session); + const snapshot = initial.session.exportAnalysisSnapshot(); + if (!snapshot.ok) throw snapshot.error; + await initial.session.close(); + const profile = snapshot.value.binding.analysis_profile; + expect(profile.parameters[parameter]).toBe(current); + const legacy = { + ...snapshot.value, + binding: { + ...snapshot.value.binding, + analysis_profile: createAnalysisProfile(profile.provider, { + ...Object.fromEntries( + Object.entries(profile.parameters).filter( + ([key]) => key !== parameter, + ), + ), + ...(prior === undefined ? {} : { [parameter]: prior }), + }), + }, + }; + const replay = fixture(); + const imported = replay.session.importAnalysisSnapshot(legacy); + if (!imported.ok) throw imported.error; + expect(await replay.session.previewTarget(TARGET)).toMatchObject({ + ok: false, + error: { _tag: "EvidenceIntegrityError" }, + }); + expect(replay.calls).toEqual([]); + await replay.session.close(); + }, + ); +}); + +describe("Ghidra snapshot cache", () => { it.each([ { operation: "analyze_function", parameters: { procedure: "0x1000" } }, { diff --git a/tests/boundary/mcp/functionCallDirectionsMcp.test.ts b/tests/boundary/mcp/functionCallDirectionsMcp.test.ts new file mode 100644 index 000000000..b4034d036 --- /dev/null +++ b/tests/boundary/mcp/functionCallDirectionsMcp.test.ts @@ -0,0 +1,138 @@ +import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; +import { Ajv2020 } from "ajv/dist/2020.js"; +import { expect, it } from "vitest"; + +import { FUNCTION_COMPARISON_EXAMPLE } from "../../../src/contracts/functionComparisonExample.js"; +import { createEvidence } from "../../../src/domain/evidence.js"; +import { functionDossierSchema } from "../../../src/domain/hopperValues.js"; +import type { RelationshipCoverage } from "../../../src/domain/relationshipCoverage.js"; +import { createServer } from "../../../src/server/createServer.js"; +import { createTestBinarySession } from "../../fixtures/binarySession.js"; + +const observe = (relationshipCoverage: RelationshipCoverage) => { + const template = FUNCTION_COMPARISON_EXAMPLE.left; + if (template.subject === null) + throw new Error("Expected artifact-bound fixture"); + const dossier = functionDossierSchema.parse(template.normalized_result); + return createEvidence( + { + path: template.subject.local_path, + sha256: template.subject.digest.sha256, + format: template.subject.format, + }, + template.provider, + { + operation: "analyze_function", + parameters: template.parameters, + result: { ...dossier, callees: [], unresolved_calls: [] }, + confidence: template.confidence, + authority: template.authority, + relationshipCoverage, + }, + ); +}; + +it("preserves directional gaps through advertised schemas and public path reconstruction", async () => { + const session = createTestBinarySession(() => { + throw new Error("Offline call paths must not launch a provider"); + }); + const server = createServer({ kind: "session", session }); + const client = new Client({ name: "function-call-directions", version: "1" }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + try { + await server.connect(serverTransport); + await client.connect(clientTransport); + const advertised = (await client.listTools()).tools.find( + ({ name }) => name === "build_call_path", + ); + if (advertised === undefined) + throw new Error("Missing build_call_path contract"); + const ajv = new Ajv2020({ strict: false, validateFormats: false }); + expect(ajv.validateSchema(advertised.inputSchema)).toBe(true); + const validate = ajv.compile(advertised.inputSchema); + for (const { directions, status, exhaustive } of [ + { + directions: ["callers"] as ["callers"], + status: "not_found", + exhaustive: true, + }, + { + directions: ["callees"] as ["callees"], + status: "unknown", + exhaustive: false, + }, + { + directions: ["callers", "callees"] as ["callers", "callees"], + status: "unknown", + exhaustive: false, + }, + ]) { + const limitation = + "An observed call reference is absent from the inventory."; + const coverage: RelationshipCoverage = { + status: "partial", + limitations: [limitation], + limited_directions: directions, + }; + const observation = observe(coverage); + expect(session.recordEvidence(observation).ok).toBe(true); + const input = { + functions: [observation], + start: { address: "0x1000" }, + goal: { address: "0x9999" }, + }; + expect(validate(input), JSON.stringify(validate.errors)).toBe(true); + for (const limited_directions of [ + [], + ["callers", "callers"], + ["callees", "callees"], + ["callers", "callees", "callers"], + ["incoming"], + ]) + expect( + validate({ + ...input, + functions: [ + { + ...observation, + relationship_coverage: { + ...coverage, + limited_directions, + }, + }, + ], + }), + ).toBe(false); + const result = await client.callTool({ + name: "build_call_path", + arguments: input, + }); + if (result.isError) throw new Error(JSON.stringify(result)); + expect(result.structuredContent).toMatchObject({ + normalized_result: { + status, + search_scope: { exhaustive }, + limitations: expect.arrayContaining([limitation]), + }, + }); + const comparison = await client.callTool({ + name: "compare_functions", + arguments: { left: observation, right: observation }, + }); + if (comparison.isError) throw new Error(JSON.stringify(comparison)); + expect(comparison.structuredContent).toMatchObject({ + normalized_result: { + dimensions: expect.arrayContaining([ + expect.objectContaining({ dimension: "calls", status: "unknown" }), + ]), + }, + }); + // Each scenario owns its Evidence and residual-unknown ledger. + const closed = await session.close(); + if (!closed.ok) throw closed.error; + } + } finally { + await Promise.allSettled([session.close(), client.close(), server.close()]); + } +}); diff --git a/tests/boundary/mcp/ghidraEvidenceMcp.test.ts b/tests/boundary/mcp/ghidraEvidenceMcp.test.ts index e786fc3cc..e0ceeeda3 100644 --- a/tests/boundary/mcp/ghidraEvidenceMcp.test.ts +++ b/tests/boundary/mcp/ghidraEvidenceMcp.test.ts @@ -15,9 +15,17 @@ import { type GhidraFunctionOperation, } from "../../../src/ghidra/GhidraFunctionValues.js"; -it.each([true, false])( - "compares observed empty Ghidra facets while preserving pseudocode availability (%s)", - async (pseudocodeAvailable) => { +it.each([ + { pseudocodeAvailable: true, reportsCoverage: true }, + { pseudocodeAvailable: false, reportsCoverage: true }, + { pseudocodeAvailable: true, reportsCoverage: false }, + { pseudocodeAvailable: false, reportsCoverage: false }, +])( + "compares observed empty Ghidra facets with pseudocode=$pseudocodeAvailable and coverage=$reportsCoverage", + async ({ pseudocodeAvailable, reportsCoverage }) => { + const coverage = reportsCoverage + ? { status: "complete" as const } + : undefined; const dossier = functionDossierSchema.parse(ghidraFunctionDossier()); Object.assign(dossier, { comments: [], @@ -47,7 +55,13 @@ it.each([true, false])( if (operation !== "analyze_function") throw new Error(`Unexpected operation: ${operation}`); return Promise.resolve( - ok({ value: jsonValueSchema.parse(dossier), limitations: [] }), + ok({ + value: jsonValueSchema.parse(dossier), + limitations: [], + ...(coverage === undefined + ? {} + : { relationship_coverage: coverage }), + }), ); }, ); @@ -61,9 +75,7 @@ it.each([true, false])( harness.session, analyzed.structuredContent, ); - expect(evidence.relationship_coverage).toMatchObject({ - status: "complete", - }); + expect(evidence.relationship_coverage).toEqual(coverage ?? null); expect(evidence.normalized_result).toEqual(dossier); const reply = await harness.mcp.callTool({ name: "compare_functions", @@ -86,7 +98,7 @@ it.each([true, false])( pseudocode: pseudocodeAvailable ? "unchanged" : "unknown", assembly: "unchanged", comments: "unchanged", - calls: "unchanged", + calls: reportsCoverage ? "unchanged" : "unknown", references: "unchanged", strings_names: "unchanged", cfg: "unchanged", @@ -96,9 +108,7 @@ it.each([true, false])( evidence.parameters, ); if (!replay.ok) throw replay.error; - expect(replay.value.relationshipCoverage).toEqual( - evidence.relationship_coverage, - ); + expect(replay.value.relationshipCoverage).toEqual(coverage); expect(harness.calls).toEqual(["analyze_function"]); } finally { await harness.close(); diff --git a/tests/conformance/ghidra/ReaNoReturnProbe.java b/tests/conformance/ghidra/ReaNoReturnProbe.java index b13c2b5e9..19f98f346 100644 --- a/tests/conformance/ghidra/ReaNoReturnProbe.java +++ b/tests/conformance/ghidra/ReaNoReturnProbe.java @@ -12,6 +12,8 @@ import ghidra.program.model.listing.FlowOverride; import ghidra.program.model.listing.Function; import ghidra.program.model.listing.Instruction; import ghidra.program.model.symbol.SourceType; +import ghidra.program.model.symbol.Reference; +import ghidra.program.model.symbol.RefType; import java.io.File; import java.lang.reflect.Method; import java.nio.file.Files; @@ -20,9 +22,12 @@ import java.util.HexFormat; import java.util.LinkedHashMap; import java.util.List; import java.util.Map; +import java.util.ArrayList; /** Injects reported analysis flags into imported ELF/Mach-O functions; never executes target code. */ public class ReaNoReturnProbe extends GhidraScript { + private record MemoryCallReference(Address source, Address target, RefType type, + SourceType sourceType, int operandIndex, boolean primary) {} private final JsonArray checks = new JsonArray(); private final Map originalEnds = new LinkedHashMap<>(); private final Map originalSignatures = new LinkedHashMap<>(); @@ -85,6 +90,114 @@ public class ReaNoReturnProbe extends GhidraScript { return instance; } + private void knownInteriorCall(GhidraScript bridge) throws Exception { + Function caller = function("rea_tls_chain"); + Function target = function("rea_tls"); + Address interior = target.getEntryPoint().add(1); + require("interior_target_is_owned", currentProgram.getFunctionManager().getFunctionAt(interior) == null && + target.equals(currentProgram.getFunctionManager().getFunctionContaining(interior))); + Instruction call = null; + for (Instruction instruction : currentProgram.getListing().getInstructions(caller.getBody(), true)) { + if (instruction.getFlowType().isCall()) { call = instruction; break; } + } + if (call == null) throw new IllegalStateException("Missing real call instruction"); + var references = currentProgram.getReferenceManager(); + List originals = new ArrayList<>(); + List saved = new ArrayList<>(); + for (Reference reference : call.getReferencesFrom()) { + if (!reference.getReferenceType().isCall()) continue; + originals.add(reference); + saved.add(new MemoryCallReference(reference.getFromAddress(), reference.getToAddress(), + reference.getReferenceType(), reference.getSource(), reference.getOperandIndex(), reference.isPrimary())); + } + require("original_call_reference_present", !originals.isEmpty()); + Reference changed = null; + try { + for (Reference reference : originals) references.delete(reference); + changed = references.addMemoryReference(call.getAddress(), interior, + RefType.UNCONDITIONAL_CALL, SourceType.USER_DEFINED, 0); + require("interior_target_omitted_by_callee_getter", !caller.getCalledFunctions(monitor).contains(target)); + JsonObject query = new JsonObject(); + query.addProperty("document", currentProgram.getName()); + query.addProperty("procedure", caller.getName()); + query.addProperty("direction", "outgoing"); + Method read = bridge.getClass().getDeclaredMethod("procedureReferences", JsonObject.class); + read.setAccessible(true); + JsonObject output = (JsonObject) read.invoke(bridge, query); + require("interior_reference_keeps_known_procedure", output.getAsJsonArray("references").asList().stream().anyMatch( + edge -> !edge.getAsJsonObject().get("target_procedure").isJsonNull() && + edge.getAsJsonObject().getAsJsonObject("target_procedure").get("name").getAsString().equals(target.getName()))); + require("known_reference_is_not_also_unresolved", output.getAsJsonArray("unresolved_calls").isEmpty()); + query.remove("direction"); + Method callees = bridge.getClass().getDeclaredMethod("procedureCalls", JsonObject.class, boolean.class); + callees.setAccessible(true); + JsonObject inventory = (JsonObject) callees.invoke(bridge, query, false); + require("omitted_callee_inventory_stays_partial", inventory.getAsJsonObject("relationship_coverage").get("status").getAsString().equals("partial")); + require("omitted_callee_direction_is_explicit", + inventory.getAsJsonObject("relationship_coverage").getAsJsonArray("limited_directions").toString().equals("[\"callees\"]")); + require("interior_caller_omitted_by_entry_getter", !target.getCallingFunctions(monitor).contains(caller)); + query.addProperty("procedure", target.getName()); + JsonObject incoming = (JsonObject) callees.invoke(bridge, query, true); + require("off_entry_caller_inventory_stays_partial", + incoming.getAsJsonObject("relationship_coverage").get("status").getAsString().equals("partial")); + require("off_entry_caller_direction_is_explicit", + incoming.getAsJsonObject("relationship_coverage").getAsJsonArray("limited_directions").toString().equals("[\"callers\"]")); + JsonObject dossierQuery = new JsonObject(); + dossierQuery.addProperty("procedure", target.getName()); + Method analyze = bridge.getClass().getDeclaredMethod("analyzeFunctionObservation", JsonObject.class); + analyze.setAccessible(true); + Object observation = analyze.invoke(bridge, dossierQuery); + Method coverage = observation.getClass().getDeclaredMethod("relationshipCoverage"); + coverage.setAccessible(true); + require("dossier_preserves_caller_only_gap", + ((JsonObject) coverage.invoke(observation)).getAsJsonArray("limited_directions").toString().equals("[\"callers\"]")); + } finally { + if (changed != null) references.delete(changed); + for (MemoryCallReference reference : saved) { + Reference restored = references.addMemoryReference(reference.source(), reference.target(), + reference.type(), reference.sourceType(), reference.operandIndex()); + references.setPrimary(restored, reference.primary()); + } + } + } + + private void nonCallInstructionReference(GhidraScript bridge) throws Exception { + Function caller = function("rea_tls_chain"); + Function target = function("rea_memcpy"); + Instruction source = null; + for (Instruction instruction : currentProgram.getListing().getInstructions(caller.getBody(), true)) { + if (!instruction.getFlowType().isCall()) { source = instruction; break; } + } + if (source == null) throw new IllegalStateException("Missing non-call instruction"); + var references = currentProgram.getReferenceManager(); + Reference added = references.addMemoryReference(source.getAddress(), target.getEntryPoint().add(1), + RefType.UNCONDITIONAL_CALL, SourceType.USER_DEFINED, -1); + try { + require("non_call_reference_target_omitted", !caller.getCalledFunctions(monitor).contains(target)); + JsonObject query = new JsonObject(); + query.addProperty("document", currentProgram.getName()); + query.addProperty("procedure", caller.getName()); + Method read = bridge.getClass().getDeclaredMethod("procedureCalls", JsonObject.class, boolean.class); + read.setAccessible(true); + JsonObject output = (JsonObject) read.invoke(bridge, query, false); + require("non_call_instruction_reference_stays_partial", + output.getAsJsonObject("relationship_coverage").get("status").getAsString().equals("partial")); + query.addProperty("direction", "outgoing"); + Method edges = bridge.getClass().getDeclaredMethod("procedureReferences", JsonObject.class); + edges.setAccessible(true); + JsonObject known = (JsonObject) edges.invoke(bridge, query); + require("non_call_known_reference_is_not_unresolved", known.getAsJsonArray("unresolved_calls").isEmpty()); + references.delete(added); + Address unknown = currentProgram.getMemory().getMaxAddress().add(0x1000); + added = references.addMemoryReference(source.getAddress(), unknown, + RefType.UNCONDITIONAL_CALL, SourceType.USER_DEFINED, -1); + JsonObject unresolved = (JsonObject) edges.invoke(bridge, query); + require("non_call_unknown_reference_keeps_site", unresolved.getAsJsonArray("unresolved_calls").size() == 1); + } finally { + references.delete(added); + } + } + @Override public void run() throws Exception { String[] args = getScriptArgs(); @@ -164,6 +277,8 @@ public class ReaNoReturnProbe extends GhidraScript { Object output = pseudocode.invoke(bridge, query); require("recovered_pseudocode", output instanceof JsonObject value && value.get("value").getAsString().contains("rea_after_call")); + nonCallInstructionReference(bridge); + knownInteriorCall(bridge); } finally { ((ghidra.app.decompiler.DecompInterface) field.get(bridge)).dispose(); }