Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(ghidra): name the startup deadline setting when startup times out (#4590)

Syed Rishad1b56237caec2
diff --git a/docs/installation.md b/docs/installation.md
index 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,647
milliseconds 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 and
passes 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 transport
diff --git a/src/domain/analysisErrorCore.ts b/src/domain/analysisErrorCore.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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