diff --git a/docs/guides/android/android-analysis.md b/docs/guides/android/android-analysis.md index 24cbf28e3d..8f928fe32f 100644 --- a/docs/guides/android/android-analysis.md +++ b/docs/guides/android/android-analysis.md @@ -665,9 +665,13 @@ uses native memory. A typed JVM memory allocation failure during APK loading reports `resource_constraint` with the observed maximum heap in bytes. Known heap failures name `REA_JADX_HEAP_MIB` in remediation; other memory regions remain unknown. A healthy doctor configuration check does not establish that -any particular APK fits. Failures before the bridge can report a typed result -and upstream errors from other operations retain their existing diagnostics; -error text alone does not establish memory exhaustion. +any particular APK fits. If the launcher stops before the bridge answers and +its retained stderr carries HotSpot's `java.lang.OutOfMemoryError: Java heap +space` or `GC overhead limit exceeded`, REA reports `resource_constraint` with +`observed_max_heap_bytes: null`, since no runtime fact measured the heap, and +the same `REA_JADX_HEAP_MIB` remediation. Other failures before the bridge can +report a typed result and upstream errors from other operations retain their +existing diagnostics; error text alone does not establish memory exhaustion. Independent REA instances have independent queues. Whole operations have a **120-second** execution deadline by default, starting after diff --git a/docs/user-visible-errors.csv b/docs/user-visible-errors.csv index e6f90dc47c..2583d15152 100644 --- a/docs/user-visible-errors.csv +++ b/docs/user-visible-errors.csv @@ -124,3 +124,4 @@ Then rerun this installer.",implemented,verified by shell branch inspection 91,src/application/binaryDiagnostics/ByteEntropyService.ts (issues); src/domain/analysisErrorPresentation.ts (recovery),Invalid file or window,Expected a regular file.; Selected file could not be found.; Selected byte window starts beyond the end of the file.; Selected byte window extends beyond the end of the file.; File size exceeds exact numeric offset representation.,Invalid selection cannot produce complete entropy Evidence,"Read the declared input schema or CLI usage for inspect_byte_entropy; if using MCP and the catalog may be stale, call tools/list. Correct the listed fields, then retry. Do not repeat the unchanged call.",unchanged,Executed CLI/stdio MCP: path/offset/length refusals and tiny + system-binary controls; shared canonical recovery; service/MCP tests check classification and fields; remaining listed errors source-inspected 92,src/domain/analysisView/byteEntropyView.ts,Non-summary entropy view,Byte entropy Evidence supports the summary view; retrieve parent Evidence for the complete block series.,Unsupported view selection,Use the summary view or retrieve complete parent Evidence,implemented,typed input rejection 93,src/windows/WindowsNativeLoader.ts:load refused,Windows refuses to load the digest-verified native addon (for example Smart App Control or App Control policy),"REA Windows native controls are unavailable: Windows refused to load the verified native/windows/build/rea-windows-x64.node: {OS error} The file matched the package manifest, so restoring or reinstalling it will not help. ...",Previous artifact copy told users to restore or rebuild files that were already intact,"Name the OS refusal, say restoring cannot help, state that Ghidra and JADX need native controls while setup can still register clients, and point to a policy-allowed host or a maintainer-signed build",implemented,simulated loader refusal unit test; real Smart App Control block not reproduced +94,src/android/JadxFailure.ts:startup failure,"JADX worker heap too small for REA's bridge, so the JVM stops before the protocol handshake","Java could not start REA's Android bridge using : Connection closed. Review the retained launcher diagnostics. Review the selected Java/JADX configuration; for a JVM memory limit, review REA_JADX_HEAP_MIB and inherited JVM options such as JAVA_TOOL_OPTIONS.","Buried: reported as capability_unavailable, so a caller cannot tell a heap limit from a missing JDK","The JADX worker JVM ran out of heap before REA's Android bridge answered. Increase REA_JADX_HEAP_MIB (MiB) in the environment that starts REA, within the host or container memory budget. REA passes it as an explicit -Xmx, so JAVA_TOOL_OPTIONS and JDK_JAVA_OPTIONS set the heap only while it is unset, and _JAVA_OPTIONS overrides it. An observed heap is this run's limit, not the heap the APK requires.",implemented,child-process MCP fixture (start-heap-exhausted) integration test and stderr classification test diff --git a/src/android/JadxFailure.ts b/src/android/JadxFailure.ts index 8d92379ab4..7eaf117afe 100644 --- a/src/android/JadxFailure.ts +++ b/src/android/JadxFailure.ts @@ -6,6 +6,7 @@ import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisOutputError, + AnalysisResourceConstraintError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js"; import { ProviderAdapterError } from "../domain/providerAdapterError.js"; @@ -24,6 +25,8 @@ import { import { androidSnapshotCopy } from "./AndroidTargetSnapshot.js"; import type { JadxSession } from "./JadxSession.js"; import type { JadxMcpTransport } from "./JadxMcpTransport.js"; +import { jadxHeapExhausted } from "./JadxProtocol.js"; +import { JADX_HEAP_REMEDIATION } from "./JadxRelease.js"; interface FailureContext { readonly cause: unknown; @@ -326,6 +329,21 @@ const presentDiagnosticFailure = ( if (failure.kind === "output") return new AnalysisOutputError(failure.operation, failure.reason, options); if (failure.kind === "startup") { + // Before the handshake the retained stderr is the only evidence of why the + // launcher stopped; a heap shortage there is a resource limit, not setup. + if (jadxHeapExhausted(output?.stderr ?? "")) + return new AnalysisResourceConstraintError( + failure.operation, + "memory", + "The JADX worker JVM ran out of heap before REA's Android bridge answered", + // The bridge never reported its heap, so the limit stays unknown. + { observed_max_heap_bytes: null }, + { + ...options, + retryable: false, + remediationAction: JADX_HEAP_REMEDIATION, + }, + ); const reason = `Java could not start REA's Android bridge using ${failure.command}: ${failure.cause instanceof Error ? failure.cause.message : String(failure.cause)}. ${output === undefined || output.stderr.length === 0 ? "No launcher stderr was observed." : "Review the retained launcher diagnostics."}${output?.truncated === true ? " Diagnostics are incomplete." : ""} Review the selected Java/JADX configuration; for a JVM memory limit, review REA_JADX_HEAP_MIB and inherited JVM options such as JAVA_TOOL_OPTIONS.`; return new AnalysisCapabilityUnavailableError( "jadx", diff --git a/src/android/JadxProtocol.ts b/src/android/JadxProtocol.ts index 66bfbd39ed..11be5f2004 100644 --- a/src/android/JadxProtocol.ts +++ b/src/android/JadxProtocol.ts @@ -36,6 +36,19 @@ const bridgeFailureSchema = z.discriminatedUnion("kind", [ jadxReferenceLimitSchema, ]); +/** + * HotSpot's heap-exhaustion `OutOfMemoryError` reasons. Before the bridge + * answers there is no named failure, so a launcher's retained stderr is the + * only evidence. Other reasons (metaspace, direct buffers, native threads) are + * not remedied by the worker heap setting. + */ +const JADX_HEAP_EXHAUSTION = + /java\.lang\.OutOfMemoryError: (?:Java heap space|GC overhead limit exceeded)/u; + +/** Whether a launcher's retained stderr reports JVM heap exhaustion. */ +export const jadxHeapExhausted = (text: string): boolean => + JADX_HEAP_EXHAUSTION.test(text); + /** Arbitrary upstream failure text stays text unless it matches a named bridge contract. */ export const parseJadxFailure = ( text: string, diff --git a/src/android/JadxRelease.ts b/src/android/JadxRelease.ts index 4123d6f1ae..ba9e1f84cf 100644 --- a/src/android/JadxRelease.ts +++ b/src/android/JadxRelease.ts @@ -24,6 +24,15 @@ export const JADX_JAVA_RUNTIME_REMEDIATION = export const JADX_JVM_OPTIONS_REMEDIATION = "Set REA_JADX_HEAP_MIB to a positive integer (heap size in MiB) and REA_JADX_ACTIVE_PROCESSOR_COUNT to a positive integer within the JVM's signed 32-bit range."; +/** + * Remediation for a JADX worker heap shortage, whether the bridge reported it or + * the launcher stopped before answering. REA passes REA_JADX_HEAP_MIB as an + * explicit command-line -Xmx, which outranks JAVA_TOOL_OPTIONS and + * JDK_JAVA_OPTIONS, while _JAVA_OPTIONS outranks the command line. + */ +export const JADX_HEAP_REMEDIATION = + "Increase REA_JADX_HEAP_MIB (MiB) in the environment that starts REA, within the host or container memory budget. REA passes it as an explicit -Xmx, so JAVA_TOOL_OPTIONS and JDK_JAVA_OPTIONS set the heap only while it is unset, and _JAVA_OPTIONS overrides it. An observed heap is this run's limit, not the heap the APK requires."; + /** Remediation when the host cannot run the Android JADX subprocess. */ export const JADX_UNSUPPORTED_HOST_REMEDIATION = "Use Linux, macOS, or Windows x64 with its bundled native controls for Android JADX analysis."; diff --git a/src/android/JadxSession.ts b/src/android/JadxSession.ts index 915d033f52..08c1e94ac1 100644 --- a/src/android/JadxSession.ts +++ b/src/android/JadxSession.ts @@ -48,6 +48,7 @@ import { JADX_RELEASE, JADX_PROVIDER_IDENTITY, JADX_LIMITATIONS, + JADX_HEAP_REMEDIATION, } from "./JadxRelease.js"; type JadxCall = { @@ -406,7 +407,7 @@ export class JadxSession { retryable: false, remediationAction: failure.memory_area === "heap" - ? "Increase REA_JADX_HEAP_MIB (MiB) in the environment that starts REA, within the host or container memory budget. Review JAVA_TOOL_OPTIONS and other JVM heap overrides. The observed heap is this run's limit, not the heap the APK requires." + ? JADX_HEAP_REMEDIATION : "Review the JVM allocation failure and the host or container memory limits. The observed maximum heap does not establish which memory region was exhausted; increasing heap alone may not help.", diagnostics: { upstream_operation: name, diff --git a/tests/boundary/android/jadxProtocol.test.ts b/tests/boundary/android/jadxProtocol.test.ts index a750c57794..d9b841508e 100644 --- a/tests/boundary/android/jadxProtocol.test.ts +++ b/tests/boundary/android/jadxProtocol.test.ts @@ -5,9 +5,28 @@ import { parseJadxJson, normalizeJadxText, parseJadxFailure, + jadxHeapExhausted, } from "../../../src/android/JadxProtocol.js"; import { androidInputSchemas } from "../../../src/domain/android/androidAnalysis.js"; +it("recognizes only HotSpot heap-exhaustion OutOfMemoryError reasons", () => { + for (const text of [ + 'Exception in thread "main" java.lang.OutOfMemoryError: Java heap space', + "java.lang.OutOfMemoryError: GC overhead limit exceeded", + ]) + expect(jadxHeapExhausted(text), text).toBe(true); + // Other memory areas are not fixed by the worker heap, and unanchored text + // that merely mentions the heap is not a JVM failure. + for (const text of [ + "java.lang.OutOfMemoryError: Metaspace", + "java.lang.OutOfMemoryError: Direct buffer memory", + "java.lang.OutOfMemoryError: unable to create new native thread", + "warning: Java heap space is low", + "", + ]) + expect(jadxHeapExhausted(text), text).toBe(false); +}); + it("recognizes named bridge failures without reinterpreting arbitrary engine text", () => { const failure = { kind: "jvm-memory-failure", diff --git a/tests/boundary/process/jadxIntegration.test.ts b/tests/boundary/process/jadxIntegration.test.ts index 1f85546c6a..b972bb3e05 100644 --- a/tests/boundary/process/jadxIntegration.test.ts +++ b/tests/boundary/process/jadxIntegration.test.ts @@ -1424,3 +1424,30 @@ it("retains parsed native body absence without claiming an empty implementation" await provider.close(); await verifyCleanup(launches); }); + +it("classifies a heap shortage that stops the bridge before the handshake", async () => { + const { service, apk, launches, provider } = await setup( + "start-heap-exhausted", + ); + const outcome = await service.execute("inspect_android_package", { + path: apk, + }); + if (outcome.ok) throw new Error("Expected a heap-exhaustion failure"); + const projected = projectAnalysisError(outcome.error); + expect(projected).toMatchObject({ + code: "resource_constraint", + retryable: false, + remediation: { action: expect.stringContaining("REA_JADX_HEAP_MIB") }, + details: { + operation: "inspect_android_package", + resource: "memory", + // The bridge never answered, so nothing measured this run's heap. + reported_limits: { observed_max_heap_bytes: null }, + captured_output: { + stderr: expect.stringContaining("OutOfMemoryError: Java heap space"), + }, + }, + }); + await provider.close(); + await verifyCleanup(launches); +}); diff --git a/tests/fixtures/android/jadx-mcp.mjs b/tests/fixtures/android/jadx-mcp.mjs index 97c73740ab..b6c2831951 100644 --- a/tests/fixtures/android/jadx-mcp.mjs +++ b/tests/fixtures/android/jadx-mcp.mjs @@ -6,6 +6,14 @@ import { JADX_BRIDGE_IDENTITY } from "../../../src/android/JadxRelease.ts"; // An actual child MCP server exercising the production stdio/process seam. // It is a protocol fixture, not evidence of JADX decompiler support. const mode = process.env.REA_FAKE_JADX_MODE ?? "normal"; +// A worker heap too small for the bridge stops the JVM before the handshake, +// so the retained stderr is the only heap evidence. +if (mode === "start-heap-exhausted") { + process.stderr.write( + 'Exception in thread "main" java.lang.OutOfMemoryError: Java heap space\n', + ); + process.exit(1); +} const server = new McpServer({ name: mode === "empty-server-identity" ? "" : "rea-jadx-bridge", version: