Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
import { ProcessOutputTokenScanner } from "../process/ProcessOutputTokenScanner.js";
import { GhidraNativeAotSnapshotOwner } from "./GhidraNativeAotSnapshotOwner.js";
import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
import { resolvedAnalysisError } from "../domain/analysisErrorBase.js";
import { createDeferred } from "../../tests/fixtures/binarySession.js";
import { ProviderInspectionScope } from "../providers/ProviderInspectionScope.js";
import { ok as javaProbeOk } from "../domain/result.js";
import type { GhidraJavaObservation } from "./GhidraJavaProbe.js";
import type { GhidraSeedReport } from "./GhidraAnalysisSeeds.js";
import type { GhidraDisabledAnalyzerReport } from "./GhidraDisabledAnalyzers.js";
import { createHash } from "node:crypto";
import { execFile } from "node:child_process";
// Fake-backed provider coverage; real Ghidra verification lives in
// `npm run verify:ghidra` and its focused variants.
import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
import { afterEach, describe, expect, it, onTestFinished, vi } from "vitest";
import * as nativeLoader from "../windows/WindowsNativeLoader.js";
import { WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON } from "../process/WindowsAuthority.js";
import {
fixtureDosLoadImage,
compareDosClientFixture,
} from "./GhidraLoadImage.fixture.js";
import { fixtureRawBinaryLoadImage } from "./GhidraRawBinaryLoadImage.fixture.js";
import {
nativeAotPeDigest,
nativeAotPeFixture,
nativeAotPeHeaderIndirectionFixture,
nativeAotPeOptionalHeaderFixture,
nativeAotPeVirtualSectionFixture,
} from "../../tests/fixtures/nativeaotPe.js";
import { jsonValueSchema, type JsonValue } from "../domain/jsonValue.js";
import { parseConfig } from "../config/parseConfig.js";
import type { BinaryTarget } from "../domain/binaryTargetTypes.js";
import { parseExecutableHeader } from "../domain/binaryTarget.js";
import { elf, thinMach } from "../domain/binaryTarget.fixture.js";
import { GhidraProvider } from "./GhidraProvider.js";
import type { GhidraTargetSnapshot } from "./GhidraClient.js";
import type { GhidraProviderClientFactory } from "./GhidraProviderClient.js";
import type { GhidraHeadlessLauncher } from "./GhidraLauncher.js";
import type { GhidraInstallationHost } from "./GhidraInstallation.js";
import { GHIDRA_SESSION_CAPABILITIES } from "./GhidraSessionValues.js";
import { err, ok } from "../domain/result.js";
import type { Result } from "../domain/result.js";
import { GhidraSessionError } from "./GhidraSessionError.js";
import { silentLogger } from "../logger.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
import { createAnalysisProfile } from "../domain/analysisProfile.js";
import { createAnalysisExecution } from "../application/AnalysisProvider.js";
import { AnalysisSnapshotCache } from "../application/binary/AnalysisSnapshotCache.js";
import { createEvidence } from "../domain/evidence.js";
import { createEvidenceBundle } from "../domain/evidenceBundle.js";
const INSTALL = "/opt/ghidra_12.1.4_PUBLIC";
afterEach(() => vi.restoreAllMocks());
const installationHost = (
platform: NodeJS.Platform = "linux",
): GhidraInstallationHost => ({
platform,
architecture: "x64",
readText: () => "application.version=12.1.4\napplication.java.min=21\n",
executable: () => true,
probeJava: () =>
javaProbeOk<GhidraJavaObservation>({
osArch: "amd64",
osName: platform === "win32" ? "Windows 11" : "Linux",
version: "21.0.11",
major: 21,
home: "/usr/lib/jvm/jdk-21",
bits: 64,
runtime: "jdk",
vmName: "OpenJDK 64-Bit Server VM",
}),
});
const provider = (
host = installationHost(),
clientFactory?: GhidraProviderClientFactory,
): GhidraProvider => {
const config = parseConfig({ GHIDRA_INSTALL_DIR: INSTALL });
if (!config.ok) throw config.error;
return new GhidraProvider(
config.value,
silentLogger,
{},
host,
clientFactory,
);
};
const createElfClient = async (ghidra: GhidraProvider) => {
const target = executableTarget("elf", "x86_64");
const resolved = await ghidra.resolveAnalysisProfile(target);
if (!resolved.ok) throw resolved.error;
if (resolved.value.profile === null)
throw new Error("Expected a bound Ghidra profile");
return ghidra.createClient(target, resolved.value.profile);
};
it.each(["readiness", "client"] as const)(
"keeps completed Java prerequisite failure primary across late cancellation in %s",
async (consumer) => {
const controller = new AbortController();
const reason = { request: "late Java cancellation" };
let armed = false;
let nativeCreates = 0;
const base = installationHost();
const ghidra = provider(
{
...base,
probeJava: (command, environment, options) => {
if (!armed) return base.probeJava(command, environment, options);
controller.abort(reason);
return err({
_tag: "GhidraJavaProbeFailure",
code: "version_unresolved",
detail: "completed invalid Java report",
});
},
},
() => {
nativeCreates++;
throw new Error("A failed prerequisite cannot create a native client");
},
);
const client =
consumer === "client" ? await createElfClient(ghidra) : undefined;
armed = true;
try {
if (client === undefined) {
const availability = await ghidra.inspectAvailability({
signal: controller.signal,
});
expect(availability).toMatchObject({
status: "unavailable",
diagnostics: { java_probe_failure: { code: "version_unresolved" } },
});
} else {
const result = await client.execute(
"analyze_function",
{},
{ signal: controller.signal },
);
if (result.ok)
throw new Error("Expected physical prerequisite failure");
expect(result.error).toMatchObject({
_tag: "ProviderAdapterError",
operation: "analyze_function",
diagnostics: { java_probe_failure: { code: "version_unresolved" } },
});
expect(projectAnalysisError(result.error).code).toBe(
"execution_failure",
);
}
expect(nativeCreates).toBe(0);
} finally {
await client?.close();
await ghidra.closeOwnedResources();
}
},
);
it.each([
"program-info-v1",
"program-info-v2",
"program-info-v3",
"program-info-v4",
])(
"retains historical PE PDB Evidence for %s without replaying its old projection",
async (pdbObservations) => {
const target = peTarget("x86_64");
const resolved = await provider().resolveAnalysisProfile(target);
if (!resolved.ok || resolved.value.profile === null)
throw new Error("Expected admitted PE profile");
const current = resolved.value.profile;
const prior = createAnalysisProfile(current.provider, {
...current.parameters,
pdb_observations: pdbObservations,
});
const operation = "search_procedures";
const parameters = { pattern: "wmain" };
const limitations = [
pdbObservations === "program-info-v4"
? "Legacy projection discarded NB10 declaration when the reported GUID was omitted."
: "Legacy projection collapsed unknown PDB load state.",
];
const cache = new AnalysisSnapshotCache();
cache.record({
target,
profile: prior,
operation,
parameters,
execution: createAnalysisExecution([], prior.provider, {
subject: target,
analysisProfile: prior,
limitations,
}),
});
const evidence = createEvidence(target, prior.provider, {
operation,
parameters,
result: [],
analysisProfile: prior,
limitations,
});
const exported = cache.export(
target,
prior,
createEvidenceBundle([evidence]),
);
if (!exported.ok) throw exported.error;
const imported = new AnalysisSnapshotCache();
expect(imported.import(exported.value, undefined, () => ok(0)).ok).toBe(
true,
);
expect(
imported.lookup(target, current, operation, parameters),
).toBeUndefined();
expect(
imported.lookup(target, prior, operation, parameters)?.limitations,
).toEqual(expect.arrayContaining(limitations));
expect(exported.value.evidence_bundle.records).toContainEqual(evidence);
},
);
it("carries the inspected release identity into the production launcher", async () => {
const launchers: GhidraHeadlessLauncher[] = [];
const ghidra = provider(
{
...installationHost(),
readText: () =>
"application.version=12.1.4\napplication.release.name=PUBLIC\napplication.java.min=21\n",
},
(options) => {
launchers.push(options.launcher as GhidraHeadlessLauncher);
return {
start: () => Promise.resolve(ok(sessionInfo())),
callTool: () => Promise.resolve(ok(null)),
close: () => Promise.resolve(ok(null)),
};
},
);
const client = await createElfClient(ghidra);
expect(launchers).toHaveLength(0);
expect((await client.execute("health", {})).ok).toBe(true);
expect(launchers[0]?.options).toMatchObject({
configurationDirectoryName: "ghidra_12.1.4_PUBLIC",
});
await client.close();
});
describe("Ghidra provider", () => {
it("commits DOS loader and real-mode language while retaining the CPU family", async () => {
const ghidra = provider();
const target: BinaryTarget = {
path: "/tmp/legacy.exe",
sha256: "a".repeat(64),
kind: "executable",
format: "dos-mz",
architecture: "x86",
availableArchitectures: ["x86"],
};
expect(ghidra.inspectTargetSupport(target).status).toBe("supported");
const resolved = await ghidra.resolveAnalysisProfile(target);
expect(resolved.ok && resolved.value).toMatchObject({
profile: {
parameters: {
target_format: "dos-mz",
architecture: "x86",
loader: "MzLoader",
load_image_evidence: "independent-mz-mapping-relocations-v2",
language_id: "x86:LE:16:Real Mode",
compiler_spec_id: "default",
load_segment: "0x1000",
address_coordinates: "linear-byte-offset",
},
},
});
const windows = provider(installationHost("win32"));
expect(windows.inspectTargetSupport(target).status).toBe("unsupported");
});
it("admits parsed Hexagon ELF targets through Ghidra profile selection and declines them on Windows", async () => {
const parsed = parseExecutableHeader(elf(1, 1, 164), "x64");
if (!parsed.ok) throw new Error("Expected valid Hexagon ELF target");
const target: BinaryTarget = {
path: "/tmp/chre_pal.so",
sha256: "a".repeat(64),
kind: "executable",
...parsed.value,
};
const ghidra = provider();
expect(ghidra.inspectTargetSupport(target)).toMatchObject({
status: "supported",
});
const resolved = await ghidra.resolveAnalysisProfile(target);
expect(resolved.ok && resolved.value).toMatchObject({
profile: {
parameters: {
target_format: "elf",
architecture: "hexagon",
loader: "auto-from-header",
language_id: "auto-from-header",
compiler_spec_id: "auto-default",
},
},
});
const windows = provider(installationHost("win32"));
expect(windows.inspectTargetSupport(target)).toMatchObject({
status: "unsupported",
code: "target_format_unsupported",
});
});
it("re-observes the exact installation for each fresh task without launching Ghidra", async () => {
let probeCount = 0;
const host: GhidraInstallationHost = {
...installationHost(),
probeJava: () => {
probeCount += 1;
return javaProbeOk<GhidraJavaObservation>({
osArch: "amd64",
osName: "Linux",
version: "21.0.11",
major: 21,
home: "/usr/lib/jvm/jdk-21",
bits: 64,
runtime: "jdk",
});
},
};
const ghidra = provider(host);
expect(ghidra.capabilities()).toEqual(
expect.arrayContaining([
expect.objectContaining({
operation: "list_procedures",
effects: expect.objectContaining({
mutatesArtifact: false,
mayShowUi: false,
mayWriteFilesystem: true,
}),
}),
expect.objectContaining({
operation: "analyze_function",
limitations: expect.arrayContaining([
expect.stringContaining(
"unresolved targetless flows remain unknown",
),
]),
}),
]),
);
expect(await ghidra.inspectAvailability()).toMatchObject({
status: "available",
diagnostics: {
install_dir: INSTALL,
provider_version: "12.1.4",
java_version: "21.0.11",
},
});
expect(await ghidra.inspectAvailability()).toMatchObject({
status: "available",
});
expect(probeCount).toBe(2);
});
it("separates target kind, format, and concrete architecture", () => {
const ghidra = provider();
expect(
ghidra.inspectTargetSupport(executableTarget("elf", "x86_64")),
).toMatchObject({
status: "supported",
});
expect(
ghidra.inspectTargetSupport(executableTarget("pe", "arm64")),
).toMatchObject({
status: "supported",
});
expect(
ghidra.inspectTargetSupport({
path: "/tmp/fixture.asar",
sha256: "a".repeat(64),
kind: "archive",
format: "asar",
}),
).toMatchObject({
status: "unsupported",
code: "target_kind_unsupported",
});
expect(
ghidra.inspectTargetSupport({
path: "/tmp/fixture.js",
sha256: "a".repeat(64),
kind: "artifact",
format: "javascript",
}),
).toMatchObject({
status: "unsupported",
code: "target_kind_unsupported",
});
});
});
describe("Ghidra raw-binary profile", () => {
it("admits raw 6502 on Windows and binds its 16-bit language without mutation authority", async () => {
const ghidra = provider(installationHost("win32"));
const target: BinaryTarget = {
path: "/tmp/6502.bin",
sha256: "a".repeat(64),
kind: "executable",
format: "raw-binary",
architecture: "6502",
availableArchitectures: ["6502"],
entryPoint: "0x8001",
entryPointSource: "0x008001",
};
expect(ghidra.inspectTargetSupport(target).status).toBe("supported");
const resolved = await ghidra.resolveAnalysisProfile(target);
if (!resolved.ok) throw resolved.error;
expect(resolved.value.profile?.parameters).toMatchObject({
architecture: "6502",
loader: "BinaryLoader",
language_id: "6502:LE:16:default",
compiler_spec_id: "default",
entry_point: "0x8001",
language_selection: "caller-supplied-v1",
load_image_evidence: "independent-raw-mapping-context-v4",
});
expect(
ghidra
.capabilities()
.some(({ available, effects }) => available && effects.mutatesArtifact),
).toBe(false);
});
it("commits BinaryLoader language and caller-supplied entry", async () => {
const ghidra = provider();
const target: BinaryTarget = {
path: "/tmp/ecu.bin",
sha256: "a".repeat(64),
kind: "executable",
format: "raw-binary",
architecture: "arm",
availableArchitectures: ["arm"],
entryPoint: "0x8000000",
entryPointSource: "0x08000000",
};
expect(ghidra.inspectTargetSupport(target).status).toBe("supported");
const resolved = await ghidra.resolveAnalysisProfile(target);
expect(resolved.ok && resolved.value).toMatchObject({
profile: {
parameters: {
target_format: "raw-binary",
architecture: "arm",
loader: "BinaryLoader",
language_id: "ARM:LE:32:v7",
compiler_spec_id: "default",
language_selection: "caller-supplied-v1",
entry_point: "0x8000000",
},
},
});
const shifted = await ghidra.resolveAnalysisProfile({
...target,
entryPoint: "0x8001000",
entryPointSource: "0x8001000",
});
expect(resolved.ok && shifted.ok).toBe(true);
if (!resolved.ok || !shifted.ok || resolved.value.profile === null)
throw new Error("expected raw-binary profiles");
expect(shifted.value.profile?.digest).not.toBe(
resolved.value.profile.digest,
);
const windows = provider(installationHost("win32"));
expect(windows.inspectTargetSupport(target).status).toBe("unsupported");
});
it("binds raw m68k to the big-endian 68000 language outside Windows P0", async () => {
const target: BinaryTarget = {
path: "/tmp/m68k.bin",
sha256: "a".repeat(64),
kind: "executable",
format: "raw-binary",
architecture: "m68k",
availableArchitectures: ["m68k"],
entryPoint: "0x1000",
entryPointSource: "0x00001000",
};
const ghidra = provider();
expect(ghidra.inspectTargetSupport(target).status).toBe("supported");
const resolved = await ghidra.resolveAnalysisProfile(target);
if (!resolved.ok) throw resolved.error;
expect(resolved.value.profile?.parameters).toMatchObject({
target_format: "raw-binary",
architecture: "m68k",
loader: "BinaryLoader",
language_id: "68000:BE:32:default",
compiler_spec_id: "default",
language_selection: "caller-supplied-v1",
entry_point: "0x1000",
});
expect(
provider(installationHost("win32")).inspectTargetSupport(target),
).toMatchObject({
status: "unsupported",
code: "target_format_unsupported",
});
});
});
describe("Ghidra Mach-O slice support", () => {
it("declines parsed thin arm64_32 Mach-O targets", () => {
const parsed = parseExecutableHeader(
thinMach(0xcefaedfe, 0x0200000c),
"arm64",
);
if (!parsed.ok) throw new Error("Expected valid arm64_32 Mach-O target");
expect(
provider().inspectTargetSupport({
path: "/tmp/watch.o",
sha256: "a".repeat(64),
kind: "executable",
...parsed.value,
}),
).toMatchObject({
status: "unsupported",
code: "architecture_unsupported",
});
});
it("refuses universal targets whose selected slice cannot be enforced", () => {
const ghidra = provider();
const universal: BinaryTarget = {
path: "/tmp/fixture",
sha256: "a".repeat(64),
kind: "executable",
format: "mach-o-universal",
architecture: "arm64",
availableArchitectures: ["x86_64", "arm64"],
universalSlice: { offset: 0, size: 32 },
};
expect(ghidra.inspectTargetSupport(universal)).toMatchObject({
status: "unsupported",
code: "architecture_unsupported",
reason: expect.stringContaining("universal Mach-O"),
diagnostics: {
architecture: "arm64",
available_architectures: ["x86_64", "arm64"],
},
});
expect(
ghidra.inspectTargetSupport(executableTarget("mach-o", "arm64")),
).toMatchObject({ status: "supported" });
expect(
ghidra.inspectTargetSupport({
...universal,
availableArchitectures: ["arm64"] as const,
}),
).toMatchObject({ status: "supported" });
});
});
describe("Ghidra platform support", () => {
it.each([
{ architecture: "arm", languageId: "ARM:LE:32:v7" },
{ architecture: "arm64", languageId: "AARCH64:LE:64:v8A" },
] as const)(
"records explicit Windows $architecture processor selection without claiming loader selection",
async ({ architecture, languageId }) => {
const directory = await mkdtemp(
join(tmpdir(), "rea-arm-profile-language-"),
);
onTestFinished(() => rm(directory, { recursive: true, force: true }));
const languages = join(
directory,
"Ghidra/Processors/fixture/data/languages",
);
await mkdir(languages, { recursive: true });
await writeFile(
join(languages, "fixture.ldefs"),
`<language_definitions><language processor="${architecture === "arm" ? "ARM" : "AARCH64"}" endian="little" size="${architecture === "arm" ? 32 : 64}" variant="fixture" id="${languageId}"><compiler name="Visual Studio" spec="fixture.cspec" id="windows"/></language></language_definitions>`,
);
const config = parseConfig({
GHIDRA_INSTALL_DIR: directory,
REA_GHIDRA_LANGUAGE_ID: languageId,
REA_GHIDRA_COMPILER_SPEC_ID: "windows",
});
if (!config.ok) throw config.error;
const ghidra = new GhidraProvider(
config.value,
silentLogger,
{},
installationHost("win32"),
);
const resolved = await ghidra.resolveAnalysisProfile(
peTarget(architecture),
);
if (!resolved.ok) throw resolved.error;
expect(resolved.value.profile?.parameters).toMatchObject({
windows_arm_pe_import: "explicit-language-v1",
windows_arm_pe_machine: peTarget(architecture).peMachine,
language_id: languageId,
compiler_spec_id: "windows",
});
},
);
it("versions the Windows ARM PE import without changing other profile lanes", async () => {
for (const platform of ["win32", "linux"] as const) {
const ghidra = provider(installationHost(platform));
for (const architecture of ["x86", "x86_64", "arm", "arm64"] as const) {
const resolved = await ghidra.resolveAnalysisProfile(
peTarget(architecture),
);
if (!resolved.ok) throw resolved.error;
if (resolved.value.profile === null)
throw new Error("Expected a PE analysis profile");
const parameters = resolved.value.profile.parameters;
if (
platform === "win32" &&
(architecture === "arm" || architecture === "arm64")
)
expect(parameters).toHaveProperty(
"windows_arm_pe_import",
"loader-selected-language-v1",
);
else expect(parameters).not.toHaveProperty("windows_arm_pe_import");
if (
platform === "win32" &&
(architecture === "arm" || architecture === "arm64")
)
expect(parameters.windows_arm_pe_machine).toBe(
peTarget(architecture).peMachine,
);
else expect(parameters).not.toHaveProperty("windows_arm_pe_machine");
}
}
});
it("commits the PE role and managed classification to profile identity", async () => {
const ghidra = provider(installationHost("win32"));
const application = peTarget("x86_64");
const library = {
...application,
executableRole: "shared-library",
} as const;
const digests = new Set<string>();
for (const target of [
application,
library,
{ ...library, managed: true },
]) {
const resolved = await ghidra.resolveAnalysisProfile(target);
if (!resolved.ok) throw resolved.error;
const profile = resolved.value.profile;
if (profile === null) throw new Error("Expected a PE analysis profile");
expect(profile.parameters).toMatchObject({
executable_role: target.executableRole,
managed: target.managed,
native_aot_metadata: {
contract_revision: "rtr-9.1-x64-pe-read-only-v5",
source_bytes: 128 * 1024 * 1024,
work_units: 64 * 1024 * 1024,
working_memory_bytes: 64 * 1024 * 1024,
report_bytes: 4 * 1024 * 1024,
},
});
digests.add(profile.digest);
}
expect(digests.size).toBe(3);
const nonPe = await ghidra.resolveAnalysisProfile(
executableTarget("elf", "x86_64"),
);
if (!nonPe.ok || nonPe.value.profile === null)
throw new Error("Expected a non-PE analysis profile");
expect(nonPe.value.profile.parameters).not.toHaveProperty(
"native_aot_metadata",
);
});
it("keeps Windows annotation mutation unavailable independently of native controls", () => {
const ghidra = provider(installationHost("win32"));
expect(
ghidra
.capabilities()
.find(({ operation }) => operation === "annotate_native_function"),
).toMatchObject({
available: false,
reason: "Windows Ghidra P0 does not admit database mutation.",
availabilityCode: "unsupported_host",
});
});
});
describe("Ghidra Windows platform support", () => {
it("keeps Windows P0 unavailable until native isolation authority exists", async () => {
const native = vi
.spyOn(nativeLoader, "systemWindowsNativeAuthority")
.mockReturnValue({
available: false,
failureStage: "artifact",
reason: WINDOWS_NATIVE_AUTHORITY_UNAVAILABLE_REASON,
});
onTestFinished(() => native.mockRestore());
const ghidra = provider(installationHost("win32"));
const nativeApplication = peTarget("x86_64");
for (const architecture of ["x86", "x86_64"] as const)
expect(ghidra.inspectTargetSupport(peTarget(architecture))).toMatchObject(
{
status: "supported",
diagnostics: {
host_platform: "win32",
architecture,
executable_role: "application",
managed: false,
},
},
);
expect(await ghidra.inspectAvailability()).toMatchObject({
status: "unavailable",
code: "runtime_missing",
reason: expect.stringContaining(
"Windows native controls are unavailable",
),
diagnostics: {
windows_native_failure: {
stage: "artifact",
remediation: expect.any(String),
},
windows_security: {
job_object_process_ownership: expect.objectContaining({
available: false,
proof: "not-proven",
}),
private_runtime_dacl: expect.objectContaining({
available: false,
proof: "not-proven",
}),
reparse_safe_path_admission: expect.objectContaining({
available: false,
proof: "not-proven",
}),
},
},
});
expect(ghidra.capabilities()).toEqual(
expect.arrayContaining([
expect.objectContaining({
operation: "list_procedures",
available: false,
availabilityCode: "runtime_missing",
limitations: expect.arrayContaining([
expect.stringContaining(
"matching packaged Windows x64 native addon",
),
expect.stringContaining(
"private DACLs, and Job Object ownership automatically",
),
]),
}),
]),
);
expect(
ghidra.inspectTargetSupport({
...nativeApplication,
executableRole: "non-executable",
}),
).toMatchObject({
status: "unsupported",
code: "target_role_unsupported",
});
expect(
ghidra.inspectTargetSupport({ ...nativeApplication, managed: true }),
).toMatchObject({
status: "unsupported",
code: "managed_target_unsupported",
});
expect(
ghidra.inspectTargetSupport(executableTarget("elf", "x86_64")),
).toMatchObject({
status: "unsupported",
code: "target_format_unsupported",
});
// ARM64 PE is admitted on Windows P0 (bounded; see docs/windows-ghidra-p0.md).
expect(
ghidra.inspectTargetSupport(executableTarget("pe", "arm64")).status,
).toBe("supported");
expect(
ghidra.inspectTargetSupport(executableTarget("pe", "arm")).status,
).toBe("supported");
});
});
describe("Windows Ghidra native failure diagnostics", () => {
it.each([
["artifact", "runtime_missing"],
["self-test", "runtime_unavailable"],
["inspection", "runtime_unavailable"],
] as const)(
"keeps Windows P0 unavailable after a %s failure",
async (failureStage, code) => {
const load = vi
.spyOn(nativeLoader, "systemWindowsNativeAuthority")
.mockReturnValue({
available: false,
failureStage,
reason: "Windows native controls are unavailable: missing manifest",
});
const ghidra = provider(installationHost("win32"));
const nativeApplication = peTarget("x86_64");
for (const architecture of ["x86", "x86_64"] as const)
expect(
ghidra.inspectTargetSupport(peTarget(architecture)),
).toMatchObject({
status: "supported",
diagnostics: {
host_platform: "win32",
architecture,
executable_role: "application",
managed: false,
},
});
expect(await ghidra.inspectAvailability()).toMatchObject({
status: "unavailable",
code,
reason: expect.stringContaining(
"Windows native controls are unavailable",
),
diagnostics: {
windows_native_failure: {
stage: failureStage,
remediation: expect.any(String),
},
windows_security: {
job_object_process_ownership: expect.objectContaining({
available: false,
proof: "not-proven",
}),
private_runtime_dacl: expect.objectContaining({
available: false,
proof: "not-proven",
}),
reparse_safe_path_admission: expect.objectContaining({
available: false,
proof: "not-proven",
}),
},
},
});
expect(load).toHaveBeenCalledTimes(1);
expect(ghidra.capabilities()).toEqual(
expect.arrayContaining([
expect.objectContaining({
operation: "list_procedures",
available: false,
availabilityCode: code,
limitations: expect.arrayContaining([
expect.stringContaining(
"matching packaged Windows x64 native addon",
),
expect.stringContaining(
"private DACLs, and Job Object ownership automatically",
),
]),
}),
]),
);
expect(
ghidra.inspectTargetSupport({
...nativeApplication,
executableRole: "non-executable",
}),
).toMatchObject({
status: "unsupported",
code: "target_role_unsupported",
});
expect(
ghidra.inspectTargetSupport({ ...nativeApplication, managed: true }),
).toMatchObject({
status: "unsupported",
code: "managed_target_unsupported",
});
expect(
ghidra.inspectTargetSupport(executableTarget("elf", "x86_64")),
).toMatchObject({
status: "unsupported",
code: "target_format_unsupported",
});
const client = ghidra.createClient(nativeApplication);
const health = await client.execute("health", {});
if (health.ok)
throw new Error(
"Failed native admission must not create a ready client",
);
expect(projectAnalysisError(health.error)).toMatchObject({
code: "capability_unavailable",
details: {
reason: "Windows native controls are unavailable: missing manifest",
},
});
expect(load).toHaveBeenCalledTimes(3);
},
);
});
describe("Ghidra Windows PE fixture admission", () => {
it.each(["arm", "arm64"] as const)(
"does not infer a COFF machine from an unobserved %s family",
(architecture) => {
const { peMachine, ...unobserved } = peTarget(architecture);
expect(peMachine).toBeDefined();
expect(
provider(installationHost("win32")).inspectTargetSupport(unobserved),
).toMatchObject({
status: "unsupported",
code: "architecture_unsupported",
diagnostics: { pe_machine: null },
});
},
);
it("admits generated PE32 and PE32+ DLLs and applications while preserving native-only Windows admission", async () => {
const root = fileURLToPath(new URL("../../", import.meta.url));
await promisify(execFile)(process.execPath, [
join(root, "scripts/create-ghidra-windows-fixture.mjs"),
]);
const ghidra = provider(installationHost("win32"));
for (const architecture of ["x86", "x86_64", "arm", "arm64"] as const) {
for (const dll of [false, true]) {
const suffix = architecture === "x86_64" ? "" : `-${architecture}`;
const path = join(
root,
"build/fixtures",
`rea-ghidra-windows${suffix}.${dll ? "dll" : "exe"}`,
);
const bytes = await readFile(path);
const metadata = parseExecutableHeader(bytes, "x64");
const role = dll ? "shared-library" : "application";
expect(metadata).toMatchObject({
ok: true,
value: {
format: "pe",
architecture,
executableRole: role,
managed: false,
},
});
if (!metadata.ok) throw new Error(metadata.error);
if (metadata.value.format !== "pe")
throw new Error("Expected a PE fixture");
const target: BinaryTarget = {
path,
sha256: createHash("sha256").update(bytes).digest("hex"),
kind: "executable",
...metadata.value,
};
expect(ghidra.inspectTargetSupport(target).status).toBe("supported");
if (architecture === "arm") {
for (const peMachine of [0x01c0, 0x01c2]) {
const legacy = Buffer.from(bytes);
legacy.writeUInt16LE(peMachine, legacy.readUInt32LE(0x3c) + 4);
const parsed = parseExecutableHeader(legacy, "x64");
if (!parsed.ok) throw new Error(parsed.error);
if (parsed.value.format !== "pe")
throw new Error("Expected a PE fixture");
expect(parsed.value).toMatchObject({ architecture, peMachine });
expect(
ghidra.inspectTargetSupport({
...target,
...parsed.value,
sha256: createHash("sha256").update(legacy).digest("hex"),
}),
).toMatchObject({
status: "unsupported",
code: "architecture_unsupported",
diagnostics: { pe_machine: peMachine },
});
}
}
for (const [candidate, code] of [
[
{ ...target, executableRole: "non-executable" },
"target_role_unsupported",
],
[{ ...target, managed: true }, "managed_target_unsupported"],
] as const) {
expect(ghidra.inspectTargetSupport(candidate)).toMatchObject({
status: "unsupported",
code,
});
}
}
}
});
});
describe("Ghidra startup configuration", () => {
it("carries supplied startup settings through configuration, the provider, the timer and timeout diagnostics", async () => {
const target = executableTarget("elf", "x86_64");
for (const [raw, expected] of [
[undefined, 330_000],
["900000", 900_000],
["1260000", 1_260_000],
["2147483647", 2_147_483_647],
] as const) {
const config = parseConfig({
GHIDRA_INSTALL_DIR: INSTALL,
...(raw === undefined ? {} : { REA_GHIDRA_STARTUP_TIMEOUT_MS: raw }),
});
if (!config.ok) throw config.error;
let timeout: number | undefined;
const ghidra = new GhidraProvider(
config.value,
silentLogger,
{},
installationHost(),
(options) => {
timeout = options.startupTimeoutMs;
return {
start: () =>
Promise.resolve(
err(
new GhidraSessionError(
"timeout",
"Startup deadline elapsed",
{},
),
),
),
callTool: () => Promise.resolve(ok([])),
close: () => Promise.resolve(ok(null)),
};
},
);
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok) throw profile.error;
if (profile.value.profile === null)
throw new Error("Expected a bound profile");
const client = ghidra.createClient(target, profile.value.profile);
try {
const failure = await client.execute("health", {});
expect(timeout, String(raw)).toBe(expected);
expect(failure).toMatchObject({
ok: false,
error: { _tag: "AnalysisTimeoutError", timeoutMs: expected },
});
if (timeout === undefined)
throw new Error("Provider omitted startup deadline");
const deadline = new ProviderStartupDeadline(timeout);
try {
expect(await deadline.wait(20)).toBe("elapsed");
expect(deadline.signal.aborted).toBe(false);
} finally {
deadline.dispose();
}
} finally {
await client.close();
}
}
});
});
describe("Ghidra client projection", () => {
it("commits exact provider, isolation, and resource semantics", async () => {
const toolCalls: Array<{
readonly operation: string;
readonly input: unknown;
readonly options: unknown;
}> = [];
let startCount = 0;
const factoryOptions: unknown[] = [];
const callTool: ReturnType<GhidraProviderClientFactory>["callTool"] = (
operation,
input,
options,
) => {
toolCalls.push({ operation, input, options });
return Promise.resolve(
ok([
{
address: "0x1000",
value: "fixture_main",
procedure: {
external: false,
thunk: false,
thunk_target: null,
},
},
]),
);
};
const clientFactory: GhidraProviderClientFactory = (options) => {
factoryOptions.push(options);
return {
start: () => {
startCount += 1;
return Promise.resolve(ok(sessionInfo()));
},
callTool,
close: () => Promise.resolve(ok(null)),
};
};
const ghidra = provider(installationHost(), clientFactory);
const resolved = await ghidra.resolveAnalysisProfile(
executableTarget("elf", "x86_64"),
);
if (!resolved.ok) throw resolved.error;
if (resolved.value.profile === null)
throw new Error("Expected a bound Ghidra profile");
expect(resolved.value.profile).toMatchObject({
provider: { id: "ghidra", name: "Ghidra", version: "12.1.4" },
parameters: {
import_mode: "ephemeral-source-immutable",
annotation_policy: "atomic-function-entry-metadata-v1",
analyzer_preset: "ghidra-default",
},
});
expect(resolved.value.profile.parameters).toMatchObject({
language_id: "auto-from-header",
compiler_spec_id: "auto-default",
call_relationship_coverage: "function-body-call-coverage-v5",
function_dossier_coverage: "observed-facets-and-call-relationships-v1",
});
const result = await ghidra
.createClient(executableTarget("elf", "x86_64"), resolved.value.profile, {
runId: "11111111-1111-4111-8111-111111111111",
})
.execute("list_procedures", {});
expect(factoryOptions).toEqual([
expect.objectContaining({
runId: "11111111-1111-4111-8111-111111111111",
platform: "linux",
launcher: expect.objectContaining({
options: expect.objectContaining({
javaVmName: "OpenJDK 64-Bit Server VM",
}),
}),
}),
]);
expect(toolCalls).toEqual([
{
operation: "list_procedures",
input: { document: null },
options: {},
},
]);
expect(result).toMatchObject({
ok: true,
value: {
provider: {
id: "ghidra",
name: "Ghidra",
version: "12.1.4",
},
analysisProfile: resolved.value.profile,
result: [{ address: "0x1000", value: "fixture_main" }],
rawResult: null,
},
});
expect(startCount).toBe(0);
});
});
describe("Ghidra result projection", () => {
it("rejects malformed inventory output before Evidence creation", async () => {
const ghidra = provider(installationHost(), () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: () => Promise.resolve(ok({ items: "not-an-inventory" })),
close: () => Promise.resolve(ok(null)),
}));
const client = await createElfClient(ghidra);
await expect(client.execute("list_procedures", {})).resolves.toMatchObject({
ok: false,
error: { _tag: "AnalysisOutputError" },
});
});
it("projects terminal-call facts from the function bridge into execution limitations", async () => {
const limitation =
"Ghidra Listing reports a terminal call at 0x401020 to 0x7f001000 __tls_get_addr (external=true, thunk=false, hasNoReturn=true); fallthrough is excluded by Ghidra's flow model. This records Ghidra's FunctionManager flag, not an independent verification that the callee cannot return.";
const ghidra = provider(installationHost(), () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: () =>
Promise.resolve(
ok({ value: "void main() {}", limitations: [limitation] }),
),
close: () => Promise.resolve(ok(null)),
}));
const client = await createElfClient(ghidra);
const execution = await client.execute("procedure_pseudo_code", {
procedure: "main",
});
if (!execution.ok) throw execution.error;
expect(execution.value.result).toBe("void main() {}");
expect(execution.value.limitations).toContain(limitation);
expect(execution.value.rawResult).toBeNull();
await client.close();
});
it.each([
["invalid_request", "AnalysisInputError"],
["not_found", "AnalysisInputError"],
["ambiguous", "AnalysisInputError"],
["method_unavailable", "AnalysisCapabilityUnavailableError"],
] as const)(
"projects remote %s without losing its typed meaning",
async (code, tag) => {
const ghidra = provider(installationHost(), () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: () =>
Promise.resolve(
err(
new GhidraSessionError(
"remote",
"Fixture remote failure",
{ remote_code: code },
{ remoteCode: code },
),
),
),
close: () => Promise.resolve(ok(null)),
}));
const client = await createElfClient(ghidra);
await expect(
client.execute("list_procedures", {}),
).resolves.toMatchObject({
ok: false,
error: { _tag: tag },
});
},
);
it("preserves the rejected name constraint and function address", async () => {
const message =
"Invalid function name at 0x10100: Symbol name contains invalid characters";
const ghidra = provider(installationHost(), () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: () =>
Promise.resolve(
err(
new GhidraSessionError(
"remote",
message,
{},
{ remoteCode: "invalid_function_name" },
),
),
),
close: () => Promise.resolve(ok(null)),
}));
const client = await createElfClient(ghidra);
await expect(
client.execute("annotate_native_function", {
procedure: "0x10100",
name: "bad name",
}),
).resolves.toMatchObject({
ok: false,
error: {
_tag: "AnalysisInputError",
issues: [{ path: ["name"], reason: "invalid_value", message }],
},
});
});
it("projects remote decompile cancellation as a provider-neutral interruption", async () => {
const code = "decompile_cancelled";
const tag = "AnalysisCancelledError";
const ghidra = provider(installationHost(), () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: () =>
Promise.resolve(
err(
new GhidraSessionError(
"remote",
"Fixture decompiler interruption",
{ remote_code: code },
{ remoteCode: code },
),
),
),
close: () => Promise.resolve(ok(null)),
}));
const client = await createElfClient(ghidra);
const result = await client.execute("procedure_pseudo_code", {
procedure: "main",
});
expect(result).toMatchObject({
ok: false,
error: { _tag: tag },
});
if (!result.ok)
expect(projectAnalysisError(result.error)).toMatchObject({
code: "cancelled",
details: { diagnostics: { remote_code: code } },
});
});
it("returns cancellation before profile work", async () => {
const controller = new AbortController();
controller.abort();
await expect(
provider().resolveAnalysisProfile(executableTarget("elf", "x86_64"), {
signal: controller.signal,
}),
).resolves.toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError", operation: "open_binary" },
});
});
});
describe("Ghidra decompiler failure projection", () => {
it("reports a procedure decompiler failure without blaming the environment", async () => {
const code = "decompile_failed";
const message =
"Ghidra decompilation failed: Low-level Error: Fixture decompiler failure";
const ghidra = provider(installationHost(), () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: () =>
Promise.resolve(
err(
new GhidraSessionError(
"remote",
message,
{ remote_code: code },
{ remoteCode: code },
),
),
),
close: () => Promise.resolve(ok(null)),
}));
const client = await createElfClient(ghidra);
const result = await client.execute("procedure_pseudo_code", {
procedure: "main",
});
expect(result).toMatchObject({
ok: false,
error: { _tag: "ProviderAdapterError" },
});
if (!result.ok) {
const projected = projectAnalysisError(result.error);
expect(projected).toMatchObject({
code: "execution_failure",
retryable: false,
message: `${message}. Only the decompiler failed for this procedure; the Ghidra session remains usable.`,
details: { diagnostics: { remote_code: code } },
});
expect(projected.message).not.toContain("rea doctor");
expect(projected.remediation.action).toContain("analyze_function");
expect(projected.remediation.action).toContain(
"facet_availability.pseudocode",
);
expect(projected.remediation.action).not.toContain("rea doctor");
}
});
});
describe("Ghidra PE CodeView debug symbol limitations", () => {
it.each([
["absent report", undefined, "load state unknown"],
["unknown load", null, "load state unknown"],
["not loaded", false, "reports not loaded"],
["loaded", true, "reports a loaded PDB"],
] as const)(
"preserves %s in operation and health Evidence without duplicate caveats",
async (_, loaded, expected) => {
const ghidra = provider(installationHost(), () => ({
start: () =>
Promise.resolve(
ok({
...sessionInfo(),
...(loaded === undefined
? {}
: {
pdb: {
file: "test.pdb",
guid: "01234567-89ab-cdef-0123-456789abcdef",
age: "1",
signature: null,
version: "RSDS",
loaded,
},
}),
}),
),
callTool: () => Promise.resolve(ok([])),
close: () => Promise.resolve(ok(null)),
}));
const target = {
...peTarget("x86_64"),
codeView: {
pdbPath: "test.pdb",
pdbFileName: "test.pdb",
guid: "01234567-89ab-cdef-0123-456789abcdef",
age: 1,
},
};
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("expected PE profile");
const client = ghidra.createClient(target, profile.value.profile);
try {
const search = await client.execute("search_procedures", {
pattern: "add_numbers",
});
if (!search.ok) throw search.error;
const health = await client.execute("health", {});
if (!health.ok) throw health.error;
for (const observation of [search.value, health.value]) {
const caveats = observation.limitations.filter((limit) =>
limit.includes("PDB"),
);
expect(caveats).toHaveLength(1);
expect(caveats[0]).toContain(expected);
expect(caveats[0]).not.toContain("names are analysis-generated");
expect(caveats[0]).not.toContain("that were not applied");
}
} finally {
await client.close();
}
},
);
});
describe("Ghidra relationship coverage", () => {
it("marks the full direct call-reference response complete while keeping static caveats", async () => {
const ghidra = provider(installationHost(), () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: (operation) =>
Promise.resolve(
ok(
operation === "procedure_callees"
? {
value: ["0x2000"],
limitations: [],
relationship_coverage: {
status: "complete",
diagnostics: [
"Only resolved Ghidra call references are returned; unresolved computed or indirect calls remain unknown, while function classifications distinguish thunks and externals.",
],
},
}
: { value: [], limitations: [] },
),
),
close: () => Promise.resolve(ok(null)),
}));
const client = await createElfClient(ghidra);
const execution = await client.execute("procedure_callees", {
procedure: "0x1000",
document: "fixture",
});
if (!execution.ok) throw execution.error;
expect(execution.value.relationshipCoverage).toEqual({
status: "complete",
diagnostics: [
"Only resolved Ghidra call references are returned; unresolved computed or indirect calls remain unknown, while function classifications distinguish thunks and externals.",
],
});
expect(execution.value.limitations).not.toContain(
"Only resolved Ghidra call references are returned; unresolved computed or indirect calls remain unknown, while function classifications distinguish thunks and externals.",
);
await client.close();
});
});
describe("Ghidra measured raw load-image projection", () => {
it.each([
"verified",
"mapping-mismatch",
"changed-snapshot",
"cancelled",
"malformed-coordinate",
] as const)(
"streams raw snapshot identity and preserves %s outcomes",
async (state) => {
const fixture = fixtureRawBinaryLoadImage();
if (state === "malformed-coordinate")
fixture.observation.image_base = "not-an-address";
if (state === "mapping-mismatch") {
const mapping = fixture.observation.mappings[0];
if (mapping === undefined)
throw new Error("Missing source mapping fixture");
mapping.overlay = true;
}
const controller = new AbortController();
const signals: (AbortSignal | undefined)[] = [];
const ghidra = provider(installationHost(), () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: (operation) => {
if (operation !== "inspect_native_load_image")
throw new Error(`unexpected operation ${operation}`);
return Promise.resolve(
ok(jsonValueSchema.parse(fixture.observation)),
);
},
readTargetSnapshot: () => {
throw new Error(
"raw verification must not capture the complete file",
);
},
hashTargetSnapshot: (signal) => {
signals.push(signal);
if (state === "cancelled") {
controller.abort();
return Promise.resolve(
err(
new GhidraSessionError(
"cancelled",
"Snapshot hashing cancelled",
),
),
);
}
return Promise.resolve(
ok({
...fixture.snapshot,
...(state === "changed-snapshot"
? { sha256: "f".repeat(64) }
: {}),
}),
);
},
close: () => Promise.resolve(ok(null)),
}));
const resolved = await ghidra.resolveAnalysisProfile(fixture.target);
if (!resolved.ok) throw resolved.error;
if (resolved.value.profile === null)
throw new Error("expected raw profile");
const client = ghidra.createClient(
fixture.target,
resolved.value.profile,
);
try {
const result = await client.execute(
"inspect_native_load_image",
{},
{ signal: controller.signal },
);
expect(signals).toEqual(
state === "malformed-coordinate" ? [] : [controller.signal],
);
if (state === "verified" || state === "mapping-mismatch") {
if (!result.ok) throw result.error;
expect(result.value.result).toMatchObject({
status: state === "verified" ? "verified" : "mismatch",
observations: fixture.observation,
});
if (state === "mapping-mismatch") {
expect(result.value.result).toMatchObject({
checks: expect.arrayContaining([
expect.objectContaining({
name: "mapping.overlay",
observed: true,
matched: false,
}),
]),
});
}
} else {
expect(result).toMatchObject({
ok: false,
error: {
_tag:
state === "cancelled"
? "AnalysisCancelledError"
: state === "malformed-coordinate"
? "AnalysisOutputError"
: "ProviderAdapterError",
},
});
}
} finally {
await client.close();
}
},
);
});
describe("Ghidra measured DOS load-image projection", () => {
it.each([
"verified",
"mismatch",
"changed-snapshot",
"unsupported",
"missing-snapshot",
] as const)(
"preserves %s state and producing observations",
async (state) => {
const fixture = fixtureDosLoadImage();
if (state === "mismatch") fixture.observation.entry_points = ["0x10001"];
if (state === "changed-snapshot") fixture.bytes[0] = 0;
const factory: GhidraProviderClientFactory = () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: () =>
Promise.resolve(ok(jsonValueSchema.parse(fixture.observation))),
close: () => Promise.resolve(ok(null)),
...(state === "missing-snapshot"
? {}
: {
attestDosTargetSnapshot: async (observations) =>
compareDosClientFixture(
fixture.bytes,
fixture.sha256,
observations,
),
}),
});
const ghidra = provider(installationHost(), factory);
const target: BinaryTarget = {
path: "/tmp/source-owned-fixture.exe",
sha256: fixture.sha256,
kind: "executable",
format: state === "unsupported" ? "elf" : "dos-mz",
architecture: "x86",
availableArchitectures: ["x86"],
};
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected admitted profile");
const result = await ghidra
.createClient(target, profile.value.profile)
.execute("inspect_native_load_image", {});
if (state === "changed-snapshot" || state === "missing-snapshot") {
expect(result).toMatchObject({
ok: false,
error: {
_tag: "ProviderAdapterError",
diagnostics: { reason: expect.stringContaining("snapshot") },
},
});
} else {
expect(result).toMatchObject({
ok: true,
value: {
result: { status: state, observations: fixture.observation },
rawResult: fixture.observation,
analysisProfile: profile.value.profile,
},
});
}
},
);
});
const unavailableNativeAotDatabaseType = (address: string | null) => ({
status: "unavailable",
reason:
"No exact database type or defined typed data exists at the selected identity",
id: null,
name: null,
kind: "unavailable",
source: "analysis-database",
source_archive: null,
address,
size_bytes: null,
alignment_bytes: null,
packing_enabled: null,
referenced_type: null,
array_count: null,
array_stride_bytes: null,
fields: [],
members: [],
total_fields: 0,
truncated: false,
limitations: [],
});
it("returns read-only NativeAOT metadata inline and drills down by derived MethodTable address", async () => {
const bytes = nativeAotPeFixture();
const readSnapshot = vi.fn(async () =>
ok({ kind: "captured" as const, bytes }),
);
const observations = fixtureDosLoadImage().observation;
observations.image_base = "0x140000000";
const factory: GhidraProviderClientFactory = () => ({
start: () =>
Promise.resolve(
ok({
...sessionInfo(),
target: { ...sessionInfo().target, image_base: "0x140000000" },
}),
),
callTool: (operation) =>
Promise.resolve(
ok(
jsonValueSchema.parse(
operation === "inspect_native_load_image"
? observations
: unavailableNativeAotDatabaseType("0x140002280"),
),
),
),
readTargetSnapshot: readSnapshot,
close: () => Promise.resolve(ok(null)),
});
const ghidra = provider(installationHost(), factory);
const target = { ...peTarget("x86_64"), sha256: nativeAotPeDigest(bytes) };
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected admitted PE profile");
const client = ghidra.createClient(target, profile.value.profile);
const image = await client.execute("inspect_native_load_image", {});
expect(image).toMatchObject({
ok: true,
value: {
result: {
status: "unsupported",
observations: {
metadata_recovery: [
{
status: "complete",
analysis_mode: "read-only-derived-overlay",
method_tables: 3,
frozen_strings: [{ value: "REA_NATIVEAOT_FROZEN" }],
},
],
},
},
rawResult: observations,
},
});
for (const address of [
"0x140002280",
"140002280",
"ram:0x140002280",
"%72am:0x140002280",
"0X0140002280",
]) {
const detail = await client.execute("inspect_native_data_type", {
address,
});
expect(detail).toMatchObject({
ok: true,
value: {
rawResult: unavailableNativeAotDatabaseType("0x140002280"),
result: {
status: "unavailable",
source: "analysis-database",
metadata_recovery: {
source: "read-only-derived-overlay",
method_table_address: "0x140002280",
related_type: { address: "0x140002200", type: null },
},
},
},
});
}
expect(readSnapshot).toHaveBeenCalledOnce();
await client.close();
});
it.each([
["0x140002280", "0x140002280", "0x140002280"],
["140002280", "0x140002280", "0x140002280"],
["ram:0x140002280", "0x140002280", "0x140002280"],
["%72am:0x140002280", "0x140002280", "0x140002280"],
["0X0140002280", "0x140002280", "0x140002280"],
["0x140002280", "0x140002200", "0x140002200"],
["0x140002280", null, null],
["0x140002280", "register:0x140002280", null],
["0x140002280", "overlay%3Aspace:0x140002280", null],
["0x140002280", "0x140002288", null],
["register:0x140002280", "register:0x140002280", null],
] as const)(
"looks up NativeAOT type %s using resolved identity %s",
async (address, resolvedAddress, expectedTable) => {
const bytes = nativeAotPeFixture();
const operations: string[] = [];
const callerAddresses: unknown[] = [];
const readSnapshot = vi.fn(async () =>
ok({ kind: "captured" as const, bytes }),
);
const factory: GhidraProviderClientFactory = () => ({
start: () =>
Promise.resolve(
ok({
...sessionInfo(),
target: { ...sessionInfo().target, image_base: "0x140000000" },
}),
),
callTool: (operation, parameters) => {
operations.push(operation);
callerAddresses.push(parameters.address);
return Promise.resolve(
ok(
jsonValueSchema.parse(
unavailableNativeAotDatabaseType(resolvedAddress),
),
),
);
},
readTargetSnapshot: readSnapshot,
close: () => Promise.resolve(ok(null)),
});
const ghidra = provider(installationHost(), factory);
const target = { ...peTarget("x86_64"), sha256: nativeAotPeDigest(bytes) };
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected admitted PE profile");
const client = ghidra.createClient(target, profile.value.profile);
const detail = await client.execute("inspect_native_data_type", {
address,
});
expect(detail.ok).toBe(true);
if (!detail.ok) throw detail.error;
expect(detail.value.result).toMatchObject({ address: resolvedAddress });
if (expectedTable === null) {
expect(detail.value.result).not.toHaveProperty("metadata_recovery");
} else {
expect(detail.value.result).toMatchObject({
metadata_recovery: {
source: "read-only-derived-overlay",
method_table_address: expectedTable,
},
});
}
expect(callerAddresses).toEqual([address]);
expect(readSnapshot).toHaveBeenCalledTimes(
resolvedAddress === null ? 0 : 1,
);
expect(operations).toEqual(["inspect_native_data_type"]);
await client.close();
},
);
it("retains engine-provided NativeAOT metadata without deriving another snapshot", async () => {
const bytes = nativeAotPeFixture();
const metadata = {
format: "dotnet-nativeaot",
source: "analysis-database",
status: "partial",
header_address: "0x140002000",
format_major: 9,
format_minor: 1,
method_table_address: "0x140002280",
name_origin: "generated",
original_name: null,
base_size_bytes: 32,
related_type: null,
interfaces: [],
virtual_slots: [],
derived_memory: null,
diagnostics: ["Engine-provided fixture metadata"],
limitations: ["Fixture has no original managed names"],
};
const readSnapshot = vi.fn(async () => {
throw new Error("Unexpected source snapshot read");
});
const factory: GhidraProviderClientFactory = () => ({
start: async () =>
ok({
...sessionInfo(),
target: { ...sessionInfo().target, image_base: "0x140000000" },
}),
callTool: async () =>
ok(
jsonValueSchema.parse({
...unavailableNativeAotDatabaseType("0x140002280"),
status: "available",
reason: null,
id: "/NativeAOT/Example_MT",
name: "Example_MT",
kind: "struct",
size_bytes: 32,
alignment_bytes: 8,
packing_enabled: false,
metadata_recovery: metadata,
}),
),
readTargetSnapshot: readSnapshot,
close: async () => ok(null),
});
const ghidra = provider(installationHost(), factory);
const target = { ...peTarget("x86_64"), sha256: nativeAotPeDigest(bytes) };
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected admitted PE profile");
const client = ghidra.createClient(target, profile.value.profile);
const detail = await client.execute("inspect_native_data_type", {
address: "0x140002280",
});
expect(detail).toMatchObject({
ok: true,
value: { result: { status: "available", metadata_recovery: metadata } },
});
expect(readSnapshot).not.toHaveBeenCalled();
await client.close();
});
it("shares one session snapshot across callers while isolating cancellation and rejecting a changed base", async () => {
const bytes = nativeAotPeFixture();
const baseObservation = fixtureDosLoadImage().observation;
baseObservation.image_base = "0x140000000";
let calls = 0;
let snapshotReads = 0;
let snapshotSignal: AbortSignal | undefined;
let releaseSnapshot:
| ((value: Result<GhidraTargetSnapshot, GhidraSessionError>) => void)
| undefined;
let markSnapshotStarted: (() => void) | undefined;
const snapshotStarted = new Promise<void>((resolve) => {
markSnapshotStarted = resolve;
});
const snapshotResult = new Promise<
Result<GhidraTargetSnapshot, GhidraSessionError>
>((resolve) => {
releaseSnapshot = resolve;
});
const factory: GhidraProviderClientFactory = () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: (operation) => {
calls += 1;
const observation = {
...baseObservation,
source_files: [
{ ...baseObservation.source_files[0]!, name: `caller-${calls}` },
],
};
return Promise.resolve(
ok(
jsonValueSchema.parse(
operation === "inspect_native_load_image"
? observation
: unavailableNativeAotDatabaseType("0x140002280"),
),
),
);
},
readTargetSnapshot: (_maximumBytes, signal) => {
snapshotReads += 1;
snapshotSignal = signal;
markSnapshotStarted?.();
return snapshotResult;
},
close: () => Promise.resolve(ok(null)),
});
const ghidra = provider(installationHost(), factory);
const target = { ...peTarget("x86_64"), sha256: nativeAotPeDigest(bytes) };
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected admitted PE profile");
const client = ghidra.createClient(target, profile.value.profile);
const firstCaller = new AbortController();
const secondCaller = new AbortController();
const first = client.execute(
"inspect_native_load_image",
{},
{
signal: firstCaller.signal,
},
);
const second = client.execute(
"inspect_native_load_image",
{},
{
signal: secondCaller.signal,
},
);
await snapshotStarted;
expect(snapshotReads).toBe(1);
expect(snapshotSignal).toBeDefined();
expect(snapshotSignal).not.toBe(firstCaller.signal);
expect(snapshotSignal).not.toBe(secondCaller.signal);
firstCaller.abort();
await expect(first).resolves.toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError" },
});
releaseSnapshot?.(ok({ kind: "captured", bytes }));
const secondResult = await second;
expect(secondResult).toMatchObject({
ok: true,
value: {
rawResult: {
source_files: [{ name: "caller-2" }],
},
result: {
observations: {
source_files: [{ name: "caller-2" }],
},
},
},
});
expect(snapshotReads).toBe(1);
expect(calls).toBe(2);
baseObservation.image_base = "0x150000000";
const conflictingBase = await client.execute("inspect_native_load_image", {});
expect(conflictingBase).toMatchObject({
ok: false,
error: {
_tag: "ProviderAdapterError",
diagnostics: {
reason: expect.stringContaining("different loaded image base"),
},
},
});
expect(snapshotReads).toBe(1);
await client.close();
// The completed producer needs no stop; active-close joining is covered below.
expect(snapshotSignal?.aborted).toBe(false);
});
it("retries a failed NativeAOT snapshot read without retaining a failed derivation", async () => {
const bytes = nativeAotPeFixture();
const observations = fixtureDosLoadImage().observation;
observations.image_base = "0x140000000";
let snapshotReads = 0;
const factory: GhidraProviderClientFactory = () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: () => Promise.resolve(ok(jsonValueSchema.parse(observations))),
readTargetSnapshot: () => {
snapshotReads += 1;
return Promise.resolve(
snapshotReads === 1
? err(
new GhidraSessionError(
"process",
"temporary snapshot read failure",
),
)
: ok({ kind: "captured", bytes }),
);
},
close: () => Promise.resolve(ok(null)),
});
const ghidra = provider(installationHost(), factory);
const target = { ...peTarget("x86_64"), sha256: nativeAotPeDigest(bytes) };
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected admitted PE profile");
const client = ghidra.createClient(target, profile.value.profile);
await expect(
client.execute("inspect_native_load_image", {}),
).resolves.toMatchObject({
ok: false,
error: { _tag: "ProviderAdapterError" },
});
await expect(
client.execute("inspect_native_load_image", {}),
).resolves.toMatchObject({
ok: true,
value: {
result: {
observations: {
metadata_recovery: [{ status: "complete" }],
},
},
},
});
expect(snapshotReads).toBe(2);
await client.close();
});
it.each(["captured", "cancelled-with-facts"] as const)(
"rejects all waiters when the loaded image base changes during derivation (%s)",
async (outcome) => {
const bytes = nativeAotPeFixture();
const observation = fixtureDosLoadImage().observation;
let calls = 0;
let resolveSnapshot:
| ((value: Result<GhidraTargetSnapshot, GhidraSessionError>) => void)
| undefined;
let markSnapshotStarted: (() => void) | undefined;
const snapshotStarted = new Promise<void>((resolve) => {
markSnapshotStarted = resolve;
});
const snapshot = new Promise<
Result<GhidraTargetSnapshot, GhidraSessionError>
>((resolve) => {
resolveSnapshot = resolve;
});
const factory: GhidraProviderClientFactory = () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: () => {
calls += 1;
return Promise.resolve(
ok(
jsonValueSchema.parse({
...observation,
image_base: calls === 1 ? "0x140000000" : "0x150000000",
}),
),
);
},
readTargetSnapshot: () => {
markSnapshotStarted?.();
return snapshot;
},
close: () => Promise.resolve(ok(null)),
});
const ghidra = provider(installationHost(), factory);
const target = { ...peTarget("x86_64"), sha256: nativeAotPeDigest(bytes) };
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected admitted PE profile");
const client = ghidra.createClient(target, profile.value.profile);
const originalBase = client.execute("inspect_native_load_image", {});
await snapshotStarted;
const changedBase = await client.execute("inspect_native_load_image", {});
expect(changedBase).toMatchObject({
ok: false,
error: {
_tag: "ProviderAdapterError",
diagnostics: {
observed_image_base: "0x150000000",
measured_observation: { image_base: "0x150000000" },
},
},
});
resolveSnapshot?.(
outcome === "captured"
? ok({ kind: "captured", bytes })
: err(
new GhidraSessionError(
"cancelled",
"Controlled identity stop",
{},
{
cancellation: { reason: "identity conflict" },
partialObservation: {
kind: "file-snapshot-hash",
path: "/controlled/snapshot",
sha256: "a".repeat(64),
bytes: 17,
},
},
),
),
);
const originalResult = await originalBase;
expect(originalResult).toMatchObject({
ok: false,
error: {
_tag: "ProviderAdapterError",
diagnostics: {
reason: expect.stringContaining("conflicting loaded image bases"),
measured_observation: { image_base: "0x140000000" },
conflicting_observation: { image_base: "0x150000000" },
},
},
});
if (outcome === "cancelled-with-facts") {
expect(originalResult).toMatchObject({
ok: false,
error: {
partialObservation: { kind: "file-snapshot-hash", bytes: 17 },
},
});
}
expect(calls).toBe(2);
await client.close();
},
);
it("preserves NativeAOT source facts and cleanup when a later caller contradicts identity", async () => {
const partial = {
kind: "file-snapshot-hash" as const,
path: "/controlled/snapshot",
sha256: "a".repeat(64),
bytes: 17,
};
const cleanup = new ProviderCleanupError("ghidra", [partial.path], {
reason: "controlled close failure",
});
const lease = new AnalysisCleanupLease(async () => {}, [partial.path]);
lease.bindCleanupError(cleanup);
onTestFinished(() => lease.release());
const owner = new GhidraNativeAotSnapshotOwner({
targetSha256: partial.sha256,
readSnapshot: async () =>
err(
new GhidraSessionError(
"protocol",
"Controlled snapshot failure",
{},
{ partialObservation: partial },
).withCleanupFailure(cleanup),
),
projectFailure: () => cleanup,
});
await owner.derive("0x140000000", "inspect_native_load_image", undefined, {
image_base: "0x140000000",
});
const conflict = await owner.derive(
"0x150000000",
"inspect_native_load_image",
undefined,
{ image_base: "0x150000000" },
);
if (conflict.ok) throw new Error("Expected conflicting snapshot identity");
expect(conflict.error.partialObservation).toEqual(partial);
expect(conflict.error.cleanupIncomplete).toBe(true);
await lease.release();
expect(conflict.error.cleanupIncomplete).toBe(false);
await owner.close();
});
const nativeAotWaiterClient = async () => {
const bytes = nativeAotPeFixture();
const observations = fixtureDosLoadImage().observation;
observations.image_base = "0x140000000";
const started = createDeferred<AbortSignal>();
const snapshot =
createDeferred<Result<GhidraTargetSnapshot, GhidraSessionError>>();
const close = vi.fn(async () => ok(null));
const readSnapshot = vi.fn(
(_maximum: number | undefined, signal: AbortSignal | undefined) => {
if (signal === undefined) throw new Error("Missing owned read signal");
started.resolve(signal);
return snapshot.promise;
},
);
const factory: GhidraProviderClientFactory = () => ({
start: async () => ok(sessionInfo()),
callTool: async (operation) =>
ok(
jsonValueSchema.parse(
operation === "inspect_native_load_image"
? observations
: unavailableNativeAotDatabaseType("0x140002280"),
),
),
readTargetSnapshot: readSnapshot,
close,
});
const ghidra = provider(installationHost(), factory);
const target = { ...peTarget("x86_64"), sha256: nativeAotPeDigest(bytes) };
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected admitted PE profile");
const client = ghidra.createClient(target, profile.value.profile);
onTestFinished(async () => {
snapshot.resolve(ok({ kind: "captured", bytes }));
await client.close();
});
return { client, bytes, started, snapshot, close, readSnapshot };
};
it("joins the in-flight NativeAOT producer before closing its owning client", async () => {
const fixture = await nativeAotWaiterClient();
const pending = fixture.client.execute("inspect_native_load_image", {});
const signal = await fixture.started.promise;
let closed = false;
const closing = fixture.client.close().then((result) => {
closed = true;
return result;
});
await new Promise<void>((resolve) => setImmediate(resolve));
expect(signal.aborted).toBe(true);
expect(closed).toBe(false);
expect(fixture.close).not.toHaveBeenCalled();
fixture.snapshot.resolve(ok({ kind: "captured", bytes: fixture.bytes }));
await expect(pending).resolves.toMatchObject({
ok: false,
error: { _tag: "AnalysisCancelledError" },
});
expect((await closing).ok).toBe(true);
});
it("joins final NativeAOT waiter cancellation and retains exact producer cleanup", async () => {
const fixture = await nativeAotWaiterClient();
const caller = new AbortController();
const reason = { caller: "final snapshot waiter" };
let settled = false;
const pending = fixture.client
.execute("inspect_native_load_image", {}, { signal: caller.signal })
.then((result) => {
settled = true;
return result;
});
const signal = await fixture.started.promise;
const cleanup = new ProviderCleanupError(
"ghidra",
["controlled snapshot descriptor"],
{ reason: "controlled close failure" },
);
const lease = new AnalysisCleanupLease(async () => {}, [
"controlled snapshot descriptor",
]);
lease.bindCleanupError(cleanup);
onTestFinished(() => lease.release());
caller.abort(reason);
await new Promise<void>((resolve) => setImmediate(resolve));
expect(signal.aborted).toBe(true);
expect(signal.reason).toBe(reason);
expect(settled).toBe(false);
fixture.snapshot.resolve(
err(
new GhidraSessionError(
"cancelled",
"Controlled snapshot cancelled",
{},
{ cancellation: { reason }, cause: reason },
).withCleanupFailure(cleanup),
),
);
const result = await pending;
if (result.ok) throw new Error("Expected cancelled snapshot cleanup");
expect(result.error.cleanupIncomplete).toBe(true);
expect(result.error.cleanupPrimary?.cause).toBe(reason);
const refused = await fixture.client.execute("inspect_native_load_image", {});
expect(refused.ok).toBe(false);
expect(fixture.readSnapshot).toHaveBeenCalledTimes(1);
await lease.release();
expect(result.error.cleanupIncomplete).toBe(false);
expect(resolvedAnalysisError(result.error).cause).toBe(reason);
});
it.each([null, "caller stopped", new Error("caller stopped")])(
"preserves final NativeAOT cancellation reason and late capture (%s)",
async (reason) => {
const fixture = await nativeAotWaiterClient();
const caller = new AbortController();
const pending = fixture.client.execute(
"inspect_native_load_image",
{},
{ signal: caller.signal },
);
const signal = await fixture.started.promise;
caller.abort(reason);
await new Promise<void>((resolve) => setImmediate(resolve));
expect(signal.aborted).toBe(true);
expect(signal.reason).toBe(reason);
fixture.snapshot.resolve(ok({ kind: "captured", bytes: fixture.bytes }));
const cancelled = await pending;
if (cancelled.ok) throw new Error("Expected final caller cancellation");
expect(cancelled.error.cause).toBe(reason);
expect(cancelled.error.partialObservation).toMatchObject({
kind: "native-aot-snapshot",
capture: { status: "captured", bytes: fixture.bytes.length },
});
const retried = await fixture.client.execute(
"inspect_native_load_image",
{},
);
expect(retried.ok).toBe(true);
expect(fixture.readSnapshot).toHaveBeenCalledTimes(2);
await fixture.client.execute("inspect_native_load_image", {});
expect(fixture.readSnapshot).toHaveBeenCalledTimes(2);
},
);
it.each(["caller", "owner"] as const)(
"preserves NativeAOT physical failure and retained cleanup across %s cancellation",
async (interruption) => {
const fixture = await nativeAotWaiterClient();
const caller = new AbortController();
const pending = fixture.client.execute(
"inspect_native_load_image",
{},
{ signal: caller.signal },
);
await fixture.started.promise;
const cleanup = new ProviderCleanupError(
"ghidra",
["controlled snapshot descriptor"],
{ reason: "controlled close failure" },
);
const lease = new AnalysisCleanupLease(async () => {}, [
"controlled snapshot descriptor",
]);
lease.bindCleanupError(cleanup);
onTestFinished(() => lease.release());
const closing =
interruption === "owner" ? fixture.client.close() : undefined;
if (interruption === "caller") caller.abort("late caller");
await new Promise<void>((resolve) => setImmediate(resolve));
fixture.snapshot.resolve(
err(
new GhidraSessionError(
"protocol",
"Controlled independent physical failure",
{ physical_failure: "read rejected" },
{
partialObservation: {
kind: "file-snapshot-hash",
path: "/controlled/snapshot",
sha256: "a".repeat(64),
bytes: 17,
},
},
).withCleanupFailure(cleanup),
),
);
const result = await pending;
if (result.ok) throw new Error("Expected retained physical failure");
expect(result.error.cleanupIncomplete).toBe(true);
expect(projectAnalysisError(result.error)).toMatchObject({
code: "cleanup_incomplete",
details: {
partial_observation: { bytes: 17 },
diagnostics: { primary_error: { code: "execution_failure" } },
},
});
if (closing !== undefined) {
const closed = await closing;
expect(closed.ok).toBe(false);
}
expect(result.error.cleanupPrimary?.diagnostics).toMatchObject({
measured_observation: { image_base: "0x140000000" },
});
await lease.release();
expect(result.error.cleanupIncomplete).toBe(false);
expect(resolvedAnalysisError(result.error).diagnostics).toMatchObject({
measured_observation: { image_base: "0x140000000" },
});
expect((await fixture.client.close()).ok).toBe(true);
},
);
it("lets a new NativeAOT caller join a draining attempt before retrying", async () => {
const fixture = await nativeAotWaiterClient();
const caller = new AbortController();
const first = fixture.client.execute(
"inspect_native_load_image",
{},
{ signal: caller.signal },
);
await fixture.started.promise;
caller.abort("first caller");
await new Promise<void>((resolve) => setImmediate(resolve));
const second = fixture.client.execute("inspect_native_load_image", {});
await new Promise<void>((resolve) => setImmediate(resolve));
expect(fixture.readSnapshot).toHaveBeenCalledTimes(1);
fixture.snapshot.resolve(ok({ kind: "captured", bytes: fixture.bytes }));
expect((await first).ok).toBe(false);
expect((await second).ok).toBe(true);
expect(fixture.readSnapshot).toHaveBeenCalledTimes(2);
});
it("preserves a draining NativeAOT physical failure before later caller cancellation", async () => {
const fixture = await nativeAotWaiterClient();
const firstCaller = new AbortController();
const first = fixture.client.execute(
"inspect_native_load_image",
{},
{ signal: firstCaller.signal },
);
await fixture.started.promise;
firstCaller.abort("first caller");
await new Promise<void>((resolve) => setImmediate(resolve));
const secondCaller = new AbortController();
const second = fixture.client.execute(
"inspect_native_load_image",
{},
{ signal: secondCaller.signal },
);
await new Promise<void>((resolve) => setImmediate(resolve));
const cleanup = new ProviderCleanupError(
"ghidra",
["controlled snapshot descriptor"],
{ reason: "controlled close failure" },
);
const lease = new AnalysisCleanupLease(async () => {}, [
"controlled snapshot descriptor",
]);
lease.bindCleanupError(cleanup);
onTestFinished(() => lease.release());
// The reader resumes first. Abort after its result settles the shared producer,
// while the caller is still awaiting consumption of that completed result.
void fixture.snapshot.promise.then(() =>
queueMicrotask(() => secondCaller.abort("late second caller")),
);
fixture.snapshot.resolve(
err(
new GhidraSessionError(
"protocol",
"Controlled draining physical failure",
).withCleanupFailure(cleanup),
),
);
const result = await second;
if (result.ok) throw new Error("Expected draining physical failure");
expect(secondCaller.signal.aborted).toBe(true);
expect(projectAnalysisError(result.error)).toMatchObject({
code: "cleanup_incomplete",
details: { diagnostics: { primary_error: { code: "execution_failure" } } },
});
expect(fixture.readSnapshot).toHaveBeenCalledTimes(1);
expect((await first).ok).toBe(false);
await lease.release();
});
it("retains drained NativeAOT capture facts with the later caller's exact abort reason", async () => {
const fixture = await nativeAotWaiterClient();
const firstCaller = new AbortController();
const first = fixture.client.execute(
"inspect_native_load_image",
{},
{ signal: firstCaller.signal },
);
await fixture.started.promise;
firstCaller.abort("first caller");
await new Promise<void>((resolve) => setImmediate(resolve));
const secondCaller = new AbortController();
const reason = { caller: "later draining waiter" };
const second = fixture.client.execute(
"inspect_native_load_image",
{},
{ signal: secondCaller.signal },
);
await new Promise<void>((resolve) => setImmediate(resolve));
void fixture.snapshot.promise.then(() =>
queueMicrotask(() => secondCaller.abort(reason)),
);
fixture.snapshot.resolve(ok({ kind: "captured", bytes: fixture.bytes }));
const result = await second;
if (result.ok) throw new Error("Expected draining caller cancellation");
expect(result.error.cause).toBe(reason);
expect(result.error.partialObservation).toMatchObject({
kind: "native-aot-snapshot",
capture: { status: "captured", bytes: fixture.bytes.length },
});
expect(fixture.readSnapshot).toHaveBeenCalledTimes(1);
expect((await first).ok).toBe(false);
});
it("attributes shared NativeAOT producer failure to each requesting operation", async () => {
const fixture = await nativeAotWaiterClient();
const image = fixture.client.execute("inspect_native_load_image", {});
await fixture.started.promise;
const detail = fixture.client.execute("inspect_native_data_type", {
address: "0x140002280",
});
await new Promise<void>((resolve) => setImmediate(resolve));
fixture.snapshot.resolve(
err(new GhidraSessionError("protocol", "Controlled shared failure")),
);
await expect(image).resolves.toMatchObject({
ok: false,
error: { operation: "inspect_native_load_image" },
});
await expect(detail).resolves.toMatchObject({
ok: false,
error: { operation: "inspect_native_data_type" },
});
expect(fixture.readSnapshot).toHaveBeenCalledTimes(1);
});
describe("Ghidra NativeAOT snapshot budget", () => {
it("reports snapshot-capacity omissions inline through the load-image result", async () => {
const observations = fixtureDosLoadImage().observation;
const target = peTarget("x86_64");
const factory: GhidraProviderClientFactory = () => ({
start: () => Promise.resolve(ok(sessionInfo())),
callTool: () => Promise.resolve(ok(jsonValueSchema.parse(observations))),
readTargetSnapshot: () =>
Promise.resolve(
ok({
kind: "over-capacity",
sourceBytesAtLeast: 128 * 1024 * 1024 + 1,
maximumBytes: 128 * 1024 * 1024,
}),
),
close: () => Promise.resolve(ok(null)),
});
const ghidra = provider(installationHost(), factory);
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected admitted PE profile");
const client = ghidra.createClient(target, profile.value.profile);
const image = await client.execute("inspect_native_load_image", {});
expect(image).toMatchObject({
ok: true,
value: {
result: {
observations: {
metadata_recovery: [
{
status: "partial",
truncated: true,
coverage: { truncation_reason: "source-byte-budget" },
},
],
},
},
},
});
await client.close();
});
});
const sessionInfo = () => ({
name: "REA Ghidra bridge" as const,
run_id: "11111111-1111-4111-8111-111111111111",
profile_digest: "a".repeat(64),
provider: { id: "ghidra" as const, version: "12.1.4" },
read_only: false as const,
analysis_complete: true,
analysis_timed_out: false,
capabilities: [...GHIDRA_SESSION_CAPABILITIES],
target: {
name: "fixture",
language_id: "x86:LE:64:default",
compiler_spec_id: "gcc",
image_base: "0x1000",
default_address_space: "ram",
sha256: "a".repeat(64),
},
});
describe("Ghidra PDB coverage", () => {
it.each([
{ name: "missing bridge report", pdb: undefined, warns: true },
{
name: "report without a PDB reference",
pdb: {
file: null,
guid: null,
age: null,
signature: null,
version: null,
loaded: null,
},
warns: false,
},
])("distinguishes $name in direct PE searches", async ({ pdb, warns }) => {
const ghidra = provider(installationHost(), () => ({
start: () =>
Promise.resolve(
ok(pdb === undefined ? sessionInfo() : { ...sessionInfo(), pdb }),
),
callTool: () => Promise.resolve(ok([])),
close: () => Promise.resolve(ok(null)),
}));
const target = executableTarget("pe", "x86_64");
const resolved = await ghidra.resolveAnalysisProfile(target);
if (!resolved.ok || resolved.value.profile === null)
throw new Error("Expected a PE profile");
const client = ghidra.createClient(target, resolved.value.profile);
try {
const searched = await client.execute("search_procedures", {
pattern: "add_numbers",
});
if (!searched.ok) throw searched.error;
expect(searched.value.result).toEqual([]);
const warnings = searched.value.limitations.filter((limitation) =>
limitation.includes("PDB"),
);
expect(warnings).toEqual(
warns
? [
"Ghidra did not report PDB attributes; debug-symbol coverage is unknown.",
]
: [],
);
} finally {
await client.close();
}
});
const pdb = {
file: "C:\\build\\fixture.pdb",
guid: "01234567-89AB-CDEF-0123-456789ABCDEF",
age: "a",
signature: null,
version: "RSDS",
loaded: false as boolean | null,
};
it.each([false, null, true])(
"carries PDB load state %s into direct search and health Evidence",
async (loaded) => {
let starts = 0;
const ghidra = provider(installationHost(), () => ({
start: () => {
starts += 1;
return Promise.resolve(
ok({ ...sessionInfo(), pdb: { ...pdb, loaded } }),
);
},
callTool: () => Promise.resolve(ok([])),
close: () => Promise.resolve(ok(null)),
}));
const target = executableTarget("pe", "x86_64");
const resolved = await ghidra.resolveAnalysisProfile(target);
if (!resolved.ok || resolved.value.profile === null)
throw new Error("Expected a PE profile");
const client = ghidra.createClient(target, resolved.value.profile);
// No preceding health call: a name search must establish symbol coverage itself.
const searched = await client.execute("search_procedures", {
pattern: "add_numbers",
});
expect(starts).toBe(1);
if (!searched.ok) throw searched.error;
expect(searched.value.result).toEqual([]);
const health = await client.execute("health", {});
if (!health.ok) throw health.error;
expect(health.value.result).toMatchObject({ pdb: { ...pdb, loaded } });
for (const observation of [searched.value, health.value]) {
const limitations = observation.limitations.join("\n");
if (loaded === true) {
expect(limitations).toContain("loaded PDB");
expect(limitations).toContain("not an independent PDB identity");
expect(limitations).toContain("empty name search does not prove");
} else {
expect(limitations).toContain(pdb.file);
expect(limitations).toContain(pdb.guid);
expect(limitations).toContain("age (hex) a");
expect(limitations).toContain("list_procedures");
expect(limitations).toContain(
loaded === null ? "unknown" : "not loaded",
);
}
}
await client.close();
},
);
});
const executableTarget = (
format: "mach-o" | "elf" | "pe",
architecture: Extract<BinaryTarget, { format: "pe" }>["architecture"],
): BinaryTarget =>
format === "pe"
? peTarget(architecture)
: {
path: "/tmp/fixture",
sha256: "a".repeat(64),
kind: "executable",
format,
architecture,
availableArchitectures: [architecture],
};
const peTarget = (
architecture: Extract<BinaryTarget, { format: "pe" }>["architecture"],
): Extract<BinaryTarget, { format: "pe" }> => ({
path: "/tmp/fixture",
sha256: "a".repeat(64),
kind: "executable",
format: "pe",
peMachine: { x86: 0x014c, x86_64: 0x8664, arm: 0x01c4, arm64: 0xaa64 }[
architecture
],
architecture,
availableArchitectures: [architecture],
executableRole: "application",
managed: false,
});
describe("Ghidra extension failures", () => {
it.each(["unsupported", "failed", "malformed"] as const)(
"preserves %s recovery diagnostics and closes without restarting",
async (status) => {
const directory = await mkdtemp(
join(tmpdir(), "rea-provider-extension-"),
);
try {
const jar = join(directory, "addon.jar");
await writeFile(jar, Buffer.from([0x50, 0x4b, 3, 4]));
const config = parseConfig({
GHIDRA_INSTALL_DIR: INSTALL,
REA_GHIDRA_NATIVEAOT_JAR: jar,
});
if (!config.ok) throw config.error;
let starts = 0,
calls = 0,
closes = 0;
const ghidra = new GhidraProvider(
config.value,
silentLogger,
{},
installationHost(),
() => ({
start: () => {
starts++;
return Promise.resolve(
ok({
...sessionInfo(),
analysis_extensions: [
{
id: "nativeaot",
sha256:
status === "malformed"
? "0".repeat(64)
: createHash("sha256")
.update(Buffer.from([0x50, 0x4b, 3, 4]))
.digest("hex"),
status: status === "malformed" ? "failed" : status,
reason:
"directory-discovery: Unsupported layout at 0x401000",
result: {
id: "nativeaot",
integration_api: 1,
source_revision:
"effeb734fc570c32650f88b159608979dc7b423e",
source_revision_authority: "build-reported-unattested",
status: status === "malformed" ? "failed" : status,
reason:
"directory-discovery: Unsupported layout at 0x401000",
method_tables: 0,
diagnostics: ["exact producer diagnostic"],
},
},
],
}),
);
},
callTool: () => {
calls++;
return Promise.resolve(ok(null));
},
close: () => {
closes++;
return Promise.resolve(ok(null));
},
}),
);
const target = executableTarget("elf", "x86_64");
const resolved = await ghidra.resolveAnalysisProfile(target);
if (!resolved.ok || resolved.value.profile === null)
throw new Error("expected extension profile");
const client = ghidra.createClient(target, resolved.value.profile);
const failed = await client.execute("health", {});
expect(failed.ok).toBe(false);
if (!failed.ok) {
expect(failed.error._tag).toBe(
status === "unsupported"
? "AnalysisCapabilityUnavailableError"
: "ProviderAdapterError",
);
expect(JSON.stringify(failed.error)).toContain(
status === "malformed"
? "identity mismatch"
: "Unsupported layout at 0x401000",
);
}
expect(await client.execute("list_procedures", {})).toEqual(failed);
expect({ starts, calls, closes }).toEqual({
starts: 1,
calls: 0,
closes: 1,
});
} finally {
await rm(directory, { recursive: true, force: true });
}
},
);
});
describe("compatible Ghidra builds", () => {
it("accepts the build and reports that it is unverified", async () => {
const ghidra = provider(
{
...installationHost(),
readText: () =>
"application.version=12.1.2\napplication.java.min=21\napplication.java.max=\n",
probeJava: () =>
javaProbeOk<GhidraJavaObservation>({
osArch: "amd64",
osName: "Linux",
version: "27",
major: 27,
home: "/usr/lib/jvm/java-27-openjdk",
bits: 64,
runtime: "jdk",
}),
},
() => ({
start: () =>
Promise.resolve(
ok({
...sessionInfo(),
provider: { id: "ghidra", version: "12.1.2" },
}),
),
callTool: () =>
Promise.resolve(
ok([
{
address: "0x1000",
value: "fixture_main",
procedure: {
external: false,
thunk: false,
thunk_target: null,
},
},
]),
),
close: () => Promise.resolve(ok(null)),
}),
);
const resolved = await ghidra.resolveAnalysisProfile(
executableTarget("elf", "x86_64"),
);
if (!resolved.ok || resolved.value.profile === null)
throw new Error("expected a compatible Ghidra profile");
const client = ghidra.createClient(
executableTarget("elf", "x86_64"),
resolved.value.profile,
);
const health = await client.execute("health", {});
const procedures = await client.execute("list_procedures", {});
expect(await ghidra.inspectAvailability()).toMatchObject({
status: "available",
diagnostics: { provider_version: "12.1.2", java_version: "27" },
});
expect(health.ok && health.value.provider.version).toBe("12.1.2");
const unverified = expect.stringContaining("12.1.2");
expect(health.ok && health.value.limitations).toEqual(
expect.arrayContaining([unverified]),
);
expect(procedures.ok && procedures.value.limitations).toEqual(
expect.arrayContaining([unverified]),
);
expect(procedures.ok && procedures.value.provider.version).toBe("12.1.2");
});
});
it("projects Ghidra startup failure and its incomplete cleanup together", async () => {
const cleanup = new ProviderCleanupError("ghidra", ["owned-ghidra-process"], {
reason: "process cleanup unconfirmed",
});
const ghidra = provider(installationHost(), () => ({
start: async () =>
err(
new GhidraSessionError(
"timeout",
"Ghidra startup deadline elapsed",
{ failure_kind: "timeout" },
{ timeoutMs: 250, cleanupFailure: cleanup },
),
),
callTool: async () => ok(null),
close: async () => err(cleanup),
}));
const target = executableTarget("elf", "x86_64");
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected Ghidra analysis profile");
const result = await ghidra
.createClient(target, profile.value.profile)
.execute("health", {});
expect(result.ok).toBe(false);
if (!result.ok)
expect(projectAnalysisError(result.error)).toMatchObject({
code: "cleanup_incomplete",
details: {
resources: ["owned-ghidra-process"],
diagnostics: {
primary_error: {
code: "provider_timeout",
details: {
timeout_ms: 250,
diagnostics: { failure_kind: "timeout" },
},
},
cleanup_error: { code: "cleanup_incomplete" },
},
},
});
});
describe("Ghidra deadline guidance", () => {
const timedOut = async (phase: "start" | "request", message: string) => {
const failure = new GhidraSessionError(
"timeout",
message,
{ failure_kind: "timeout" },
{ timeoutMs: 250 },
);
const ghidra = provider(installationHost(), () => ({
start: async () => (phase === "start" ? err(failure) : ok(sessionInfo())),
callTool: async () => err(failure),
close: async () => ok(null),
}));
const target = executableTarget("elf", "x86_64");
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected Ghidra analysis profile");
const result = await ghidra
.createClient(target, profile.value.profile)
.execute("list_documents", {});
if (result.ok) throw new Error("Expected a Ghidra timeout");
return projectAnalysisError(result.error);
};
it("names the startup deadline setting and its value when startup times out", async () => {
const projected = await timedOut(
"start",
"Ghidra startup deadline elapsed",
);
expect(projected).toMatchObject({
code: "provider_timeout",
details: { timeout_ms: 250 },
});
expect(projected.message).toContain(
"250 ms startup deadline (REA_GHIDRA_STARTUP_TIMEOUT_MS)",
);
expect(projected.remediation.action).toContain(
"REA_GHIDRA_STARTUP_TIMEOUT_MS above 250",
);
expect(projected.remediation.action).toContain(
"REA_GHIDRA_DISABLED_ANALYZERS",
);
expect(projected.remediation.action).toContain("restart REA");
expect(projected.remediation.action).toContain("reconnect the MCP client");
expect(projected.remediation.action).toContain("export useful Evidence");
expect(projected.remediation.action).toContain(
"Reopening alone keeps the current server settings",
);
expect(projected.remediation.action).not.toContain("rea doctor");
});
it("keeps generic guidance for a bridge request deadline", async () => {
const projected = await timedOut(
"request",
"Ghidra bridge request timed out",
);
expect(projected.code).toBe("provider_timeout");
expect(projected.message).not.toContain("REA_GHIDRA_STARTUP_TIMEOUT_MS");
expect(projected.remediation.action).not.toContain(
"REA_GHIDRA_STARTUP_TIMEOUT_MS",
);
});
});
describe("Ghidra analysis seeds and configured language", () => {
const seedSession = async (
report: (sha256: string) => GhidraSeedReport | undefined,
) => {
const directory = await mkdtemp(join(tmpdir(), "rea-provider-seeds-"));
const seeds = join(directory, "seeds.tsv");
await writeFile(seeds, "0x401000\tfunction\tentry\n0x401010\tcode\n");
const config = parseConfig({
GHIDRA_INSTALL_DIR: INSTALL,
REA_GHIDRA_SEED_FILE: seeds,
});
if (!config.ok) throw config.error;
const counts = { starts: 0, calls: 0, closes: 0 };
const ghidra = new GhidraProvider(
config.value,
silentLogger,
{},
installationHost(),
() => ({
start: () => {
counts.starts++;
const seedReport = report(
createHash("sha256")
.update("0x401000\tfunction\tentry\n0x401010\tcode\n")
.digest("hex"),
);
return Promise.resolve(
ok({
...sessionInfo(),
...(seedReport === undefined
? {}
: { analysis_seeds: seedReport }),
}),
);
},
callTool: () => {
counts.calls++;
return Promise.resolve(ok(null));
},
close: () => {
counts.closes++;
return Promise.resolve(ok(null));
},
}),
);
const target = executableTarget("elf", "x86_64");
const resolved = await ghidra.resolveAnalysisProfile(target);
if (!resolved.ok || resolved.value.profile === null)
throw new Error("expected seed profile");
return {
directory,
counts,
client: ghidra.createClient(target, resolved.value.profile),
};
};
const applied = (sha256: string): GhidraSeedReport => ({
format: "rea-ghidra-seeds-v1",
sha256,
entries: 2,
function_created: 1,
function_existing: 0,
function_failed: 0,
code_decoded: 0,
code_failed: 1,
label_applied: 0,
label_failed: 0,
unmapped: 0,
});
it("reports the verified seed outcome as a session limitation", async () => {
const { directory, client } = await seedSession(applied);
try {
const health = await client.execute("health", {});
if (!health.ok) throw health.error;
expect(health.value.limitations).toEqual(
expect.arrayContaining([
expect.stringContaining("caller assertions, not Ghidra discoveries"),
expect.stringContaining(
"1 functions created, 0 already present, 0 failed; 0 code seeds decoded, 1 failed",
),
]),
);
} finally {
await rm(directory, { recursive: true, force: true });
}
});
it.each([
["no seed report", () => undefined],
[
"a report for other seeds",
(sha256: string): GhidraSeedReport => ({
...applied(sha256),
sha256: "0".repeat(64),
}),
],
])("fails closed on %s before any analysis call", async (_label, report) => {
const { directory, counts, client } = await seedSession(report);
try {
const failed = await client.execute("list_procedures", {});
expect(failed.ok).toBe(false);
if (!failed.ok) expect(failed.error._tag).toBe("ProviderAdapterError");
expect(counts).toEqual({ starts: 1, calls: 0, closes: 1 });
} finally {
await rm(directory, { recursive: true, force: true });
}
});
it("refuses a profile resolved without the configured seeds or language", async () => {
const plain = parseConfig({ GHIDRA_INSTALL_DIR: INSTALL });
if (!plain.ok) throw plain.error;
const target = executableTarget("elf", "x86_64");
const resolved = await new GhidraProvider(
plain.value,
silentLogger,
{},
installationHost(),
).resolveAnalysisProfile(target);
if (!resolved.ok || resolved.value.profile === null)
throw new Error("expected profile");
for (const environment of [
{ REA_GHIDRA_SEED_FILE: "/seeds.tsv" },
{ REA_GHIDRA_LANGUAGE_ID: "x86:LE:32:default" },
]) {
const configured = parseConfig({
GHIDRA_INSTALL_DIR: INSTALL,
...environment,
});
if (!configured.ok) throw configured.error;
let starts = 0;
const client = new GhidraProvider(
configured.value,
silentLogger,
{},
installationHost(),
() => ({
start: () => {
starts++;
return Promise.resolve(ok(sessionInfo()));
},
callTool: () => Promise.resolve(ok(null)),
close: () => Promise.resolve(ok(null)),
}),
).createClient(target, resolved.value.profile);
const failed = await client.execute("health", {});
expect(failed.ok).toBe(false);
expect(starts).toBe(0);
}
});
});
const configuredProvider = (
environment: Record<string, string>,
clientFactory?: GhidraProviderClientFactory,
) => {
const config = parseConfig({ GHIDRA_INSTALL_DIR: INSTALL, ...environment });
if (!config.ok) throw config.error;
return new GhidraProvider(
config.value,
silentLogger,
{},
installationHost(),
clientFactory,
);
};
const analyzerReport = (
...analyzers: readonly (readonly [
name: string,
status: GhidraDisabledAnalyzerReport["analyzers"][number]["status"],
])[]
): GhidraDisabledAnalyzerReport => ({
format: "rea-ghidra-disabled-analyzers-v1",
analyzers: analyzers.map(([name, status]) => ({ name, status })),
});
describe("Ghidra disabled analyzer options", () => {
it("records the configured analyzer options in the analysis profile", async () => {
const ghidra = configuredProvider({
REA_GHIDRA_DISABLED_ANALYZERS:
"Objective-C Message Analyzer,Decompiler Switch Analysis",
});
const resolved = await ghidra.resolveAnalysisProfile(
executableTarget("elf", "x86_64"),
);
if (!resolved.ok || resolved.value.profile === null)
throw new Error("expected a bound Ghidra profile");
expect(resolved.value.profile.parameters).toMatchObject({
analyzer_preset:
"ghidra-default+disabled:Objective-C Message Analyzer,Decompiler Switch Analysis",
analysis_options: {
disabled_analyzers: [
"Objective-C Message Analyzer",
"Decompiler Switch Analysis",
],
},
});
});
it("hands the configured analyzers to the launcher for a matching profile", async () => {
const launchers: GhidraHeadlessLauncher[] = [];
const ghidra = configuredProvider(
{ REA_GHIDRA_DISABLED_ANALYZERS: "Objective-C Message Analyzer" },
(options) => {
launchers.push(options.launcher as GhidraHeadlessLauncher);
return {
start: () =>
Promise.resolve(
ok({
...sessionInfo(),
disabled_analyzers: analyzerReport([
"Objective-C Message Analyzer",
"not_applicable",
]),
}),
),
callTool: () => Promise.resolve(ok(null)),
close: () => Promise.resolve(ok(null)),
};
},
);
const target = executableTarget("elf", "x86_64");
const resolved = await ghidra.resolveAnalysisProfile(target);
if (!resolved.ok || resolved.value.profile === null)
throw new Error("expected a bound Ghidra profile");
const client = ghidra.createClient(target, resolved.value.profile);
const health = await client.execute("health", {});
expect(health.ok).toBe(true);
expect(launchers).toHaveLength(1);
expect(launchers[0]?.options.disabledAnalyzers).toEqual([
"Objective-C Message Analyzer",
]);
});
it("binds analyzer overrides and raw import settings in one profile", async () => {
const launchers: GhidraHeadlessLauncher[] = [];
const ghidra = configuredProvider(
{ REA_GHIDRA_DISABLED_ANALYZERS: "Decompiler Switch Analysis" },
(options) => {
launchers.push(options.launcher as GhidraHeadlessLauncher);
return {
start: () =>
Promise.resolve(
ok({
...sessionInfo(),
disabled_analyzers: analyzerReport([
"Decompiler Switch Analysis",
"disabled",
]),
}),
),
callTool: () => Promise.resolve(ok(null)),
close: () => Promise.resolve(ok(null)),
};
},
);
const target: BinaryTarget = {
path: "/tmp/entry.bin",
sha256: "a".repeat(64),
kind: "executable",
format: "raw-binary",
architecture: "x86",
availableArchitectures: ["x86"],
entryPoint: "0x1000",
entryPointSource: "0x1000",
};
const resolved = await ghidra.resolveAnalysisProfile(target);
if (!resolved.ok || resolved.value.profile === null)
throw new Error("expected a bound raw-binary profile");
expect(resolved.value.profile.parameters).toMatchObject({
target_format: "raw-binary",
entry_point: "0x1000",
analyzer_preset: "ghidra-default+disabled:Decompiler Switch Analysis",
analysis_options: { disabled_analyzers: ["Decompiler Switch Analysis"] },
});
const client = ghidra.createClient(target, resolved.value.profile);
expect(launchers).toHaveLength(0);
expect((await client.execute("health", {})).ok).toBe(true);
expect(launchers).toHaveLength(1);
expect(launchers[0]?.options).toMatchObject({
disabledAnalyzers: ["Decompiler Switch Analysis"],
rawBinary: {
languageId: "x86:LE:32:default",
compilerSpecId: "gcc",
baseAddr: "0x1000",
},
});
await client.close();
});
it("refuses a profile resolved without or with other analyzer options", async () => {
const target = executableTarget("elf", "x86_64");
const plainProvider = configuredProvider({});
const plain = await plainProvider.resolveAnalysisProfile(target);
if (!plain.ok || plain.value.profile === null)
throw new Error("expected profile");
const configuredProvider2 = configuredProvider({
REA_GHIDRA_DISABLED_ANALYZERS: "Objective-C Message Analyzer",
});
const configured = await configuredProvider2.resolveAnalysisProfile(target);
if (!configured.ok || configured.value.profile === null)
throw new Error("expected configured profile");
for (const [profile, environment] of [
[
plain.value.profile,
{ REA_GHIDRA_DISABLED_ANALYZERS: "Objective-C Message Analyzer" },
],
[configured.value.profile, {}],
[
configured.value.profile,
{ REA_GHIDRA_DISABLED_ANALYZERS: "Decompiler Switch Analysis" },
],
] as const) {
let starts = 0;
const client = configuredProvider(environment, () => ({
start: () => {
starts++;
return Promise.resolve(ok(sessionInfo()));
},
callTool: () => Promise.resolve(ok(null)),
close: () => Promise.resolve(ok(null)),
})).createClient(target, profile);
const failed = await client.execute("health", {});
expect(failed.ok).toBe(false);
if (!failed.ok) expect(failed.error._tag).toBe("ProviderAdapterError");
expect(starts).toBe(0);
}
});
});
describe("Ghidra disabled analyzer applicability per program", () => {
const analyzerSession = async (
setting: string | undefined,
report: GhidraDisabledAnalyzerReport | undefined,
) => {
const counts = { starts: 0, calls: 0, closes: 0 };
const ghidra = configuredProvider(
setting === undefined ? {} : { REA_GHIDRA_DISABLED_ANALYZERS: setting },
() => ({
start: () => {
counts.starts++;
return Promise.resolve(
ok({
...sessionInfo(),
...(report === undefined ? {} : { disabled_analyzers: report }),
}),
);
},
callTool: () => {
counts.calls++;
return Promise.resolve(
ok([
{
address: "0x1000",
value: "fixture_main",
procedure: {
external: false,
thunk: false,
thunk_target: null,
},
},
]),
);
},
close: () => {
counts.closes++;
return Promise.resolve(ok(null));
},
}),
);
const target = executableTarget("elf", "x86_64");
const resolved = await ghidra.resolveAnalysisProfile(target);
if (!resolved.ok || resolved.value.profile === null)
throw new Error("expected a bound Ghidra profile");
return {
counts,
profile: resolved.value.profile,
client: ghidra.createClient(target, resolved.value.profile),
};
};
it("adds no limitation when every configured analyzer was disabled", async () => {
const { client } = await analyzerSession(
"Decompiler Switch Analysis",
analyzerReport(["Decompiler Switch Analysis", "disabled"]),
);
const health = await client.execute("health", {});
if (!health.ok) throw health.error;
expect(health.value.limitations).not.toEqual(
expect.arrayContaining([expect.stringContaining("(n/a)")]),
);
await client.close();
});
it("opens a program for which a configured analyzer is not applicable", async () => {
const { counts, profile, client } = await analyzerSession(
"Decompiler Switch Analysis,Objective-C Message Analyzer",
analyzerReport(
["Decompiler Switch Analysis", "disabled"],
["Objective-C Message Analyzer", "not_applicable"],
),
);
const procedures = await client.execute("list_procedures", {});
expect(counts.calls).toBe(1);
if (!procedures.ok) throw procedures.error;
expect(procedures.value.analysisProfile?.parameters).toMatchObject({
analyzer_preset:
"ghidra-default+disabled:Decompiler Switch Analysis,Objective-C Message Analyzer",
});
expect(procedures.value.analysisProfile?.digest).toBe(profile.digest);
expect(procedures.value.limitations).toEqual(
expect.arrayContaining([
expect.stringContaining(
"Applied analyzer preset: ghidra-default+disabled:Decompiler Switch Analysis,Objective-C Message Analyzer(n/a).",
),
]),
);
await client.close();
});
it.each([
["no analyzer report", undefined],
[
"a report for other analyzers",
analyzerReport(["Decompiler Switch Analysis", "not_applicable"]),
],
[
"a report missing a configured analyzer",
analyzerReport(["Objective-C Message Analyzer", "not_applicable"]),
],
])("fails closed on %s before any analysis call", async (_label, report) => {
const { counts, client } = await analyzerSession(
"Objective-C Message Analyzer,Demangler Swift",
report,
);
const failed = await client.execute("list_procedures", {});
expect(failed.ok).toBe(false);
if (!failed.ok) {
expect(failed.error._tag).toBe("ProviderAdapterError");
expect(failed.error.diagnostics?.reason).toEqual(
expect.stringContaining("REA_GHIDRA_DISABLED_ANALYZERS"),
);
}
expect(counts).toEqual({ starts: 1, calls: 0, closes: 1 });
});
it("fails closed on an analyzer report the profile did not commit", async () => {
const { counts, client } = await analyzerSession(
undefined,
analyzerReport(["Objective-C Message Analyzer", "not_applicable"]),
);
const failed = await client.execute("health", {});
expect(failed.ok).toBe(false);
if (!failed.ok) expect(failed.error._tag).toBe("ProviderAdapterError");
expect(counts).toEqual({ starts: 1, calls: 0, closes: 1 });
});
});
describe("Ghidra queries after the owned provider is lost", () => {
const lostProviderSession = async (
state: "exited" | "unreachable" | "idle",
failureKind: "process" | "protocol" | "remote" = "process",
answeredBeforeLoss = true,
) => {
let calls = 0;
const ghidra = provider(installationHost(), () => ({
start: async () =>
err(new GhidraSessionError("start", "startup is not exercised")),
callTool: async () => {
calls += 1;
if (answeredBeforeLoss && calls === 1) return ok(null);
return err(
new GhidraSessionError(
failureKind,
"Ghidra bridge socket closed",
{ failure_kind: failureKind },
failureKind === "remote" ? { remoteCode: "internal" } : {},
),
);
},
close: async () => ok(null),
operationHealthSnapshot: () =>
state === "idle"
? undefined
: {
state,
stage: null,
retryAction: "restart_provider",
exitCode: state === "exited" ? 137 : null,
requests: [],
},
}));
const target = executableTarget("elf", "x86_64");
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected Ghidra analysis profile");
const client = ghidra.createClient(target, profile.value.profile);
if (answeredBeforeLoss) await client.execute("list_documents", {});
return client;
};
it("tells the caller to reopen the target when Ghidra exited", async () => {
const client = await lostProviderSession("exited");
const result = await client.execute("list_documents", {});
expect(result.ok).toBe(false);
if (result.ok) return;
const projected = projectAnalysisError(result.error);
expect(projected).toMatchObject({
code: "execution_failure",
retryable: false,
details: { provider_id: "ghidra", operation: "list_documents" },
});
expect(projected.message).toContain("exited with code 137");
expect(projected.message).toContain("Call open_binary");
expect(projected.remediation.action).toContain("Call open_binary");
expect(projected.remediation.action).not.toContain("rea doctor");
});
it("tells the caller to reopen the target when the bridge became unreachable", async () => {
const client = await lostProviderSession("unreachable", "protocol");
const result = await client.execute("list_procedures", {});
expect(result.ok).toBe(false);
if (result.ok) return;
const projected = projectAnalysisError(result.error);
expect(projected.message).toContain("became unreachable");
expect(projected.remediation.action).toContain("Call open_binary");
});
it("keeps installation guidance when Ghidra dies before it ever answered", async () => {
const client = await lostProviderSession("exited", "process", false);
const result = await client.execute("list_documents", {});
expect(result.ok).toBe(false);
if (result.ok) return;
const projected = projectAnalysisError(result.error);
expect(projected.message).not.toContain("Call open_binary");
expect(projected.remediation.action).toContain("rea doctor");
});
it("keeps the generic failure when the provider is not known to be lost", async () => {
const client = await lostProviderSession("idle");
const result = await client.execute("list_documents", {});
expect(result.ok).toBe(false);
if (result.ok) return;
expect(projectAnalysisError(result.error).remediation.action).toContain(
"rea doctor",
);
});
it("does not reinterpret a bridge-reported failure as a lost provider", async () => {
const client = await lostProviderSession("exited", "remote");
const result = await client.execute("list_documents", {});
expect(result.ok).toBe(false);
if (result.ok) return;
expect(projectAnalysisError(result.error).message).not.toContain(
"Call open_binary",
);
});
});
const output = (text: string) => ({
text,
bytes: Buffer.byteLength(text),
retained_bytes: Buffer.byteLength(text),
});
const failureOutput = (stdout = "", stderr = "") => ({
stdout: output(stdout),
stderr: output(stderr),
complete: true,
observed_oome: (["stdout", "stderr"] as const).flatMap((stream) => {
const bytes = Buffer.from(stream === "stdout" ? stdout : stderr);
const scanner = new ProcessOutputTokenScanner("java.lang.OutOfMemoryError");
scanner.scan(bytes, 0);
scanner.finish();
const observed = scanner.latestWithin(0, bytes.length);
return observed === undefined
? []
: [
{
stream,
offset: observed.offset,
line: observed.line,
truncated: observed.truncated,
},
];
}),
});
const projectFailure = async (
kind: "cancelled" | "process" | "protocol" | "remote" | "timeout",
diagnostics: Readonly<Record<string, JsonValue>>,
) => {
const ghidra = provider(installationHost(), () => ({
start: async () =>
err(new GhidraSessionError("start", "startup is not exercised")),
callTool: async () =>
err(
new GhidraSessionError(
kind,
"Ghidra request failed",
{ failure_kind: kind, ...diagnostics },
kind === "remote" ? { remoteCode: "internal" } : {},
),
),
close: async () => ok(null),
}));
const target = executableTarget("elf", "x86_64");
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected Ghidra analysis profile");
const result = await ghidra
.createClient(target, profile.value.profile)
.execute("list_documents", {});
if (result.ok) throw new Error("Expected a Ghidra failure");
return projectAnalysisError(result.error);
};
const issueOutput = [
"INFO ANALYZING all memory and code: /hugo (HeadlessAnalyzer)",
"ERROR Abort due to Headless analyzer error: Java heap space (HeadlessAnalyzer) java.lang.OutOfMemoryError:",
"\tat ghidra.app.plugin.core.analysis.GolangSymbolAnalyzer$PropagateRttiBackgroundCommand.applyTo",
].join("\n");
describe("Ghidra OOME error projection", () => {
it("recognizes the headless analyzer's real detail-before-class output", async () => {
const projected = await projectFailure("process", {
stdout: output(issueOutput),
stderr: output(""),
failure_output: failureOutput(issueOutput),
configured_jvm_max_heap: "4G",
});
expect(projected).toMatchObject({
code: "resource_constraint",
details: {
resource: "memory",
reported_limits: { configured_jvm_max_heap: "4G" },
},
});
expect(projected.message).toContain("Java heap space");
expect(projected.remediation.action).toContain("GHIDRA_HEADLESS_MAXMEM");
expect(projected.remediation.action).toContain(
"REA_GHIDRA_DISABLED_ANALYZERS",
);
});
it("retains an unknown heap for GC overhead when the launch did not report one", async () => {
const projected = await projectFailure("timeout", {
stdout: output(""),
stderr: output(""),
failure_output: failureOutput(
"",
'Exception in thread "main" java.lang.OutOfMemoryError: GC overhead limit exceeded',
),
});
expect(projected).toMatchObject({
code: "resource_constraint",
details: {
resource: "memory",
reported_limits: { configured_jvm_max_heap: null },
},
});
expect(projected.remediation.action).toContain("GHIDRA_HEADLESS_MAXMEM");
});
it.each([
["Metaspace", "java.lang.OutOfMemoryError: Metaspace"],
[
"array VM limit",
"java.lang.OutOfMemoryError: Requested array size exceeds VM limit",
],
])("does not recommend a larger Java heap for %s", async (_name, text) => {
const projected = await projectFailure("process", {
stdout: output(""),
stderr: output(""),
failure_output: failureOutput("", text),
configured_jvm_max_heap: "4G",
});
expect(projected.code).toBe("resource_constraint");
expect(projected.message).toContain(text);
expect(projected.remediation.action).not.toContain(
"GHIDRA_HEADLESS_MAXMEM",
);
});
it("reports native-thread exhaustion as capacity without inventing a limit", async () => {
const projected = await projectFailure("process", {
stdout: output(""),
stderr: output(""),
failure_output: failureOutput(
"",
"java.lang.OutOfMemoryError: unable to create native thread: possibly out of memory or process/resource limits reached",
),
configured_jvm_max_heap: "4G",
});
expect(projected).toMatchObject({
code: "resource_constraint",
details: { resource: "capacity", reported_limits: null },
});
expect(projected.remediation.action).not.toContain(
"GHIDRA_HEADLESS_MAXMEM",
);
});
it("keeps a bare OOME class at unknown subtype without heap advice", async () => {
const projected = await projectFailure("process", {
failure_output: failureOutput("", "java.lang.OutOfMemoryError"),
});
expect(projected).toMatchObject({
code: "resource_constraint",
details: { resource: "memory", reported_limits: null },
});
expect(projected.remediation.action).not.toContain(
"GHIDRA_HEADLESS_MAXMEM",
);
});
it("does not reclassify a later failure from OOME retained after an earlier success", async () => {
let calls = 0;
const ghidra = provider(installationHost(), () => ({
start: async () =>
err(new GhidraSessionError("start", "startup is not exercised")),
callTool: async () => {
calls += 1;
if (calls === 1) return ok(["fixture"]);
return err(
new GhidraSessionError(
"protocol",
"Ghidra returned an invalid later response",
{
stdout: output(issueOutput),
stderr: output(""),
// The OOME remains visible in full process history above, but
// the current operation produced no such error.
failure_output: failureOutput(),
},
),
);
},
close: async () => ok(null),
}));
const target = executableTarget("elf", "x86_64");
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected Ghidra analysis profile");
const client = ghidra.createClient(target, profile.value.profile);
const earlier = await client.execute("list_documents", {});
expect(earlier.ok).toBe(true);
const later = await client.execute("list_procedures", {});
expect(later.ok).toBe(false);
if (later.ok) return;
const projected = projectAnalysisError(later.error);
expect(projected.code).toBe("execution_failure");
expect(projected.details?.diagnostics).toMatchObject({
stdout: { text: issueOutput },
});
});
it("keeps cancellation primary even when the current operation reports an OOME", async () => {
const projected = await projectFailure("cancelled", {
stdout: output(""),
stderr: output(""),
failure_output: failureOutput(issueOutput),
configured_jvm_max_heap: "4G",
});
expect(projected.code).toBe("cancelled");
});
it("does not reinterpret a bridge-reported OOME as a local process failure", async () => {
const projected = await projectFailure("remote", {
stdout: output(""),
stderr: output(""),
failure_output: failureOutput(issueOutput),
configured_jvm_max_heap: "4G",
});
expect(projected.code).not.toBe("resource_constraint");
});
});
describe("Ghidra OOME beyond the retention budget", () => {
it("projects an observed OOME line that the retained text omits", async () => {
const projected = await projectFailure("process", {
stdout: output(""),
stderr: output(""),
failure_output: {
...failureOutput("", ""),
complete: false,
observed_oome: [
{
stream: "stderr",
offset: 9_000_000,
line: "ERROR Abort due to Headless analyzer error: Java heap space (HeadlessAnalyzer) java.lang.OutOfMemoryError: Java heap space",
},
],
},
configured_jvm_max_heap: "4G",
});
expect(projected).toMatchObject({
code: "resource_constraint",
details: {
resource: "memory",
reported_limits: { configured_jvm_max_heap: "4G" },
},
});
expect(projected.message).toContain("Java heap space");
});
it("keeps the original failure when incomplete output shows no OOME", async () => {
const projected = await projectFailure("process", {
stdout: output(""),
stderr: output(""),
failure_output: { ...failureOutput("", ""), complete: false },
configured_jvm_max_heap: "4G",
});
expect(projected.code).toBe("execution_failure");
});
});
it("reuses readiness only inside its active task and provider lifetime", async () => {
let probes = 0;
let version = "21.0.11";
const base = installationHost();
const ghidra = provider({
...base,
probeJava: async (command, environment, options) => {
probes++;
const observed = await base.probeJava(command, environment, options);
return observed.ok
? javaProbeOk({ ...observed.value, version })
: observed;
},
});
const scope = new ProviderInspectionScope();
try {
expect((await ghidra.inspectAvailability({ scope })).status).toBe(
"available",
);
expect(
(
await ghidra.resolveAnalysisProfile(executableTarget("elf", "x86_64"), {
scope,
})
).ok,
).toBe(true);
expect(probes).toBe(1);
version = "21.0.12";
expect(await ghidra.closeOwnedResources()).toMatchObject({ ok: true });
expect(
(await ghidra.inspectAvailability({ scope })).diagnostics.java_version,
).toBe(version);
expect(probes).toBe(2);
scope.close();
version = "21.0.13";
expect(
(await ghidra.inspectAvailability({ scope })).diagnostics.java_version,
).toBe(version);
expect(probes).toBe(3);
} finally {
scope.close();
await ghidra.closeOwnedResources();
}
});
it("refuses a changed installation before creating a target-bound native client", async () => {
let release = "12.1.4",
nativeCreates = 0;
const ghidra = provider(
{
...installationHost(),
readText: () =>
`application.version=${release}\napplication.java.min=21\n`,
},
() => {
nativeCreates++;
throw new Error("Changed installation must not create a native client");
},
);
const target = executableTarget("elf", "x86_64");
const resolved = await ghidra.resolveAnalysisProfile(target);
if (!resolved.ok || resolved.value.profile === null)
throw new Error("Expected initial profile");
const client = ghidra.createClient(target, resolved.value.profile);
release = "12.1.5";
try {
const result = await client.execute("analyze_function", {});
if (result.ok) throw new Error("Changed installation was admitted");
expect(result.error).toMatchObject({
operation: "analyze_function",
diagnostics: {
selected_provider_version: "12.1.4",
current_installation: { provider_version: "12.1.5" },
},
});
expect(client.reuseReadiness?.()).toBe("blocked");
expect(nativeCreates).toBe(0);
} finally {
await client.close();
await ghidra.closeOwnedResources();
}
});
it("rejects an absent profile before probing Java and attributes it to the requested operation", async () => {
let probes = 0;
const base = installationHost();
const ghidra = provider({
...base,
probeJava: (...args) => {
probes++;
return base.probeJava(...args);
},
});
const client = ghidra.createClient(executableTarget("elf", "x86_64"));
try {
const result = await client.execute("analyze_function", {});
expect(result).toMatchObject({
ok: false,
error: { _tag: "ProviderAdapterError", operation: "analyze_function" },
});
expect(probes).toBe(0);
} finally {
await client.close();
await ghidra.closeOwnedResources();
}
});
it.each([
{
layout: "crossed header interval",
fixture: () => nativeAotPeHeaderIndirectionFixture(0x3fc),
basis: "no-rtr-header",
},
{
layout: "short optional header",
fixture: () => nativeAotPeOptionalHeaderFixture(56),
basis: "unsupported-layout",
},
{
layout: "overlapping virtual sections",
fixture: () => nativeAotPeVirtualSectionFixture(0x2000, 0x400),
basis: "unsupported-layout",
},
{
layout: "section overlapping headers",
fixture: () => nativeAotPeVirtualSectionFixture(0x200, 0x80),
basis: "unsupported-layout",
},
])(
"retains NativeAOT unsupported-layout facts for a $layout through the provider",
async ({ fixture, basis }) => {
const bytes = fixture();
const observations = fixtureDosLoadImage().observation;
observations.image_base = "0x140000000";
const readSnapshot = vi.fn(async () =>
ok({ kind: "captured" as const, bytes }),
);
const factory: GhidraProviderClientFactory = () => ({
start: () =>
Promise.resolve(
ok({
...sessionInfo(),
target: { ...sessionInfo().target, image_base: "0x140000000" },
}),
),
callTool: (operation) =>
Promise.resolve(
ok(
jsonValueSchema.parse(
operation === "inspect_native_load_image"
? observations
: unavailableNativeAotDatabaseType("0x140002280"),
),
),
),
readTargetSnapshot: readSnapshot,
close: () => Promise.resolve(ok(null)),
});
const ghidra = provider(installationHost(), factory);
const target = { ...peTarget("x86_64"), sha256: nativeAotPeDigest(bytes) };
const profile = await ghidra.resolveAnalysisProfile(target);
if (!profile.ok || profile.value.profile === null)
throw new Error("Expected admitted PE profile");
const client = ghidra.createClient(target, profile.value.profile);
try {
const result = await client.execute("inspect_native_load_image", {});
expect(result).toMatchObject({
ok: true,
value: {
result: {
observations: {
metadata_recovery: [
{
status: "not_applicable",
header_address: null,
method_tables: 0,
analysis_artifact_sha256: target.sha256,
coverage: { basis },
},
],
},
},
},
});
const detail = await client.execute("inspect_native_data_type", {
address: "0x140002280",
});
if (!detail.ok) throw detail.error;
expect(detail.value.result).not.toHaveProperty("metadata_recovery");
expect(readSnapshot).toHaveBeenCalledTimes(1);
} finally {
await client.close();
}
},
);
it.each([
{
unrelated: "INFO unrelated capacity: unable to create native thread",
reported: "Java heap space",
heapAdvice: true,
},
{
unrelated: "INFO unrelated configuration: Java heap space",
reported: "Metaspace",
heapAdvice: false,
},
])(
"binds Ghidra OOME detail to the reporting line instead of unrelated output ($reported)",
async ({ unrelated, reported, heapAdvice }) => {
const projected = await projectFailure("process", {
failure_output: failureOutput(
`${unrelated}\njava.lang.OutOfMemoryError: ${reported}\n`,
),
configured_jvm_max_heap: "4G",
});
expect(projected).toMatchObject({
code: "resource_constraint",
details: { resource: "memory" },
});
expect(projected.message).toContain(reported);
expect(
projected.remediation.action.includes("GHIDRA_HEADLESS_MAXMEM"),
).toBe(heapAdvice);
},
);
it("does not infer a complete OOME token from a budget-cut text prefix", async () => {
const projected = await projectFailure("process", {
failure_output: {
stdout: output("java.lang.OutOfMemoryError"),
stderr: output(""),
complete: false,
observed_oome: [],
},
});
expect(projected.code).toBe("execution_failure");
expect(projected.message).toContain("a memory cause cannot be ruled out");
});
it.each([false, true])(
"preserves valid OOME facts among malformed observations without inventing a constraint (confirmed=%s)",
async (confirmed) => {
const malformed: JsonValue[] = [
null,
{},
{ stream: "stderr", offset: 0, line: "" },
{ stream: "unknown", offset: 0, line: "java.lang.OutOfMemoryError" },
];
const projected = await projectFailure("process", {
failure_output: {
complete: false,
observed_oome: [
...malformed,
...(confirmed
? [
{
stream: "stderr",
offset: 0,
line: "java.lang.OutOfMemoryError: Metaspace",
},
]
: []),
],
},
});
expect(projected.code).toBe(
confirmed ? "resource_constraint" : "execution_failure",
);
expect(projected.message).toContain(
confirmed ? "Metaspace" : "a memory cause cannot be ruled out",
);
},
);