Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(ghidra): reject a native decompiler built for another host (#1280)
Dery Ferdika3728c8267b4f
diff --git a/docs/installation.md b/docs/installation.mdindex 1152dd848..c47062a6f 100644--- a/docs/installation.md+++ b/docs/installation.md@@ -472,8 +472,11 @@ and JDK 21. Each installation must include the native decompiler for the hostarchitecture in `Ghidra/Features/Decompiler/os/<platform>/` or the corresponding`build/os/<platform>/` directory. Linux ARM64 uses `linux_arm_64`; officialrelease archives may require you to build that native component separately.-REA checks the executable prerequisite and does not build or install native-tools, or change Gatekeeper quarantine settings.+REA checks the executable prerequisite by inspecting the file's own executable+header, so a native component built for another platform or architecture is+reported as incompatible instead of being admitted from its directory name, and+a header that cannot be read or recognized is reported as unknown. REA does not+build or install native tools, or change Gatekeeper quarantine settings.The adapter exposes 25 read-only operations: thirteen inventory/name/searchoperations and twelve function-analysis operations. These cover metadata,diff --git a/src/ghidra/GhidraInstallation.test.ts b/src/ghidra/GhidraInstallation.test.tsindex d81447c8d..4f5dfce63 100644--- a/src/ghidra/GhidraInstallation.test.ts+++ b/src/ghidra/GhidraInstallation.test.ts@@ -1,5 +1,6 @@import { afterEach, describe, expect, it, vi } from "vitest";+import { elf, fat, thinMach } from "../domain/binaryTarget.fixture.js";import { projectGhidraDoctorInspection } from "./GhidraDoctor.js";import {ghidraJavaEnvironment,@@ -510,3 +511,171 @@ describe("Ghidra configuration paths", () => {);});});++describe("Ghidra FAT native decompiler admission", () => {+ it.each([+ {+ name: "foreign-only FAT",+ bytes: fat([0x01000007]),+ status: "unavailable",+ detail: "requires mach-o arm64",+ },+ {+ name: "matching universal FAT",+ bytes: fat([0x01000007, 0x0100000c]),+ status: "available",+ detail: "matches darwin/arm64",+ },+ {+ name: "truncated FAT table",+ bytes: fat([0x01000007], 2),+ status: "available",+ detail: "could not be established",+ },+ ])("distinguishes $name", ({ bytes, status, detail }) => {+ const result = inspectGhidraInstallation(+ {+ environment: {},+ installDir: INSTALL,+ platform: "darwin",+ architecture: "arm64",+ },+ host({ executableHeader: () => ({ bytes, size: bytes.length }) }),+ );+ expect(result.status).toBe(status);+ expect(+ result.checks.find(({ name }) => name === "native_decompiler")?.detail,+ ).toContain(detail);+ });++ it("keeps a truncated host slice unknown despite a readable foreign slice", () => {+ const bytes = fat([0x01000007, 0x0100000c]);+ bytes.writeUInt32BE(bytes.length + 1, 8 + 20 + 12);+ const result = inspectGhidraInstallation(+ {+ environment: {},+ installDir: INSTALL,+ platform: "darwin",+ architecture: "arm64",+ },+ host({ executableHeader: () => ({ bytes, size: bytes.length }) }),+ );+ expect(result.status).toBe("available");+ expect(+ result.checks.find(({ name }) => name === "native_decompiler")?.detail,+ ).toContain("could not be established");+ });+});++describe("Ghidra native decompiler admission", () => {+ it.each([+ {+ name: "a Linux x86-64 decompiler at the macOS arm64 path",+ options: {+ environment: {},+ installDir: INSTALL,+ platform: "darwin" as const,+ architecture: "arm64" as const,+ },+ executableHeader: (path: string) =>+ path === MAC_DECOMPILER+ ? { bytes: elf(2, 1, 62), size: 52 }+ : undefined,+ },+ {+ name: "a macOS arm64 decompiler at the Linux x64 path",+ options: {+ environment: {},+ installDir: INSTALL,+ platform: "linux" as const,+ architecture: "x64" as const,+ },+ executableHeader: (path: string) =>+ path === LINUX_DECOMPILER+ ? { bytes: thinMach(0xcffaedfe, 0x0100000c), size: 32 }+ : undefined,+ },+ ])("distinguishes $name", ({ options, executableHeader }) => {+ const result = inspectGhidraInstallation(+ options,+ host({ executableHeader }),+ );+ expect(result.status).toBe("unavailable");+ expect(+ result.checks.find(({ status }) => status === "failed"),+ ).toMatchObject({ name: "native_decompiler", code: "executable_missing" });+ });++ it("explains an accepted decompiler by its header, not only its path", () => {+ const result = inspectGhidraInstallation(+ {+ environment: {},+ installDir: INSTALL,+ platform: "linux",+ architecture: "x64",+ },+ host({+ executableHeader: (path: string) =>+ path === LINUX_DECOMPILER+ ? { bytes: elf(2, 1, 62), size: 52 }+ : undefined,+ }),+ );+ expect(result.status).toBe("available");+ if (result.status !== "available") return;+ expect(+ result.checks.find(({ name }) => name === "native_decompiler"),+ ).toMatchObject({+ status: "passed",+ detail: `${LINUX_DECOMPILER} reports elf x86_64, which matches linux/x64`,+ });+ });++ it("keeps an unreadable header unknown instead of failing the install", () => {+ const result = inspectGhidraInstallation(+ {+ environment: {},+ installDir: INSTALL,+ platform: "linux",+ architecture: "x64",+ },+ host({ executableHeader: () => undefined }),+ );+ expect(result.status).toBe("available");+ if (result.status !== "available") return;+ expect(+ result.checks.find(({ name }) => name === "native_decompiler"),+ ).toMatchObject({+ status: "passed",+ detail: expect.stringContaining("could not be established"),+ });+ });++ it("names the observed and the required executable in the failure", () => {+ const result = inspectGhidraInstallation(+ {+ environment: {},+ installDir: INSTALL,+ platform: "darwin",+ architecture: "arm64",+ },+ host({+ executableHeader: (path: string) =>+ path === MAC_DECOMPILER+ ? { bytes: elf(2, 1, 62), size: 52 }+ : undefined,+ }),+ );+ expect(result.status).toBe("unavailable");+ if (result.status !== "unavailable") return;+ expect(+ result.checks.find(({ name }) => name === "native_decompiler"),+ ).toMatchObject({+ status: "failed",+ detail: expect.stringMatching(+ /reports elf x86_64, but darwin\/arm64 requires mach-o arm64/u,+ ),+ remediation: expect.stringContaining("os/mac_arm_64/decompile"),+ });+ });+});diff --git a/src/ghidra/GhidraInstallation.ts b/src/ghidra/GhidraInstallation.tsindex c01d8d475..d60d447ed 100644--- a/src/ghidra/GhidraInstallation.ts+++ b/src/ghidra/GhidraInstallation.ts@@ -1,10 +1,23 @@import { snapshotEnvironment } from "../process/snapshotEnvironment.js";import { spawnSync } from "node:child_process";import { constants } from "node:fs";-import { accessSync, readFileSync } 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 type { BinaryArchitecture } from "../domain/binaryTargetTypes.js";import type { JsonValue } from "../domain/jsonValue.js";import {ghidraApplicationProperties,@@ -34,6 +47,103 @@ const NATIVE_PLATFORMS: Readonly<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;++/** 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.includes(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}`;+ if (observed === expected)+ 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>;@@ -117,12 +227,27 @@ export interface GhidraJavaObservation {readonly runtime: "jdk" | "jre";}+/** 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,@@ -352,15 +477,7 @@ const installationChecks = ({remediation:"Restore support/analyzeHeadless or support/analyzeHeadless.bat from the official Ghidra release.",}),- installationCheck({- name: "native_decompiler",- passed: coordinates.nativeDecompilerPath !== null,- code: "executable_missing",- detail:- coordinates.nativeDecompilerPath ??- `Matching native decompiler for ${platform}/${architecture} was not found`,- 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.`,- }),+ nativeDecompilerCheck({ coordinates, platform, architecture, host }),javaCheck(coordinates.java,coordinates.javaCommand,@@ -472,6 +589,40 @@ const installationCheck = (options: {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),+ );+ 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.`,+ });+};+const versionCheck = (properties: GhidraApplicationProperties | undefined,): GhidraInstallationCheck => {@@ -543,10 +694,30 @@ const systemGhidraInstallationHost = (): GhidraInstallationHost => ({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 true;+ return statSync(path).isFile();} catch (cause: unknown) {// best-effort cleanup: optional executable probing; failure means missing.void cause;