Files
rea/src/ghidra/GhidraInstallation.ts
T
20e4f83097 fix(ghidra): fail doctor when the JVM os.arch selects an unvalidated decompiler directory (#2792)
* fix(ghidra): fail doctor when the JVM os.arch selects an unvalidated decompiler directory

probeJava now also reads the JVM os.arch property. When it maps to a
different native decompiler directory than the one validated from the
host architecture (for example an x86_64 JDK under Rosetta on Apple
silicon selecting os/mac_x86_64 while only mac_arm_64 was built), the
native_decompiler check fails with a remediation pointing at a
matching-arch JDK instead of reporting a healthy installation that
fails every analysis. Unknown os.arch values keep the previous
behavior.

* fix(ghidra): tighten JVM arch remediation and cover os.arch extraction

Address review findings on the JVM os.arch decompiler-directory check:
- The remediation no longer suggests building the decompiler for the
  JVM-selected directory, which could never clear the check; it only
  advises pointing JAVA_HOME at a matching-architecture JDK.
- Add a test running the real Java probe against captured
  -XshowSettings:properties output, asserting os.arch reaches the
  installation diagnostics.
- Document the JDK-architecture prerequisite in the Ghidra setup guide.

* fix(ghidra): refuse unrecognized JVM native architectures

* docs(ghidra): align doctor prerequisites with JVM architecture admission

* fix(ghidra): reject unreported JVM architecture

* test(ghidra): separate JVM and executable admission cases

* fix(ghidra): defer decompiler arch validation when Java is absent

* fix(ghidra): reject JVM native architecture override

* fix(ghidra): validate JVM platform overrides

* fix(ghidra): validate JVM os.name and helper-environment platform overrides

* test(ci): isolate report fixtures and declare PowerPC Java bounds

* test(ghidra): provide observed JVM platform in PowerPC fixture

* fix(ghidra): parse quoted JVM environment options before admission

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
2026-10-14 07:31:11 +08:00

956 lines
33 KiB
TypeScript

import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
import { spawnSync } from "node:child_process";
import { constants } from "node:fs";
import {
accessSync,
closeSync,
fstatSync,
openSync,
readFileSync,
readSync,
statSync,
} from "node:fs";
import { posix, win32 } from "node:path";
import type { ProviderRejectionCode } from "../contracts/providerSelection.js";
import {
parseExecutableHeader,
type ExecutableMetadata,
} from "../domain/binaryTarget.js";
import {
isMachOFormat,
type BinaryArchitecture,
} from "../domain/binaryTargetTypes.js";
import type { JsonValue } from "../domain/jsonValue.js";
import {
ghidraApplicationProperties,
ghidraJavaMajorAccepted,
ghidraJavaRangeLabel,
ghidraJavaRequirement,
ghidraReleaseAccepted,
ghidraReleaseCompatibility,
ghidraReleaseLine,
ghidraVersionDetail,
SUPPORTED_GHIDRA_VERSION,
type GhidraApplicationProperties,
type GhidraJavaRequirement,
} from "./GhidraInstallationPolicy.js";
const NATIVE_PLATFORMS: Readonly<
Partial<
Record<
NodeJS.Platform,
Readonly<Partial<Record<NodeJS.Architecture, string>>>
>
>
> = {
linux: { x64: "linux_x86_64", arm64: "linux_arm_64" },
darwin: { x64: "mac_x86_64", arm64: "mac_arm_64" },
win32: { x64: "win_x86_64" },
};
/** Executable format each supported host runs its own Ghidra native tools as. */
const NATIVE_TOOL_FORMATS: Readonly<
Partial<Record<NodeJS.Platform, ExecutableMetadata["format"]>>
> = {
linux: "elf",
darwin: "mach-o",
win32: "pe",
};
/** Node architecture identifiers as the executable-header parser reports them. */
const NATIVE_ARCHITECTURES: readonly {
readonly node: NodeJS.Architecture;
readonly binary: BinaryArchitecture;
}[] = [
{ node: "x64", binary: "x86_64" },
{ node: "ia32", binary: "x86" },
{ node: "arm", binary: "arm" },
{ node: "arm64", binary: "arm64" },
];
/** Bound installation discovery reads; larger headers remain unknown. */
const EXECUTABLE_HEADER_PROBE_BYTES = 4096;
/**
* Bound the Java version probe so a chatty or hostile JVM cannot force an
* unbounded in-memory capture. Well-behaved JVMs print a few kilobytes for
* `-XshowSettings:properties`; the same 1 MiB budget used for other Java
* listings leaves ample headroom. A probe that exceeds the budget yields no
* observation and is reported through the existing failed-probe path.
*/
const JAVA_PROBE_MAX_OUTPUT_BYTES = 1024 * 1024;
/** Compatibility of one present native decompiler with the inspected host. */
type NativeDecompilerCompatibility =
| {
readonly status: "incompatible";
readonly detail: string;
readonly remediation: string;
}
| { readonly status: "compatible"; readonly detail: string }
| { readonly status: "unknown"; readonly detail: string };
/**
* Judge a native decompiler by its own executable header instead of the
* directory name that admits it.
*
* Only a header that positively contradicts the host is `incompatible`. An
* absent, unreadable, truncated, or unrecognized header stays `unknown`, so a
* file the other checks already accept is never refused on missing evidence.
*/
const assessNativeDecompiler = (
path: string,
platform: NodeJS.Platform,
architecture: NodeJS.Architecture,
probe: GhidraExecutableHeaderProbe | undefined,
): NativeDecompilerCompatibility => {
const expectedFormat = NATIVE_TOOL_FORMATS[platform];
const expectedArchitecture = NATIVE_ARCHITECTURES.find(
({ node }) => node === architecture,
)?.binary;
if (expectedFormat === undefined || expectedArchitecture === undefined)
return {
status: "unknown",
detail: `${path} is executable, but no native tool format is defined for ${platform}/${architecture}`,
};
let parsed =
probe === undefined
? undefined
: parseExecutableHeader(probe.bytes, architecture, probe.size);
if (probe !== undefined && parsed !== undefined && !parsed.ok) {
// FAT parsing selects a host slice. A validated foreign slice can still
// prove that its complete architecture table excludes this host. If the
// host is listed but its slice is malformed, preserve the unknown outcome.
for (const { node } of NATIVE_ARCHITECTURES) {
if (node === architecture) continue;
const alternative = parseExecutableHeader(probe.bytes, node, probe.size);
if (
alternative.ok &&
!alternative.value.availableArchitectures.some(
(available) => available === expectedArchitecture,
)
) {
parsed = alternative;
break;
}
}
}
if (parsed === undefined || !parsed.ok)
return {
status: "unknown",
detail: `${path} is executable, but its executable format for ${platform}/${architecture} could not be established`,
};
const observed = `${parsed.value.format} ${parsed.value.architecture}`;
const expected = `${expectedFormat} ${expectedArchitecture}`;
const formatMatches = isMachOFormat(expectedFormat)
? isMachOFormat(parsed.value.format)
: parsed.value.format === expectedFormat;
if (formatMatches && parsed.value.architecture === expectedArchitecture)
return {
status: "compatible",
detail: `${path} reports ${observed}, which matches ${platform}/${architecture}`,
};
const nativeDirectory = NATIVE_PLATFORMS[platform]?.[architecture];
const executable = platform === "win32" ? "decompile.exe" : "decompile";
return {
status: "incompatible",
detail: `${path} reports ${observed}, but ${platform}/${architecture} requires ${expected}`,
remediation: `Provide an executable Ghidra/Features/Decompiler/os/${nativeDirectory ?? "<platform>"}/${executable} built for ${expected}, or its build/os equivalent. REA does not build or install native tools.`,
};
};
/** Caller-owned paths and host coordinates used for one installation probe. */
export interface GhidraInstallationOptions {
readonly environment: Readonly<NodeJS.ProcessEnv>;
readonly installDir?: string;
readonly javaHome?: string;
readonly platform?: NodeJS.Platform;
readonly architecture?: NodeJS.Architecture;
}
/** One independently actionable part of the supported-installation contract. */
export type GhidraInstallationCheck =
| {
readonly status: "passed";
readonly name: GhidraInstallationCheckName;
readonly detail: string;
}
| {
readonly status: "failed";
readonly name: GhidraInstallationCheckName;
readonly code: ProviderRejectionCode;
readonly detail: string;
readonly remediation: string;
};
/** Stable identity for one Ghidra installation check. */
export type GhidraInstallationCheckName =
| "configuration"
| "platform"
| "architecture"
| "installation"
| "version"
| "headless"
| "native_decompiler"
| "java";
interface GhidraInstallationObservation {
readonly platform: NodeJS.Platform;
readonly architecture: NodeJS.Architecture;
readonly applicationPropertiesPath: string | null;
readonly nativeDecompilerPath: string | null;
readonly javaCommand: string;
/** Observed java.vm.name; omitted when the probe cannot establish VM identity. */
readonly javaVmName?: string;
/**
* Observed JVM os.arch; omitted when the probe cannot establish it. Ghidra
* selects its native decompiler directory from this value.
*/
readonly javaOsArch?: string;
/**
* Observed JVM os.name; omitted when the probe cannot establish it. Ghidra
* selects its native decompiler OS directory from the JVM OS/architecture
* pair, so a non-host value selects an unvalidated directory.
*/
readonly javaOsName?: string;
readonly checks: readonly GhidraInstallationCheck[];
}
/** Bounded observation of a supported BYO Ghidra installation and JDK. */
export interface AvailableGhidraInstallation extends GhidraInstallationObservation {
readonly status: "available";
readonly installDir: string;
readonly analyzeHeadlessPath: string;
readonly applicationPropertiesPath: string;
readonly providerVersion: string;
readonly javaHome: string;
readonly javaVersion: string;
}
/** Bounded observation explaining why a BYO Ghidra installation is unusable. */
export interface UnavailableGhidraInstallation extends GhidraInstallationObservation {
readonly status: "unavailable";
readonly installDir: string | null;
readonly analyzeHeadlessPath: string | null;
readonly providerVersion: string | null;
readonly javaHome: string | null;
readonly javaVersion: string | null;
readonly rejection: Readonly<{
code: ProviderRejectionCode;
reason: string;
}>;
}
/** Parsed available or unavailable state of one BYO Ghidra installation. */
export type GhidraInstallationInspection =
| AvailableGhidraInstallation
| UnavailableGhidraInstallation;
/** Parsed identity of the JDK selected for Ghidra. */
export interface GhidraJavaObservation {
readonly version: string;
readonly major: number;
readonly home: string;
readonly bits: number;
readonly runtime: "jdk" | "jre";
readonly vmName?: string;
/**
* Observed JVM os.arch property, which Ghidra uses to select its native
* decompiler directory. Omitted when the probe cannot establish it.
*/
readonly osArch?: string;
/**
* Observed JVM os.name property, which Ghidra uses with os.arch to select
* its native decompiler OS directory. Omitted when the probe cannot
* establish it.
*/
readonly osName?: string;
}
/** A bounded executable-header probe: a small prefix plus the whole file size. */
export interface GhidraExecutableHeaderProbe {
/** A bounded prefix; a larger or unreadable header remains unknown. */
readonly bytes: Buffer;
/** Whole-file size, since header commitments are checked against it, not the prefix. */
readonly size: number;
}
/** Narrow synchronous seam used by provider discovery without launching Ghidra. */
export interface GhidraInstallationHost {
readonly platform?: NodeJS.Platform;
readonly architecture?: NodeJS.Architecture;
readText(path: string): string | undefined;
executable(path: string): boolean;
/**
* Read a bounded header prefix of one executable so admission can reject a
* tool built for another platform or architecture. An omitted seam, or an
* unreadable file, reports the header as unknown and never rejects an
* installation that the other checks already accept.
*/
executableHeader?(path: string): GhidraExecutableHeaderProbe | undefined;
probeJava(
command: string,
environment: NodeJS.ProcessEnv,
): GhidraJavaObservation | undefined;
}
interface GhidraInstallationCoordinates {
readonly installDir: string | null;
readonly applicationPropertiesPath: string | null;
readonly analyzeHeadlessPath: string | null;
readonly nativeDecompilerPath: string | null;
readonly properties: GhidraApplicationProperties | undefined;
readonly javaCommand: string;
readonly java: GhidraJavaObservation | undefined;
}
interface GhidraInstallationCheckContext {
readonly coordinates: GhidraInstallationCoordinates;
readonly platform: NodeJS.Platform;
readonly architecture: NodeJS.Architecture;
readonly javaHome: string | undefined;
readonly host: GhidraInstallationHost;
}
/** Inspect an installation without importing a target or modifying Ghidra. */
export const inspectGhidraInstallation = (
options: GhidraInstallationOptions,
host: GhidraInstallationHost = systemGhidraInstallationHost(),
): GhidraInstallationInspection => {
const platform = options.platform ?? process.platform;
const architecture = options.architecture ?? process.arch;
const coordinates = installationCoordinates(
options,
platform,
architecture,
host,
);
const checks = installationChecks({
coordinates,
platform,
architecture,
javaHome: options.javaHome,
host,
});
const failed = checks.find(
(check): check is Extract<GhidraInstallationCheck, { status: "failed" }> =>
check.status === "failed",
);
const observation = {
platform,
architecture,
applicationPropertiesPath: coordinates.applicationPropertiesPath,
nativeDecompilerPath: coordinates.nativeDecompilerPath,
javaCommand: coordinates.javaCommand,
...(coordinates.java?.vmName === undefined
? {}
: { javaVmName: coordinates.java.vmName }),
...(coordinates.java?.osArch === undefined
? {}
: { javaOsArch: coordinates.java.osArch }),
...(coordinates.java?.osName === undefined
? {}
: { javaOsName: coordinates.java.osName }),
checks,
};
if (failed !== undefined)
return {
status: "unavailable",
...observation,
installDir: coordinates.installDir,
analyzeHeadlessPath: coordinates.analyzeHeadlessPath,
providerVersion: coordinates.properties?.providerVersion ?? null,
javaHome: coordinates.java?.home ?? options.javaHome ?? null,
javaVersion: coordinates.java?.version ?? null,
rejection: { code: failed.code, reason: failed.remediation },
};
return availableInstallation(coordinates, observation);
};
const availableInstallation = (
coordinates: GhidraInstallationCoordinates,
observation: GhidraInstallationObservation,
): AvailableGhidraInstallation => {
const providerVersion = coordinates.properties?.providerVersion;
if (
coordinates.installDir === null ||
coordinates.applicationPropertiesPath === null ||
coordinates.analyzeHeadlessPath === null ||
providerVersion === null ||
providerVersion === undefined ||
coordinates.java === undefined
)
throw new TypeError(
"Passing Ghidra installation checks produced incomplete coordinates",
);
return {
status: "available",
...observation,
installDir: coordinates.installDir,
analyzeHeadlessPath: coordinates.analyzeHeadlessPath,
applicationPropertiesPath: coordinates.applicationPropertiesPath,
providerVersion,
javaHome: coordinates.java.home,
javaVersion: coordinates.java.version,
};
};
const installationCoordinates = (
options: GhidraInstallationOptions,
platform: NodeJS.Platform,
architecture: NodeJS.Architecture,
host: GhidraInstallationHost,
): GhidraInstallationCoordinates => {
const path = platform === "win32" ? win32 : posix;
const installDir = options.installDir ?? null;
const applicationPropertiesPath =
installDir === null
? null
: path.join(installDir, "Ghidra", "application.properties");
const analyzeHeadlessPath =
installDir === null
? null
: path.join(
installDir,
"support",
platform === "win32" ? "analyzeHeadless.bat" : "analyzeHeadless",
);
const decompilerPlatform = NATIVE_PLATFORMS[platform]?.[architecture];
const decompilerExecutable =
platform === "win32" ? "decompile.exe" : "decompile";
const nativeDecompilerPath =
installDir === null || decompilerPlatform === undefined
? null
: ([
path.join(
installDir,
"Ghidra",
"Features",
"Decompiler",
"os",
decompilerPlatform,
decompilerExecutable,
),
path.join(
installDir,
"Ghidra",
"Features",
"Decompiler",
"build",
"os",
decompilerPlatform,
decompilerExecutable,
),
].find((candidate) => host.executable(candidate)) ?? null);
const properties =
applicationPropertiesPath === null
? undefined
: host.readText(applicationPropertiesPath);
const javaCommand =
options.javaHome === undefined
? platform === "win32"
? "java.exe"
: "java"
: path.join(
options.javaHome,
"bin",
platform === "win32" ? "java.exe" : "java",
);
return {
installDir,
applicationPropertiesPath,
analyzeHeadlessPath,
nativeDecompilerPath,
properties:
properties === undefined
? undefined
: ghidraApplicationProperties(properties),
javaCommand,
// The configuration check rejects a relative JAVA_HOME. Probing it would
// run whatever `bin/java` the current directory holds.
java:
options.javaHome === undefined || path.isAbsolute(options.javaHome)
? host.probeJava(
javaCommand,
ghidraJavaEnvironment(
options.javaHome,
options.environment,
platform,
),
)
: undefined,
};
};
const installationChecks = ({
coordinates,
platform,
architecture,
javaHome,
host,
}: GhidraInstallationCheckContext): readonly GhidraInstallationCheck[] => [
configurationCheck(coordinates.installDir, javaHome, platform),
installationCheck({
name: "platform",
passed: NATIVE_PLATFORMS[platform] !== undefined,
code: "unsupported_host",
detail: platform,
remediation:
"Use Linux or macOS x64/arm64, or Windows x64 with matching native Ghidra tools.",
}),
installationCheck({
name: "architecture",
passed: NATIVE_PLATFORMS[platform]?.[architecture] !== undefined,
code: "unsupported_host",
detail: architecture,
remediation: "Use x64/arm64 on Linux or macOS, or x64 on Windows.",
}),
installationCheck({
name: "installation",
passed: coordinates.properties !== undefined,
code: "executable_missing",
detail:
coordinates.applicationPropertiesPath ??
"Ghidra application properties unavailable",
remediation:
"Point GHIDRA_INSTALL_DIR at the root of an extracted official Ghidra release.",
}),
versionCheck(coordinates.properties),
installationCheck({
name: "headless",
passed:
coordinates.analyzeHeadlessPath !== null &&
host.executable(coordinates.analyzeHeadlessPath),
code: "executable_missing",
detail: coordinates.analyzeHeadlessPath ?? "analyzeHeadless unavailable",
remediation:
"Restore support/analyzeHeadless or support/analyzeHeadless.bat from the official Ghidra release.",
}),
nativeDecompilerCheck({ coordinates, platform, architecture, host }),
javaCheck(
coordinates.java,
coordinates.javaCommand,
javaHome,
coordinates.properties,
),
];
/**
* REA's configuration parser, and so the MCP server and analysis, accept only
* absolute paths; a relative one that happens to resolve here must not pass.
*/
const configurationCheck = (
installDir: string | null,
javaHome: string | undefined,
platform: NodeJS.Platform,
): GhidraInstallationCheck => {
const { isAbsolute } = platform === "win32" ? win32 : posix;
const relative = [
...(installDir !== null && !isAbsolute(installDir)
? ["GHIDRA_INSTALL_DIR"]
: []),
...(javaHome !== undefined && !isAbsolute(javaHome) ? ["JAVA_HOME"] : []),
];
if (installDir === null || relative.length === 0)
return installationCheck({
name: "configuration",
passed: installDir !== null,
code: "not_configured",
detail: installDir ?? "GHIDRA_INSTALL_DIR is not set",
remediation: `Set GHIDRA_INSTALL_DIR to an extracted Ghidra ${ghidraReleaseLine()} release directory.`,
});
const settings = relative.join(" and ");
return installationCheck({
name: "configuration",
passed: false,
code: "not_configured",
detail: `${settings} must be absolute`,
remediation: `Set ${settings} to ${relative.length === 1 ? "an absolute path" : "absolute paths"}. REA's analysis and MCP server reject relative paths even when they resolve from the current directory.`,
});
};
/** Project an installation probe into caller-visible, secret-free diagnostics. */
export const ghidraInstallationDiagnostics = (
inspection: GhidraInstallationInspection,
): Readonly<Record<string, JsonValue>> => ({
install_dir: inspection.installDir,
analyze_headless_path: inspection.analyzeHeadlessPath,
native_decompiler_path: inspection.nativeDecompilerPath,
application_properties_path: inspection.applicationPropertiesPath,
provider_version: inspection.providerVersion,
java_command: inspection.javaCommand,
java_home: inspection.javaHome,
java_version: inspection.javaVersion,
java_vm_name: inspection.javaVmName ?? null,
java_os_arch: inspection.javaOsArch ?? null,
java_os_name: inspection.javaOsName ?? null,
platform: inspection.platform,
architecture: inspection.architecture,
checks: inspection.checks.map((check) => ({
name: check.name,
ok: check.status === "passed",
code: check.status === "failed" ? check.code : null,
detail: check.detail,
})),
});
/** Environment that makes an explicitly selected JDK win over PATH discovery. */
export const ghidraJavaEnvironment = (
javaHome: string | undefined,
environment: Readonly<NodeJS.ProcessEnv>,
platform: NodeJS.Platform = process.platform,
): NodeJS.ProcessEnv => {
const selectedEnvironment = snapshotEnvironment(environment, platform);
const boundedEnvironment = {
...selectedEnvironment,
_JAVA_OPTIONS: "",
JAVA_TOOL_OPTIONS: "",
JDK_JAVA_OPTIONS: "",
GHIDRA_JAVA_OPTIONS: "",
};
return javaHome === undefined
? boundedEnvironment
: {
...boundedEnvironment,
JAVA_HOME: javaHome,
PATH: `${(platform === "win32" ? win32 : posix).join(
javaHome,
"bin",
)}${platform === "win32" ? win32.delimiter : posix.delimiter}${selectedEnvironment.PATH ?? ""}`,
};
};
const installationCheck = (options: {
readonly name: GhidraInstallationCheckName;
readonly passed: boolean;
readonly detail: string;
readonly code: ProviderRejectionCode;
readonly remediation: string;
}): GhidraInstallationCheck =>
options.passed
? {
status: "passed",
name: options.name,
detail: options.detail,
}
: {
status: "failed",
name: options.name,
code: options.code,
detail: options.detail,
remediation: options.remediation,
};
/** Require a present native decompiler without positively incompatible bytes. */
const nativeDecompilerCheck = ({
coordinates,
platform,
architecture,
host,
}: Pick<
GhidraInstallationCheckContext,
"coordinates" | "platform" | "architecture" | "host"
>): GhidraInstallationCheck => {
const path = coordinates.nativeDecompilerPath;
const compatibility =
path === null
? undefined
: assessNativeDecompiler(
path,
platform,
architecture,
host.executableHeader?.(path),
);
// Ghidra resolves its native decompiler directory from the JVM's os.arch,
// not the host process architecture. A JDK running under emulation (for
// example x86_64 under Rosetta on Apple silicon) selects a directory that
// was never validated, so every analysis fails after a passing doctor.
// Ghidra resolves the OS directory from the JVM os.name/os.arch pair, so a
// JVM reporting a non-host os.name (for example through -Dos.name=Windows)
// selects a different OS directory even when os.arch matches.
const osArch = coordinates.java?.osArch;
const osName = coordinates.java?.osName;
const selectedDirectory = jvmOsArchNativeDirectory(platform, osArch);
const validatedDirectory = NATIVE_PLATFORMS[platform]?.[architecture];
// Without a JVM observation the java check reports the missing runtime;
// the decompiler directory cannot be selected, so this check defers to it.
if (coordinates.java !== undefined) {
if (selectedDirectory === undefined)
return installationCheck({
name: "native_decompiler",
passed: false,
code: "executable_missing",
detail:
osArch === undefined
? "The Java probe did not report os.arch; the JVM-selected native decompiler directory is unknown and cannot be matched to the validated host directory"
: `JVM reports unrecognized os.arch=${osArch}; its selected native decompiler directory is unknown and cannot be matched to the validated host directory`,
remediation: `Point JAVA_HOME at a JDK whose reported architecture maps to the validated Ghidra decompiler (${validatedDirectory ?? "unsupported host"}). REA does not build or install native tools.`,
});
if (
validatedDirectory !== undefined &&
selectedDirectory !== validatedDirectory &&
path !== null
)
return installationCheck({
name: "native_decompiler",
passed: false,
code: "executable_missing",
detail: `JVM reports os.arch=${osArch}, so Ghidra selects its native decompiler from os/${selectedDirectory}, but the validated decompiler targets ${validatedDirectory} (host ${platform}/${architecture})`,
remediation: `Point JAVA_HOME at a JDK whose architecture matches the built decompiler (${validatedDirectory}). REA does not build or install native tools.`,
});
if (osName === undefined)
return installationCheck({
name: "native_decompiler",
passed: false,
code: "executable_missing",
detail:
"The Java probe did not report os.name; the JVM-selected native decompiler OS directory is unknown and cannot be matched to the validated host platform",
remediation: `Point JAVA_HOME at a JDK whose reported operating system matches the host platform (${platform}). REA does not build or install native tools.`,
});
if (!jvmOsNameMatchesPlatform(platform, osName) && path !== null)
return installationCheck({
name: "native_decompiler",
passed: false,
code: "executable_missing",
detail: `JVM reports os.name=${osName}, which does not match the validated host platform ${platform} (host ${platform}/${architecture})`,
remediation: `Point JAVA_HOME at a JDK whose reported operating system matches the host platform (${platform}). REA does not build or install native tools.`,
});
}
return installationCheck({
name: "native_decompiler",
passed: path !== null && compatibility?.status !== "incompatible",
code: "executable_missing",
detail:
compatibility?.detail ??
`Matching native decompiler for ${platform}/${architecture} was not found`,
remediation:
compatibility?.status === "incompatible"
? compatibility.remediation
: `Provide an executable Ghidra/Features/Decompiler/os/${NATIVE_PLATFORMS[platform]?.[architecture] ?? "<platform>"}/${platform === "win32" ? "decompile.exe" : "decompile"}, or its build/os equivalent. REA does not build or install native tools.`,
});
};
/**
* Whether a JVM os.name value selects the host platform's native OS directory.
* Unknown values never align with the validated host directory; admission
* must not treat them as matching.
*/
const jvmOsNameMatchesPlatform = (
platform: NodeJS.Platform,
osName: string,
): boolean => {
const normalized = osName.toLowerCase();
if (platform === "win32") return normalized.startsWith("windows");
if (platform === "darwin")
return normalized.startsWith("mac") || normalized.startsWith("darwin");
if (platform === "linux") return normalized.startsWith("linux");
return false;
};
/**
* Map a JVM os.arch value to the Ghidra native directory that JVM selects.
* Unknown values stay unknown; admission must not treat them as aligned with
* the validated host directory.
*/
const jvmOsArchNativeDirectory = (
platform: NodeJS.Platform,
osArch: string | undefined,
): string | undefined => {
if (osArch === undefined) return undefined;
const normalized = osArch.toLowerCase();
const node: NodeJS.Architecture | undefined =
normalized === "x86_64" || normalized === "amd64" || normalized === "x64"
? "x64"
: normalized === "aarch64" || normalized === "arm64"
? "arm64"
: undefined;
return node === undefined ? undefined : NATIVE_PLATFORMS[platform]?.[node];
};
const versionCheck = (
properties: GhidraApplicationProperties | undefined,
): GhidraInstallationCheck => {
const raw = properties?.providerVersion;
const parseError = properties?.parseError;
return installationCheck({
name: "version",
passed: parseError == null && ghidraReleaseAccepted(raw),
code:
parseError != null
? "version_unresolved"
: ghidraReleaseCompatibility(raw).status === "unsupported"
? "unsupported_version"
: "version_unresolved",
detail:
parseError == null
? ghidraVersionDetail(raw)
: `application.properties could not be parsed: ${parseError}`,
remediation: `Install a Ghidra ${ghidraReleaseLine()} release (verified with ${SUPPORTED_GHIDRA_VERSION}), or update REA for another Ghidra line.`,
});
};
const javaCheck = (
observation: GhidraJavaObservation | undefined,
command: string,
configuredHome: string | undefined,
properties: GhidraApplicationProperties | undefined,
): GhidraInstallationCheck => {
const requirement = ghidraJavaRequirement(properties);
const range = ghidraJavaRangeLabel(requirement);
const supported =
observation !== undefined &&
ghidraJavaMajorAccepted(observation.major, requirement) &&
observation.bits === 64 &&
observation.runtime === "jdk";
const detail =
observation === undefined
? requirement.unresolved === null
? command
: `${command}; ${requirement.unresolved}`
: `${observation.version}; ${String(observation.bits)}-bit; ${observation.runtime === "jdk" ? "JDK" : "runtime only"}; ${observation.home}; accepted ${range}`;
return installationCheck({
name: "java",
passed: supported,
code:
requirement.unresolved !== null
? "version_unresolved"
: observation === undefined
? "runtime_missing"
: "unsupported_version",
detail,
remediation: javaRemediation(requirement, configuredHome, range),
});
};
const javaRemediation = (
requirement: GhidraJavaRequirement,
configuredHome: string | undefined,
range: string,
): string => {
if (requirement.unresolved !== null)
return `The Ghidra installation's Java bounds could not be read (${requirement.unresolved}). Install a 64-bit full JDK inside the declared application.java.min and application.java.max.`;
return configuredHome === undefined
? `Install ${range}, or set JAVA_HOME before starting REA.`
: `Update JAVA_HOME to the root of ${range} installation.`;
};
const systemGhidraInstallationHost = (): GhidraInstallationHost => ({
readText(path) {
try {
// Ghidra loads this file with Properties.load(InputStream), which maps
// bytes as ISO-8859-1 rather than decoding UTF-8.
return readFileSync(path).toString("latin1");
} catch (cause: unknown) {
// best-effort cleanup: optional install probing; unreadable means unknown.
void cause;
return undefined;
}
},
executableHeader(path) {
let handle: number | undefined;
try {
handle = openSync(
path,
constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOCTTY,
);
const metadata = fstatSync(handle);
if (!metadata.isFile()) return undefined;
const bytes = Buffer.alloc(EXECUTABLE_HEADER_PROBE_BYTES);
const read = readSync(handle, bytes, 0, bytes.length, 0);
return { bytes: bytes.subarray(0, read), size: metadata.size };
} catch (cause: unknown) {
// best-effort cleanup: a header that cannot be read stays unknown.
void cause;
return undefined;
} finally {
if (handle !== undefined) closeSync(handle);
}
},
executable(path) {
try {
accessSync(path, constants.X_OK);
return statSync(path).isFile();
} catch (cause: unknown) {
// best-effort cleanup: optional executable probing; failure means missing.
void cause;
return false;
}
},
probeJava(command, environment) {
const observed = spawnSync(
command,
[
"-Dstdout.encoding=UTF-8",
"-Dstderr.encoding=UTF-8",
// JDK 17/18 use the legacy names; JDK 19+ use the names above.
"-Dsun.stdout.encoding=UTF-8",
"-Dsun.stderr.encoding=UTF-8",
"-XX:-UsePerfData",
"-XshowSettings:properties",
"-version",
],
{
encoding: "utf8",
env: environment,
timeout: 5_000,
maxBuffer: JAVA_PROBE_MAX_OUTPUT_BYTES,
windowsHide: true,
},
);
if (observed.error !== undefined || observed.status !== 0) return undefined;
const output = `${observed.stdout ?? ""}\n${observed.stderr ?? ""}`;
const version = javaProperty(output, "java.version");
const home = javaProperty(output, "java.home");
const vmName = javaProperty(output, "java.vm.name");
const osArch = javaProperty(output, "os.arch");
const osName = javaProperty(output, "os.name");
const bits = Number.parseInt(
javaProperty(output, "sun.arch.data.model") ?? "0",
10,
);
if (version === null || home === null) return undefined;
return {
version,
major: javaMajor(version),
home,
...(vmName === null ? {} : { vmName }),
...(osArch === null ? {} : { osArch }),
...(osName === null ? {} : { osName }),
bits,
runtime: executablePath(
(process.platform === "win32" ? win32 : posix).join(
home,
"bin",
process.platform === "win32" ? "javac.exe" : "javac",
),
)
? "jdk"
: "jre",
};
},
});
const executablePath = (path: string): boolean => {
try {
accessSync(path, constants.X_OK);
return true;
} catch (cause: unknown) {
// best-effort cleanup: optional executable probing; failure means missing.
void cause;
return false;
}
};
const javaProperty = (output: string, name: string): string | null =>
new RegExp(
`^\\s*${name.replaceAll(".", "\\.")}\\s*=\\s*(.+?)\\s*$`,
"mu",
).exec(output)?.[1] ?? null;
const javaMajor = (version: string): number => {
const first = Number.parseInt(version.split(".")[0] ?? "0", 10);
if (first !== 1) return first;
return Number.parseInt(version.split(".")[1] ?? "0", 10);
};