Skip to content

armgit / rea

Public Imported from GitHub
0

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

fix(kuna): report output beyond REA's buffer as deterministic and final (#4098)

Kaoru0822b3b5c8b1334c
diff --git a/docs/kuna-provider.md b/docs/kuna-provider.md
index 1fe675432..4e71941cd 100644
--- a/docs/kuna-provider.md
+++ b/docs/kuna-provider.md
@@ -66,7 +66,7 @@ The first call query runs `kuna decompile-graph --functions ''`, admitting no C
`xrefs` runs native `xrefs --to ADDRESS --json` on demand. Kuna unifies forwarding aliases and suppresses edges internal to their class; REA filters to the requested address and records the excluded-row count. Duplicate source sites appear once. An empty result cannot establish the absence of references. Addresses are explicit u64 values or exact, unambiguous procedure names; Kuna has no cursor.
-Graph JSON admits at most 32 MiB before parsing; xref JSON at most 16 MiB. The graph is cached for the selected target and executable profile within one session. Xref reuse is an LRU charged by source bytes plus metadata, limited to 16 MiB and 128 entries; at most eight distinct native xref queries may be pending. Reference commands run one at a time per session and share the provider's foreground budget with single-function decompiles. An unproven process stop retains its admission slots until cleanup succeeds. Concurrent callers share work, individual cancellation releases only that waiter, and the last departing waiter cancels its producer and receives any unproven cleanup. Session close aborts and drains producers, releases parsed caches and retries any retained process/file cleanup.
+Graph JSON admits at most 32 MiB before parsing; xref JSON at most 16 MiB. A large image can exceed the graph budget: an arm64 Firefox `XUL` (404k functions) does, while a 14 MB Sublime Text binary produced 31.8 MB. Output beyond a buffer is reported as a `memory` resource constraint with `retryable: false`, because the same target and executable produce the same output. The session remembers a graph that overflowed, so later call queries fail at once instead of repeating the whole-program walk. The graph is cached for the selected target and executable profile within one session. Xref reuse is an LRU charged by source bytes plus metadata, limited to 16 MiB and 128 entries; at most eight distinct native xref queries may be pending. Reference commands run one at a time per session and share the provider's foreground budget with single-function decompiles. An unproven process stop retains its admission slots until cleanup succeeds. Concurrent callers share work, individual cancellation releases only that waiter, and the last departing waiter cancels its producer and receives any unproven cleanup. Session close aborts and drains producers, releases parsed caches and retries any retained process/file cleanup.
Evidence includes only selected addresses or dossier neighbors, the producing JSON's SHA-256/byte count, coverage and relevant function facts; unrequested program-wide JSON and instruction text are omitted. Reference caches are in memory and expire on close: a fresh CLI process or MCP server rebuilds them. A first call query therefore costs a whole-program reference walk even when a C export is warm. These operations do not establish full Ghidra/IDA feature parity.
diff --git a/src/kuna/KunaCommand.ts b/src/kuna/KunaCommand.ts
index c8e4b7e76..669a6709e 100644
--- a/src/kuna/KunaCommand.ts
+++ b/src/kuna/KunaCommand.ts
@@ -206,8 +206,13 @@ const commandFailure = (
snapshot === null
? undefined
: {
- // Output can be evidence-sized, not diagnostic-sized; keep only its tail.
- stdout: snapshot.stdout.text.slice(-4096),
+ // Output can be evidence-sized, not diagnostic-sized; keep only its
+ // tail. Output that overflowed its buffer is a cut-off document
+ // whose tail explains nothing, so none of it is kept.
+ stdout:
+ cause.reason === "output-limit"
+ ? ""
+ : snapshot.stdout.text.slice(-4096),
stderr: snapshot.stderr.text,
truncated:
snapshot.diagnosticTruncated === true ||
@@ -245,15 +250,20 @@ const commandFailure = (
details,
),
};
+ // The same target and executable always produce the same output, so a
+ // fixed buffer it overflows is a memory bound, not a busy admission queue.
if (cause.reason === "output-limit")
return {
kind: "failed",
error: new AnalysisResourceConstraintError(
operation,
- "capacity",
+ "memory",
`kuna ${subcommand} wrote more than ${String(request.outputBytes)} bytes of output.`,
{ output_limit_bytes: request.outputBytes },
- details,
+ {
+ ...details,
+ remediationAction: `REA buffers at most ${String(request.outputBytes)} bytes of kuna ${subcommand} output, so repeating this request for this target fails the same way. Use another provider for it.`,
+ },
),
};
const exitCode = capturedOutput?.exit_code;
diff --git a/src/kuna/KunaReferenceQueries.ts b/src/kuna/KunaReferenceQueries.ts
index aa3a93a92..01c694145 100644
--- a/src/kuna/KunaReferenceQueries.ts
+++ b/src/kuna/KunaReferenceQueries.ts
@@ -52,6 +52,12 @@ export interface KunaFunctionRelationships {
/** Lazy session facts, shared producers and bounded exact-address xref reuse. */
export class KunaReferenceQueries {
#graph: KunaCallGraph | undefined;
+ /**
+ * A graph that overflowed REA's fixed output buffer. The same target and
+ * executable produce the same graph, so later queries report this failure
+ * instead of repeating the whole-program walk.
+ */
+ #graphFailure: AnalysisError | undefined;
#pendingGraph: Pending<KunaCallGraph> | undefined;
readonly #xrefs = new Map<string, KunaIncomingReferences>();
readonly #pendingXrefs = new Map<string, Pending<KunaIncomingReferences>>();
@@ -109,6 +115,7 @@ export class KunaReferenceQueries {
operation: string,
signal: AbortSignal | undefined,
): Promise<Result<KunaCallGraph, AnalysisError>> {
+ if (this.#graphFailure !== undefined) return err(this.#graphFailure);
if (this.#graph === undefined) {
if (this.#pendingGraph?.controller.signal.aborted === true) {
const retired = await this.#wait(this.#pendingGraph, signal, operation);
@@ -134,7 +141,14 @@ export class KunaReferenceQueries {
outputBytes: KUNA_GRAPH_OUTPUT_BYTES,
signal: producerSignal,
});
- if (!run.ok) return run;
+ if (!run.ok) {
+ if (
+ run.error instanceof AnalysisResourceConstraintError &&
+ run.error.resource === "memory"
+ )
+ this.#graphFailure = run.error;
+ return run;
+ }
return this.#parsed(
parseKunaCallGraph(run.value.stdout.text, run.value.input),
"call graph",
@@ -308,6 +322,7 @@ export class KunaReferenceQueries {
/** Release parsed facts after the session has drained all owned producers. */
clear(): void {
this.#graph = undefined;
+ this.#graphFailure = undefined;
this.#pendingGraph = undefined;
this.#xrefs.clear();
this.#pendingXrefs.clear();
diff --git a/tests/boundary/providers/kuna/fakeKuna.ts b/tests/boundary/providers/kuna/fakeKuna.ts
index 4036f6cc0..6a5caee19 100644
--- a/tests/boundary/providers/kuna/fakeKuna.ts
+++ b/tests/boundary/providers/kuna/fakeKuna.ts
@@ -36,7 +36,14 @@ export interface FakeKunaBehavior {
readonly inventoryDelayMs?: number;
/** Milliseconds the export takes before writing its files. */
readonly delayMs?: number;
- readonly graph?: "ok" | "hang" | "not-json" | "miscounted" | "with-bodies";
+ /** `oversized` writes more graph output than REA buffers (32 MiB). */
+ readonly graph?:
+ | "ok"
+ | "hang"
+ | "not-json"
+ | "miscounted"
+ | "with-bodies"
+ | "oversized";
readonly graphIndirectCalls?: boolean;
readonly xrefs?: "ok" | "hang" | "not-json";
readonly referenceDelayMs?: number;
@@ -73,6 +80,7 @@ if (args[0] === "--version") {
} else if (args[0] === "decompile-graph") {
if (behavior.graph === "hang") hang();
else if (behavior.graph === "not-json") process.stdout.write("not graph JSON");
+ else if (behavior.graph === "oversized") process.stdout.write(Buffer.alloc(33 * 1024 * 1024, 0x20));
else {
if (args[args.indexOf("--functions") + 1] !== "") throw new Error("graph must request no bodies");
const nodes = [...functions, { name: "puts", addr: "0x2000" }].map((fn) => ({ address: parseInt(fn.addr, 16), name: fn.name, kind: "normal", hasIndirectCalls: behavior.graphIndirectCalls !== false && fn === functions[0], forwardsTo: null, codeC: behavior.graph === "with-bodies" ? "unrequested code" : null, assembly: null, error: null }));
diff --git a/tests/boundary/providers/kuna/kunaCommandFailures.test.ts b/tests/boundary/providers/kuna/kunaCommandFailures.test.ts
new file mode 100644
index 000000000..30aec2b7a
--- /dev/null
+++ b/tests/boundary/providers/kuna/kunaCommandFailures.test.ts
@@ -0,0 +1,82 @@
+import { expect, it as test } from "vitest";
+
+import { projectAnalysisError } from "../../../../src/domain/analysisErrorProjection.js";
+import { inspectKunaInstallation } from "../../../../src/kuna/KunaInstallation.js";
+import { KunaTargetCommands } from "../../../../src/kuna/KunaTargetCommands.js";
+import { fakeKunaCalls } from "./fakeKuna.js";
+import { session } from "./kunaSessionFixture.js";
+
+const it = test.skipIf(process.platform === "win32");
+
+it("reports output beyond REA's fixed buffer as a deterministic memory bound", async () => {
+ const { kuna, target, cacheRoot } = await session("rea-kuna-output-limit-");
+ const installed = await inspectKunaInstallation({
+ REA_KUNA_COMMAND: kuna,
+ REA_KUNA_CACHE_DIR: cacheRoot,
+ });
+ if (!installed.ok) throw new Error(installed.error.reason);
+ const controller = new AbortController();
+ const commands = new KunaTargetCommands(target, {
+ signal: controller.signal,
+ });
+ try {
+ // The fake's inventory is a few hundred bytes; admit fewer.
+ const result = await commands.run({
+ installation: installed.value,
+ operation: "list_procedures",
+ arguments: (input) => ["functions", input, "--json"],
+ timeoutMs: 10_000,
+ outputBytes: 100,
+ signal: controller.signal,
+ });
+ if (result.ok) throw new Error("the oversized inventory was admitted");
+ expect(result.error).toMatchObject({
+ _tag: "AnalysisResourceConstraintError",
+ resource: "memory",
+ reportedLimits: { output_limit_bytes: 100 },
+ // A cut-off document's tail explains nothing; it is not returned.
+ capturedOutput: { stdout: "", truncated: true },
+ });
+ // The same target and executable overflow the same buffer again, so the
+ // caller is not told to wait and retry.
+ expect(projectAnalysisError(result.error)).toMatchObject({
+ code: "resource_constraint",
+ retryable: false,
+ remediation: {
+ action:
+ "REA buffers at most 100 bytes of kuna functions output, so repeating this request for this target fails the same way. Use another provider for it.",
+ },
+ });
+ } finally {
+ controller.abort();
+ expect(await commands.close()).toEqual({ ok: true, value: null });
+ }
+});
+
+it("reports a graph beyond REA's buffer once per session instead of rebuilding it", async () => {
+ const { kuna, open } = await session("rea-kuna-graph-overflow-", {
+ graph: "oversized",
+ });
+ const client = open();
+ try {
+ for (let attempt = 0; attempt < 2; attempt += 1) {
+ const result = await client.execute("procedure_callers", {
+ procedure: "0x1000",
+ });
+ if (result.ok) throw new Error("the oversized graph was admitted");
+ expect(result.error).toMatchObject({
+ _tag: "AnalysisResourceConstraintError",
+ resource: "memory",
+ });
+ expect(projectAnalysisError(result.error).retryable).toBe(false);
+ }
+ // The second query reused the failure instead of walking the program again.
+ expect(
+ (await fakeKunaCalls(kuna)).filter(
+ ({ argv }) => argv[0] === "decompile-graph",
+ ),
+ ).toHaveLength(1);
+ } finally {
+ expect(await client.close()).toEqual({ ok: true, value: null });
+ }
+});