Files
reverse-engineering-anything/scripts/verify-real-ghidra-ppc64.mjs
T
0e0c5a8fea feat(ghidra): admit ELFv2 PPC64 executables through a Power ISA 3.0 lane (#12517)
* feat(ghidra): admit ELFv2 PPC64 executables through a Power ISA 3.0 lane

An EM_PPC64 ELF has been classified in the powerpc family since #12089, but
the Ghidra lane still refused every ELF64 file. It now admits ELF64 ET_EXEC
files that declare the ELFv2 ABI, little or big endian, and imports them with
PowerPC:LE:64:A2ALT or PowerPC:BE:64:A2ALT by byte order.

Ghidra's 64-bit "default" languages decode the G2-era instruction set and
stop at the first VSX instruction in POWER8 or POWER9 code; the A2ALT
languages are Power ISA 3.0 and decode it. The ELF loader selects A2ALT
today, and the lane passes it explicitly and records it as provider-pinned.

ELFv1 (.opd function descriptors), an undeclared ABI, other e_flags bits,
ET_DYN and ET_REL are refused with their own reasons. The 32-bit lane is
unchanged.

npm run verify:ghidra:ppc64 builds a source-owned ELFv2 fixture in both byte
orders and checks it against GNU readelf and real Ghidra through MCP and the
CLI: the bound language, fixed instruction bytes including a VSX xxlor, the
global-entry thunk to each function's local entry, direct calls, snapshot
identity, and a shared object refused before Ghidra starts.

Refs #12085

* fix(ghidra): supervise PPC64 verifier compiler and CLI processes

Timeouts on bare execFile stop only the direct child, so a linker can
outlive Clang and disappear from the parent-tree cleanup check. Launch
those commands through the shared command owner, pass that runner into
the PPC64 fixture builder, and close the owner before the lineage check.
A failed close stays registered for retry and the diagnostic workspace
is retained.

* docs(ghidra): record the PPC64 ELFv2 Power ISA 3.0 lane

Add the feature specification, plan, and tasks for the lane, and index
them with the other feature records.

* fix(ghidra): finish shared PowerPC verifier command ownership

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-11-19 18:27:31 -05:00

394 lines
14 KiB
JavaScript

#!/usr/bin/env node
import assert from "node:assert/strict";
import { createHash } from "node:crypto";
import { mkdir, readFile } 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 { parseBinaryTarget } from "../dist/application/BinaryTargetResolver.js";
import {
inspectPowerPc64Readelf,
assertPowerPc64EntryPair,
assertPowerPc64Global,
assertPowerPc64LoadedImage,
assertPowerPc64Probe,
} from "../tests/conformance/ghidra/ppc-checks.mjs";
import { parseEvidence } from "../dist/domain/evidence.js";
import { parseAnalysisSnapshot } from "../dist/domain/analysisSnapshot.js";
import { functionDossierSchema } from "../dist/domain/native/functionDossier.js";
import { inspectVerifierGhidraInstallation } from "./lib/ghidra-installation-inspection.mjs";
import { buildPowerPc64Fixture } from "../tests/conformance/ghidra/ppc-fixture.mjs";
import { requireMcpOperationResult } from "./lib/mcp-verifier-results.mjs";
import { createVerifierCommands } from "./lib/verify-commands.mjs";
import { createVerifierRun, completeVerifierRun } from "./lib/verifier-run.mjs";
import { VerifierFixture } from "./lib/verifier-fixture.mjs";
import {
FIXTURE_TOOLS,
fixtureCommand,
requireLaneToolchain,
} from "../tests/conformance/ghidra/fixture-toolchain.mjs";
// Optional cross-target lane. No tool acquisition and no target execution.
if (process.argv.length !== 2)
throw new Error("Usage: node scripts/verify-real-ghidra-ppc64.mjs");
if (!["linux", "darwin"].includes(process.platform))
throw new Error(
"PPC64 verification requires a supported Linux/macOS Ghidra host",
);
if (process.env.GHIDRA_INSTALL_DIR === undefined)
throw new Error("Missing prerequisite: caller-supplied GHIDRA_INSTALL_DIR");
const installation = await inspectVerifierGhidraInstallation({
environment: process.env,
installDir: process.env.GHIDRA_INSTALL_DIR,
...(process.env.JAVA_HOME === undefined
? {}
: { javaHome: process.env.JAVA_HOME }),
});
if (installation.status !== "available")
throw new Error(
`Ghidra prerequisite unavailable: ${JSON.stringify(installation)}`,
);
const entrypoint = fileURLToPath(new URL("./rea.mjs", import.meta.url));
const run = createVerifierRun();
// Refuse a host without the fixture toolchain before allocating anything.
await requireLaneToolchain("ppc64");
const workspaceFixture = await VerifierFixture.open({
prefix: "rea-ppc64-proof-",
// Ghidra children use the workspace as TMPDIR; a plain root admits them on every host.
private: false,
});
const workspace = workspaceFixture.path;
// A failed run keeps its workspace for diagnosis; the fixture records why.
const retainWorkspace = (message, options) => {
workspaceFixture.retain(message);
return new Error(message, options);
};
const runtime = join(workspace, "runtime");
await mkdir(runtime);
const env = {
PATH: process.env.PATH ?? "/usr/bin:/bin",
TMPDIR: runtime,
REA_LOG_LEVEL: "silent",
REA_ANALYSIS_PROVIDER: "ghidra",
REA_PROCESS_RUN_ID: run.run_id,
GHIDRA_INSTALL_DIR: installation.installDir,
JAVA_HOME: installation.javaHome,
HOPPER_LAUNCHER_PATH: "/rea-unconfigured-deep-provider/hopper",
};
for (const setting of ["GHIDRA_HEADLESS_MAXMEM", "GHIDRA_MAXMEM"]) {
if (process.env[setting] !== undefined) env[setting] = process.env[setting];
}
const sha256 = async (path) =>
createHash("sha256")
.update(await readFile(path))
.digest("hex");
// Compiler, reader and CLI launches share one command owner. Its process group is what
// a timeout stops, including a linker that would otherwise outlive Clang.
const commands = await createVerifierCommands();
/** A position-independent shared object the bounded lane must refuse by name. */
const buildSharedObject = async (directory) => {
const path = join(directory, "powerpc64le-unknown-linux-gnu.so");
await commands.exec(
fixtureCommand(FIXTURE_TOOLS.ppcClang),
[
"--target=powerpc64le-unknown-linux-gnu",
"-mabi=elfv2",
"-fPIC",
"-shared",
"-fuse-ld=lld",
"-nostdlib",
"-Wl,--build-id=none",
fileURLToPath(new URL("../tests/conformance/c/ppc64.c", import.meta.url)),
"-o",
path,
],
{ timeout: 60000 },
);
return path;
};
const reports = [];
let primaryFailure;
try {
const transport = new StdioClientTransport({
command: process.execPath,
args: [entrypoint, "mcp"],
env,
stderr: "pipe",
});
const client = new Client({ name: "rea-real-ppc64-proof", version: "1" });
let stderr = "";
transport.stderr?.on("data", (chunk) => {
stderr = (stderr + chunk.toString()).slice(-65536);
});
const call = async (name, args = {}) => {
const reply = await client.callTool(
{ name, arguments: args },
{ timeout: 180000 },
);
return requireMcpOperationResult(reply, name);
};
const dossier = async (procedure) =>
functionDossierSchema.parse(
await call("analyze_function", { procedure, detail: "complete" }),
);
try {
await client.connect(transport);
// Shared images stay outside the lane, refused before Ghidra starts.
const shared = await buildSharedObject(workspace);
const rejected = await client.callTool({
name: "open_binary",
arguments: { path: shared, provider_id: "ghidra" },
});
assert.equal(rejected.isError, true);
assert.match(JSON.stringify(rejected.content), /ET_EXEC only/u);
for (const byteOrder of ["little", "big"]) {
const fixture = await buildPowerPc64Fixture(
workspace,
byteOrder,
commands,
);
const independent = await inspectPowerPc64Readelf(
commands,
fixture.path,
byteOrder,
);
const resolved = await parseBinaryTarget(fixture.path);
if (!resolved.ok) throw resolved.error;
assert.deepEqual(
resolved.value.powerpc,
independent.powerpc,
"REA ELF interpretation disagrees with GNU readelf",
);
assert.equal(resolved.value.sha256, fixture.sha256);
const { symbols, localEntries } = independent;
const snapshotPath = join(workspace, `ppc64-${byteOrder}.snapshot.json`);
const target = await call("open_binary", {
path: fixture.path,
provider_id: "ghidra",
});
assert.equal(target.architecture, "powerpc");
assert.equal(target.sha256, fixture.sha256);
// The loaded image reports the language Ghidra actually used.
const image = await call("inspect_native_load_image");
assertPowerPc64LoadedImage(image.observations, fixture.sha256, byteOrder);
const procedures = await call("list_procedures");
const at = (address) =>
procedures.find((p) => BigInt(p.address) === BigInt(address));
for (const name of ["rea_ppc64_entry", "rea_ppc64_leaf"]) {
assert.equal(at(symbols[name])?.value, name, `${name} global entry`);
assert.ok(at(localEntries[name]), `${name} local entry missing`);
}
assert.equal(at(symbols.rea_ppc64_probe)?.value, "rea_ppc64_probe");
const probe = BigInt(symbols.rea_ppc64_probe);
const instruction = (offset) =>
call("inspect_native_instruction", {
address: `0x${(probe + offset).toString(16)}`,
});
assertPowerPc64Probe(
{
move: await instruction(0n),
branch: await instruction(8n),
vector: await instruction(12n),
},
symbols.rea_ppc64_probe,
byteOrder,
);
const global = await call("read_bytes", {
address: symbols.rea_ppc64_global,
length: 8,
});
assert.equal(global.returned_bytes, 8);
assertPowerPc64Global(global.bytes_hex, byteOrder);
const marker = await call("read_bytes", {
address: symbols.rea_ppc64_marker,
length: 31,
});
assert.equal(
marker.bytes_hex,
Buffer.from("rea-ppc64-source-owned-fixture\0").toString("hex"),
);
// ELFv2: the symbol is a thunk to the body at the local entry, and the
// body's direct call reaches the leaf's local entry.
const entry = {
global: symbols.rea_ppc64_entry,
local: localEntries.rea_ppc64_entry,
};
const local = await dossier(entry.local);
assertPowerPc64EntryPair(await dossier(entry.global), local, entry);
const callees = await call("procedure_callees", {
procedure: entry.local,
});
assert.ok(
callees.some(
(callee) => BigInt(callee) === BigInt(localEntries.rea_ppc64_leaf),
),
"Expected direct call to the leaf's local entry not recovered",
);
const assembly = await call("procedure_assembly", {
procedure: entry.local,
});
assert.ok(assembly.trim().length > 0);
const mapping = await call("address_to_file_offset", {
address: entry.local,
});
const memory = await call("read_bytes", {
address: entry.local,
length: 16,
});
const sourceBytes = await readFile(fixture.path);
assert.equal(memory.returned_bytes, 16);
assert.equal(
memory.bytes_hex,
sourceBytes
.subarray(mapping.file_offset, mapping.file_offset + 16)
.toString("hex"),
);
const saved = await call("close_binary", {
snapshot_path: snapshotPath,
});
assert.ok(saved.evidence_records > 0);
const snapshot = parseAnalysisSnapshot(
JSON.parse(await readFile(snapshotPath, "utf8")),
);
assert.equal(snapshot.target.identity.architecture, "powerpc");
assert.equal(
snapshot.binding.analysis_profile.parameters.language_id,
image.observations.language_id,
);
assert.equal(
snapshot.binding.analysis_profile.parameters.powerpc_support_lane,
"elf64-elfv2-exec-isa3",
);
assert.ok(snapshot.evidence_bundle.records.length > 0);
for (const evidence of snapshot.evidence_bundle.records)
assert.equal(
parseEvidence(evidence).subject?.identity.architecture,
"powerpc",
);
await call("open_binary", {
path: fixture.path,
provider_id: "ghidra",
snapshot_path: snapshotPath,
});
assert.deepEqual(await call("list_procedures"), procedures);
await call("close_binary");
// Same public operation through CLI, not a private injected provider.
const cli = await commands.exec(
process.execPath,
[
entrypoint,
"function",
fixture.path,
"rea_ppc64_entry",
"--provider",
"ghidra",
"--json",
],
{ env, timeout: 240000, maxBuffer: 16 * 1024 * 1024 },
);
const evidence = parseEvidence(JSON.parse(cli.stdout));
assert.equal(evidence.subject?.identity.architecture, "powerpc");
assert.equal(evidence.subject?.identity.sha256, fixture.sha256);
const cliDossier = functionDossierSchema.parse(
evidence.normalized_result,
);
assert.equal(BigInt(cliDossier.procedure.address), BigInt(entry.global));
assert.equal(
BigInt(cliDossier.procedure.classification.thunk_target),
BigInt(entry.local),
);
assert.ok(cliDossier.pseudocode.trim().length > 0);
assert.equal(
await sha256(fixture.path),
fixture.sha256,
"Analysis modified the source executable",
);
reports.push({
...fixture,
independent_reader: independent,
effective_language: image.observations.language_id,
effective_compiler_spec: image.observations.compiler_spec_id,
checks: [
"independent ELF header, symbols and ELFv2 local entries",
"loaded Ghidra identity and bound Power ISA language",
"fixed instruction bytes, immediate and VSX decoding",
"conditional branch destination",
"global doubleword and marker bytes in file byte order",
"global-entry thunk and local-entry body with direct call",
"CLI/MCP and snapshot identity",
],
procedures: procedures.length,
status: "passed",
});
}
reports.push({
path: shared,
sha256: await sha256(shared),
checks: ["ET_DYN refused before provider startup"],
status: "passed",
});
} catch (cause) {
throw new Error(`PPC64 verification failed; MCP stderr: ${stderr}`, {
cause,
});
} finally {
try {
await client.close();
} finally {
await transport.close();
}
}
} catch (cause) {
primaryFailure = cause;
}
// Close the command owner before the parent-tree check. A failed close stays
// registered for retry and the diagnostic workspace is retained.
let cleanupFailure;
try {
await workspaceFixture.closeEarly([() => commands.close()]);
} catch (cause) {
cleanupFailure = cause;
}
if (cleanupFailure !== undefined)
throw retainWorkspace(
`PPC64 command cleanup failed; retained diagnostic workspace: ${workspace}`,
{
cause:
primaryFailure === undefined
? cleanupFailure
: new AggregateError(
[primaryFailure, cleanupFailure],
"PPC64 verification and command cleanup both failed",
),
},
);
const completed = await completeVerifierRun(run);
if (
completed.process_lineage.status !== "verified" ||
completed.process_lineage.descendants.length !== 0
)
throw retainWorkspace(
`Cleanup unverified; retained diagnostic workspace: ${workspace}`,
{ cause: primaryFailure },
);
if (primaryFailure !== undefined)
throw retainWorkspace(
`PPC64 verification failed; retained workspace: ${workspace}`,
{
cause: primaryFailure,
},
);
await workspaceFixture.release();
console.log(JSON.stringify({ ...completed, fixtures: reports }, null, 2));