refactor(ghidra): decide Ghidra admission once for doctor and provider readiness (#10955)

* refactor(ghidra): decide Ghidra admission once for doctor and provider readiness

* test(ghidra): restore the Windows native authority spy after the shared-admission case
This commit is contained in:
morluto authored and GitHub committed 2026-11-15 17:41:28 +08:00
1 parent 7ed68aac93
commit 5d6e1bfa33
4 files changed
+184 -44

No files matched your search

+67
View File
@@ -0,0 +1,67 @@
import {
inspectWindowsNativeReadiness,
type WindowsNativeReadiness,
} from "../process/WindowsAuthority.js";
import type {
AvailableGhidraInstallation,
GhidraInstallationInspection,
UnavailableGhidraInstallation,
} from "./GhidraInstallation.js";
/** Why Ghidra's local prerequisites refuse an inspected installation. */
export type GhidraAdmissionRefusal =
| {
readonly kind: "installation_rejected";
readonly installation: UnavailableGhidraInstallation;
}
| {
readonly kind: "windows_native_unavailable";
readonly installation: AvailableGhidraInstallation;
readonly readiness: Extract<
WindowsNativeReadiness,
{ readonly available: false }
>;
};
/**
* Ghidra's admission of an inspected installation: the one decision doctor
* and the provider's readiness both project, so they cannot disagree. The
* installation must be usable, and a Windows installation also needs Windows
* native authority. Nothing is created and Ghidra is not launched.
*/
export type GhidraAdmission = {
/** Windows native authority, observed for a Windows installation only. */
readonly windowsNative: WindowsNativeReadiness | undefined;
} & (
| {
readonly admitted: true;
readonly installation: AvailableGhidraInstallation;
}
| { readonly admitted: false; readonly refusal: GhidraAdmissionRefusal }
);
export const admitGhidraInstallation = (
installation: GhidraInstallationInspection,
): GhidraAdmission => {
const windowsNative =
installation.platform === "win32"
? inspectWindowsNativeReadiness(installation.platform)
: undefined;
if (installation.status !== "available")
return {
windowsNative,
admitted: false,
refusal: { kind: "installation_rejected", installation },
};
if (windowsNative?.available === false)
return {
windowsNative,
admitted: false,
refusal: {
kind: "windows_native_unavailable",
installation,
readiness: windowsNative,
},
};
return { windowsNative, admitted: true, installation };
};
+72 -1
View File
@@ -3,7 +3,15 @@ import { createInspectionResources } from "../../tests/fixtures/inspectionResour
import { missingJavaProbe } from "./GhidraInstallation.fixture.js";
import { ok as javaProbeOk } from "../domain/result.js";
import type { GhidraJavaObservation } from "./GhidraJavaProbe.js";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import {
afterEach,
beforeEach,
describe,
expect,
it,
onTestFinished,
vi,
} from "vitest";
import { runDoctor, type DoctorHost } from "../application/Doctor.js";
import { createDoctorHostFixture } from "../application/Doctor.fixture.js";
@@ -18,6 +26,9 @@ import {
inspectSystemGhidraProvider,
projectGhidraDoctorInspection,
} from "./GhidraDoctor.js";
import { GhidraProvider } from "./GhidraProvider.js";
import { parseConfig } from "../config/parseConfig.js";
import { silentLogger } from "../logger.js";
let inspectionResources = createInspectionResources();
afterEach(async () => {
@@ -545,3 +556,63 @@ it("does not claim probe deletion failed when only descriptor cleanup remains",
expect(check?.detail).not.toContain("could not delete");
expect(check?.detail).not.toContain("remains");
});
it.each([
{
name: "a usable Linux installation",
platform: "linux",
java: true,
native: undefined,
},
{ name: "missing Java", platform: "linux", java: false, native: undefined },
{
name: "unavailable Windows native authority",
platform: "win32",
java: true,
native: {
available: false,
failureStage: "self-test",
retryable: true,
reason: "cleanup failed (145)",
},
},
] as const)(
"doctor and provider readiness project one admission: $name",
async ({ platform, java, native }) => {
if (native !== undefined) {
const authority = vi
.spyOn(nativeLoader, "systemWindowsNativeAuthority")
.mockReturnValue(native);
onTestFinished(() => authority.mockRestore());
}
const overrides = java ? {} : { probeJava: () => missingJavaProbe };
const doctor = projectGhidraDoctorInspection(
await inspection({ installDir: INSTALL, platform }, overrides),
);
const config = parseConfig({ GHIDRA_INSTALL_DIR: INSTALL });
if (!config.ok) throw config.error;
const provider = new GhidraProvider(
config.value,
silentLogger,
{},
{
...installationHost(overrides, platform),
platform,
architecture: "x64",
},
);
try {
const availability = await provider.inspectAvailability();
expect(doctor.available).toBe(availability.status === "available");
if (availability.status === "unavailable")
expect(doctor.checks).toContainEqual(
expect.objectContaining({
ok: false,
remediation: availability.remediation,
}),
);
} finally {
await provider.closeOwnedResources();
}
},
);
+5 -8
View File
@@ -5,7 +5,7 @@ import type {
DoctorProviderCheck,
DoctorProviderInspection,
} from "../application/Doctor.js";
import { inspectWindowsNativeReadiness } from "../process/WindowsAuthority.js";
import { admitGhidraInstallation } from "./GhidraAdmission.js";
import {
inspectGhidraInstallation,
type GhidraInstallationCheck,
@@ -29,19 +29,16 @@ export const projectGhidraDoctorInspection = (
inspection: GhidraInstallationInspection,
temporaryDirectory?: GhidraTemporaryDirectoryProbe,
): DoctorProviderInspection => {
const admission = admitGhidraInstallation(inspection);
// Native authority is reported once the installation itself is usable.
const readiness =
inspection.status === "available" && inspection.platform === "win32"
? inspectWindowsNativeReadiness(inspection.platform)
: undefined;
inspection.status === "available" ? admission.windowsNative : undefined;
const windowsAuthorityUnavailable = readiness?.available === false;
const temporaryDirectoryUnavailable = temporaryDirectory?.ok === false;
return {
id: "ghidra",
configured: inspection.installDir !== null,
available:
inspection.status === "available" &&
!windowsAuthorityUnavailable &&
!temporaryDirectoryUnavailable,
available: admission.admitted && !temporaryDirectoryUnavailable,
providerVersion: inspection.providerVersion,
registrationEnvironment:
inspection.status === "available"
+40 -35
View File
@@ -88,11 +88,11 @@ import {
admitGhidraClient,
type GhidraProviderClientFactory,
} from "./GhidraProviderClient.js";
import { windowsNativeCapabilities } from "../process/WindowsAuthority.js";
import {
inspectWindowsNativeReadiness,
type WindowsNativeReadiness,
windowsNativeCapabilities,
} from "../process/WindowsAuthority.js";
admitGhidraInstallation,
type GhidraAdmission,
} from "./GhidraAdmission.js";
const SUPPORTED_ARCHITECTURES = new Set<BinaryArchitecture>([
"x86",
@@ -196,11 +196,9 @@ export class GhidraProvider implements AnalysisProviderCandidate {
"binary_session",
scope,
);
const readiness =
installation.platform === "win32"
? inspectWindowsNativeReadiness(installation.platform)
: undefined;
const availability = this.#availability(installation, readiness);
const admission = admitGhidraInstallation(installation);
const readiness = admission.windowsNative;
const availability = this.#availability(installation, admission);
if (availability.status === "available" && signal.aborted)
throw cancelledBy("binary_session", signal, {
diagnostics: availability.diagnostics,
@@ -220,9 +218,10 @@ export class GhidraProvider implements AnalysisProviderCandidate {
#availability(
installation: GhidraInstallationInspection,
readiness: WindowsNativeReadiness | undefined,
admission: GhidraAdmission,
): ProviderAvailability {
const diagnostics = ghidraInstallationDiagnostics(installation);
// Runtime configuration doctor does not inspect.
if (
this.config.ghidraExistingProject !== undefined &&
installation.platform === "win32"
@@ -234,34 +233,40 @@ export class GhidraProvider implements AnalysisProviderCandidate {
remediation: EXISTING_PROJECT_WINDOWS_REMEDIATION,
diagnostics,
};
if (installation.status === "available" && readiness?.available === false)
return {
status: "unavailable",
code: readiness.code,
reason: readiness.reason,
remediation: readiness.remediation,
diagnostics: {
...diagnostics,
windows_security: jsonObjectSchema.parse(
windowsNativeCapabilities(installation.platform, readiness),
),
windows_native_failure: { stage: readiness.failureStage },
},
};
return installation.status === "available"
? {
status: "available",
code: null,
reason: null,
diagnostics,
}
: {
if (admission.admitted)
return { status: "available", code: null, reason: null, diagnostics };
const { refusal } = admission;
switch (refusal.kind) {
case "installation_rejected":
return {
status: "unavailable",
code: installation.rejection.code,
reason: installation.rejection.reason,
remediation: installation.rejection.remediation,
code: refusal.installation.rejection.code,
reason: refusal.installation.rejection.reason,
remediation: refusal.installation.rejection.remediation,
diagnostics,
};
case "windows_native_unavailable":
return {
status: "unavailable",
code: refusal.readiness.code,
reason: refusal.readiness.reason,
remediation: refusal.readiness.remediation,
diagnostics: {
...diagnostics,
windows_security: jsonObjectSchema.parse(
windowsNativeCapabilities(
installation.platform,
refusal.readiness,
),
),
windows_native_failure: { stage: refusal.readiness.failureStage },
},
};
default: {
const unreachable: never = refusal;
return unreachable;
}
}
}
inspectTargetSupport(target: BinaryTarget): ProviderTargetSupport {