diff --git a/.github/workflows/ghidra-bridge-sources.yml b/.github/workflows/ghidra-bridge-sources.yml index 71b5dde25a..c882f7a0ca 100644 --- a/.github/workflows/ghidra-bridge-sources.yml +++ b/.github/workflows/ghidra-bridge-sources.yml @@ -36,7 +36,7 @@ jobs: ghidra-bridge-sources: name: Compile packaged Ghidra bridge sources runs-on: ubuntu-24.04 - timeout-minutes: 20 + timeout-minutes: 30 env: GHIDRA_RELEASE_URL: https://github.com/NationalSecurityAgency/ghidra/releases/download/Ghidra_12.2_build/ghidra_12.2_PUBLIC_20261016.zip GHIDRA_RELEASE_SHA256: 2c2cd776db3c1f6a097ba418922378ac3649cadd5e844a6f5f088ae628a7be67 @@ -82,6 +82,12 @@ jobs: java_home_variable="JAVA_HOME_${GHIDRA_JAVA_MAJOR}_X64" export JAVA_HOME="${!java_home_variable}" npm run verify:ghidra:loader-relocation + - name: Check native prototype conflict decoding and frame paths + shell: bash + run: | + java_home_variable="JAVA_HOME_${GHIDRA_JAVA_MAJOR}_X64" + export JAVA_HOME="${!java_home_variable}" + node scripts/verify-ghidra-prototype-conflicts.mjs - name: Inspect real ARM, Thumb and MIPS instruction context through the bridge shell: bash run: | diff --git a/bridge/ghidra/ReaGhidraBridge.java b/bridge/ghidra/ReaGhidraBridge.java index 8d6448862d..144d80aea5 100644 --- a/bridge/ghidra/ReaGhidraBridge.java +++ b/bridge/ghidra/ReaGhidraBridge.java @@ -79,6 +79,7 @@ import ghidra.program.model.data.StringDataInstance; import ghidra.program.model.data.DataType; import ghidra.program.model.data.MutabilitySettingsDefinition; import ghidra.program.model.data.Undefined; +import ghidra.program.model.lang.OperandType; import ghidra.program.model.lang.Register; import ghidra.program.model.scalar.Scalar; import ghidra.program.model.listing.Bookmark; @@ -92,6 +93,7 @@ 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.listing.VariableStorage; import ghidra.program.model.mem.MemoryBlock; import ghidra.program.model.mem.MemoryBlockSourceInfo; import ghidra.program.database.mem.FileBytes; @@ -121,6 +123,7 @@ import ghidra.program.model.pcode.VarnodeAST; import ghidra.program.util.ContextEvaluatorAdapter; import ghidra.program.util.SymbolicPropogator; import ghidra.program.util.VarnodeContext; +import ghidra.util.task.TaskMonitor; public final class ReaGhidraBridge extends HeadlessScript { // At most 24 KiB after worst-case JSON escaping (six bytes per UTF-16 unit). @@ -1936,7 +1939,7 @@ public final class ReaGhidraBridge extends HeadlessScript { result.add( "native_api", decompilerFailure == null - ? nativeApiBoundary(function, decompilation) + ? nativeApiBoundary(function, decompilation, scan.instructions) : unavailableNativeApiBoundary(decompilerFailure) ); result.add( @@ -2803,7 +2806,8 @@ public final class ReaGhidraBridge extends HeadlessScript { private JsonObject nativeApiBoundary( Function function, - DecompileResults decompilation + DecompileResults decompilation, + List instructions ) throws Exception { if (decompilation == null || decompilation.getHighFunction() == null) { return unavailableNativeApiBoundary( @@ -2889,6 +2893,20 @@ public final class ReaGhidraBridge extends HeadlessScript { ); } + if (currentProgram.getLanguageID().getIdAsString().startsWith("x86:LE:32:")) { + DecompiledFunction inferred = decompilation.getDecompiledFunction(); + if (signatureSource.equals("analysis") && inferred != null) { + result.add( + "prototype_conflicts", + prototypeConflicts( + function, prototype, instructions, inferred.getSignature(), signatureSource) + ); + } + limitations.add( + "Prototype conflict checks cover direct EBP-framed argument reads and immediate RET cleanup under an inferred stdcall convention in analysis-inferred x86-32 signatures only; no diagnostic does not establish a correct signature." + ); + } + JumpTable[] recoveredJumpTables = highFunction.getJumpTables(); List caseTokens = new ArrayList<>(); if (decompilation.getCCodeMarkup() != null) { @@ -2900,6 +2918,228 @@ public final class ReaGhidraBridge extends HeadlessScript { return result; } + private JsonArray prototypeConflicts( + Function function, + FunctionPrototype prototype, + List instructions, + String signature, + String signatureSource + ) throws Exception { + JsonArray conflicts = new JsonArray(); + int count = prototype.getNumParams(); + if (count == 0) { + FrameRead read = framedStackRead(function.getEntryPoint(), instructions, monitor); + if (read != null) { + JsonObject conflict = prototypeConflict( + "stack-argument-read", signature, signatureSource, count, read.instruction()); + conflict.addProperty("frame_offset_bytes", read.offset()); + conflict.add("unresolved_assumptions", GSON.toJsonTree(List.of( + "The frame-relative read is not proof of a source-level parameter or its type.", + "The instruction does not establish the value's origin or the function's complete computation." + ))); + conflicts.add(conflict); + } + } + String convention = prototype.getModelName(); + if (!"__stdcall".equalsIgnoreCase(convention)) return conflicts; + int inferredStackBytes = 0; + for (int index = 0; index < count; index++) { + HighSymbol parameter = prototype.getParam(index); + if (parameter == null) return conflicts; + VariableStorage storage = parameter.getStorage(); + if (storage == null || !storage.isStackStorage() || storage.isCompoundStorage() || + storage.size() != 4 || storage.getStackOffset() != 4 + inferredStackBytes) + return conflicts; + inferredStackBytes += 4; + } + for (Instruction instruction : reachablePrototypeInstructions( + function.getEntryPoint(), instructions, monitor)) { + monitor.checkCancelled(); + Instruction terminal = instruction; + if (instruction.getMnemonicString().equalsIgnoreCase("JMP") && + instruction.getFlows().length == 1) { + Address target = instruction.getFlows()[0]; + // A direct one-hop shared epilogue is evidence, not additional owned + // body. A target belonging to another function is a tail call, whose + // cleanup belongs to that callee rather than this prototype. + if (!function.getBody().contains(target) && + functionAtOrContaining(target) == null) { + terminal = currentProgram.getListing().getInstructionAt(target); + if (terminal == null) continue; + } + } + Long cleanup = conflictingReturnCleanup(terminal, inferredStackBytes); + if (cleanup == null) continue; + JsonObject conflict = prototypeConflict( + "return-stack-cleanup", signature, signatureSource, count, terminal); + conflict.addProperty("cleanup_bytes", cleanup); + conflict.addProperty("inferred_stack_bytes", inferredStackBytes); + conflict.add("unresolved_assumptions", GSON.toJsonTree(List.of( + "The cleanup difference does not establish a missing, extra or differently sized source parameter.", + "Hidden arguments, alternate entry paths and the compiler's calling convention remain unverified." + ))); + conflicts.add(conflict); + break; + } + return conflicts; + } + + static Long conflictingReturnCleanup(Instruction instruction, int inferredStackBytes) { + if (!instruction.getMnemonicString().equalsIgnoreCase("RET") || + instruction.getNumOperands() != 1 || + !OperandType.isScalar(instruction.getOperandType(0))) return null; + Object[] objects = instruction.getOpObjects(0); + if (objects.length != 1 || !(objects[0] instanceof Scalar immediate)) return null; + long cleanup = immediate.getUnsignedValue(); + return cleanup <= 0xffff && cleanup != inferredStackBytes ? cleanup : null; + } + + private static Map decodedByAddress(List instructions) { + Map decoded = new HashMap<>(); + for (Instruction instruction : instructions) decoded.put(instruction.getAddress(), instruction); + return decoded; + } + + static List reachablePrototypeInstructions( + Address entry, List instructions, TaskMonitor monitor + ) throws Exception { + Map decoded = decodedByAddress(instructions); + List reachable = new ArrayList<>(); + Set
visited = new HashSet<>(); + ArrayDeque
pending = new ArrayDeque<>(); + pending.add(entry); + while (!pending.isEmpty()) { + monitor.checkCancelled(); + Address address = pending.removeFirst(); + if (!visited.add(address)) continue; + Instruction instruction = decoded.get(address); + if (instruction == null) continue; + reachable.add(instruction); + queuePrototypeSuccessors(instruction, decoded, pending); + } + return reachable; + } + + private static void queuePrototypeSuccessors( + Instruction instruction, Map decoded, ArrayDeque
pending + ) { + Address fallThrough = instruction.getFallThrough(); + if (fallThrough != null && decoded.containsKey(fallThrough)) pending.add(fallThrough); + // A call target's instructions belong to a different invocation. + if (instruction.getFlowType().isCall()) return; + for (Address destination : instruction.getFlows()) { + if (decoded.containsKey(destination)) pending.add(destination); + } + } + + /** Follow only decoded, reachable instruction edges while the entry EBP frame survives. */ + static FrameRead framedStackRead( + Address entry, + List instructions, + TaskMonitor monitor + ) throws Exception { + Map decoded = decodedByAddress(instructions); + // An owned block below the entry can precede it in the scan, so the + // prologue is located by address instead of list position. + Instruction push = decoded.get(entry); + Instruction frame = push == null ? null : decoded.get(push.getFallThrough()); + if (push == null || frame == null || + !push.getMnemonicString().equalsIgnoreCase("PUSH") || + !registerOperand(push, 0, "EBP") || + !frame.getMnemonicString().equalsIgnoreCase("MOV") || + !registerOperand(frame, 0, "EBP") || + !registerOperand(frame, 1, "ESP")) + return null; + ArrayDeque
pending = new ArrayDeque<>(); + if (frame.getFallThrough() != null) pending.add(frame.getFallThrough()); + Set
visited = new HashSet<>(); + while (!pending.isEmpty()) { + monitor.checkCancelled(); + Address address = pending.removeFirst(); + if (!visited.add(address)) continue; + Instruction instruction = decoded.get(address); + if (instruction == null) continue; + Long offset = frameArgumentOffset(instruction); + if (offset != null) return new FrameRead(instruction, offset); + // The read uses the old EBP value; a write invalidates only successors. + if (writesFramePointer(instruction)) continue; + queuePrototypeSuccessors(instruction, decoded, pending); + } + return null; + } + + static record FrameRead(Instruction instruction, long offset) {} + + private static Long frameArgumentOffset(Instruction instruction) { + PcodeOp[] operations = instruction.getPcode(); + for (int operand = 0; operand < instruction.getNumOperands(); operand++) { + int type = instruction.getOperandType(operand); + if (!OperandType.isDynamic(type) && !OperandType.isIndirect(type)) continue; + Object[] objects = instruction.getOpObjects(operand); + if (objects.length != 2) continue; + Register base = null; + Scalar offset = null; + for (Object object : objects) { + if (object instanceof Register register) base = register; + else if (object instanceof Scalar scalar) offset = scalar; + } + // An indexed operand has additional objects, not a direct [EBP + disp]. + if (base == null || offset == null || + !base.getName().equalsIgnoreCase("EBP") || offset.getSignedValue() < 8) + continue; + PcodeOp[] addressOps = instruction.getPcode(operand); + if (addressOps.length == 0) continue; + Varnode pointer = addressOps[addressOps.length - 1].getOutput(); + if (pointer == null) continue; + for (PcodeOp operation : operations) { + // LOAD's second input is the address being read. A LOAD from + // ESP (POP's source) cannot justify a read through [EBP + disp]. + if (operation.getOpcode() == PcodeOp.LOAD && + pointer.equals(operation.getInput(1))) return offset.getSignedValue(); + } + } + return null; + } + + private static boolean writesFramePointer(Instruction instruction) { + Register frame = instruction.getProgram().getRegister("EBP"); + if (frame == null) return true; + for (Object object : instruction.getResultObjects()) { + if (object instanceof Register register && + register.getBaseRegister().equals(frame.getBaseRegister())) return true; + } + // Include implicit and partial-register writes even when the listing's + // result-object summary omits them (for example LEAVE or XCHG). + for (PcodeOp operation : instruction.getPcode()) { + Varnode output = operation.getOutput(); + if (output == null || !output.isRegister()) continue; + Register register = instruction.getProgram().getRegister(output); + if (register != null && + register.getBaseRegister().equals(frame.getBaseRegister())) return true; + } + return false; + } + + private static boolean registerOperand(Instruction instruction, int index, String name) { + if (instruction.getNumOperands() <= index) return false; + Object[] objects = instruction.getOpObjects(index); + return objects.length == 1 && objects[0] instanceof Register register && + register.getName().equalsIgnoreCase(name); + } + + private static JsonObject prototypeConflict( + String kind, String signature, String source, int count, Instruction instruction + ) { + JsonObject conflict = new JsonObject(); + conflict.addProperty("kind", kind); + conflict.addProperty("inferred_signature", signature); + conflict.addProperty("signature_source", source); + conflict.addProperty("inferred_parameter_count", count); + conflict.addProperty("instruction_address", canonicalAddress(instruction.getAddress())); + conflict.addProperty("instruction", renderInstruction(instruction)); + return conflict; + } + private static JsonObject unavailableNativeValueFlow(String reason) { JsonObject unavailable = new JsonObject(); unavailable.addProperty("available", false); @@ -4363,19 +4603,23 @@ public final class ReaGhidraBridge extends HeadlessScript { private static List renderAssemblyLines(List instructions) { List result = new ArrayList<>(); for (Instruction instruction : instructions) { - StringBuilder line = new StringBuilder(); - line.append(canonicalAddress(instruction.getAddress())); - line.append(": "); - line.append(instruction.getMnemonicString()); - for (int index = 0; index < instruction.getNumOperands(); index += 1) { - line.append(index == 0 ? " " : ", "); - line.append(instruction.getDefaultOperandRepresentation(index)); - } - result.add(line.toString()); + result.add( + canonicalAddress(instruction.getAddress()) + ": " + renderInstruction(instruction) + ); } return result; } + private static String renderInstruction(Instruction instruction) { + StringBuilder line = new StringBuilder(); + line.append(instruction.getMnemonicString()); + for (int index = 0; index < instruction.getNumOperands(); index += 1) { + line.append(index == 0 ? " " : ", "); + line.append(instruction.getDefaultOperandRepresentation(index)); + } + return line.toString(); + } + private List collectReferences( Function function, String direction) throws Exception { diff --git a/docs/guides/native/native-investigation.md b/docs/guides/native/native-investigation.md index de0ec97108..820fb7dc8e 100644 --- a/docs/guides/native/native-investigation.md +++ b/docs/guides/native/native-investigation.md @@ -34,6 +34,24 @@ Select an exact name or address from the returned inventory, then use it with that every target names its entry function `entry`. MCP uses `open_binary` and focused tools such as `list_procedures` and `analyze_function` on the same session. +For analysis-inferred x86-32 Ghidra signatures, `native_api.prototype_conflicts` can +identify a direct `EBP`-framed stack argument read beyond a zero-parameter +inference, or an immediate `RET` cleanup (including zero) that disagrees with an +inferred `stdcall` prototype whose parameters are simple four-byte stack slots. +Each +diagnostic retains the inferred claim, decoded instruction address/text, +observed offset or cleanup size, and unresolved assumptions. It does **not** +change the inferred signature or establish source-level parameters. The default +`analyze_function` summary reports the diagnostic count; request the complete +dossier, `inspect_native_api`, or a retained `native_api` view for the records. +An omitted conflict list means this check was not recorded (including other +providers and architectures); an empty list does not prove a correct prototype. +The `EBP` read check requires an explicit `PUSH EBP; MOV EBP, ESP` entry frame, +a reachable direct `[EBP + displacement]` operand on a path that has not +overwritten `EBP`, and no inferred parameters. Return +cleanup covers immediate `RET` instructions in the owned body or a direct, +one-hop shared epilogue without expanding body ownership. + | Question | Section | | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | Which instructions, calls, references, or types are present? | [Native primitives](#native-instruction-call-and-type-primitives) | diff --git a/scripts/ci/scopes.mjs b/scripts/ci/scopes.mjs index cd3d3b1803..53aa7d872c 100644 --- a/scripts/ci/scopes.mjs +++ b/scripts/ci/scopes.mjs @@ -677,12 +677,14 @@ const PATH_SCOPES = { "src/ghidra/GhidraJavaProperties.ts", "src/ghidra/GhidraReleasePolicy.ts", "scripts/verify-ghidra-bridge-sources.mjs", + "scripts/verify-ghidra-prototype-conflicts.mjs", "tests/conformance/ghidra/ReaInstructionContextProbe.java", "tests/conformance/ghidra/ReaComputedCallCoverageProbe.java", "tests/conformance/ghidra/ReaDecodeProbe.java", "scripts/verify-ghidra-loader-relocation.mjs", "tests/conformance/ghidra/ReaLoaderRelocationProbe.java", "tests/conformance/ghidra/loader-relocation*.c", + "tests/conformance/ghidra/ReaPrototypeConflictProbe.java", ".github/workflows/ghidra-bridge-sources.yml", ], go_binary: [ diff --git a/scripts/verify-ghidra-prototype-conflicts.mjs b/scripts/verify-ghidra-prototype-conflicts.mjs new file mode 100644 index 0000000000..31c8335110 --- /dev/null +++ b/scripts/verify-ghidra-prototype-conflicts.mjs @@ -0,0 +1,177 @@ +#!/usr/bin/env node +// Decode source-owned x86 bytes with the installed Ghidra, then run the bridge +// producer's frame/cleanup checks. The temporary project is isolated outside +// the checkout so failed verification cannot affect an analyst's database. +import assert from "node:assert/strict"; +import { copyFile, mkdir, readdir, writeFile } from "node:fs/promises"; +import { join, resolve } from "node:path"; + +import { cleanupOwnedProcessGroup } from "../dist/process/ProcessOwnership.js"; +import { + ProviderProcessSupervisor, + spawnOwnedProviderProcess, +} from "../dist/process/ProviderProcess.js"; +import { verifierFailureReasons } from "./lib/verifier-cleanup.mjs"; +import { + VerifierFixture, + withVerifierFixture, +} from "./lib/verifier-fixture.mjs"; +import { createVerifierRun } from "./lib/verifier-run.mjs"; + +const install = process.env.GHIDRA_INSTALL_DIR; +if (!install) throw new Error("Set GHIDRA_INSTALL_DIR to Ghidra 12.1.4"); +const root = resolve(import.meta.dirname, ".."); +const run = createVerifierRun(); + +// The fixture owns the workspace root: Ghidra's headless launcher writes the +// project beneath it, so it is a plain temporary root, and it is removed only +// after the owned process confirms cleanup — otherwise it is retained and +// named for diagnosis. +const fixture = await VerifierFixture.open({ + prefix: "rea-prototype-conflicts-", + private: false, +}); +const scratch = fixture.path; +const controller = new AbortController(); +let interruptHandler; +const interrupted = new Promise((resolve) => { + interruptHandler = (signal) => { + controller.abort(new Error(`${signal} requested`)); + resolve(false); + }; +}); +const handleSigint = () => interruptHandler("SIGINT"); +const handleSigterm = () => interruptHandler("SIGTERM"); +process.on("SIGINT", handleSigint); +process.on("SIGTERM", handleSigterm); +let supervisor; +let cleanupStep = "owned process cleanup"; +fixture.releaseAfter(async () => { + if (supervisor !== undefined) { + const stopped = await supervisor.stop(); + assert.equal( + stopped.status, + "verified-cleanup", + `Ghidra process cleanup could not be verified: ${ + "reason" in stopped ? stopped.reason : String(stopped.status) + }`, + ); + } + cleanupStep = "temporary workspace deletion"; +}); +const probe = async () => { + const project = join(scratch, "project"); + await mkdir(project); + const scripts = join(scratch, "scripts"); + await mkdir(scripts); + for (const name of await readdir(join(root, "bridge/ghidra"))) { + if (name.endsWith(".java")) + await copyFile(join(root, "bridge/ghidra", name), join(scripts, name)); + } + await copyFile( + join(root, "tests/conformance/ghidra/ReaPrototypeConflictProbe.java"), + join(scripts, "ReaPrototypeConflictProbe.java"), + ); + const image = Buffer.alloc(0x0b00, 0xcc); + for (const [offset, hex] of [ + // JNE skips the early LEAVE; RET and reaches MOV ECX, [EBP + 8]. + [0x000, "5589e583f8007502c9c38b4d08c9c3"], + [0x100, "5589e587e88b4d08c9c3"], // XCHG EAX, EBP + [0x200, "5589e56689c58b4d08c9c3"], // MOV BP, AX + [0x300, "5589e58b4d08c9c3"], + [0x400, "c20800"], // RET 8 + [0x500, "c20000"], // RET 0 + [0x600, "5589e58b6d088b4d08c9c3"], // MOV EBP,[EBP+8], then a stale-frame read + [0x700, "5589e58f4508c9c3"], // POP [EBP+8] reads [ESP], not the destination + [0x800, "5589e58b4d08c9c3"], // Entry frame whose owned block sits below it. + [0xa00, "90c3"], // A decoded lower block that precedes the entry in the scan. + ]) { + Buffer.from(hex, "hex").copy(image, offset); + } + const imagePath = join(scratch, "instructions.bin"); + await writeFile(imagePath, image); + const launch = await spawnOwnedProviderProcess({ + command: join(install, "support/analyzeHeadless"), + arguments: [ + project, + "PrototypeConflicts", + "-import", + imagePath, + "-loader", + "BinaryLoader", + "-loader-baseAddr", + "0x1000", + "-processor", + "x86:LE:32:default", + "-noanalysis", + "-readOnly", + "-scriptPath", + scripts, + "-postScript", + "ReaPrototypeConflictProbe.java", + ], + runId: run.run_id, + expectedCommand: null, + cwd: scratch, + env: { JAVA_HOME: process.env.JAVA_HOME }, + signal: controller.signal, + }); + supervisor = new ProviderProcessSupervisor( + { + ...launch, + ownsProcessLifetime: true, + cleanup: () => cleanupOwnedProcessGroup(launch.ownership), + }, + { maxDiagnosticBytes: 8 * 1024 * 1024 }, + ); + const exited = await Promise.race([ + supervisor.waitForExit(180_000), + interrupted, + ]); + if (controller.signal.aborted) + throw new Error( + "Ghidra prototype conflict probe interrupted by SIGINT/SIGTERM", + ); + assert.ok(exited, "Ghidra prototype conflict probe timed out"); + assert.ok( + await supervisor.waitForOutputClose(1_000), + "Ghidra prototype conflict probe output did not close", + ); + const snapshot = supervisor.snapshot(); + const output = `${snapshot.stdout.text}\n${snapshot.stderr.text}`; + assert.equal(snapshot.exitCode, 0, output); + assert.match(output, /REA_PROTOTYPE_CONFLICT_OK/u, output.slice(-6000)); +}; + +try { + // The shared owner releases the fixture only after the registered cleanup + // confirms. A combined failure keeps the probe error as its cause and the + // retained root as its cleanup lease, so neither failure nor the owner of + // an unsafe tree is dropped from the error the caller receives. + await withVerifierFixture(fixture, probe); +} catch (cause) { + if (!fixture.released) { + // Retain cleanup diagnostics and possible evidence instead of replacing + // the cleanup failure with an interruption or deleting an unsafe tree. + console.error( + `Ghidra verifier failed during ${cleanupStep}: ${verifierFailureReasons( + cause, + ).join("; ")}`, + ); + if (cleanupStep !== "temporary workspace deletion") + console.error( + `Retained failed Ghidra verification project at ${scratch}`, + ); + } + throw cause; +} finally { + // Keep cleanup handlers installed until release has finished, so an + // interrupt cannot terminate the verifier before its owner resumes. + process.off("SIGINT", handleSigint); + process.off("SIGTERM", handleSigterm); +} +if (controller.signal.aborted) + throw new Error( + "Ghidra prototype conflict probe interrupted by SIGINT/SIGTERM", + ); +console.log("REA_PROTOTYPE_CONFLICT_OK"); diff --git a/src/domain/analysisView/analysisViewResult.ts b/src/domain/analysisView/analysisViewResult.ts index d176668b4e..a0b7c63970 100644 --- a/src/domain/analysisView/analysisViewResult.ts +++ b/src/domain/analysisView/analysisViewResult.ts @@ -1125,6 +1125,7 @@ export const nativeFunctionSummarySchema = z.strictObject({ referenced_names: declaredFacetCountSchema, swift_string_literals: recordedFacetCountSchema, swift_string_literal_omissions: recordedFacetCountSchema, + prototype_conflicts: recordedFacetCountSchema.optional(), value_flow_operations: valueFlowFacetCountSchema, value_flow_def_use: valueFlowFacetCountSchema, value_flow_effects: valueFlowFacetCountSchema, diff --git a/src/domain/analysisView/nativeFunctionView.ts b/src/domain/analysisView/nativeFunctionView.ts index 2747ea2ab1..03de56d355 100644 --- a/src/domain/analysisView/nativeFunctionView.ts +++ b/src/domain/analysisView/nativeFunctionView.ts @@ -187,6 +187,11 @@ const summarizeDossier = (dossier: FunctionDossier) => { swift_string_literal_omissions: recorded( dossier.swift_string_literal_omissions, ), + prototype_conflicts: recorded( + dossier.native_api?.available + ? dossier.native_api.prototype_conflicts + : undefined, + ), // Value-flow rows are unknown, not zero, when value flow was not recorded // or the provider declared it unavailable; parentFields names which. value_flow_operations: flow?.operations.length ?? null, diff --git a/src/domain/native/nativeApiBoundary.ts b/src/domain/native/nativeApiBoundary.ts index 09b021c118..495caa10ed 100644 --- a/src/domain/native/nativeApiBoundary.ts +++ b/src/domain/native/nativeApiBoundary.ts @@ -87,6 +87,31 @@ const inferredJumpTableSchema = z }) .strict(); +const prototypeConflictFacts = { + inferred_signature: z.string().min(1), + signature_source: z.string().min(1), + inferred_parameter_count: z.int().nonnegative(), + instruction_address: z.string().min(1), + instruction: z.string().min(1), + unresolved_assumptions: z.array(z.string().min(1)).min(1), +} as const; +const prototypeConflictSchema = z.discriminatedUnion("kind", [ + z.strictObject({ + ...prototypeConflictFacts, + kind: z.literal("stack-argument-read"), + frame_offset_bytes: z.int().positive(), + }), + z.strictObject({ + ...prototypeConflictFacts, + kind: z.literal("return-stack-cleanup"), + cleanup_bytes: z.int().nonnegative(), + inferred_stack_bytes: z.int().nonnegative(), + }), +]); + +/** One instruction-level disagreement between an inferred prototype and observed code. */ +export type NativePrototypeConflict = z.infer; + export const availableNativeApiBoundarySchema = z .object({ available: z.literal(true), @@ -95,6 +120,8 @@ export const availableNativeApiBoundarySchema = z calling_convention: z.string().min(1), return_type: inferredReturnTypeSchema, parameters: z.array(inferredParameterTypeSchema), + /** Omitted on older dossiers or providers without an instruction consistency check. */ + prototype_conflicts: z.array(prototypeConflictSchema).exactOptional(), jump_tables: z.array(inferredJumpTableSchema), pseudocode: z .object({ diff --git a/tests/boundary/filesystem/ciChangeScope.test.ts b/tests/boundary/filesystem/ciChangeScope.test.ts index 9509b8ff09..2177c9b11e 100644 --- a/tests/boundary/filesystem/ciChangeScope.test.ts +++ b/tests/boundary/filesystem/ciChangeScope.test.ts @@ -1101,6 +1101,10 @@ it.each([ "scripts/verify-ghidra-loader-relocation.mjs", { code: true, ghidra_bridge: true, runtime: false, package: false }, ], + [ + "scripts/verify-ghidra-prototype-conflicts.mjs", + { code: true, ghidra_bridge: true, runtime: false, package: false }, + ], [ "tests/conformance/ghidra/ReaLoaderRelocationProbe.java", { code: true, ghidra_bridge: true, runtime: false, package: false }, @@ -1137,6 +1141,10 @@ it.each([ "tests/conformance/ghidra/ReaDecodeProbe.java", { ghidra_bridge: true, runtime: false, package: false }, ], + [ + "tests/conformance/ghidra/ReaPrototypeConflictProbe.java", + { ghidra_bridge: true, runtime: false, package: false }, + ], [ "bridge/ghidra/Example.java", { diff --git a/tests/boundary/mcp/ghidraNativeApiMcp.test.ts b/tests/boundary/mcp/ghidraNativeApiMcp.test.ts index 626bf77962..8dbc8fc101 100644 --- a/tests/boundary/mcp/ghidraNativeApiMcp.test.ts +++ b/tests/boundary/mcp/ghidraNativeApiMcp.test.ts @@ -14,6 +14,7 @@ import { join } from "node:path"; import { jsonValueSchema } from "../../../src/domain/jsonValue.js"; import { nativeLoadImageSchema } from "../../../src/domain/native/nativeLoadImage.js"; import { nativeApiInspectionResultSchema } from "../../../src/domain/native/nativeApiBoundary.js"; +import type { NativePrototypeConflict } from "../../../src/domain/native/nativeApiBoundary.js"; import { functionDossierSchema } from "../../../src/domain/native/functionDossier.js"; import { ok } from "../../../src/domain/result.js"; import { ghidraFunctionDossier } from "../../../src/domain/ghidraValues.fixture.js"; @@ -186,6 +187,151 @@ it.each([ }, ); +const prototypeConflicts = (): NativePrototypeConflict[] => [ + { + kind: "stack-argument-read", + inferred_signature: "undefined f(void)", + signature_source: "analysis", + inferred_parameter_count: 0, + instruction_address: "0x406400", + instruction: "FLD qword ptr [EBP + 0x8]", + frame_offset_bytes: 8, + unresolved_assumptions: [ + "The frame-relative read is not proof of a source-level parameter.", + ], + }, + { + kind: "return-stack-cleanup", + inferred_signature: "undefined f(int, int, int, int)", + signature_source: "analysis", + inferred_parameter_count: 4, + instruction_address: "0x401b10", + instruction: "RET 0x14", + cleanup_bytes: 20, + inferred_stack_bytes: 16, + unresolved_assumptions: [ + "The cleanup difference does not prove a fifth source parameter.", + ], + }, + { + kind: "return-stack-cleanup", + inferred_signature: "undefined g(int, int, int, int)", + signature_source: "analysis", + inferred_parameter_count: 4, + instruction_address: "0x401c00", + instruction: "RET 0x0", + cleanup_bytes: 0, + inferred_stack_bytes: 16, + unresolved_assumptions: [ + "A zero-byte cleanup does not establish the compiler's calling convention.", + ], + }, + { + kind: "return-stack-cleanup", + inferred_signature: "undefined h(void)", + signature_source: "analysis", + inferred_parameter_count: 0, + instruction_address: "0x401d00", + instruction: "RET 0x8", + cleanup_bytes: 8, + inferred_stack_bytes: 0, + unresolved_assumptions: [ + "A nonzero cleanup does not establish a source-level parameter.", + ], + }, +]; + +const connectPrototypeConflictHarness = async (name: string) => { + const dossier = functionDossierSchema.parse(ghidraFunctionDossier()); + if (!dossier.native_api?.available) throw new Error("Expected native API"); + const conflicts = prototypeConflicts(); + dossier.native_api.prototype_conflicts = conflicts; + const harness = await connectGhidraMcp(name, async (operation) => { + if (operation !== "analyze_function") + throw new Error(`Unexpected operation: ${operation}`); + return ok(jsonValueSchema.parse({ value: dossier, limitations: [] })); + }); + return { harness, conflicts }; +}; + +describe("Ghidra prototype conflict diagnostics", () => { + it("reports prototype conflicts in the summary and complete dossier", async () => { + const { harness, conflicts } = await connectPrototypeConflictHarness( + "ghidra-prototype-conflicts-analysis", + ); + try { + const summary = await harness.mcp.callTool({ + name: "analyze_function", + arguments: { procedure: "fixture_main" }, + }); + expect(summary.isError).not.toBe(true); + expect( + sessionEvidence(harness.session, summary.structuredContent) + .normalized_result, + ).toMatchObject({ + summary: { counts: { prototype_conflicts: conflicts.length } }, + }); + const analyze = await harness.mcp.callTool({ + name: "analyze_function", + arguments: { procedure: "fixture_main", detail: "complete" }, + }); + expect(analyze.isError).not.toBe(true); + expect( + sessionEvidence(harness.session, analyze.structuredContent) + .normalized_result, + ).toMatchObject({ + native_api: { prototype_conflicts: conflicts }, + }); + } finally { + await harness.close(); + } + }); + + it("retains prototype conflicts through inspection and selected views", async () => { + const { harness, conflicts } = await connectPrototypeConflictHarness( + "ghidra-prototype-conflicts-views", + ); + try { + const analyze = await harness.mcp.callTool({ + name: "analyze_function", + arguments: { procedure: "fixture_main", detail: "complete" }, + }); + expect(analyze.isError).not.toBe(true); + const evidence = sessionEvidence( + harness.session, + analyze.structuredContent, + ); + const inspection = await harness.mcp.callTool({ + name: "inspect_native_api", + arguments: { procedure: "fixture_main" }, + }); + expect(inspection.isError).not.toBe(true); + expect( + sessionEvidence(harness.session, inspection.structuredContent) + .normalized_result, + ).toMatchObject({ boundary: { prototype_conflicts: conflicts } }); + const view = await harness.mcp.callTool({ + name: "inspect_analysis_view", + arguments: { + source: { + kind: "retained-evidence", + evidence_id: evidence.evidence_id, + }, + view: { kind: "native", facet: "native_api", offset: 0, limit: 64 }, + }, + }); + expect(view.isError).not.toBe(true); + expect( + sessionEvidence(harness.session, view.structuredContent), + ).toMatchObject({ + normalized_result: { item: { prototype_conflicts: conflicts } }, + }); + } finally { + await harness.close(); + } + }); +}); + describe("Ghidra MCP native API evidence", () => { it("retains transient failure Evidence without freezing the composed API inspection", async () => { let failed = true; diff --git a/tests/conformance/ghidra/ReaPrototypeConflictProbe.java b/tests/conformance/ghidra/ReaPrototypeConflictProbe.java new file mode 100644 index 0000000000..76096e047a --- /dev/null +++ b/tests/conformance/ghidra/ReaPrototypeConflictProbe.java @@ -0,0 +1,84 @@ +//@category REA Verification + +import ghidra.app.script.GhidraScript; +import ghidra.program.model.address.Address; +import ghidra.program.model.listing.Instruction; +import java.util.ArrayList; +import java.util.List; + +/** Check the producer's decoded-instruction rules, not a hand-built dossier. */ +public class ReaPrototypeConflictProbe extends GhidraScript { + @Override + public void run() throws Exception { + require(currentProgram.getLanguageID().getIdAsString().startsWith("x86:LE:32:"), + "The fixture requires x86-32"); + requireRead(0x1000, 0x100a); // Branch past an earlier LEAVE; RET. + requireNoRead(0x1100); // XCHG EAX, EBP before the frame-relative read. + requireNoRead(0x1200); // MOV BP, AX before the frame-relative read. + requireRead(0x1300, 0x1303); + requireRead(0x1600, 0x1603); // Read through old frame before overwriting EBP. + requireNoRead(0x1700); // POP [EBP+8] reads from ESP, not EBP. + requireLowerBlockRead(); // An owned block below entry precedes it in the scan. + Instruction ret8 = decode(0x1400).get(0); + Instruction ret0 = decode(0x1500).get(0); + List owned = List.of(ret8, ret0); + require(ReaGhidraBridge.reachablePrototypeInstructions(address(0x1500), owned, monitor) + .equals(List.of(ret0)), + "An unrelated owned return must not become prototype evidence"); + require(Long.valueOf(8).equals(ReaGhidraBridge.conflictingReturnCleanup(ret8, 0)), + "A zero-parameter stdcall RET 8 is a mismatch"); + require(Long.valueOf(0).equals(ReaGhidraBridge.conflictingReturnCleanup(ret0, 16)), + "A four-slot stdcall RET 0 is a mismatch"); + require(ReaGhidraBridge.conflictingReturnCleanup(ret8, 8) == null, + "Matching cleanup is not a conflict"); + println("REA_PROTOTYPE_CONFLICT_OK"); + } + + private void requireRead(long entry, long expected) throws Exception { + List instructions = decode(entry); + ReaGhidraBridge.FrameRead read = + ReaGhidraBridge.framedStackRead(address(entry), instructions, monitor); + require(read != null && read.instruction().getAddress().getOffset() == expected && + read.offset() == 8, "Expected entry-frame read at " + Long.toHexString(expected)); + } + + private void requireNoRead(long entry) throws Exception { + require(ReaGhidraBridge.framedStackRead(address(entry), decode(entry), monitor) == null, + "EBP no longer holds the entry frame at " + Long.toHexString(entry)); + } + + private Address address(long offset) { + return currentProgram.getAddressFactory().getDefaultAddressSpace().getAddress(offset); + } + + /** + * A block owned below the entry can appear first in an address-ordered scan. + * The prologue must still be found by the function's entry address. + */ + private void requireLowerBlockRead() throws Exception { + List entry = decode(0x1800); + List lower = decode(0x1a00); + require(!lower.isEmpty(), "The lower block requires decoded instructions"); + List scanned = new ArrayList<>(lower); + scanned.addAll(entry); + ReaGhidraBridge.FrameRead read = + ReaGhidraBridge.framedStackRead(address(0x1800), scanned, monitor); + require(read != null && read.instruction().getAddress().getOffset() == 0x1803 && + read.offset() == 8, "A lower owned block must not hide the entry frame"); + } + + private List decode(long entry) throws Exception { + Address address = address(entry); + disassemble(address); + List instructions = new ArrayList<>(); + for (Instruction instruction : currentProgram.getListing().getInstructions(true)) { + long offset = instruction.getAddress().getOffset(); + if (offset >= entry && offset < entry + 0x40) instructions.add(instruction); + } + return instructions; + } + + private static void require(boolean condition, String message) { + if (!condition) throw new IllegalStateException(message); + } +}