From cffff06ee7d0995fc96f9590931d8850951ef93e Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 07:28:34 -0500 Subject: [PATCH] fix(apple): bound FAT disambiguation to plausible JVM classes (#12316) --- docs/guides/native/native-investigation.md | 23 ++++++----- scripts/verify/baselines/raw-buffer-read.json | 1 - src/application/BinaryTargetResolver.ts | 7 ++-- .../apple/MachoLoadCommandReader.test.ts | 23 +++++++++++ src/artifacts/apple/machoContainer.test.ts | 15 +++++++ src/domain/apple/jvmClassFile.ts | 40 ++++++++++++------- src/domain/apple/machoLoadCommandReader.ts | 6 +-- .../applications/jvmAdmissionIdentity.test.ts | 40 ++++++++++++++++++- 8 files changed, 120 insertions(+), 35 deletions(-) diff --git a/docs/guides/native/native-investigation.md b/docs/guides/native/native-investigation.md index cef7e49f63..6b85f07129 100644 --- a/docs/guides/native/native-investigation.md +++ b/docs/guides/native/native-investigation.md @@ -685,12 +685,13 @@ Native target admission checks Mach-O slice headers before assigning FAT identity. A shared `CAFEBABE` prefix whose declarations do not identify Mach-O images receives the generic unsupported-format refusal, including JVM class files larger than the bounded admission probe. This does not identify a partial -prefix as a validated JVM class. For files sharing `CAFEBABE`, target admission -checks complete JVM framing within the same 16 MiB class identity bound as the -Mach-O image reader. A complete class remains unsupported even if its constant -pool resembles a known FAT CPU declaration. Above that bound, an ambiguous -malformed FAT interpretation remains unresolved. Malformed recognized FAT -declarations retain their format-specific reasons. +prefix as a validated JVM class. When the shared header fields form a plausible +JVM version, target admission and the Mach-O image reader check complete JVM +framing up to 16 MiB. A complete class remains +unsupported even if its constant pool resembles a known FAT CPU declaration. +Above that bound, a malformed FAT interpretation remains unresolved if the +prefix could still belong to a JVM class. A header that rules out a JVM class +allows the reader to report a recognized FAT range error directly. `inspect_artifact` and `extract_artifact` retain universal Mach-O slices under their exact `lipo` names, including 32-bit ARM implementations such as `armv7`, @@ -827,11 +828,11 @@ command timeout does not raise these budgets. `inspect_macho.encryption` reports the `LC_ENCRYPTION_INFO(_64)` state of every slice, not only the selected one. It decodes only the FAT table, slice headers -and load commands. Like every Mach-O container read, a `0xcafebabe` input of at -most 16 MiB is first read whole to rule out a JVM class file, so that read -includes code bytes; larger inputs and thin images read only the structures -above. A slice is `encrypted` when its single encryption command has a nonzero -`cryptid`, `not-encrypted` when `cryptid` is zero, and `absent` only when every +and load commands. A `0xcafebabe` input of at most 16 MiB with a plausible JVM +version is first read whole to resolve its identity. That read can include code +bytes. Other inputs read only the structures above. A slice is `encrypted` +when its single encryption command has a nonzero `cryptid`, `not-encrypted` +when `cryptid` is zero, and `absent` only when every load command was read and none was an encryption command. A command whose width or `cmdsize` contradicts the image, more than one such command, or a range past the slice is `malformed`; a slice whose commands could not be fully read is diff --git a/scripts/verify/baselines/raw-buffer-read.json b/scripts/verify/baselines/raw-buffer-read.json index 4399c81fcf..02c3138672 100644 --- a/scripts/verify/baselines/raw-buffer-read.json +++ b/scripts/verify/baselines/raw-buffer-read.json @@ -1,5 +1,4 @@ { - "src/application/BinaryTargetResolver.ts": 1, "src/application/MipsElfMetadata.ts": 10, "src/application/MipsGnuAttributes.ts": 2, "src/artifacts/DesktopFileInspection.ts": 4, diff --git a/src/application/BinaryTargetResolver.ts b/src/application/BinaryTargetResolver.ts index 74232b742e..890cfdec4c 100644 --- a/src/application/BinaryTargetResolver.ts +++ b/src/application/BinaryTargetResolver.ts @@ -120,6 +120,7 @@ import { type MachoHeaderPrefixFacts, } from "../domain/apple/machoContainer.js"; import { + hasJvmClassHeader, isJvmClassFile, MAX_JVM_CLASS_IDENTITY_BYTES, JVM_CLASS_IDENTITY_LIMIT_REASON, @@ -1017,9 +1018,9 @@ const readExecutableMetadata = async ( signal, }); if (thin !== null) return thin; - const hasJvmMagic = bytes.length >= 4 && bytes.readUInt32BE(0) === 0xcafebabe; + const mayBeJvmClass = hasJvmClassHeader(bytes); if ( - hasJvmMagic && + mayBeJvmClass && fileSize > bytes.length && fileSize <= MAX_JVM_CLASS_IDENTITY_BYTES ) { @@ -1034,7 +1035,7 @@ const readExecutableMetadata = async ( signal, ); if ( - hasJvmMagic && + mayBeJvmClass && fileSize > MAX_JVM_CLASS_IDENTITY_BYTES && fatEvidence !== undefined && classifyFatContainerIdentity( diff --git a/src/artifacts/apple/MachoLoadCommandReader.test.ts b/src/artifacts/apple/MachoLoadCommandReader.test.ts index 70b1625739..e9abb0598d 100644 --- a/src/artifacts/apple/MachoLoadCommandReader.test.ts +++ b/src/artifacts/apple/MachoLoadCommandReader.test.ts @@ -31,6 +31,7 @@ import { hasMachoMagic } from "../../domain/apple/machoContainer.js"; import { traceDylibResolution } from "./DylibResolutionReader.js"; import { createTestTempDirectory } from "../../../tests/fixtures/temporaryDirectory.js"; import { javaClassFile } from "../../../tests/fixtures/javaClassFile.js"; +import { MAX_JVM_CLASS_IDENTITY_BYTES } from "../../domain/apple/jvmClassFile.js"; import { DirectoryArtifactReader } from "../../resources/index.js"; // Independently exercise the dependency and reference budgets. @@ -1791,6 +1792,28 @@ describe("Mach-O load command reader inputs", () => { ).toEqual({ status: "malformed", reason: "Mach-O header is truncated" }); }); + it.each([MAX_JVM_CLASS_IDENTITY_BYTES, MAX_JVM_CLASS_IDENTITY_BYTES + 1])( + "reports a known FAT range error and skips full class reads for %i bytes", + async (size) => { + const header = Buffer.alloc(28); + header.writeUInt32BE(0xcafebabe, 0); + header.writeUInt32BE(1, 4); + header.writeUInt32BE(CPU.arm64.type, 8); + header.writeUInt32BE(size, 16); + header.writeUInt32BE(32, 20); + const readAt = vi.fn(async (offset: number, length: number) => + header.subarray(offset, offset + length), + ); + expect(await readMachoImage(readAt, size)).toMatchObject({ + status: "malformed", + reason: expect.stringContaining("slice range extends beyond the file"), + }); + expect(Math.max(...readAt.mock.calls.map(([, length]) => length))).toBe( + 28, + ); + }, + ); + it("keeps oversized CAFEBABE identity unknown when class payload is sparse", async () => { const classPrefix = Buffer.from(javaClassFile(4000, true)); const payloadBytes = MAX_LOAD_COMMAND_BYTES + 1; diff --git a/src/artifacts/apple/machoContainer.test.ts b/src/artifacts/apple/machoContainer.test.ts index a85ef9eff6..3ef88e0786 100644 --- a/src/artifacts/apple/machoContainer.test.ts +++ b/src/artifacts/apple/machoContainer.test.ts @@ -314,6 +314,21 @@ describe("FAT Mach-O identity", () => { }); describe("FAT slice header identity and bounds", () => { + it.each([ + { major: 55, minor: 1, expected: true }, + { major: 56, minor: 0, expected: true }, + { major: 56, minor: 65535, expected: true }, + { major: 56, minor: 1, expected: false }, + ])( + "checks class major $major and minor $minor for JVM identity", + ({ major, minor, expected }) => { + const bytes = javaClassFile(); + bytes.writeUInt16BE(minor, 4); + bytes.writeUInt16BE(major, 6); + expect(isJvmClassFile(bytes)).toBe(expected); + }, + ); + const classWithInterface = (reference: number): Buffer => { // Retain enough bytes for the coincident FAT table claim to be readable; // otherwise rejecting JVM identity would still yield not-fat on truncation. diff --git a/src/domain/apple/jvmClassFile.ts b/src/domain/apple/jvmClassFile.ts index d7f9271491..f9ddf446bb 100644 --- a/src/domain/apple/jvmClassFile.ts +++ b/src/domain/apple/jvmClassFile.ts @@ -13,8 +13,8 @@ class ClassFileCursor { this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength); } - get atEnd(): boolean { - return this.offset === this.bytes.byteLength; + get remaining(): number { + return this.bytes.byteLength - this.offset; } u1(): number | null { @@ -44,10 +44,24 @@ class ClassFileCursor { } private has(length: number): boolean { - return this.offset <= this.bytes.byteLength - length; + return length <= this.remaining; } } +const readMajorVersion = (cursor: ClassFileCursor): number | null => { + if (cursor.u4() !== 0xcafebabe) return null; + const minor = cursor.u2(); + const major = cursor.u2(); + // JVMS §4.1 permits arbitrary minors through major 55. Later releases + // use 0 for ordinary class files and 65535 for preview features. + if (minor === null || major === null || major < 45) return null; + return major < 56 || minor === 0 || minor === 65535 ? major : null; +}; + +/** Establish whether the fixed prefix warrants a complete JVM identity scan. */ +export const hasJvmClassHeader = (bytes: Uint8Array): boolean => + readMajorVersion(new ClassFileCursor(bytes)) !== null; + interface ConstantPool { readonly tags: (number | null)[]; readonly first: (number | null)[]; @@ -58,6 +72,10 @@ const readConstantPool = ( cursor: ClassFileCursor, count: number, ): ConstantPool | null => { + // JVMS §4.4: the smallest entries take three bytes. A long or double + // consumes two pool slots in nine bytes, so that lower bound still holds. + // §4.1 also requires seven u2 fields after the pool, even with no members. + if ((count - 1) * 3 + 14 > cursor.remaining) return null; const pool: ConstantPool = { tags: Array.from({ length: count }, () => null), first: Array.from({ length: count }, () => null), @@ -231,18 +249,10 @@ const readMembers = (cursor: ClassFileCursor, pool: ConstantPool): boolean => { /** Validate class-file framing and constant-pool references before FAT parsing. */ export const isJvmClassFile = (bytes: Uint8Array): boolean => { const cursor = new ClassFileCursor(bytes); - if (cursor.u4() !== 0xcafebabe) return false; - const minor = cursor.u2(); - const major = cursor.u2(); + const major = readMajorVersion(cursor); + if (major === null) return false; const poolCount = cursor.u2(); - if ( - minor === null || - major === null || - major < 45 || - poolCount === null || - poolCount === 0 - ) - return false; + if (poolCount === null || poolCount === 0) return false; const pool = readConstantPool(cursor, poolCount); if (pool === null || !hasValidPoolReferences(pool, major)) return false; if (cursor.u2() === null) return false; @@ -269,6 +279,6 @@ export const isJvmClassFile = (bytes: Uint8Array): boolean => { return ( attributes !== null && readAttributes(cursor, pool, attributes) && - cursor.atEnd + cursor.remaining === 0 ); }; diff --git a/src/domain/apple/machoLoadCommandReader.ts b/src/domain/apple/machoLoadCommandReader.ts index b10d81a4d7..869828811b 100644 --- a/src/domain/apple/machoLoadCommandReader.ts +++ b/src/domain/apple/machoLoadCommandReader.ts @@ -17,6 +17,7 @@ import { type MachoCommandStringFailure, } from "./machoLoadCommands.js"; import { + hasJvmClassHeader, MAX_JVM_CLASS_IDENTITY_BYTES, JVM_CLASS_IDENTITY_LIMIT_REASON, } from "./jvmClassFile.js"; @@ -36,7 +37,6 @@ import { findOverlappingFatSlices, hasMachoMagic, readFatContainerHeader, - readFatHeaderPrefix, readFatSliceDeclarations, readMachoHeaderPrefixFacts, validateFatSlice, @@ -151,9 +151,7 @@ export const readMachoContainer = async ( reason: "Mach-O header is truncated", } : { kind: "not-mach-o" }; - const fatPrefix = readFatHeaderPrefix(head); - const mayBeJvmClass = - fatPrefix.state === "parsed" && !fatPrefix.wide && !fatPrefix.littleEndian; + const mayBeJvmClass = hasJvmClassHeader(head); let header: FatContainerHeader; if (mayBeJvmClass && size <= MAX_JVM_CLASS_IDENTITY_BYTES) { const complete = await readAt(0, size); diff --git a/tests/acceptance/applications/jvmAdmissionIdentity.test.ts b/tests/acceptance/applications/jvmAdmissionIdentity.test.ts index 4aaf6148b3..ef076a13b1 100644 --- a/tests/acceptance/applications/jvmAdmissionIdentity.test.ts +++ b/tests/acceptance/applications/jvmAdmissionIdentity.test.ts @@ -1,7 +1,8 @@ -import { readFile, writeFile } from "node:fs/promises"; +import { open, readFile, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { expect } from "vitest"; +import { MAX_JVM_CLASS_IDENTITY_BYTES } from "../../../src/domain/apple/jvmClassFile.js"; import { javaClassFile } from "../../fixtures/javaClassFile.js"; import { connectLocalToolsMcp } from "../../fixtures/localToolsMcp.js"; import { parseMcpToolError } from "../../fixtures/mcpToolError.js"; @@ -37,3 +38,40 @@ cliTest( } }, ); + +cliTest( + "reports a FAT slice range error when the shared magic cannot identify a JVM class", + async ({ cli }) => { + const directory = await createTestTempDirectory("rea-fat-admission-"); + const path = join(directory, "image"); + const size = MAX_JVM_CLASS_IDENTITY_BYTES + 1; + const header = Buffer.alloc(28); + header.writeUInt32BE(0xcafebabe, 0); + header.writeUInt32BE(1, 4); + header.writeUInt32BE(0x0100000c, 8); + header.writeUInt32BE(size, 16); + header.writeUInt32BE(32, 20); + const handle = await open(path, "w+"); + try { + await handle.write(header); + await handle.truncate(size); + } finally { + await handle.close(); + } + const refusal = { + code: "target_unavailable", + details: { + reason: "FAT architecture 0 slice range extends beyond the file", + }, + }; + const analyzed = await cli.run({ + arguments: ["analyze", path, "--format", "json"], + }); + expect(analyzed.exitCode, analyzed.stderr).toBe(1); + expect(analyzed.json).toMatchObject(refusal); + const { call } = await connectLocalToolsMcp(); + const opened = await call("open_binary", { path }); + expect(opened.isError, JSON.stringify(opened)).toBe(true); + expect(parseMcpToolError(opened).error).toMatchObject(refusal); + }, +);