Skip to content

armgit / rea

Public Imported from GitHub
0

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

fix(android): bound inline search Evidence with retained inventory provenance (#1890)

akushonkamen7a0140b4aa43
diff --git a/src/application/android/AndroidSearchEvidenceSummary.ts b/src/application/android/AndroidSearchEvidenceSummary.ts
new file mode 100644
index 000000000..42c0fb80f
--- /dev/null
+++ b/src/application/android/AndroidSearchEvidenceSummary.ts
@@ -0,0 +1,120 @@
+import type { EvidenceWriter } from "../investigation/InvestigationRecordPort.js";
+import { createEvidence, type Evidence } from "../../domain/evidence.js";
+import type { AnalysisError } from "../../domain/analysisErrorBase.js";
+import type { JsonValue } from "../../domain/jsonValue.js";
+import { ok, type Result } from "../../domain/result.js";
+
+/**
+ * Complete class-inventory pages dominate raw-call provenance for focused
+ * searches: one traversal embeds every examined class name regardless of the
+ * match count. The summary keeps the pagination audit inline (totals, page
+ * offsets and sizes, elided item counts) and links the retained record that
+ * still carries the complete inventory.
+ */
+const elideInventoryText = (text: string): string | undefined => {
+ let page: JsonValue;
+ try {
+ page = JSON.parse(text) as JsonValue;
+ } catch {
+ return undefined;
+ }
+ if (
+ typeof page !== "object" ||
+ page === null ||
+ Array.isArray(page) ||
+ !Array.isArray(page.items)
+ )
+ return undefined;
+ const { items, ...audited } = page;
+ return JSON.stringify({ ...audited, items_omitted: items.length });
+};
+
+/** Replace inventoried page bodies with their pagination audit. */
+const summarizeInventoryCall = (call: JsonValue): JsonValue => {
+ if (
+ typeof call !== "object" ||
+ call === null ||
+ Array.isArray(call) ||
+ call.operation !== "list_classes"
+ )
+ return call;
+ const response = call.response;
+ if (
+ typeof response !== "object" ||
+ response === null ||
+ Array.isArray(response) ||
+ !Array.isArray(response.content)
+ )
+ return call;
+ let elided = false;
+ const content = response.content.map((entry: JsonValue) => {
+ if (
+ typeof entry !== "object" ||
+ entry === null ||
+ Array.isArray(entry) ||
+ typeof entry.text !== "string"
+ )
+ return entry;
+ const summarized = elideInventoryText(entry.text);
+ if (summarized === undefined) return entry;
+ elided = true;
+ return { ...entry, text: summarized };
+ });
+ return elided
+ ? { ...call, inventory_elided: true, response: { ...response, content } }
+ : call;
+};
+
+/**
+ * Retain the complete search Evidence — full raw provider calls included —
+ * in the session record, then deliver a bounded summary Evidence inline.
+ * Callers without a retaining session keep the complete inline delivery, so
+ * complete CLI JSON output is unchanged. Coverage metadata stays truthful in
+ * both copies: the examined inventory is never rewritten to matched-only.
+ */
+export const summarizeRetainedAndroidSearch = (
+ evidence: Evidence,
+ recordEvidence: EvidenceWriter["recordEvidence"] | undefined,
+): Result<Evidence, AnalysisError> => {
+ if (recordEvidence === undefined) return ok(evidence);
+ const recorded = recordEvidence(evidence);
+ if (!recorded.ok) return recorded;
+ const subject = evidence.subject;
+ const raw = evidence.raw_result;
+ const summarized: JsonValue =
+ raw === null ||
+ typeof raw !== "object" ||
+ Array.isArray(raw) ||
+ !Array.isArray(raw.calls)
+ ? raw
+ : {
+ ...raw,
+ complete_evidence_id: evidence.evidence_id,
+ calls: raw.calls.map(summarizeInventoryCall),
+ };
+ return ok(
+ createEvidence(
+ subject === null
+ ? undefined
+ : {
+ path: subject.local_path,
+ sha256: subject.digest.sha256,
+ format: subject.format,
+ ...(subject.architecture === null
+ ? {}
+ : { architecture: subject.architecture }),
+ },
+ evidence.provider,
+ {
+ operation: evidence.operation,
+ parameters: evidence.parameters,
+ result: evidence.normalized_result,
+ rawResult: summarized,
+ confidence: evidence.confidence,
+ limitations: evidence.limitations,
+ locations: evidence.locations,
+ evidenceLinks: [evidence.evidence_id],
+ },
+ ),
+ );
+};
diff --git a/src/server/registerAndroidTools.ts b/src/server/registerAndroidTools.ts
index 887e263dd..722bd6695 100644
--- a/src/server/registerAndroidTools.ts
+++ b/src/server/registerAndroidTools.ts
@@ -1,9 +1,13 @@
import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import { AndroidAnalysisService } from "../application/android/AndroidAnalysisService.js";
+import { summarizeRetainedAndroidSearch } from "../application/android/AndroidSearchEvidenceSummary.js";
import { toolContract } from "../contracts/toolContracts.js";
import type { Logger } from "pino";
-import { createContractToolHandler } from "./contractToolHandler.js";
+import {
+ createContractToolHandler,
+ type ContractToolService,
+} from "./contractToolHandler.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
@@ -22,6 +26,23 @@ export const registerAndroidTools = (
recordEvidence,
withAdmittedAnalysis,
);
+ // Focused class searches keep complete raw inventory in the retained
+ // record and deliver a bounded summary inline; the generic handler then
+ // records and delivers the summary as the search contract's Evidence.
+ const searchService: ContractToolService<"search_android_classes"> = {
+ execute: async (operation, input, options) => {
+ const executed = await service.execute(operation, input, options);
+ if (!executed.ok) return executed;
+ return summarizeRetainedAndroidSearch(executed.value, recordEvidence);
+ },
+ };
+ const searchHandler = createContractToolHandler(
+ server,
+ searchService,
+ logger,
+ recordEvidence,
+ withAdmittedAnalysis,
+ );
const packageContract = toolContract("inspect_android_package");
server.registerTool(
packageContract.name,
@@ -32,7 +53,7 @@ export const registerAndroidTools = (
server.registerTool(
searchContract.name,
toolRegistrationOptions(searchContract),
- handler(searchContract),
+ searchHandler(searchContract),
);
const classContract = toolContract("inspect_android_class");
server.registerTool(
diff --git a/tests/boundary/process/androidSearchEvidenceBudget.test.ts b/tests/boundary/process/androidSearchEvidenceBudget.test.ts
new file mode 100644
index 000000000..143c72189
--- /dev/null
+++ b/tests/boundary/process/androidSearchEvidenceBudget.test.ts
@@ -0,0 +1,131 @@
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
+import { expect, it as test, onTestFinished } from "vitest";
+import { androidResultSchemas } from "../../../src/domain/android/androidAnalysis.js";
+import { parseEvidence } from "../../../src/domain/evidence.js";
+import { createServer } from "../../../src/server/createServer.js";
+import { createTestBinarySession } from "../../fixtures/binarySession.js";
+import {
+ createJadxProtocolFixture,
+ verifyJadxFixtureCleanup,
+} from "../../fixtures/android/jadx.js";
+
+const INVENTORY_CLASS_COUNT = 7096;
+
+/** Count inventoried names across raw call records: MCP pages ride in text content. */
+const rawInventoryNames = (raw: unknown): number => {
+ const calls =
+ (
+ raw as {
+ calls?: {
+ operation: string;
+ response: { content?: { text?: string }[] };
+ }[];
+ }
+ ).calls ?? [];
+ return calls
+ .flatMap((call) => call.response.content ?? [])
+ .map((entry) =>
+ entry.text === undefined ? {} : (JSON.parse(entry.text) as unknown),
+ )
+ .filter((page) => Array.isArray((page as { items?: unknown[] }).items))
+ .flatMap((page) => (page as { items: unknown[] }).items).length;
+};
+
+test("delivers bounded search_android_classes Evidence while retaining the complete inventory", async () => {
+ const { provider, apk, launches } = await createJadxProtocolFixture(
+ "normal",
+ undefined,
+ { classCount: INVENTORY_CLASS_COUNT - 1 },
+ );
+ const session = createTestBinarySession(() => {
+ throw new Error("APK analysis must not acquire a deep binary provider");
+ });
+ const server = createServer(
+ { kind: "session", session },
+ { androidAnalysis: provider },
+ );
+ const client = new Client({
+ name: "android-search-inventory-budget",
+ version: "1",
+ });
+ onTestFinished(async () => {
+ await client.close();
+ await server.close();
+ await session.close();
+ });
+ const [clientTransport, serverTransport] =
+ InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ await client.connect(clientTransport);
+
+ const search = async (query: string) =>
+ parseEvidence(
+ (
+ await client.callTool({
+ name: "search_android_classes",
+ arguments: { path: apk, query },
+ })
+ ).structuredContent,
+ );
+
+ const single = await search("Target");
+ expect(
+ androidResultSchemas.search_android_classes.parse(single.normalized_result),
+ ).toMatchObject({
+ query: "Target",
+ total_classes: INVENTORY_CLASS_COUNT,
+ matches: ["fixture.Target"],
+ coverage: "complete",
+ });
+ // The inline raw record keeps the pagination audit, not the class names.
+ const singleRaw = JSON.stringify(single.raw_result);
+ expect(singleRaw).not.toContain("fixture.Class");
+ expect(singleRaw).toContain("items_omitted");
+ expect(Buffer.byteLength(JSON.stringify(single))).toBeLessThan(32 * 1024);
+ // The complete inventory stays locally retrievable through the retained record.
+ const completeId = single.evidence_links[0];
+ expect(completeId).toBeDefined();
+ expect(completeId).toBe(
+ (single.raw_result as { complete_evidence_id: string })
+ .complete_evidence_id,
+ );
+ const complete = session.evidenceById(completeId as string);
+ expect(complete).toBeDefined();
+ expect(complete?.operation).toBe("search_android_classes");
+ expect(rawInventoryNames(complete?.raw_result)).toBe(INVENTORY_CLASS_COUNT);
+ expect(JSON.stringify(complete?.raw_result)).toContain("fixture.Class7094");
+
+ const empty = await search("fixture.Missing");
+ expect(
+ androidResultSchemas.search_android_classes.parse(empty.normalized_result),
+ ).toMatchObject({
+ query: "fixture.Missing",
+ total_classes: INVENTORY_CLASS_COUNT,
+ matches: [],
+ coverage: "complete",
+ });
+ expect(JSON.stringify(empty.raw_result)).not.toContain("fixture.Class");
+
+ await client.close();
+ await server.close();
+ await verifyJadxFixtureCleanup(launches);
+});
+
+test("keeps the complete search inventory inline without a retaining session", async () => {
+ const { service, apk, launches, provider } = await createJadxProtocolFixture(
+ "normal",
+ undefined,
+ { classCount: INVENTORY_CLASS_COUNT - 1 },
+ );
+ const result = await service.execute("search_android_classes", {
+ path: apk,
+ query: "Target",
+ });
+ if (!result.ok) throw result.error;
+ // Complete CLI JSON output keeps the full raw provider inventory.
+ expect(rawInventoryNames(result.value.raw_result)).toBe(
+ INVENTORY_CLASS_COUNT,
+ );
+ await provider.close();
+ await verifyJadxFixtureCleanup(launches);
+});
diff --git a/tests/fixtures/android/jadx-mcp.mjs b/tests/fixtures/android/jadx-mcp.mjs
index e95029d53..4c008a7f4 100644
--- a/tests/fixtures/android/jadx-mcp.mjs
+++ b/tests/fixtures/android/jadx-mcp.mjs
@@ -10,10 +10,20 @@ const server = new McpServer({
version:
mode === "empty-server-identity" ? "" : mode === "version" ? "99.0.0" : "1",
});
+const requestedCount = Number.parseInt(
+ process.env.REA_FAKE_JADX_CLASS_COUNT ?? "",
+ 10,
+);
+const generatedCount =
+ Number.isInteger(requestedCount) && requestedCount >= 0
+ ? requestedCount
+ : mode === "large-inventory"
+ ? 9000
+ : 400;
const classes = [
"fixture.Target",
...Array.from(
- { length: mode === "large-inventory" ? 9000 : 400 },
+ { length: generatedCount },
(_, index) => `fixture.Class${index}`,
),
];
diff --git a/tests/fixtures/android/jadx.ts b/tests/fixtures/android/jadx.ts
index 49e17c2d5..373f3a624 100644
--- a/tests/fixtures/android/jadx.ts
+++ b/tests/fixtures/android/jadx.ts
@@ -27,6 +27,7 @@ const fixture = fileURLToPath(new URL("./jadx-mcp.mjs", import.meta.url));
export const createJadxProtocolFixture = async (
mode = "normal",
cleanupFailure?: () => boolean,
+ inventory?: { readonly classCount?: number },
) => {
const root = await createTestTempDirectory("rea-android-boundary-");
const apk = join(root, "fixture.apk");
@@ -64,7 +65,15 @@ export const createJadxProtocolFixture = async (
command: process.execPath,
arguments: [fixture],
expectedCommand: process.execPath,
- env: { ...options.env, REA_FAKE_JADX_MODE: mode },
+ env: {
+ ...options.env,
+ REA_FAKE_JADX_MODE: mode,
+ ...(inventory?.classCount === undefined
+ ? {}
+ : {
+ REA_FAKE_JADX_CLASS_COUNT: String(inventory.classCount),
+ }),
+ },
});
launches.push({
runId: options.runId,