fix(apple): bound FAT disambiguation to plausible JVM classes (#12316)

This commit is contained in:
morluto authored and GitHub committed 2026-11-19 07:28:34 -05:00
1 parent d50320cc61
commit cffff06ee7
8 files changed
+120 -35

No files matched your search

+12 -11
View File
@@ -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
@@ -1,5 +1,4 @@
{
"src/application/BinaryTargetResolver.ts": 1,
"src/application/MipsElfMetadata.ts": 10,
"src/application/MipsGnuAttributes.ts": 2,
"src/artifacts/DesktopFileInspection.ts": 4,
+4 -3
View File
@@ -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(
@@ -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;
@@ -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.
+25 -15
View File
@@ -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
);
};
+2 -4
View File
@@ -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);
@@ -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);
},
);