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): name the startup deadline setting when startup times out (#4590)
Syed Rishad1b56237caec2
diff --git a/docs/installation.md b/docs/installation.mdindex 19c742cb2..08eace307 100644--- a/docs/installation.md+++ b/docs/installation.md@@ -923,6 +923,9 @@ bridge, and health readiness. Large binaries can need more: set`REA_GHIDRA_STARTUP_TIMEOUT_MS` to an integer between 1 and 2,147,483,647milliseconds in the server environment. An absent setting uses the default;empty, invalid or out-of-range supplied values fail configuration validation.+When the deadline elapses, the `provider_timeout` error names+`REA_GHIDRA_STARTUP_TIMEOUT_MS` with the deadline that was applied and suggests+`REA_GHIDRA_DISABLED_ANALYZERS` for analyzers that dominate the time.REA parses the supplied configuration environment andpasses the deadline to each provider client; a startup failure is returned by the query that triggered it,without exposing partial analysis. This deadline is separate from MCP transportdiff --git a/src/domain/analysisErrorCore.ts b/src/domain/analysisErrorCore.tsindex 50b5f1af1..a0db0c06e 100644--- a/src/domain/analysisErrorCore.ts+++ b/src/domain/analysisErrorCore.ts@@ -160,16 +160,25 @@ export class AnalysisCancelledError extends AnalysisError {/** Provider-neutral operation exceeded its declared execution deadline. */export class AnalysisTimeoutError extends AnalysisError {readonly _tag = "AnalysisTimeoutError";+ override readonly userMessage: string | undefined;+ readonly remediationAction: string | undefined;constructor(readonly operation: string,readonly timeoutMs: number,- options?: AnalysisErrorOptions,+ options?: AnalysisErrorOptions & {+ /** Provider-specific explanation of which deadline elapsed. */+ readonly userMessage?: string;+ /** Provider-specific setting or action that changes that deadline. */+ readonly remediationAction?: string;+ },) {super(`Analysis operation timed out after ${String(timeoutMs)}ms: ${operation}`,options,);+ this.userMessage = options?.userMessage;+ this.remediationAction = options?.remediationAction;}}diff --git a/src/domain/analysisErrorPresentation.ts b/src/domain/analysisErrorPresentation.tsindex 6b4f1d15f..410dfae2a 100644--- a/src/domain/analysisErrorPresentation.ts+++ b/src/domain/analysisErrorPresentation.ts@@ -6,6 +6,7 @@ import {AnalysisOutputError,AnalysisUnsupportedTargetError,AnalysisResourceConstraintError,+ AnalysisTimeoutError,} from "./analysisErrorCore.js";import { ArtifactOperationError } from "./artifactOperationError.js";import {@@ -70,6 +71,11 @@ export const analysisErrorRemediationAction = (? "Review the reported worker file-size limits and write failure. Retry with a sufficient file-size allowance for the evidence reply; REA retains tighter inherited limits.": "Review the reported worker memory limits and available host memory. Retry with sufficient memory or a smaller artifact; REA retains tighter inherited limits."));+ if (+ error instanceof AnalysisTimeoutError &&+ error.remediationAction !== undefined+ )+ return error.remediationAction;if (error instanceof HopperTimeoutError)return error.operation === undefined? "Review details.launcher and inspect Hopper for ongoing initial analysis or a pending loader, demo, or license dialog. For a large target, increase REA_HOPPER_STARTUP_TIMEOUT_MS in the environment that starts REA and allow at least that long in the MCP client. Resolve retained cleanup before reopening."diff --git a/src/ghidra/GhidraClient.ts b/src/ghidra/GhidraClient.tsindex 2b4b62d70..64788e8f6 100644--- a/src/ghidra/GhidraClient.ts+++ b/src/ghidra/GhidraClient.ts@@ -50,6 +50,7 @@ import { GhidraResponseRouter } from "./GhidraResponseRouter.js";import { GhidraRequestQueue } from "./GhidraRequestQueue.js";import {bindGhidraSessionFailure,+ GHIDRA_STARTUP_DEADLINE_ELAPSED,GhidraSessionError,} from "./GhidraSessionError.js";import {@@ -1132,7 +1133,7 @@ export class GhidraClient {? this.#failure("cancelled", "Ghidra startup was cancelled", cause, {cancellation: { reason: deadline.signal.reason },})- : this.#failure("timeout", "Ghidra startup deadline elapsed", cause, {+ : this.#failure("timeout", GHIDRA_STARTUP_DEADLINE_ELAPSED, cause, {timeoutMs: deadline.timeoutMs,});}diff --git a/src/ghidra/GhidraClientStartup.ts b/src/ghidra/GhidraClientStartup.tsindex 80267d1d7..092e2d784 100644--- a/src/ghidra/GhidraClientStartup.ts+++ b/src/ghidra/GhidraClientStartup.ts@@ -2,9 +2,10 @@ import type { JsonValue } from "../domain/jsonValue.js";import { err, type Result } from "../domain/result.js";import type { ProviderStartupDeadline } from "../process/ProviderDeadline.js";import type { GhidraRequestOptions } from "./GhidraClientTypes.js";-import type {- GhidraSessionError,- GhidraSessionFailureFactory,+import {+ GHIDRA_STARTUP_DEADLINE_ELAPSED,+ type GhidraSessionError,+ type GhidraSessionFailureFactory,} from "./GhidraSessionError.js";import type { GhidraSessionInfo } from "./GhidraSessionValues.js";@@ -66,6 +67,6 @@ const interruptionFailure = (options.deadline.signal.reason,{ cancellation: { reason: options.deadline.signal.reason } },)- : options.failure("timeout", "Ghidra startup deadline elapsed", undefined, {+ : options.failure("timeout", GHIDRA_STARTUP_DEADLINE_ELAPSED, undefined, {timeoutMs: options.startupTimeoutMs,});diff --git a/src/ghidra/GhidraProvider.behavior.test.ts b/src/ghidra/GhidraProvider.behavior.test.tsindex 740bc1635..bc4bb927f 100644--- a/src/ghidra/GhidraProvider.behavior.test.ts+++ b/src/ghidra/GhidraProvider.behavior.test.ts@@ -2402,6 +2402,64 @@ it("projects Ghidra startup failure and its incomplete cleanup together", async});});+describe("Ghidra deadline guidance", () => {+ const timedOut = async (phase: "start" | "request", message: string) => {+ const failure = new GhidraSessionError(+ "timeout",+ message,+ { failure_kind: "timeout" },+ { timeoutMs: 250 },+ );+ const ghidra = provider(installationHost(), () => ({+ start: async () => (phase === "start" ? err(failure) : ok(sessionInfo())),+ callTool: async () => err(failure),+ close: async () => ok(null),+ }));+ const target = executableTarget("elf", "x86_64");+ const profile = await ghidra.resolveAnalysisProfile(target);+ if (!profile.ok || profile.value.profile === null)+ throw new Error("Expected Ghidra analysis profile");+ const result = await ghidra+ .createClient(target, profile.value.profile)+ .execute("list_documents", {});+ if (result.ok) throw new Error("Expected a Ghidra timeout");+ return projectAnalysisError(result.error);+ };++ it("names the startup deadline setting and its value when startup times out", async () => {+ const projected = await timedOut(+ "start",+ "Ghidra startup deadline elapsed",+ );+ expect(projected).toMatchObject({+ code: "provider_timeout",+ details: { timeout_ms: 250 },+ });+ expect(projected.message).toContain(+ "250 ms startup deadline (REA_GHIDRA_STARTUP_TIMEOUT_MS)",+ );+ expect(projected.remediation.action).toContain(+ "REA_GHIDRA_STARTUP_TIMEOUT_MS above 250",+ );+ expect(projected.remediation.action).toContain(+ "REA_GHIDRA_DISABLED_ANALYZERS",+ );+ expect(projected.remediation.action).not.toContain("rea doctor");+ });++ it("keeps generic guidance for a bridge request deadline", async () => {+ const projected = await timedOut(+ "request",+ "Ghidra bridge request timed out",+ );+ expect(projected.code).toBe("provider_timeout");+ expect(projected.message).not.toContain("REA_GHIDRA_STARTUP_TIMEOUT_MS");+ expect(projected.remediation.action).not.toContain(+ "REA_GHIDRA_STARTUP_TIMEOUT_MS",+ );+ });+});+describe("Ghidra analysis seeds and configured language", () => {const seedSession = async (report: (sha256: string) => GhidraSeedReport | undefined,diff --git a/src/ghidra/GhidraProviderClient.ts b/src/ghidra/GhidraProviderClient.tsindex ab7124743..cb47d5ba9 100644--- a/src/ghidra/GhidraProviderClient.ts+++ b/src/ghidra/GhidraProviderClient.ts@@ -94,7 +94,10 @@ import {windowsP0Limitations,limitationsFor,} from "./GhidraProviderCapabilities.js";-import type { GhidraSessionError } from "./GhidraSessionError.js";+import {+ GHIDRA_STARTUP_DEADLINE_ELAPSED,+ type GhidraSessionError,+} from "./GhidraSessionError.js";import type { GhidraSessionInfo } from "./GhidraSessionValues.js";import { ghidraExtensionFailure } from "./extensions/GhidraExtensionFailures.js";import {@@ -1147,12 +1150,16 @@ const projectPrimarySessionError = (context,);if (memoryFailure !== undefined) return memoryFailure;- if (failure.kind === "timeout")+ if (failure.kind === "timeout") {+ const timeoutMs = failure.timeoutMs ?? startupTimeoutMs;return new AnalysisTimeoutError(operation,- failure.timeoutMs ?? startupTimeoutMs,- context,+ timeoutMs,+ failure.message === GHIDRA_STARTUP_DEADLINE_ELAPSED+ ? { ...context, ...ghidraStartupTimeoutGuidance(timeoutMs) }+ : context,);+ }const exited = exitedProviderMessage(operation, failure, health);if (exited !== undefined)return new ProviderAdapterError("ghidra", operation, {@@ -1246,6 +1253,12 @@ const projectObservedJvmMemoryFailure = ();};+/** Name the settings that change Ghidra's import-and-analysis startup deadline. */+const ghidraStartupTimeoutGuidance = (timeoutMs: number) => ({+ userMessage: `Ghidra did not finish importing and analyzing the target within its ${String(timeoutMs)} ms startup deadline (REA_GHIDRA_STARTUP_TIMEOUT_MS).`,+ remediationAction: `Large binaries can need longer: set REA_GHIDRA_STARTUP_TIMEOUT_MS above ${String(timeoutMs)} in the environment that starts REA, or skip expensive analyzers with REA_GHIDRA_DISABLED_ANALYZERS, then open the target again. An MCP client's own tool-call timeout is separate and may also need raising.`,+});+/** A provider already observed as running can be restarted by reopening. */const exitedProviderMessage = (operation: AnalysisOperation,diff --git a/src/ghidra/GhidraSessionError.ts b/src/ghidra/GhidraSessionError.tsindex 4de4807c8..8ab30f171 100644--- a/src/ghidra/GhidraSessionError.ts+++ b/src/ghidra/GhidraSessionError.ts@@ -25,6 +25,10 @@ export type GhidraSessionFailureKind =| "remote"| "analysis_timeout";+/** Message of the failure raised when the provider startup deadline elapses. */+export const GHIDRA_STARTUP_DEADLINE_ELAPSED =+ "Ghidra startup deadline elapsed";+/** Additional structured context for a Ghidra session failure. */export interface GhidraSessionErrorOptions extends ErrorOptions {readonly cancellation?: { readonly reason: unknown };diff --git a/src/ghidra/GhidraSocketConnection.ts b/src/ghidra/GhidraSocketConnection.tsindex 6124fd434..6e39f7e6c 100644--- a/src/ghidra/GhidraSocketConnection.ts+++ b/src/ghidra/GhidraSocketConnection.ts@@ -4,6 +4,7 @@ import { createConnection, type Socket } from "node:net";import { err, ok, type Result } from "../domain/result.js";import type { ProviderStartupDeadline } from "../process/ProviderDeadline.js";import {+ GHIDRA_STARTUP_DEADLINE_ELAPSED,GhidraSessionError,type GhidraSessionFailureFactory,} from "./GhidraSessionError.js";@@ -95,7 +96,7 @@ export const connectGhidraSocket = async (return err(interruptionFailure(options));}return err(- options.failure("timeout", "Ghidra startup deadline elapsed", undefined, {+ options.failure("timeout", GHIDRA_STARTUP_DEADLINE_ELAPSED, undefined, {timeoutMs: options.startupTimeoutMs,}),);@@ -161,7 +162,7 @@ const interruptionFailure = (? options.failure("cancelled", "Ghidra startup was cancelled", cause, {cancellation: { reason: options.deadline.signal.reason },})- : options.failure("timeout", "Ghidra startup deadline elapsed", cause, {+ : options.failure("timeout", GHIDRA_STARTUP_DEADLINE_ELAPSED, cause, {timeoutMs: options.startupTimeoutMs,});return cause?.cleanupFailure === undefined