Files
reverse-engineering-anything/scripts/verify-real-ghidra-address-context.mjs
T
d5818ad0da refactor(verify): run Ghidra verifier commands through the supervised owner (1 of 2) (#12719)
* refactor(verify): run Ghidra verifier commands through the supervised owner

Route the first Ghidra verifier batch's compilers, linkers, and CLI through
createVerifierCommands, and close that owner before the lineage check.
Replace MCP isError prose checks with the structured refusal each tool builds.

* fix(verify): resolve Windows 6502 toolchain names through the command owner

runOwnedCommand passes a bare ca65 or ld65 name to the Windows process
owner, which accepts only a drive-absolute path. The verifier command
owner resolves those PATH names before launch.

Co-authored-by: morluto <morluto@users.noreply.github.com>

* fix(verify): release the Ghidra fixture when a toolchain probe fails

retain() only registered a cleanup that nothing ran, so a failed compiler
probe left the empty fixture directory behind. Release it after the command
owner closes, and name the retained path when that close does not confirm.

Co-authored-by: morluto <morluto@users.noreply.github.com>

* fix(verify): close the m68k command owner when session shutdown fails

Client, transport, and command cleanup are independent. A failed client or
transport close, or a failed runtime read, no longer skips the command owner.

Co-authored-by: morluto <morluto@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <morluto@users.noreply.github.com>
2026-11-19 23:04:57 -05:00

380 lines
13 KiB
JavaScript

import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import { mkdir, readFile, readdir } from "node:fs/promises";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { parseEvidence } from "../dist/domain/evidence.js";
import {
requireMcpOperationResult,
requireMcpOutput,
requireMcpToolError,
} from "./lib/mcp-verifier-results.mjs";
import {
assertVerifierCleanupComplete,
createVerifierRun,
completeVerifierRun,
} from "./lib/verifier-run.mjs";
import { createVerifierCommands } from "./lib/verify-commands.mjs";
import { VerifierFixture } from "./lib/verifier-fixture.mjs";
if (process.argv.length !== 2 || process.platform !== "linux")
throw new Error("Run this ELF verifier on Linux without arguments.");
if (!process.env.GHIDRA_INSTALL_DIR)
throw new Error("Set GHIDRA_INSTALL_DIR to a caller-installed Ghidra.");
const run = createVerifierRun();
const root = fileURLToPath(new URL("..", import.meta.url));
// Ghidra children use the workspace as TMPDIR; a plain root admits them on every host.
const workspaceFixture = await VerifierFixture.open({
prefix: "rea-address-context-",
private: false,
});
const workspace = workspaceFixture.path;
const runtime = join(workspace, "runtime");
await mkdir(runtime);
const path = join(workspace, "pie.elf");
const entrypoint = join(root, "scripts/rea.mjs");
const env = {
...process.env,
TMPDIR: runtime,
REA_ANALYSIS_PROVIDER: "ghidra",
REA_LOG_LEVEL: "silent",
};
// Compiler and CLI share one command owner, created before either starts.
const commands = await createVerifierCommands();
const transport = new StdioClientTransport({
command: process.execPath,
args: [entrypoint, "mcp"],
env,
stderr: "pipe",
});
const client = new Client({ name: "rea-real-address-context", version: "1" });
let stderr = "";
transport.stderr?.on("data", (chunk) => {
stderr = (stderr + chunk.toString()).slice(-65536);
});
let report;
let connected = false;
let primaryFailure;
let verifierRun;
try {
const compiler = process.env.CC ?? "gcc";
const version = await commands.exec(compiler, ["--version"], {
timeout: 10000,
});
await commands.exec(
compiler,
[
"-O0",
"-g",
"-fPIE",
"-pie",
"-nostdlib",
"-Wl,-e,rea_pie_entry",
"-Wl,--build-id=none",
join(root, "tests/conformance/c/pie-address-context.c"),
"-o",
path,
],
{ timeout: 30000 },
);
const bytes = await readFile(path);
assert.equal(bytes.subarray(0, 6).toString("hex"), "7f454c460201");
assert.equal(bytes.readUInt16LE(16), 3); // ET_DYN: source-owned x86-64 PIE.
assert.equal(bytes.readUInt16LE(18), 62);
const declaredEntry = `0x${bytes.readBigUInt64LE(24).toString(16)}`;
const sha256 = createHash("sha256").update(bytes).digest("hex");
await client.connect(transport);
connected = true;
await call("open_binary", { path, provider_id: "ghidra" });
const overview = parseEvidence(await call("binary_overview"));
assert.equal(overview.subject.identity.sha256, sha256);
const base = overview.normalized_result.image_base;
assert.match(base, /^0x[0-9a-f]+$/u);
assert.notEqual(base, "0x0");
const active = await call("binary_session");
const image = parseEvidence(await call("inspect_native_load_image"));
assert.equal(base, image.normalized_result.observations.image_base);
assert.ok(overview.normalized_result.segments.length > 0);
assert.ok(
overview.normalized_result.segments.every(
(segment) =>
segment.image_base === base &&
typeof segment.address_space === "string",
),
);
const procedures = parseEvidence(await call("list_procedures"));
const strings = parseEvidence(await call("list_strings"));
assert.equal(
overview.normalized_result.procedure_count,
procedures.normalized_result.length,
);
assert.equal(
overview.normalized_result.string_count,
strings.normalized_result.length,
);
assert.ok(
overview.limitations.some((text) =>
text.includes("Ghidra-defined string Data"),
),
);
const entry = procedures.normalized_result.find(
(item) => item.value === "rea_pie_entry",
);
const addition = procedures.normalized_result.find(
(item) => item.value === "rea_pie_add",
);
assert.ok(entry && addition);
assert.notEqual(entry.address, declaredEntry);
assert.ok(
image.normalized_result.observations.entry_points.includes(entry.address),
);
const mapping = image.normalized_result.observations.mappings.find(
(item) =>
item.source_file_index === 0 &&
item.file_offset !== null &&
item.address_space === "ram" &&
BigInt(item.start) <= BigInt(entry.address) &&
BigInt(item.end) >= BigInt(entry.address),
);
assert.ok(mapping);
const offset =
mapping.file_offset + Number(BigInt(entry.address) - BigInt(mapping.start));
const reverseMapping = parseEvidence(
await call("address_to_file_offset", { address: entry.address }),
);
assert.equal(reverseMapping.normalized_result.file_offset, offset);
const memory = parseEvidence(
await call("read_bytes", { address: entry.address, length: 8 }),
);
assert.equal(
memory.normalized_result.bytes_hex,
bytes.subarray(offset, offset + 8).toString("hex"),
);
const fromOffset = parseEvidence(
await call("procedure_pseudo_code", {
procedure: `file-offset:0x${offset.toString(16)}`,
}),
);
assert.ok(
fromOffset.locations.some(
(location) =>
location.kind === "file-offset" && location.offset === offset,
),
);
assert.equal(fromOffset.raw_result.selection.mapped_address, entry.address);
const fromNumericOffset = parseEvidence(
await call("procedure_pseudo_code", {
procedure: `0x${offset.toString(16)}`,
}),
);
assert.equal(
fromNumericOffset.normalized_result,
fromOffset.normalized_result,
);
const missingProcedure = "rea_missing_procedure_fixture";
const missingName = await client.callTool(
{
name: "procedure_pseudo_code",
arguments: { procedure: missingProcedure },
},
{ timeout: 240000 },
);
assert.equal(missingName.isError, true);
const missingNameError = JSON.parse(
missingName.content.find((item) => item.type === "text").text,
).error;
assert.equal(missingNameError.code, "invalid_request");
assert.match(missingNameError.message, /rea_missing_procedure_fixture/u);
assert.match(missingNameError.remediation.action, /list_procedures/u);
assert.match(missingNameError.remediation.action, /does not prove/u);
assert.equal(missingNameError.recovery, undefined);
const unmappedOffset = await client.callTool(
{
name: "procedure_pseudo_code",
arguments: { procedure: "file-offset:0x1fffffffffffff" },
},
{ timeout: 240000 },
);
assert.equal(unmappedOffset.isError, true);
const unmappedError = JSON.parse(
unmappedOffset.content.find((item) => item.type === "text").text,
).error;
assert.equal(unmappedError.code, "invalid_request");
assert.match(unmappedError.message, /no loaded source mapping/u);
assert.match(unmappedError.remediation.action, /inspect_native_load_image/u);
assert.equal(unmappedError.recovery, undefined);
const missingAddress = "ram:0xffffffff";
const rejected = await client.callTool(
{ name: "procedure_pseudo_code", arguments: { procedure: missingAddress } },
{ timeout: 240000 },
);
// procedure_not_found keeps the caller-selected procedure and the inventory tools.
const rejectedError = requireMcpToolError(rejected);
assert.partialDeepStrictEqual(rejectedError, {
code: "invalid_request",
details: {
operation: "procedure_pseudo_code",
related_operations: ["list_procedures", "search_procedures"],
issues: [
{
path: ["procedure"],
reason: "invalid_value",
observed: { procedure: missingAddress },
},
],
diagnostics: { remote_code: "procedure_not_found" },
},
});
assert.equal(rejectedError.recovery, undefined);
const pseudo = parseEvidence(
await call("procedure_pseudo_code", { procedure: addition.address }),
);
assert.match(pseudo.normalized_result, /\+\s*(?:7|0x7)\b/u);
const retained = await call("binary_session");
assert.equal(retained.analysis_run.run_id, active.analysis_run.run_id);
await call("close_binary");
const cli = async (args) =>
commands.exec(
process.execPath,
[entrypoint, ...args, "--provider", "ghidra", "--json"],
{ env, timeout: 240000, maxBuffer: 16 * 1024 * 1024 },
);
const cliOverview = parseEvidence(
JSON.parse((await cli(["analyze", path])).stdout),
);
assert.deepEqual(cliOverview.normalized_result, overview.normalized_result);
let cliFailure;
try {
await cli(["decompile", path, missingAddress]);
} catch (cause) {
cliFailure = cause;
}
const cliStdout = cliFailure?.snapshot?.stdout?.text;
assert.equal(typeof cliStdout, "string");
const error = JSON.parse(cliStdout);
assert.equal(error.code, "invalid_request");
assert.ok(JSON.stringify(error).includes(`Ghidra image base: ${base}`));
for (const command of [
"rea search <path> . --kind procedures --mode regex",
"rea analyze <path>",
"rea inspect-native-load-image <path>",
])
assert.ok(JSON.stringify(error).includes(command));
const cliProcedures = parseEvidence(
JSON.parse(
(
await cli([
"search",
path,
".",
"--kind",
"procedures",
"--mode",
"regex",
])
).stdout,
),
);
const cliEntry = cliProcedures.normalized_result.find(
(item) => item.value === "rea_pie_entry",
);
assert.ok(cliEntry);
assert.equal(cliEntry.address, entry.address);
const cliImage = parseEvidence(
JSON.parse((await cli(["inspect-native-load-image", path])).stdout),
);
assert.equal(cliImage.normalized_result.observations.image_base, base);
const cliPseudo = parseEvidence(
JSON.parse((await cli(["decompile", path, cliEntry.address])).stdout),
);
const cliOffset = parseEvidence(
JSON.parse(
(await cli(["decompile", path, `--file-offset=0x${offset.toString(16)}`]))
.stdout,
),
);
assert.equal(cliOffset.normalized_result, fromOffset.normalized_result);
assert.deepEqual(cliOffset.locations, fromOffset.locations);
assert.match(cliPseudo.normalized_result, /rea_pie_add/u);
assert.deepEqual(await readFile(path), bytes);
assert.deepEqual(await readdir(runtime), []);
report = {
ok: true,
mocked: false,
provider: image.provider,
compiler: version.stdout.split("\n")[0],
sha256,
declared_elf_entry: declaredEntry,
loaded_entry: entry.address,
observed_image_base: base,
cli_mcp_overview_parity: true,
failed_lookup_guidance: true,
cli_recovery_commands: true,
loaded_decompilation: true,
file_offset_decompilation: true,
address_file_offset_round_trip: true,
source_unchanged: true,
runtime_cleanup: "complete",
};
} catch (cause) {
primaryFailure = { cause };
if (stderr) process.stderr.write(stderr);
}
const cleanupFailures = [];
// Await provider-owned cleanup before the SDK can terminate its MCP parent.
// The workspace is removed only after every cleanup and check confirms.
if (connected) workspaceFixture.releaseAfter(() => call("close_binary"));
workspaceFixture.releaseAfter(() => client.close());
workspaceFixture.releaseAfter(() => transport.close());
workspaceFixture.releaseAfter(async () => {
assert.deepEqual(await readdir(runtime), []);
verifierRun = await completeVerifierRun(run);
assertVerifierCleanupComplete(verifierRun.process_lineage);
});
if (primaryFailure !== undefined)
workspaceFixture.retain(
`Address-context verification failed; retained workspace: ${workspace}`,
);
try {
await workspaceFixture.closeEarly([() => commands.close()]);
} catch (cause) {
cleanupFailures.push(cause);
}
try {
await workspaceFixture.release();
} catch (cause) {
cleanupFailures.push(cause);
}
if (cleanupFailures.length > 0) {
process.stderr.write(
`Retained verifier workspace after cleanup failure: ${workspace}\n`,
);
throw Object.assign(
new AggregateError(
primaryFailure === undefined
? cleanupFailures
: [primaryFailure.cause, ...cleanupFailures],
"Ghidra address-context verifier cleanup failed",
),
// The caller can retry the retained workspace from the final failure.
workspaceFixture.released ? {} : { cleanupLeases: [workspaceFixture] },
);
}
if (primaryFailure !== undefined) throw primaryFailure.cause;
process.stdout.write(
JSON.stringify({ verifier_run: verifierRun, ...report }) + "\n",
);
async function call(name, args = {}) {
const result = await client.callTool(
{ name, arguments: args },
{ timeout: 240000 },
);
return ["open_binary", "binary_session", "close_binary"].includes(name)
? requireMcpOperationResult(result, name)
: requireMcpOutput(result, name);
}