From 5d6e1bfa3378857f320e31308c5af78db7214ecd Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 15 Nov 2026 17:41:28 +0800 Subject: [PATCH] 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 --- src/ghidra/GhidraAdmission.ts | 67 +++++++++++++++++++++++++++++ src/ghidra/GhidraDoctor.test.ts | 73 +++++++++++++++++++++++++++++++- src/ghidra/GhidraDoctor.ts | 13 +++--- src/ghidra/GhidraProvider.ts | 75 ++++++++++++++++++--------------- 4 files changed, 184 insertions(+), 44 deletions(-) create mode 100644 src/ghidra/GhidraAdmission.ts diff --git a/src/ghidra/GhidraAdmission.ts b/src/ghidra/GhidraAdmission.ts new file mode 100644 index 0000000000..fb18a57ace --- /dev/null +++ b/src/ghidra/GhidraAdmission.ts @@ -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 }; +}; diff --git a/src/ghidra/GhidraDoctor.test.ts b/src/ghidra/GhidraDoctor.test.ts index 64dbcf8268..3a918d56a8 100644 --- a/src/ghidra/GhidraDoctor.test.ts +++ b/src/ghidra/GhidraDoctor.test.ts @@ -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(); + } + }, +); diff --git a/src/ghidra/GhidraDoctor.ts b/src/ghidra/GhidraDoctor.ts index 335d0a1be8..9ceef65c30 100644 --- a/src/ghidra/GhidraDoctor.ts +++ b/src/ghidra/GhidraDoctor.ts @@ -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" diff --git a/src/ghidra/GhidraProvider.ts b/src/ghidra/GhidraProvider.ts index abaf3e3c13..d4e26b4192 100644 --- a/src/ghidra/GhidraProvider.ts +++ b/src/ghidra/GhidraProvider.ts @@ -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([ "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 {