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): preserve decoded return flow evidence
N0zoM1z0bcc8a773e2a7
diff --git a/bridge/ghidra/ReaGhidraBridge.java b/bridge/ghidra/ReaGhidraBridge.javaindex b64955a2e..ea1b8d2d6 100644--- a/bridge/ghidra/ReaGhidraBridge.java+++ b/bridge/ghidra/ReaGhidraBridge.java@@ -866,6 +866,7 @@ public final class ReaGhidraBridge extends HeadlessScript {JsonArray operands = new JsonArray();JsonArray references = new JsonArray();JsonArray destinations = new JsonArray();+ JsonArray flowEvidence = new JsonArray();JsonObject flow = new JsonObject();flow.addProperty("kind", "unavailable");flow.addProperty("conditional", false);@@ -881,7 +882,20 @@ public final class ReaGhidraBridge extends HeadlessScript {result.addProperty("mnemonic", instruction.getMnemonicString());result.addProperty("raw_disassembly", instruction.toString());RefType type = instruction.getFlowType();- flow.addProperty("kind", type.isCall() ? "call" : type.isJump() ? "jump" : type.isTerminal() ? "terminal" : "fallthrough");+ JsonObject listingFlow = new JsonObject();+ listingFlow.addProperty("source", "ghidra-listing-flow-type");+ listingFlow.addProperty("value", type.getName());+ flowEvidence.add(listingFlow);+ boolean decodedReturn = false;+ for (PcodeOp operation : instruction.getPcode()) {+ if (operation.getOpcode() != PcodeOp.RETURN) continue;+ decodedReturn = true;+ JsonObject returnEvidence = new JsonObject();+ returnEvidence.addProperty("source", "ghidra-instruction-pcode");+ returnEvidence.addProperty("value", operation.getMnemonic());+ flowEvidence.add(returnEvidence);+ }+ flow.addProperty("kind", type.isCall() ? "call" : type.isJump() ? "jump" : decodedReturn ? "return" : type.isTerminal() ? "terminal" : "fallthrough");flow.addProperty("conditional", type.isConditional());flow.addProperty("computed", type.isComputed());if (!type.isComputed()) for (Address target : instruction.getFlows()) destinations.add(canonicalAddress(target));@@ -917,10 +931,13 @@ public final class ReaGhidraBridge extends HeadlessScript {}}flow.add("direct_destinations", destinations);+ flow.add("classification_evidence", flowEvidence);result.add("operands", operands);result.add("flow", flow);result.add("references", references);- result.add("limitations", GSON.toJsonTree(List.of("Operand components are Ghidra Listing decoder tokens; effective memory base/index/displacement roles and per-instruction context mode are unavailable. The mode field is the program language variant.", "Terminal flow is not classified as a return without provider evidence.")));+ List<String> limitations = new ArrayList<>(List.of("Operand components are Ghidra Listing decoder tokens; effective memory base/index/displacement roles and per-instruction context mode are unavailable. The mode field is the program language variant."));+ if (flow.get("kind").getAsString().equals("terminal")) limitations.add("No RETURN operation was observed in the provider's instruction p-code; terminal classification remains generic.");+ result.add("limitations", GSON.toJsonTree(limitations));return result;}diff --git a/docs/native-investigation.md b/docs/native-investigation.mdindex 902831169..4ebbe86ed 100644--- a/docs/native-investigation.md+++ b/docs/native-investigation.md@@ -185,6 +185,19 @@ outside-memory and undecodable addresses have separate outcomes. Effectivememory base/index/displacement roles and per-instruction context mode remainunavailable; `mode` is the program language variant.+Ghidra distinguishes a return using decoded instruction p-code's `RETURN`+operation. `flow.classification_evidence` preserves the Listing flow type and+the observed return evidence; mnemonic spelling alone is not the classifier.+Other terminal or trap flows retain the provider's classification, and this+inspection does not change function extents or prove a calling convention.+The analysis profile commits this decoder behavior. Snapshots from the earlier+profile produce a profile mismatch rather than replaying the former generic+terminal result. The old snapshot's `evidence_bundle` remains valid retained+Evidence: copy that object to a separate JSON file and use `rea evidence-import`+to validate it. Run analysis without the old snapshot and save a fresh one+under the current profile. Other providers and older captures may omit the+classification evidence field.+Call resolution reports direct, resolved indirect, ambiguous, unresolved andnon-call outcomes from static call references. It does not establish runtimeexecution or classify Objective-C/Swift/vtable/closure mechanisms from names.diff --git a/scripts/lib/real-ghidra-boundaries.mjs b/scripts/lib/real-ghidra-boundaries.mjsindex 47e90e60e..0f0b09b6b 100644--- a/scripts/lib/real-ghidra-boundaries.mjs+++ b/scripts/lib/real-ghidra-boundaries.mjs@@ -15,6 +15,7 @@ import { verifyGhidraTargetAdmission } from "./real-ghidra-target-admission.mjs"import { verifyGhidraLargeResults } from "./real-ghidra-large-results.mjs";import { verifyGhidraEntryAliases } from "./real-ghidra-entry-aliases.mjs";import { verifyGhidraNamespaceAnnotations } from "./real-ghidra-namespace-annotations.mjs";+import { verifyGhidraInstructionFlow } from "./real-ghidra-instruction-flow.mjs";/** Probe real Ghidra location, annotation and error contracts through public adapters. */export async function verifyGhidraBoundaries(@@ -157,6 +158,7 @@ export async function verifyGhidraBoundaries(/Annotations require a local function entry/u,);const names = await call("list_names");+ const instructionFlow = await verifyGhidraInstructionFlow(call, names, cli);const leaf = names.find((item) =>item.value.endsWith("rea_ghidra_inventory_leaf"),);@@ -766,6 +768,7 @@ export async function verifyGhidraBoundaries(missing_and_nonregular_source_rejected: true,imported_source_identity_retained: true,equivalent_instruction_address_spellings: true,+ instruction_flow: instructionFlow,qualified_annotation_name_roundtrip: true,imported_entry_alias_selection: true,oversized_result_retention_and_complete_export: true,diff --git a/scripts/lib/real-ghidra-instruction-flow.mjs b/scripts/lib/real-ghidra-instruction-flow.mjsnew file mode 100644index 000000000..25bad8073--- /dev/null+++ b/scripts/lib/real-ghidra-instruction-flow.mjs@@ -0,0 +1,110 @@+import assert from "node:assert/strict";++/** Verify decoded return evidence and distinct non-return flows on owned fixtures. */+export async function verifyGhidraInstructionFlow(call, names, cli) {+ const leaf = names.find((item) =>+ item.value.endsWith("rea_ghidra_inventory_leaf"),+ );+ assert.ok(leaf, "Source fixture lacks its returning leaf");+ const leafInstructions = await inspectFunction(call, leaf.address);+ const returned = leafInstructions.find(+ (instruction) => instruction.flow.kind === "return",+ );+ assert.ok(returned, "Returning source leaf lacks decoded RETURN evidence");+ assertReturnEvidence(returned);+ assert.equal(+ (await call("resolve_native_call_targets", { address: returned.address }))+ .status,+ "not-call",+ );+ assert.deepEqual(+ await cli("inspect-native-instruction", returned.address),+ returned,+ );++ const controls = [+ ["rea_ghidra_flow_return", "RET", "c3"],+ ["rea_ghidra_flow_cleanup_return", "RET", "c21000"],+ ["rea_ghidra_flow_shared_tail", "JMP", null],+ ["rea_ghidra_flow_trap", "UD2", "0f0b"],+ ];+ let checked = 0;+ for (const [symbol, mnemonic, bytes] of controls) {+ const procedure = names.find((item) => item.value === symbol);+ if (procedure === undefined) continue;+ const before = await call("resolve_containing_procedure", {+ address: procedure.address,+ });+ const instructions = await inspectFunction(call, procedure.address);+ const instruction = instructions.find((item) => item.mnemonic === mnemonic);+ assert.ok(instruction, `Source fixture lacks ${symbol}'s ${mnemonic}`);+ if (bytes !== null) assert.equal(instruction.bytes, bytes);+ if (mnemonic === "RET") {+ assertReturnEvidence(instruction);+ assert.equal(instruction.flow.kind, "return");+ if (bytes === "c21000")+ assert.equal(instruction.operands[0]?.raw, "0x10");+ } else {+ assert.notEqual(instruction.flow.kind, "return");+ assert.ok(+ instruction.flow.classification_evidence.some(+ (item) => item.source === "ghidra-listing-flow-type",+ ),+ );+ }+ assert.deepEqual(+ await call("resolve_containing_procedure", {+ address: procedure.address,+ }),+ before,+ );+ checked++;+ }+ const unavailable = await call("inspect_native_instruction", {+ address: "0x0",+ });+ assert.equal(unavailable.status, "outside-memory");+ assert.equal(unavailable.flow.kind, "unavailable");+ assert.deepEqual(unavailable.flow.classification_evidence, []);+ return {+ return_instruction: returned.address,+ decoded_pcode_return: true,+ return_cli_mcp_parity: true,+ explicit_x86_elf_controls: checked,+ explicit_control_scope:+ checked === 0+ ? "Not present on this host-native fixture format/architecture"+ : "x86-64 ELF",+ generic_unknown_preserved: true,+ };+}++async function inspectFunction(call, procedure) {+ const listing = await call("read_function_instructions", { procedure });+ const instructions = [];+ for (const line of listing.instructions) {+ const delimiter = line.indexOf(": ");+ assert.ok(delimiter > 0, `Malformed provider instruction listing: ${line}`);+ instructions.push(+ await call("inspect_native_instruction", {+ address: line.slice(0, delimiter),+ }),+ );+ }+ return instructions;+}++function assertReturnEvidence(instruction) {+ assert.equal(instruction.status, "decoded");+ assert.ok(+ instruction.flow.classification_evidence.some(+ (item) =>+ item.source === "ghidra-instruction-pcode" && item.value === "RETURN",+ ),+ );+ assert.ok(+ !instruction.limitations.some((text) =>+ text.includes("not classified as a return"),+ ),+ );+}diff --git a/scripts/verify-real-ghidra-function.mjs b/scripts/verify-real-ghidra-function.mjsindex c8c7cf0c6..8200f3f2e 100644--- a/scripts/verify-real-ghidra-function.mjs+++ b/scripts/verify-real-ghidra-function.mjs@@ -92,8 +92,7 @@ export async function verifyDebugFunctionOperations(if (instruction.status !== "decoded" ||instruction.length < 1 ||- instruction.bytes.length !== instruction.length * 2 ||- instruction.operands.length === 0+ instruction.bytes.length !== instruction.length * 2)throw new Error("Structured native instruction facts drifted");const directSite = outgoing.references.find(diff --git a/src/domain/native/nativeInstruction.ts b/src/domain/native/nativeInstruction.tsindex b9509f036..744707ed2 100644--- a/src/domain/native/nativeInstruction.ts+++ b/src/domain/native/nativeInstruction.ts@@ -59,6 +59,17 @@ export const nativeInstructionSchema = z.strictObject({conditional: z.boolean(),computed: z.boolean(),direct_destinations: z.array(z.string()),+ classification_evidence: z+ .array(+ z.strictObject({+ source: z.string().min(1),+ value: z.string().min(1),+ }),+ )+ .optional()+ .describe(+ "Observed provider facts used to classify flow; older captures or other providers may omit them.",+ ),}),references: z.array(reference),limitations: z.array(z.string()),diff --git a/src/ghidra/GhidraAnalysisProfile.ts b/src/ghidra/GhidraAnalysisProfile.tsindex 57fc2f1f2..31c923be9 100644--- a/src/ghidra/GhidraAnalysisProfile.ts+++ b/src/ghidra/GhidraAnalysisProfile.ts@@ -44,6 +44,7 @@ export const resolveGhidraAnalysisProfile = (function_body_evidence: "complete-inclusive-ranges-v1",function_references: "complete-body-and-entry-reference-manager-v2",location_resolution: "explicit-address-exact-entry-symbol-first-v3",+ instruction_flow_evidence: "decoded-return-pcode-v1",process_launch:installation.platform === "win32"? "official-headless-script-v1"diff --git a/tests/conformance/ghidra/inventory.c b/tests/conformance/ghidra/inventory.cindex 3655de0bb..8b57aa1ce 100644--- a/tests/conformance/ghidra/inventory.c+++ b/tests/conformance/ghidra/inventory.c@@ -2,6 +2,22 @@volatile int rea_ghidra_inventory_global = 7;+#if defined(__x86_64__) && defined(__ELF__)+// Static decoder controls: these functions are retained but never executed.+__attribute__((naked, noinline, used)) void rea_ghidra_flow_return(void) {+ __asm__("ret");+}+__attribute__((naked, noinline, used)) void rea_ghidra_flow_cleanup_return(void) {+ __asm__("ret $16");+}+__attribute__((naked, noinline, used)) void rea_ghidra_flow_shared_tail(void) {+ __asm__("jmp rea_ghidra_flow_return");+}+__attribute__((naked, noinline, used)) void rea_ghidra_flow_trap(void) {+ __asm__("ud2");+}+#endif+// This literal reproduces stack exhaustion in Java's recursive regex matcher.#define REA_REPEAT_4(value) value value value value#define REA_REPEAT_16(value) REA_REPEAT_4(REA_REPEAT_4(value))