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 { DeferredAnalysisClient } from "../providers/DeferredAnalysisClient.js";
import type { ProviderInspectionScope } from "../providers/ProviderInspectionScope.js";
import { analysisClientFailureForOperation } from "../providers/AnalysisClientFailure.js";
import { AnalysisCleanupLease } from "../artifacts/AnalysisCleanupLease.js";
import {
SharedStartupAttempt,
STARTUP_OWNER_CLOSED,
} from "../process/SharedStartupAttempt.js";
import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import { bindArtifactFileCleanup } from "../artifacts/ArtifactFileOperation.js";
import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
import type {
AnalysisClient,
AnalysisClientContext,
AnalysisProviderInspectionOptions,
RetainedResourceScope,
AnalysisProfileResolutionOptions,
AnalysisProfileResolution,
AnalysisProviderCandidate,
AnalysisProviderReadinessSnapshot,
CapabilityDescriptor,
ProviderAvailability,
ProviderIdentity,
ProviderTargetSupport,
} from "../application/AnalysisProvider.js";
import type { AppConfig } from "../config/types.js";
import {
createAnalysisProfile,
type AnalysisProfileCommitment,
} from "../domain/analysisProfile.js";
import {
isMachOFormat,
type BinaryTarget,
} from "../domain/binaryTargetTypes.js";
import {
jsonObjectSchema,
jsonValueSchema,
type JsonValue,
} from "../domain/jsonValue.js";
import { err, ok, type Result } from "../domain/result.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import type { Logger } from "pino";
import { GhidraClient } from "./GhidraClient.js";
import {
ghidraInstallationDiagnostics,
inspectGhidraInstallation,
type GhidraInstallationHost,
type GhidraInstallationInspection,
} from "./GhidraInstallation.js";
import { resolveGhidraAnalysisProfile } from "./GhidraAnalysisProfile.js";
import { AnalysisCancelledError } from "../domain/analysisErrorCore.js";
import { resolveGhidraAnalysisSeeds } from "./GhidraAnalysisSeeds.js";
import {
admitGhidraLanguageOverride,
readGhidraLanguageCatalog,
} from "./GhidraLanguageCatalog.js";
import { ghidraFileFailure } from "./GhidraFileArtifacts.js";
import {
ghidraProcessorUnsupportedReason,
isGhidraPspTarget,
} from "./GhidraPspProfile.js";
import { resolveGhidraExtensions } from "./extensions/GhidraExtensions.js";
import {
CAPABILITIES,
windowsP0Capabilities,
GHIDRA_PROVIDER_IDENTITY,
WINDOWS_P0_NATIVE_PE_ARCHITECTURES,
} from "./GhidraProviderCapabilities.js";
import {
createGhidraProviderClient,
admitGhidraClient,
type GhidraProviderClientFactory,
} from "./GhidraProviderClient.js";
import {
inspectWindowsNativeReadiness,
type WindowsNativeReadiness,
windowsNativeCapabilities,
} from "../process/WindowsAuthority.js";
const SUPPORTED_ARCHITECTURES = new Set([
"x86",
"x86_64",
"arm",
"arm64",
"mips",
"6502",
"riscv",
"powerpc",
"m68k",
"hexagon",
]);
/** Ghidra candidate backed by an isolated ephemeral headless import. */
export class GhidraProvider implements AnalysisProviderCandidate {
readonly #inspectionResources = new ArtifactResourceScope();
readonly #inspectionWork = new Set<Promise<unknown>>();
#lifetime = new AbortController();
readonly #observations = new WeakMap<
ProviderInspectionScope,
{
readonly lifetime: AbortSignal;
readonly installation: GhidraInstallationInspection;
}
>();
#inspectionAttempt:
| SharedStartupAttempt<Result<GhidraInstallationInspection, AnalysisError>>
| undefined;
readonly #inspectionOwner: RetainedResourceScope = {
retain: (owner, resource) =>
this.#inspectionResources.retain({
kind: "lease",
resource,
lease: AnalysisCleanupLease.forCloseOwner(owner, resource),
}),
run: (operation) => this.#inspectionResources.run(operation),
};
#closing: Promise<Result<null, AnalysisError>> | undefined;
private readonly environment: NodeJS.ProcessEnv;
constructor(
private readonly config: AppConfig,
private readonly logger: Logger,
environment: Readonly<NodeJS.ProcessEnv>,
private readonly installationHost?: GhidraInstallationHost,
private readonly clientFactory: GhidraProviderClientFactory = (options) =>
new GhidraClient(options),
) {
this.environment = snapshotEnvironment(
environment,
installationHost?.platform,
);
}
identity(): ProviderIdentity {
return GHIDRA_PROVIDER_IDENTITY;
}
capabilities(): readonly CapabilityDescriptor[] {
return (this.installationHost?.platform ?? process.platform) === "win32"
? windowsP0Capabilities()
: CAPABILITIES;
}
async inspectAvailability(
options: AnalysisProviderInspectionOptions = {},
): Promise<ProviderAvailability> {
return (await this.inspectReadinessSnapshot(options)).availability;
}
inspectReadinessSnapshot(
options: AnalysisProviderInspectionOptions = {},
): Promise<AnalysisProviderReadinessSnapshot> {
return this.#runInspectionWork(
(signal) => this.#readinessSnapshot(signal, options.scope),
options.signal,
);
}
async #readinessSnapshot(
signal: AbortSignal,
scope?: ProviderInspectionScope,
): Promise<AnalysisProviderReadinessSnapshot> {
const installation = await this.#inspectInstallation(
signal,
"binary_session",
scope,
);
const readiness =
installation.platform === "win32"
? inspectWindowsNativeReadiness(installation.platform)
: undefined;
const availability = this.#availability(installation, readiness);
if (availability.status === "available" && signal.aborted)
throw new AnalysisCancelledError("binary_session", {
cause: signal.reason,
diagnostics: availability.diagnostics,
});
return {
availability,
capabilities:
readiness === undefined
? CAPABILITIES
: windowsP0Capabilities(readiness),
};
}
#availability(
installation: GhidraInstallationInspection,
readiness: WindowsNativeReadiness | undefined,
): ProviderAvailability {
const diagnostics = ghidraInstallationDiagnostics(installation);
if (installation.status === "available" && readiness?.available === false)
return {
status: "unavailable",
code: readiness.code,
reason: readiness.reason,
diagnostics: {
...diagnostics,
windows_security: jsonObjectSchema.parse(
windowsNativeCapabilities(installation.platform, readiness),
),
windows_native_failure: {
stage: readiness.failureStage,
remediation: readiness.remediation,
},
},
};
return installation.status === "available"
? {
status: "available",
code: null,
reason: null,
diagnostics,
}
: {
status: "unavailable",
code: installation.rejection.code,
reason: installation.rejection.reason,
diagnostics,
};
}
inspectTargetSupport(target: BinaryTarget): ProviderTargetSupport {
const hostPlatform = this.installationHost?.platform ?? process.platform;
const diagnostics = {
host_platform: hostPlatform,
target_kind: target.kind,
target_format: target.format,
architecture: target.architecture ?? null,
available_architectures:
target.kind === "executable"
? [...target.availableArchitectures]
: null,
executable_role: target.executableRole ?? null,
managed: target.managed ?? null,
};
if (target.kind !== "executable")
return {
status: "unsupported",
code: "target_kind_unsupported",
reason: `Ghidra v1 imports executable targets, not ${target.kind} targets.`,
diagnostics,
};
if (hostPlatform === "win32")
return inspectWindowsP0TargetSupport(target, diagnostics);
const mipsReason =
isGhidraPspTarget(target) &&
(hostPlatform !== "linux" ||
(this.installationHost?.architecture ?? process.arch) !== "x64")
? "The initial PSP Allegrex profile is verified on Linux x64 only."
: ghidraProcessorUnsupportedReason(target);
if (mipsReason !== null)
return {
status: "unsupported",
code: "architecture_unsupported",
reason: mipsReason,
diagnostics,
};
if (
isMachOFormat(target.format) &&
target.availableArchitectures.length > 1
)
return {
status: "unsupported",
code: "architecture_unsupported",
reason:
"Ghidra v1 cannot enforce the selected architecture when importing a universal Mach-O; analyze a thinned Mach-O slice instead.",
diagnostics,
};
if (!SUPPORTED_ARCHITECTURES.has(target.architecture))
return {
status: "unsupported",
code: "architecture_unsupported",
reason:
"Ghidra v1 requires a supported x86, x86_64, arm, arm64, MIPS, RISC-V, raw 6502, or raw m68k target profile.",
diagnostics,
};
return {
status: "supported",
code: null,
reason: null,
diagnostics,
};
}
hasPendingOwnedResources(): boolean {
return (
this.#inspectionWork.size > 0 ||
this.#inspectionAttempt !== undefined ||
this.#inspectionResources.hasPending
);
}
closeOwnedResources() {
this.#closing ??= Promise.resolve()
.then(async () => {
this.#lifetime.abort(STARTUP_OWNER_CLOSED);
this.#inspectionAttempt?.close();
await Promise.allSettled([
...this.#inspectionWork,
...(this.#inspectionAttempt === undefined
? []
: [this.#inspectionAttempt.promise]),
]);
return this.#closeInspectionResources();
})
.finally(() => {
this.#lifetime = new AbortController();
this.#closing = undefined;
});
return this.#closing;
}
async #closeInspectionResources() {
try {
await this.#inspectionResources.retryCleanup();
return ok(null);
} catch (cause: unknown) {
const error = new ProviderCleanupError(
"ghidra",
cause instanceof ArtifactReaderFailure
? (cause.cleanup?.resources ?? [])
: [],
{ reason: providerFailureText(cause) },
{ cause },
);
bindArtifactFileCleanup(cause, error);
return err(error);
}
}
async resolveAnalysisProfile(
target: BinaryTarget,
options?: AnalysisProfileResolutionOptions,
): Promise<Result<AnalysisProfileResolution, AnalysisError>> {
try {
return await this.#runInspectionWork(async (signal) => {
const result = await this.#resolveProfile(target, {
...options,
signal,
});
if (!result.ok && result.error instanceof AnalysisCancelledError)
return err(
analysisClientFailureForOperation(
result.error,
"ghidra",
"open_binary",
),
);
if (result.ok && signal.aborted)
return err(
new AnalysisCancelledError("open_binary", {
cause: signal.reason,
diagnostics: {
completed_profile_digest: result.value.profile?.digest ?? null,
},
}),
);
return result;
}, options?.signal);
} catch (cause: unknown) {
return err(
analysisClientFailureForOperation(
cause,
"ghidra",
cause instanceof AnalysisCancelledError
? "open_binary"
: "resolve_analysis_profile",
),
);
}
}
async #resolveProfile(
target: BinaryTarget,
options?: AnalysisProfileResolutionOptions,
) {
const installation = await this.#inspectInstallation(
options?.signal,
"resolve_analysis_profile",
options?.scope,
);
const resolved = await resolveGhidraAnalysisProfile(
target,
GHIDRA_PROVIDER_IDENTITY,
installation,
this.#inspectionResources,
options?.signal,
this.config.ghidraLanguageOverride,
this.config.ghidraDisabledAnalyzers,
);
if (!resolved.ok || resolved.value.profile === null) return resolved;
const override = this.config.ghidraLanguageOverride;
if (override !== undefined && installation.status === "available") {
let catalog: Awaited<ReturnType<typeof readGhidraLanguageCatalog>>;
try {
catalog = await readGhidraLanguageCatalog(
installation.installDir,
this.#inspectionResources,
options?.signal,
);
} catch (cause: unknown) {
return err(
ghidraFileFailure(cause, "resolve_analysis_profile", {
setting: "REA_GHIDRA_LANGUAGE_ID",
}),
);
}
const refused = admitGhidraLanguageOverride(
override,
catalog,
installation.providerVersion,
);
if (refused !== null) return err(refused);
}
const extensions = await resolveGhidraExtensions(
this.config,
target,
installation.platform,
this.#inspectionResources,
options?.signal,
);
if (!extensions.ok) return extensions;
if (options?.signal?.aborted === true)
return err(
new AnalysisCancelledError("open_binary", {
cause: options.signal.reason,
}),
);
const seeds = await resolveGhidraAnalysisSeeds(
this.config.ghidraSeedFile,
this.#inspectionResources,
options?.signal,
);
if (!seeds.ok) return seeds;
if (extensions.value.length === 0 && seeds.value === undefined)
return resolved;
return ok({
...resolved.value,
profile: createAnalysisProfile(resolved.value.profile.provider, {
...resolved.value.profile.parameters,
...(extensions.value.length === 0
? {}
: { analysis_extensions: jsonValueSchema.parse(extensions.value) }),
...(seeds.value === undefined
? {}
: { analysis_seeds: jsonValueSchema.parse(seeds.value) }),
}),
});
}
createClient(
target: BinaryTarget,
profile?: AnalysisProfileCommitment,
context?: AnalysisClientContext,
): AnalysisClient {
return new DeferredAnalysisClient(async (signal, resourceOwner) => {
const admitted = admitGhidraClient(
target,
profile,
this.installationHost?.platform ?? process.platform,
);
if (!admitted.ok) throw admitted.error;
const installation = await this.#observeInstallation(
signal,
resourceOwner,
);
const created = createGhidraProviderClient({
config: this.config,
environment: this.environment,
logger: this.logger,
clientFactory: this.clientFactory,
admission: admitted.value,
...(context === undefined ? {} : { context }),
installation,
signal,
});
if (!created.ok) throw created.error;
return created.value;
}, "ghidra");
}
async #runInspectionWork<T>(
operation: (signal: AbortSignal) => Promise<T>,
callerSignal?: AbortSignal,
): Promise<T> {
if (this.#closing !== undefined) {
const closed = await this.#closing;
if (!closed.ok) throw closed.error;
}
const signal =
callerSignal === undefined
? this.#lifetime.signal
: AbortSignal.any([callerSignal, this.#lifetime.signal]);
if (signal.aborted)
throw new AnalysisCancelledError("ghidra:inspection", {
cause: signal.reason,
});
const work = Promise.resolve().then(() => operation(signal));
this.#inspectionWork.add(work);
try {
return await work;
} finally {
this.#inspectionWork.delete(work);
}
}
async #inspectInstallation(
callerSignal: AbortSignal | undefined,
operation: string,
scope?: ProviderInspectionScope,
): Promise<GhidraInstallationInspection> {
if (callerSignal?.aborted)
throw new AnalysisCancelledError(operation, {
cause: callerSignal.reason,
});
if (scope?.active) {
const observed = this.#observations.get(scope);
if (observed?.lifetime === this.#lifetime.signal)
return observed.installation;
}
let attempt = this.#inspectionAttempt;
if (attempt === undefined) {
attempt = new SharedStartupAttempt(
(signal) =>
Promise.resolve().then(async () => {
try {
return ok(await this.#observeInstallation(signal));
} catch (cause: unknown) {
return err(
analysisClientFailureForOperation(
cause,
"ghidra",
"ghidra:inspection",
),
);
}
}),
this.#lifetime.signal,
);
const owned = attempt;
this.#inspectionAttempt = owned;
void owned.promise.then(
() => {
if (this.#inspectionAttempt === owned)
this.#inspectionAttempt = undefined;
},
() => {
if (this.#inspectionAttempt === owned)
this.#inspectionAttempt = undefined;
},
);
}
const waited = await attempt.wait(callerSignal);
if (waited.status === "cancelled")
throw new AnalysisCancelledError(operation, {
cause: callerSignal?.reason,
});
if (!waited.value.ok)
throw analysisClientFailureForOperation(
waited.value.error,
"ghidra",
operation,
);
if (
waited.value.value.status === "available" &&
(callerSignal?.aborted || attempt.signal.aborted)
)
throw new AnalysisCancelledError(operation, {
cause: callerSignal?.aborted
? callerSignal.reason
: attempt.signal.reason,
diagnostics: ghidraInstallationDiagnostics(waited.value.value),
});
if (scope?.active && !callerSignal?.aborted && !attempt.signal.aborted)
this.#observations.set(scope, {
lifetime: this.#lifetime.signal,
installation: waited.value.value,
});
return waited.value.value;
}
#observeInstallation(
signal: AbortSignal,
resourceOwner: RetainedResourceScope = this.#inspectionOwner,
): Promise<GhidraInstallationInspection> {
const options = {
resourceOwner,
signal,
environment: this.environment,
...(this.config.ghidraInstallDir === undefined
? {}
: { installDir: this.config.ghidraInstallDir }),
...(this.config.ghidraJavaHome === undefined
? {}
: { javaHome: this.config.ghidraJavaHome }),
...(this.installationHost?.platform === undefined
? {}
: { platform: this.installationHost.platform }),
...(this.installationHost?.architecture === undefined
? {}
: { architecture: this.installationHost.architecture }),
};
return this.installationHost === undefined
? inspectGhidraInstallation(options)
: inspectGhidraInstallation(options, this.installationHost);
}
}
const providerFailureText = (cause: unknown): string =>
cause instanceof Error ? cause.message : String(cause);
const inspectWindowsP0TargetSupport = (
target: BinaryTarget,
diagnostics: Readonly<Record<string, JsonValue>>,
): ProviderTargetSupport => {
// The raw 6502 lane uses the same immutable snapshot and native ownership boundary.
if (target.format === "raw-binary" && target.architecture === "6502")
return { status: "supported", code: null, reason: null, diagnostics };
if (target.format !== "pe")
return {
status: "unsupported",
code: "target_format_unsupported",
reason:
"Windows Ghidra P0 accepts native PE and explicitly selected raw 6502 targets only.",
diagnostics,
};
if (!WINDOWS_P0_NATIVE_PE_ARCHITECTURES.includes(target.architecture))
return {
status: "unsupported",
code: "architecture_unsupported",
reason:
"Windows Ghidra P0 accepts x86, x86-64, ARM and ARM64 PE targets only.",
diagnostics,
};
if (
target.executableRole !== "application" &&
target.executableRole !== "shared-library"
)
return {
status: "unsupported",
code: "target_role_unsupported",
reason:
"Windows Ghidra P0 accepts PE applications and DLLs, not non-executable or unclassified images.",
diagnostics,
};
if (target.managed !== false)
return {
status: "unsupported",
code: "managed_target_unsupported",
reason:
"Windows Ghidra P0 accepts native PE applications and DLLs; managed or unclassified PE targets are unsupported.",
diagnostics,
};
if (
(target.architecture === "arm" && target.peMachine !== 0x01c4) ||
(target.architecture === "arm64" && target.peMachine !== 0xaa64)
)
return {
status: "unsupported",
code: "architecture_unsupported",
reason:
"Windows Ghidra P0 ARM PE targets require observed ARMNT (0x01c4) or ARM64 (0xaa64) COFF machines; legacy ARM/Thumb and unknown machines are unsupported.",
diagnostics: { ...diagnostics, pe_machine: target.peMachine ?? null },
};
return {
status: "supported",
code: null,
reason: null,
diagnostics,
};
};