rea/scripts/verify-real-ghidra-windows.mjs

#!/usr/bin/env node

import { access, readFile } from "node:fs/promises";
import { isAbsolute, resolve } from "node:path";
import { fileURLToPath } from "node:url";

import { resolveGhidraAnalysisProfile } from "../dist/ghidra/GhidraAnalysisProfile.js";
import { GhidraClient } from "../dist/ghidra/GhidraClient.js";
import {
  GHIDRA_FUNCTION_OPERATIONS,
  parseGhidraFunctionInput,
  parseGhidraFunctionResult,
} from "../dist/ghidra/GhidraFunctionValues.js";
import {
  GHIDRA_INVENTORY_OPERATIONS,
  parseGhidraInventoryInput,
  parseGhidraInventoryResult,
} from "../dist/ghidra/GhidraInventoryValues.js";
import { inspectGhidraInstallation } from "../dist/ghidra/GhidraInstallation.js";
import { SUPPORTED_GHIDRA_VERSION } from "../dist/ghidra/GhidraInstallationPolicy.js";
import { GhidraHeadlessLauncher } from "../dist/ghidra/GhidraLauncher.js";
import { GHIDRA_PROVIDER_IDENTITY } from "../dist/ghidra/GhidraProviderCapabilities.js";
import { windowsP0Capabilities } from "../dist/ghidra/GhidraProviderCapabilities.js";
import { GHIDRA_SESSION_CAPABILITIES } from "../dist/ghidra/GhidraSessionValues.js";
import { parseBinaryTarget } from "../dist/application/BinaryTargetResolver.js";
import { completeVerifierRun, createVerifierRun } from "./lib/verifier-run.mjs";
import { verifyGhidraCompactReferences } from "./lib/real-ghidra-compact-references.mjs";

const verifierRun = createVerifierRun();
const SESSION_CAPABILITIES = GHIDRA_SESSION_CAPABILITIES.filter(
  (name) => name !== "annotate_native_function",
);

if (process.platform !== "win32" || process.arch !== "x64")
  throw new Error(
    "The real Windows Ghidra verifier requires a Windows x64 host",
  );
if (
  windowsP0Capabilities().some(
    ({ available, effects }) => available && effects.mutatesArtifact,
  )
)
  throw new Error("Windows Ghidra must not advertise database mutation");
const installDir = process.env.GHIDRA_INSTALL_DIR;
if (installDir === undefined || !isAbsolute(installDir))
  throw new Error(
    "Set GHIDRA_INSTALL_DIR to the absolute root of Ghidra 12.1.4.",
  );
const installation = inspectGhidraInstallation({
  environment: process.env,
  installDir,
  ...(process.env.JAVA_HOME === undefined
    ? {}
    : { javaHome: process.env.JAVA_HOME }),
});
if (
  installation.status !== "available" ||
  installation.analyzeHeadlessPath === null ||
  installation.providerVersion !== SUPPORTED_GHIDRA_VERSION
)
  throw new Error(
    `Windows Ghidra installation is unavailable: ${JSON.stringify(installation)}`,
  );

const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
const architecture = process.argv.includes("--x86") ? "x86" : "x86_64";
const dllFixture = process.argv.includes("--dll");
const role = dllFixture ? "shared-library" : "application";
const targetPath = resolve(
  root,
  "build",
  "fixtures",
  `rea-ghidra-windows${architecture === "x86" ? "-x86" : ""}.${dllFixture ? "dll" : "exe"}`,
);
const target = await parseBinaryTarget(targetPath);
if (
  !target.ok ||
  target.value.format !== "pe" ||
  target.value.architecture !== architecture ||
  target.value.executableRole !== role ||
  target.value.managed !== false
)
  throw new Error(
    `Controlled Windows fixture failed admission: ${JSON.stringify(target)}`,
  );
const profile = await resolveGhidraAnalysisProfile(
  target.value,
  GHIDRA_PROVIDER_IDENTITY,
  installation,
);
if (!profile.ok || profile.value.profile === null)
  throw new Error("Windows Ghidra profile could not be committed");
if (profile.value.profile.parameters.executable_role !== role)
  throw new Error("Windows Ghidra profile lost the observed PE role");

const client = new GhidraClient({
  platform: installation.platform,
  launcher: new GhidraHeadlessLauncher({
    environment: process.env,
    analyzeHeadlessPath: installation.analyzeHeadlessPath,
    ...(process.env.JAVA_HOME === undefined
      ? {}
      : { javaHome: process.env.JAVA_HOME }),
    bridgeScriptPath: fileURLToPath(
      new URL("../bridge/ghidra/ReaGhidraBridge.java", import.meta.url),
    ),
    platform: "win32",
  }),
  targetPath: target.value.path,
  targetSha256: target.value.sha256,
  transport: "authenticated-loopback-tcp",
  providerVersion: SUPPORTED_GHIDRA_VERSION,
  profileDigest: profile.value.profile.digest,
});

let coordinates;
let report;
let primaryFailure;
const observed = new Set();
try {
  const started = await client.start();
  if (!started.ok) throw started.error;
  assertSession(
    started.value,
    target.value.sha256,
    profile.value.profile.digest,
  );
  const languagePrefix = architecture === "x86" ? "x86:LE:32:" : "x86:LE:64:";
  if (!started.value.target.language_id.startsWith(languagePrefix))
    throw new Error("Windows fixture imported with the wrong Ghidra language");
  coordinates = client.diagnostics();
  assertRuntimeCoordinates(coordinates, target.value.sha256);

  const documents = await inventory("list_documents", {});
  const names = await inventory("list_names", {});
  const procedures = await inventory("list_procedures", {});
  const segments = await inventory("list_segments", {});
  const strings = await inventory("list_strings", {});
  if (
    !Array.isArray(documents) ||
    documents.length !== 1 ||
    !Array.isArray(procedures) ||
    procedures.length === 0 ||
    !Array.isArray(segments) ||
    segments.length === 0 ||
    !Array.isArray(names) ||
    !Array.isArray(strings)
  )
    throw new Error("Windows Ghidra inventory proof was incomplete");
  const procedure = procedures.find(
    (item) => item.procedure?.external === false,
  );
  if (procedure === undefined)
    throw new Error("Windows Ghidra fixture exposed no local procedure");
  const calleeAddress = architecture === "x86" ? 0x401010n : 0x140001010n;
  const callee = procedures.find(
    (item) => BigInt(item.address) === calleeAddress,
  );
  if (callee === undefined)
    throw new Error("Windows fixture exposed no controlled callee");
  const pseudoCode = await functionOperation("procedure_pseudo_code", {
    procedure: callee.value,
  });
  if (typeof pseudoCode !== "string" || !/\b(?:42|0x2a)\b/iu.test(pseudoCode))
    throw new Error(
      "Windows fixture decompilation lost its known return value",
    );
  if (dllFixture) {
    const callerAddress = architecture === "x86" ? "0x401000" : "0x140001000";
    const callees = await functionOperation("procedure_callees", {
      procedure: callerAddress,
    });
    if (!callees.includes(callee.address))
      throw new Error("DLL export caller lost its controlled call reference");
    const callerCode = await functionOperation("procedure_pseudo_code", {
      procedure: callerAddress,
    });
    if (typeof callerCode !== "string" || !/\+\s*1\b/u.test(callerCode))
      throw new Error("DLL export caller lost its addition of one");
  }

  await inventory("inspect_native_load_image", {});
  const memory = await inventory("read_bytes", {
    address: procedure.address,
    length: 16,
  });
  const mapping = await inventory("address_to_file_offset", {
    address: procedure.address,
  });
  const sourceBytes = await readFile(targetPath);
  if (
    memory.complete !== true ||
    memory.returned_bytes !== 16 ||
    memory.bytes_hex !==
      sourceBytes
        .subarray(mapping.file_offset, mapping.file_offset + 16)
        .toString("hex")
  )
    throw new Error(
      "Windows loaded bytes disagree with the observed source-file mapping",
    );

  await inventory("address_name", { address: procedure.address });
  const resolvedAddress = await inventory("procedure_address", {
    procedure: procedure.value,
  });
  if (resolvedAddress !== procedure.address)
    throw new Error("Windows procedure name/address resolution drifted");
  await inventory("resolve_containing_procedure", {
    address: procedure.address,
  });
  await inventory("search_procedures", { pattern: procedure.value });
  await inventory("search_strings", { pattern: "rea" });

  for (const operation of [
    "procedure_assembly",
    "procedure_callees",
    "procedure_callers",
    "procedure_info",
    "procedure_pseudo_code",
    "read_function_instructions",
    "procedure_references",
  ])
    await functionOperation(operation, { procedure: procedure.value });
  await functionOperation("xrefs", { address: procedure.address });
  await functionOperation("inspect_native_data_type", { type: "/undefined8" });
  await functionOperation("inspect_native_instruction", {
    address: procedure.address,
  });
  await functionOperation("resolve_native_call_targets", {
    address: procedure.address,
  });
  await functionOperation("analyze_function", {
    procedure: procedure.value,
  });

  const expected = [
    ...GHIDRA_INVENTORY_OPERATIONS,
    ...GHIDRA_FUNCTION_OPERATIONS.filter(
      (name) => name !== "annotate_native_function",
    ),
  ];
  if (
    observed.size !== expected.length ||
    expected.some((operation) => !observed.has(operation))
  )
    throw new Error(
      `Windows Ghidra operation proof was incomplete: ${JSON.stringify([...observed])}`,
    );

  // The reference controls occupy the EXE fixture's additional function.
  // DLL fixtures retain their independent exported-caller/return controls.
  const compactReferences = dllFixture
    ? null
    : await verifyGhidraCompactReferences(
        functionOperation,
        architecture === "x86",
      );
  report = {
    ok: true,
    provider: { id: "ghidra", version: SUPPORTED_GHIDRA_VERSION },
    language_id: started.value.target.language_id,
    target: {
      format: target.value.format,
      architecture: target.value.architecture,
      executable_role: target.value.executableRole,
      managed: target.value.managed,
      sha256: target.value.sha256,
    },
    transport: "authenticated-loopback-tcp",
    operations: [...observed].sort((left, right) => left.localeCompare(right)),
    cleanup: "complete",
    compact_references: compactReferences,
    native_controls: {
      job_object: true,
      protected_dacl: true,
      handle_admission: true,
    },
    limitations: [
      "approved-non-sensitive-fixtures-only",
      "windows-x64-local-ntfs-only",
      "native-x86-and-x86-64-pe-applications-and-dlls-only",
      "no-gui-or-mutation-authority",
    ],
  };
} catch (cause) {
  primaryFailure = cause;
  throw cause;
} finally {
  const closed = await client.close();
  if (!closed.ok)
    throw primaryFailure === undefined
      ? closed.error
      : new AggregateError(
          [primaryFailure, closed.error],
          "Ghidra verification and cleanup failed",
        );
  if (coordinates !== undefined) await assertCleanup(coordinates);
}
if (report === undefined)
  throw new Error("Windows Ghidra report was not produced");
process.stdout.write(
  `${JSON.stringify({ verifier_run: await completeVerifierRun(verifierRun), ...report })}\n`,
);

async function inventory(operation, parameters) {
  const input = parseGhidraInventoryInput(operation, parameters);
  if (!input.ok) throw input.error;
  const called = await client.callTool(operation, input.value);
  if (!called.ok) throw called.error;
  const result = parseGhidraInventoryResult(operation, called.value);
  if (!result.ok) throw result.error;
  observed.add(operation);
  return result.value;
}

async function functionOperation(operation, parameters) {
  const input = parseGhidraFunctionInput(operation, parameters);
  if (!input.ok) throw input.error;
  const called = await client.callTool(operation, input.value);
  if (!called.ok) throw called.error;
  const result = parseGhidraFunctionResult(operation, called.value);
  if (!result.ok) throw result.error;
  observed.add(operation);
  return result.value;
}

function assertSession(session, targetSha256, profileDigest) {
  if (
    session.provider.id !== "ghidra" ||
    session.provider.version !== SUPPORTED_GHIDRA_VERSION ||
    session.profile_digest !== profileDigest ||
    session.target.sha256 !== targetSha256 ||
    session.read_only !== true ||
    session.analysis_complete !== true ||
    session.analysis_timed_out !== false ||
    session.capabilities.length !== SESSION_CAPABILITIES.length ||
    new Set(session.capabilities).size !== SESSION_CAPABILITIES.length ||
    SESSION_CAPABILITIES.some((name) => !session.capabilities.includes(name))
  )
    throw new Error(
      `Windows Ghidra session commitment drifted: ${JSON.stringify(session)}`,
    );
}

function assertRuntimeCoordinates(runtime, targetSha256) {
  if (
    runtime.transport !== "authenticated-loopback-tcp" ||
    runtime.target_sha256 !== targetSha256 ||
    typeof runtime.runtime_root !== "string" ||
    typeof runtime.endpoint_path !== "string" ||
    typeof runtime.project_root !== "string" ||
    typeof runtime.process_id !== "number" ||
    typeof runtime.target_admission !== "object" ||
    runtime.target_admission === null
  )
    throw new Error(
      `Windows Ghidra runtime coordinates are incomplete: ${JSON.stringify(runtime)}`,
    );
}

async function assertCleanup(runtime) {
  for (const name of ["runtime_root", "endpoint_path", "project_root"]) {
    const path = runtime[name];
    if (typeof path === "string" && (await exists(path)))
      throw new Error(`Windows Ghidra cleanup left ${name}: ${path}`);
  }
  if (
    typeof runtime.process_id === "number" &&
    processExists(runtime.process_id)
  )
    throw new Error(
      `Windows Ghidra cleanup left process ${String(runtime.process_id)}`,
    );
}

async function exists(path) {
  try {
    await access(path);
    return true;
  } catch {
    return false;
  }
}

function processExists(pid) {
  try {
    process.kill(pid, 0);
    return true;
  } catch (cause) {
    return !(
      cause instanceof Error &&
      "code" in cause &&
      cause.code === "ESRCH"
    );
  }
}