From 18b72ca4610d8ee1d9c75205bf0f78b07858704c Mon Sep 17 00:00:00 2001 From: gensokyo-dev Date: Sat, 14 Nov 2026 12:23:22 +0000 Subject: [PATCH] fix(android): qualify the JNI library inventory by required splits A base APK whose manifest requires ABI or density splits keeps its native libraries in those splits, yet inspect_android_jni_bindings reported a complete library inventory with zero libraries. The bridge's native declaration inventory now also decodes the root binary manifest without a session and reports its requiredSplitTypes and isSplitRequired facts, or why they are unknown (bridge identity 11). When splits are required or unknown, the library inventory is partial with an unknown that says so, and a binding without a candidate is unknown instead of unmatched. The binary manifest fixture from #9769 was used to check the bridge with the real jadx-headless-mcp 0.7.1 JAR, including stripped attribute names that resolve through framework resource IDs. Fixes #9756 Co-Authored-By: 2SinceJuly <202121119+2SinceJuly@users.noreply.github.com> Co-Authored-By: Phon Co-Authored-By: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com> --- bridge/android/ReaJadxBridge.java | 80 ++++++++++++++++--- docs/guides/android/android-analysis.md | 8 ++ src/android/AndroidNativeInventory.test.ts | 27 +++++++ src/android/JadxRelease.ts | 2 +- src/domain/android/androidJniBindings.test.ts | 77 +++++++++++++++++- src/domain/android/androidJniBindings.ts | 32 +++++++- .../android/androidNativeDeclarations.ts | 9 +++ .../android/androidJniLibrary.test.ts | 5 ++ .../mcp/androidPackageSummaryMcp.test.ts | 5 ++ .../android/ReaJadxMetadataRegression.java | 15 ++++ tests/fixtures/android/jadx-mcp.mjs | 5 ++ 11 files changed, 252 insertions(+), 13 deletions(-) diff --git a/bridge/android/ReaJadxBridge.java b/bridge/android/ReaJadxBridge.java index 0678d111c1..5b09d967e8 100644 --- a/bridge/android/ReaJadxBridge.java +++ b/bridge/android/ReaJadxBridge.java @@ -203,6 +203,7 @@ class ReaJadxBridge { // One bounded DEX at a time, beside the already admitted analysis JVM. The // response allowance accounts for worst-case JSON escaping before retention. private static final int NATIVE_DEX_BYTES = 64 * 1024 * 1024; + private static final int NATIVE_MANIFEST_BYTES = 8 * 1024 * 1024; private static final long NATIVE_TOTAL_DEX_BYTES = 256L * 1024 * 1024; // This JSON is escaped again inside an 8 MiB MCP frame. private static final long NATIVE_JSON_BYTES = 4L * 1024 * 1024; @@ -248,6 +249,8 @@ class ReaJadxBridge { int examinedMethods; boolean partial; boolean diagnosticLimit; + Map manifestSplits = + Map.of("status", "unknown", "reason", "Root AndroidManifest.xml was not examined"); void unknown(String reason) { partial = true; @@ -276,19 +279,67 @@ class ReaJadxBridge { "coverage", Map.of("status", partial ? "partial" : "complete", "dex_entries", dexEntries, "examined_dex_entries", examinedDexEntries, "examined_classes", examinedClasses, "examined_methods", examinedMethods), - "unknowns", List.copyOf(unknowns)); + "unknowns", List.copyOf(unknowns), "manifest_splits", manifestSplits); } } + /** + * Whether the root manifest requires split APKs, which can carry native + * libraries outside this APK. Decoded without a loaded session: the binary + * XML parser resolves framework attribute names through their resource IDs. + */ + static Map manifestSplitRequirements(ZipFile archive, int manifests) { + if (manifests != 1) + return Map.of("status", "unknown", "reason", manifests == 0 + ? "Root AndroidManifest.xml is absent" + : "Root AndroidManifest.xml entry name is ambiguous"); + try { + byte[] bytes = readNativeMember(archive, archive.getEntry("AndroidManifest.xml"), + "AndroidManifest.xml", NATIVE_MANIFEST_BYTES, "8 MiB"); + return manifestSplitFacts(new BinaryXMLParser(new RootNode(new JadxArgs())) + .parse(new java.io.ByteArrayInputStream(bytes)).getCodeStr()); + } catch (IOException | RuntimeException failure) { + if (failure instanceof java.util.concurrent.CancellationException) throw (RuntimeException) failure; + return Map.of("status", "unknown", "reason", + "Root AndroidManifest.xml split requirements could not be read: " + + failure.getClass().getSimpleName() + + (failure.getMessage() == null ? "" : " (" + failure.getMessage() + ")")); + } + } + + /** Split requirements declared by decoded manifest text. */ + static Map manifestSplitFacts(String xml) { + Element root = manifestRoot(xml); + String android = "http://schemas.android.com/apk/res/android"; + List types = new ArrayList<>(); + for (String type : root.getAttributeNS(android, "requiredSplitTypes").split(",")) { + if (!type.isBlank()) types.add(type.strip()); + } + boolean required = false; + for (Node child = root.getFirstChild(); child != null; child = child.getNextSibling()) { + if (child instanceof Element element && element.getNamespaceURI() == null + && element.getTagName().equals("application")) + required |= element.getAttributeNS(android, "isSplitRequired").equals("true"); + } + return Map.of("status", "observed", "required_split_types", List.copyOf(types), + "split_required", required); + } + /** Match Android's standard root multidex carriers, without a basename guess. */ private static boolean nativeDexEntry(String name) { return name.equals("classes.dex") || name.matches("classes[0-9]+\\.dex"); } private static byte[] readNativeDex(ZipFile archive, ZipEntry entry) throws IOException { + return readNativeMember(archive, entry, "DEX", NATIVE_DEX_BYTES, "64 MiB"); + } + + /** Read one stored or deflated root member exactly, checked against its CRC32. */ + private static byte[] readNativeMember(ZipFile archive, ZipEntry entry, String label, + int maximum, String allowance) throws IOException { long size = entry.getSize(); - if (size < 0 || size > NATIVE_DEX_BYTES) - throw new IllegalArgumentException("DEX exceeds the 64 MiB single-member read allowance"); + if (size < 0 || size > maximum) + throw new IllegalArgumentException(label + " exceeds the " + allowance + " single-member read allowance"); byte[] bytes = new byte[(int) size]; CRC32 crc = new CRC32(); try (InputStream input = archive.getInputStream(entry)) { @@ -296,15 +347,15 @@ class ReaJadxBridge { while (offset < bytes.length) { checkNativeInterrupted(); int read = input.read(bytes, offset, Math.min(65536, bytes.length - offset)); - if (read < 0) throw new IOException("DEX is shorter than its ZIP declaration"); + if (read < 0) throw new IOException(label + " is shorter than its ZIP declaration"); if (read == 0) continue; crc.update(bytes, offset, read); offset += read; } - if (input.read() != -1) throw new IOException("DEX exceeds its ZIP declaration"); + if (input.read() != -1) throw new IOException(label + " exceeds its ZIP declaration"); } if (entry.getCrc() < 0 || entry.getCrc() != crc.getValue()) - throw new IOException("DEX does not match its ZIP CRC32 declaration"); + throw new IOException(label + " does not match its ZIP CRC32 declaration"); return bytes; } @@ -321,7 +372,12 @@ class ReaJadxBridge { inventory.dexEntries++; names.merge(entry.getName(), 1, Integer::sum); } + if (!entry.isDirectory() && entry.getName().equals("AndroidManifest.xml")) + names.merge(entry.getName(), 1, Integer::sum); } + // Before any early return, so every result states whether splits hold code. + inventory.manifestSplits = manifestSplitRequirements(archive, + names.getOrDefault("AndroidManifest.xml", 0)); long totalBytes = 0; int entryIndex = -1; directory = archive.entries(); @@ -436,8 +492,8 @@ class ReaJadxBridge { } } - /** One parsed XML owner supplies namespace-aware values alongside the exact decoded text. */ - static Map manifestSummary(String xml) { + /** One namespace-aware XML owner for the decoded manifest text. */ + static Element manifestRoot(String xml) { Element root; try { // Match REA's existing JDK XML setup: document types are unsupported. @@ -455,6 +511,12 @@ class ReaJadxBridge { } if (!root.getTagName().equals("manifest") || root.getNamespaceURI() != null) throw new IllegalArgumentException("AndroidManifest.xml root must be an unnamespaced "); + return root; + } + + /** One parsed XML owner supplies namespace-aware values alongside the exact decoded text. */ + static Map manifestSummary(String xml) { + Element root = manifestRoot(xml); String android = "http://schemas.android.com/apk/res/android"; String minSdk = ""; String targetSdk = ""; @@ -1009,7 +1071,7 @@ class ReaJadxBridge { SessionHolder holder = new SessionHolder(defaults); ServerCapabilities capabilities = new ServerCapabilities( new ServerCapabilities.Tools(null), null, null, null, null, null, null, Map.of()); - Server server = new Server(new Implementation("rea-jadx-bridge", "10", null, null, null), + Server server = new Server(new Implementation("rea-jadx-bridge", "11", null, null, null), new ServerOptions(capabilities), "", ignored -> Unit.INSTANCE); SessionToolsKt.registerSessionTools(server, holder); ClassToolsKt.registerClassTools(server, holder); diff --git a/docs/guides/android/android-analysis.md b/docs/guides/android/android-analysis.md index 8f928fe32f..09e8ad9a18 100644 --- a/docs/guides/android/android-analysis.md +++ b/docs/guides/android/android-analysis.md @@ -410,6 +410,14 @@ original ZIP spelling. Omitted filters include all scoped facts; `[]` matches none. Class selection never narrows the global inventory used for table-class attribution. +Only libraries inside the selected APK are examined. `native_inventory.manifest_splits` +reports the root manifest's `android:requiredSplitTypes` and the +`` `android:isSplitRequired` flag, decoded without loading the APK. +When the manifest requires splits, or those requirements cannot be read, native +libraries may live in split APKs that were not examined: `library_inventory` is +then `partial` with an unknown that says so, and a binding with no candidate is +`unknown` rather than `unmatched`. + Independent `declarations`, `libraries`, `candidates` and `bindings` collections have stable IDs and source ordinals. Candidates retain APK/library digests, ABI, function addresses and file offsets. Table candidates also retain section, diff --git a/src/android/AndroidNativeInventory.test.ts b/src/android/AndroidNativeInventory.test.ts index 18445e19c6..b90e03414c 100644 --- a/src/android/AndroidNativeInventory.test.ts +++ b/src/android/AndroidNativeInventory.test.ts @@ -2,6 +2,7 @@ import { expect, it } from "vitest"; import { readAndroidNativeInventory } from "./AndroidNativeInventory.js"; import type { JadxToolPort } from "./JadxAnalysis.js"; import type { JsonValue } from "../domain/jsonValue.js"; +import type { AndroidNativeDeclarations } from "../domain/android/androidNativeDeclarations.js"; const SNAPSHOT = "/admitted/immutable target.apk"; @@ -26,6 +27,11 @@ const inventory = () => ({ examined_methods: 9, }, unknowns: [] as string[], + manifest_splits: { + status: "observed", + required_split_types: [] as string[], + split_required: false, + }, }); const tools = (value: unknown): JadxToolPort => ({ json: async (name, input) => { @@ -56,6 +62,23 @@ it("preserves duplicate native identities from distinct original DEX members", a expect(actual.coverage.status).toBe("complete"); }); +it("keeps the manifest's split requirements and unread split facts", async () => { + for (const manifest_splits of [ + { + status: "observed", + required_split_types: ["base__abi", "base__density"], + split_required: true, + }, + { status: "unknown", reason: "Root AndroidManifest.xml is absent" }, + ] satisfies AndroidNativeDeclarations["manifest_splits"][]) { + const source = { ...inventory(), manifest_splits }; + expect( + (await readAndroidNativeInventory(tools(source), SNAPSHOT)) + .manifest_splits, + ).toEqual(manifest_splits); + } +}); + it("keeps usable facts and explicit incomplete DEX coverage", async () => { const source = inventory(); source.coverage.status = "partial"; @@ -88,6 +111,10 @@ it.each([ (source: ReturnType) => { source.methods.push({ ...row, source_index: 1, dex_entry: "other.dex" }); }, + // A bridge that predates split facts cannot say whether splits hold code. + (source: ReturnType) => { + delete (source as Partial).manifest_splits; + }, ])("rejects malformed or inconsistent producer facts (%#)", async (mutate) => { const source = inventory(); mutate(source); diff --git a/src/android/JadxRelease.ts b/src/android/JadxRelease.ts index ba9e1f84cf..072d735102 100644 --- a/src/android/JadxRelease.ts +++ b/src/android/JadxRelease.ts @@ -10,7 +10,7 @@ export const JADX_RELEASE = Object.freeze({ /** Identity of REA's metadata bridge, distinct from the producing engine. */ export const JADX_BRIDGE_IDENTITY = Object.freeze({ name: "rea-jadx-bridge", - version: "10", + version: "11", }); /** Remediation when `REA_JADX_MCP_JAR` is missing or not an absolute path. */ diff --git a/src/domain/android/androidJniBindings.test.ts b/src/domain/android/androidJniBindings.test.ts index 9e82a6188b..8629f6b858 100644 --- a/src/domain/android/androidJniBindings.test.ts +++ b/src/domain/android/androidJniBindings.test.ts @@ -1,4 +1,4 @@ -import { expect, it } from "vitest"; +import { describe, expect, it } from "vitest"; import { androidJniReportSchema, expectedJniNames, @@ -36,6 +36,11 @@ const inventory = (methods = [declaration()]): AndroidNativeDeclarations => ({ examined_methods: methods.length, }, unknowns: [], + manifest_splits: { + status: "observed", + required_split_types: [], + split_required: false, + }, }); const exportRow = ( @@ -355,6 +360,76 @@ it("keeps an explicit empty library selection without introducing ABI candidates }); }); +describe("split APK requirements", () => { + const withSplits = ( + manifest_splits: AndroidNativeDeclarations["manifest_splits"], + ) => + projectAndroidJniBindings({ + apk: { path: "/selected/base.apk", sha256: "a".repeat(64) }, + selection: { abis: ["arm64-v8a"] }, + inventory: { ...inventory(), manifest_splits }, + libraries: [], + libraryInventory: { + status: "complete", + examined_entries: 2776, + selected_libraries: 0, + unknowns: [], + }, + }); + + it("qualifies the library inventory when the manifest requires splits", () => { + const splits: AndroidNativeDeclarations["manifest_splits"] = { + status: "observed", + required_split_types: ["base__abi", "base__density"], + split_required: true, + }; + const result = withSplits(splits); + if (!result.ok) throw new Error(JSON.stringify(result.error)); + expect(androidJniReportSchema.safeParse(result.value).success).toBe(true); + expect(result.value.native_inventory.manifest_splits).toEqual(splits); + expect(result.value.library_inventory).toMatchObject({ + status: "partial", + examined_entries: 2776, + unknowns: [expect.stringContaining("base__abi, base__density")], + }); + // A split may hold the library, so no binding is claimed absent. + expect(result.value.bindings[0]).toMatchObject({ + abi: "arm64-v8a", + status: "unknown", + coverage: "partial", + }); + }); + + it("keeps the library inventory unknown-qualified when split requirements are unknown", () => { + const result = withSplits({ + status: "unknown", + reason: "Root AndroidManifest.xml is absent", + }); + if (!result.ok) throw new Error(JSON.stringify(result.error)); + expect(result.value.library_inventory).toMatchObject({ + status: "partial", + unknowns: [expect.stringContaining("Root AndroidManifest.xml is absent")], + }); + }); + + it("leaves an APK without required splits complete", () => { + const result = withSplits({ + status: "observed", + required_split_types: [], + split_required: false, + }); + if (!result.ok) throw new Error(JSON.stringify(result.error)); + expect(result.value.library_inventory).toMatchObject({ + status: "complete", + unknowns: [], + }); + expect(result.value.bindings[0]).toMatchObject({ + status: "unmatched", + coverage: "complete", + }); + }); +}); + it("preserves selected native declarations when no library establishes an ABI", () => { const report = project([], inventory()); expect(report.bindings).toEqual([]); diff --git a/src/domain/android/androidJniBindings.ts b/src/domain/android/androidJniBindings.ts index 858ed3608d..669bec474c 100644 --- a/src/domain/android/androidJniBindings.ts +++ b/src/domain/android/androidJniBindings.ts @@ -222,6 +222,29 @@ export const expectedJniNames = ( }; type ProjectionFailure = { readonly kind: "capacity" }; +/** + * An APK whose manifest requires splits, or whose requirements are unknown, may + * keep native libraries in split APKs this inventory never examined. + */ +const withSplitRequirements = ( + inventory: AndroidJniReport["library_inventory"], + splits: AndroidNativeDeclarations["manifest_splits"], +): AndroidJniReport["library_inventory"] => { + const reason = + splits.status === "unknown" + ? `Split APK requirements are unknown (${splits.reason}); native libraries may be in split APKs not examined here.` + : splits.split_required || splits.required_split_types.length > 0 + ? `The manifest requires split APKs${splits.required_split_types.length === 0 ? "" : ` (${splits.required_split_types.join(", ")})`}; native libraries in those splits are not in this APK.` + : undefined; + return reason === undefined + ? inventory + : { + ...inventory, + status: inventory.status === "complete" ? "partial" : inventory.status, + unknowns: [...inventory.unknowns, reason], + }; +}; + /** Join once against the COMPLETE declaration inventory before applying selection. */ export const projectAndroidJniBindings = (input: { readonly apk: AndroidJniReport["apk"]; @@ -230,6 +253,10 @@ export const projectAndroidJniBindings = (input: { readonly libraries: readonly AndroidJniLibraryObservation[]; readonly libraryInventory: AndroidJniReport["library_inventory"]; }): Result => { + const libraryInventory = withSplitRequirements( + input.libraryInventory, + input.inventory.manifest_splits, + ); const declarations = input.inventory.methods.map((method) => ({ ...method, declaration_id: id("jni_method", [ @@ -446,7 +473,7 @@ export const projectAndroidJniBindings = (input: { (candidate) => candidate.class_attribution === "ambiguous-native-pair", ); const incomplete = - input.libraryInventory.status !== "complete" || + libraryInventory.status !== "complete" || abiLibraries.some( (library) => library.failure !== null || @@ -497,13 +524,14 @@ export const projectAndroidJniBindings = (input: { scope: input.inventory.scope, coverage: input.inventory.coverage, unknowns: input.inventory.unknowns, + manifest_splits: input.inventory.manifest_splits, }; const report: AndroidJniReport = { apk: input.apk, selection: input.selection, native_inventory, library_inventory: { - ...input.libraryInventory, + ...libraryInventory, selected_libraries: libraries.length, }, declarations, diff --git a/src/domain/android/androidNativeDeclarations.ts b/src/domain/android/androidNativeDeclarations.ts index b634781e9d..809f5e6382 100644 --- a/src/domain/android/androidNativeDeclarations.ts +++ b/src/domain/android/androidNativeDeclarations.ts @@ -30,6 +30,15 @@ export const androidNativeDeclarationsSchema = z.strictObject({ examined_methods: count, }), unknowns: z.array(z.string()), + /** Root manifest split requirements; required splits can carry native libraries. */ + manifest_splits: z.discriminatedUnion("status", [ + z.strictObject({ + status: z.literal("observed"), + required_split_types: z.array(z.string().min(1)), + split_required: z.boolean(), + }), + z.strictObject({ status: z.literal("unknown"), reason: z.string().min(1) }), + ]), }); export type AndroidNativeDeclarations = z.infer< diff --git a/tests/boundary/android/androidJniLibrary.test.ts b/tests/boundary/android/androidJniLibrary.test.ts index a1431ffd6b..6cfdcbb37e 100644 --- a/tests/boundary/android/androidJniLibrary.test.ts +++ b/tests/boundary/android/androidJniLibrary.test.ts @@ -57,6 +57,11 @@ it.each(["name", "descriptor"] as const)( examined_methods: 1, }, unknowns: [], + manifest_splits: { + status: "observed", + required_split_types: [], + split_required: false, + }, }, libraries: [ { diff --git a/tests/boundary/mcp/androidPackageSummaryMcp.test.ts b/tests/boundary/mcp/androidPackageSummaryMcp.test.ts index 9503e75870..305d729b25 100644 --- a/tests/boundary/mcp/androidPackageSummaryMcp.test.ts +++ b/tests/boundary/mcp/androidPackageSummaryMcp.test.ts @@ -129,6 +129,11 @@ const createJniSummaryContractFixture = async () => { examined_methods: 2, }, unknowns: [], + manifest_splits: { + status: "observed", + required_split_types: [], + split_required: false, + }, }, library_inventory: { status: "complete", diff --git a/tests/conformance/android/ReaJadxMetadataRegression.java b/tests/conformance/android/ReaJadxMetadataRegression.java index 042b3924d0..aa522f1432 100644 --- a/tests/conformance/android/ReaJadxMetadataRegression.java +++ b/tests/conformance/android/ReaJadxMetadataRegression.java @@ -78,6 +78,21 @@ public class ReaJadxMetadataRegression { catch (IllegalArgumentException expected) { refused = true; } require(refused, "Malformed or externally described XML was accepted"); } + verifyManifestSplitFacts(); + } + + private static void verifyManifestSplitFacts() { + String android = "xmlns:a=\"http://schemas.android.com/apk/res/android\""; + Map split = ReaJadxBridge.manifestSplitFacts("" + + ""); + require(split.get("required_split_types").equals(List.of("base__abi", "base__density")) + && split.get("split_required").equals(true), "Required split facts were lost: " + split); + Map plain = ReaJadxBridge.manifestSplitFacts(""); + require(plain.get("required_split_types").equals(List.of()) + && plain.get("split_required").equals(false), + "Split facts came from an unnamespaced or false declaration: " + plain); } private static void verifyRootManifests(SessionHolder holder, SessionConfig config, diff --git a/tests/fixtures/android/jadx-mcp.mjs b/tests/fixtures/android/jadx-mcp.mjs index b6c2831951..8ce5fb3677 100644 --- a/tests/fixtures/android/jadx-mcp.mjs +++ b/tests/fixtures/android/jadx-mcp.mjs @@ -146,6 +146,11 @@ register("rea_native_declarations", ({ path }) => { mode === "partial-native-inventory" ? ["Controlled unreadable second DEX member"] : [], + manifest_splits: { + status: "observed", + required_split_types: [], + split_required: false, + }, }); }); register("get_app_info", () => {