fix(native): preserve numeric Mach-O identities and CodeView path bytes (#12458)

This commit is contained in:
morluto authored and GitHub committed 2026-11-19 18:12:35 +00:00
1 parent 11c014f022
commit a627952bd5
20 files changed
+493 -179

No files matched your search

@@ -701,6 +701,10 @@ Available CPU type, subtype/capability bits, byte range, and alignment remain
checked against the source bytes. Inventory records source ranges and hashes, and
extraction copies those ranges without running the target. This does not
expand any analysis provider's supported architectures.
An unnamed architecture can carry a numeric CPU type and base subtype in
`lipo`'s label. The `PTR_AUTH_VERSION` line identifies a userspace or kernel
ABI, while the exact version and full subtype code remain unknown when that
line is the only capability information.
Malformed successful `lipo` output reports a format failure with its parse
diagnostic.
Apple lipo's hidden ARM64 compatibility row is retained separately from the
+3
View File
@@ -148,6 +148,9 @@ PDB identity or complete symbol-coverage attestation, and retains an inline
coverage caveat. Handshake PDB strings share a 4096 UTF-16-unit serialization
budget (at most 24 KiB after JSON escaping); whole attributes that do not fit
are omitted with an explicit resource limitation, rather than truncated.
When the CodeView path's text encoding is unknown, the caveat identifies that
uncertainty and retains the original path bytes in hex when they fit the inline
locator budget. This observation is independent of Ghidra's reported filename.
Original names and types may be missing even when auto-analysis completes.
An empty name search does not establish that a function is absent; use
+5
View File
@@ -42,6 +42,11 @@ The audit composes existing readers. It does not reread Electron fuse bytes itse
| `macho.hardened_runtime` | Not assessed in this audit | |
| `android.manifest` | Not assessed in this audit | |
`native.pdb_path` retains undecodable CodeView paths as hex in
`observation.pdb_path_bytes` with the containing image path and an explicit
unknown encoding. The check can observe the reference even when its text is
unavailable. CodeView path reads stop at the first 4 KiB of each record.
`go.build_paths` reads a flag's arguments by the rules of the tool that takes them. A linker `-X` value is an application string, so a relative one is not a path. A rooted one cannot be told from a file path, so it is reported: `-X main.route=/api/v1` is sampled like `-X main.root=/srv/build`, because dropping both would miss the second.
`text.credential_markers` matches provider-prefixed forms such as a PEM private-key header and documented vendor token prefixes. The report contains the rule id and location only. Matched bytes, previews, lengths, and hashes of matched bytes are omitted.
+7 -6
View File
@@ -49,11 +49,12 @@ import {
cancelledBy,
carriedReason,
} from "../domain/analysisErrorCore.js";
import type {
BinaryTarget,
BinaryArchitecture,
PeCodeViewRecord,
UniversalMachOSlice,
import {
PE_CODEVIEW_PREFIX_BYTES,
type BinaryTarget,
type BinaryArchitecture,
type PeCodeViewRecord,
type UniversalMachOSlice,
} from "../domain/binaryTargetTypes.js";
import { err, ok, type Result } from "../domain/result.js";
import { readMipsElfMetadata } from "./MipsElfMetadata.js";
@@ -1456,7 +1457,7 @@ const readPeCodeView = async (
numberOfSections,
debugDir.sizeOfHeaders,
)) {
const maxCodeViewRead = Math.min(sizeOfData, 4096);
const maxCodeViewRead = Math.min(sizeOfData, PE_CODEVIEW_PREFIX_BYTES);
const codeViewBuffer = await readHandleRange(
handle,
pointerToRawData,
+9 -43
View File
@@ -22,7 +22,6 @@ import {
import type { MachoSlice } from "../domain/apple/dylibResolution.js";
import {
machoArchitectureFamily,
machoCpuSubtypeBase,
machoKnownArm32Subtype,
} from "../domain/apple/machoCpuIdentity.js";
import {
@@ -33,6 +32,7 @@ import type { StableRegularFileDescriptor } from "../filesystem/RegularFile.js";
import { readFileHandleRange } from "../filesystem/readFileHandleRange.js";
import type { ArtifactIntegrityPolicyName } from "../domain/artifactIntegrityPolicy.js";
import {
lipoDescribesCpu,
parseLipoOutputResult,
LipoFieldRetentionError,
type LipoArchitecture,
@@ -709,61 +709,27 @@ const lipoMatchesSlice = (
reported.cpu_subtype_code !== null;
return (
(hasPhysicalIdentity || structurallyUnique) &&
lipoNameMatches(reported.name, observed) &&
(reported.numericName !== undefined ||
lipoNameMatches(reported.name, observed)) &&
(reported.file_offset === null ||
reported.file_offset === observed.slice_offset) &&
(reported.size === null || reported.size === observed.slice_size) &&
(reported.cpu_type_code === null ||
reported.cpu_type_code === observedCpuType) &&
lipoSubtypeMatches(reported, observedCpuSubtype) &&
lipoDescribesCpu(reported, observedCpuType, observedCpuSubtype) &&
(reported.alignment === null ||
observed.fat_alignment_exponent === null ||
reported.alignment === 2 ** observed.fat_alignment_exponent)
);
};
/**
* Compare the complete subtype when lipo printed its capability byte, and
* otherwise only the subtype bits its record names.
*/
const lipoSubtypeMatches = (
reported: LipoArchitecture,
observedCpuSubtype: number,
): boolean => {
if (reported.cpu_subtype_code !== null)
return reported.cpu_subtype_code === observedCpuSubtype;
return (
reported.cpu_subtype_base === null ||
reported.cpu_subtype_base === machoCpuSubtypeBase(observedCpuSubtype)
);
};
/** ARM implementation names from cctools libstuff/arch.c, keyed by lipo spelling. */
const ARM_SUBTYPES: Readonly<Record<string, number>> = {
armv4t: 5,
armv5: 7,
xscale: 8,
armv6: 6,
armv7: 9,
armv7f: 10,
armv7s: 11,
armv7k: 12,
armv6m: 14,
armv7m: 15,
armv7em: 16,
"armv8m.main": 17,
"armv8m.base": 18,
"armv8.1m.main": 19,
};
/** Reconcile lipo's specific name with the structural reader's CPU family. */
const lipoNameMatches = (reported: string, observed: MachoSlice): boolean => {
if (reported === observed.architecture) return true;
if (observed.cpu_type === 12 && observed.architecture === "arm")
return (
ARM_SUBTYPES[reported] ===
machoCpuSubtypeBase(observed.fat_cpu_subtype ?? observed.cpu_subtype)
if (observed.cpu_type === 12 && observed.architecture === "arm") {
const subtype = machoKnownArm32Subtype(
observed.fat_cpu_subtype ?? observed.cpu_subtype,
);
return (reported === "armv5" ? "armv5tej" : reported) === subtype;
}
if (reported === machoArchitectureFamily(observed.architecture)) return true;
// Retain lipo's capability-variant spelling; physical identity is checked separately.
return (
+15 -2
View File
@@ -107,6 +107,7 @@ import {
MAX_RELEASE_EXPOSURE_SOURCE_MAPS,
MAX_RELEASE_EXPOSURE_TEXT_BYTES,
MAX_RELEASE_EXPOSURE_TEXT_MEMBER_BYTES,
type ReleaseExposurePdbPathBytes,
type ReleaseExposureScan,
} from "../domain/releaseExposure.js";
import { OwnedDirectoryHandle } from "../filesystem/OwnedDirectoryHandle.js";
@@ -784,6 +785,7 @@ const assembleScan = (
examined: state.pdbExamined,
paths: [...state.pdbPaths],
image_paths: [...state.pdbImagePaths],
path_bytes: [...state.pdbPathBytes],
failed: state.pdbFailed,
},
text_members: {
@@ -888,6 +890,7 @@ interface ScanState {
pdbExamined: number;
pdbPaths: string[];
pdbImagePaths: string[];
pdbPathBytes: ReleaseExposurePdbPathBytes[];
pdbFailed: number;
coverageUnknown: boolean;
pdbAttempts: number;
@@ -966,6 +969,7 @@ const createState = (
pdbExamined: 0,
pdbPaths: [],
pdbImagePaths: [],
pdbPathBytes: [],
pdbFailed: 0,
coverageUnknown: false,
pdbAttempts: 0,
@@ -2655,9 +2659,18 @@ const readPdb = (state: ScanState, bytes: Buffer, imagePath: string): void => {
if (!parsed.ok) {
state.pdbFailed += 1;
pushLimitation(state, `${imagePath}: ${parsed.error.message}`);
} else if (parsed.value !== undefined && parsed.value.pdbPath.length > 0) {
} else if (parsed.value !== undefined) {
const record = parsed.value;
pushSample(state.pdbPaths, record.pdbPath);
if (record.pdbPath !== null) pushSample(state.pdbPaths, record.pdbPath);
else if (
state.pdbPathBytes.length < MAX_RELEASE_EXPOSURE_SAMPLES &&
!state.pdbPathBytes.some(({ image_path }) => image_path === imagePath)
)
state.pdbPathBytes.push({
image_path: imagePath,
bytes_hex: record.pdbPathBytesHex,
encoding: "unknown",
});
pushSample(state.pdbImagePaths, imagePath);
}
} catch {
+45 -21
View File
@@ -132,6 +132,28 @@ it.each([
},
);
it("keeps a thin unnamed architecture's signed numeric identity after the echoed filename", () => {
const path = "/fixture/\narchitecture forged";
const name = "(cputype (-1) cpusubtype (16777215))";
const parsed = parseLipoFixture(
`Non-fat file: ${path} is architecture: ${name}\n`,
path,
);
expect(parsed).toMatchObject({
format: "thin",
architectures: [
{
name,
cpu_type: null,
cpu_type_code: 0xffffffff,
cpu_subtype: null,
cpu_subtype_code: null,
cpu_subtype_base: 0xffffff,
},
],
});
});
describe("lipo architecture facts", () => {
it("preserves Apple's declared and hidden ARM64 architecture scopes", () => {
const output = parseLipoFixture(`fat_magic 0xcafebabe
@@ -196,7 +218,7 @@ architecture arm64e
cpu_type: "CPU_TYPE_ARM64",
cpu_type_code: 0x0100000c,
cpu_subtype: "CPU_SUBTYPE_ARM64E",
cpu_subtype_code: 0x80000002,
cpu_subtype_code: null,
capabilities: "PTR_AUTH_VERSION USERSPACE 0",
file_offset: 65536,
size: 89088,
@@ -269,28 +291,30 @@ architecture arm64e
},
]);
});
it.each([
{ capabilities: "PTR_AUTH_VERSION USERSPACE 1", code: 0x81000002 },
{ capabilities: "", code: null },
])(
"retains an arm64e base subtype with capabilities '$capabilities'",
({ capabilities, code }) => {
expect(
parseLipoFixture(
`architecture arm64e.v1\n cputype CPU_TYPE_ARM64\n cpusubtype CPU_SUBTYPE_ARM64E\n capabilities ${capabilities}\n`,
).architectures,
).toMatchObject([
{
cpu_type_code: 0x0100000c,
cpu_subtype_code: code,
cpu_subtype_base: 2,
},
]);
},
);
});
it.each([
{ capabilities: "PTR_AUTH_VERSION USERSPACE 1", code: null },
{ capabilities: "0x81", code: 0x81000002 },
{ capabilities: "", code: null },
])(
"retains an arm64e base subtype with capabilities '$capabilities'",
({ capabilities, code }) => {
expect(
parseLipoFixture(
`architecture arm64e.v1\n cputype CPU_TYPE_ARM64\n cpusubtype CPU_SUBTYPE_ARM64E\n capabilities ${capabilities}\n`,
).architectures,
).toMatchObject([
{
cpu_type_code: 0x0100000c,
cpu_subtype_code: code,
cpu_subtype_base: 2,
capabilities: capabilities || null,
},
]);
},
);
describe("lipo FAT operand framing", () => {
it.each([
"/fixture/\narchitecture forged\n offset 123\n size 64",
+117 -45
View File
@@ -31,6 +31,13 @@ export type LipoFieldObservation =
};
export type LipoArchitecture = z.infer<typeof architectureSchema> & {
/** CPU pair lipo prints in place of a name for an unnamed architecture. */
readonly numericName?: {
readonly cpuType: number;
readonly cpuSubtypeBase: number;
};
/** ABI flags lipo names without establishing the version bits. */
readonly pointerAuthAbi?: "USERSPACE" | "KERNEL";
readonly fields: Readonly<
Record<"offset" | "size" | "align", LipoFieldObservation>
>;
@@ -71,10 +78,17 @@ const parseLipoOutput = (output: string, operandPath?: string): LipoOutput => {
// lipo echoes a thin file's pathname verbatim, including embedded newlines.
// Match its final architecture field before splitting records into lines.
const thinArchitecture =
/(?:^|\r?\n)Non-fat file:[\s\S]* is architecture: ([^\s]+)\s*$/u.exec(
output,
/(?:^|\r?\n)Non-fat file:[\s\S]* is architecture: ([^\r\n]+)$/u.exec(
output.trimEnd(),
)?.[1];
if (thinArchitecture !== undefined)
const thinNumericName =
thinArchitecture === undefined
? undefined
: numericArchitectureName(thinArchitecture);
if (
thinArchitecture !== undefined &&
(thinNumericName !== undefined || /^\S+$/u.test(thinArchitecture))
)
return {
format: "thin",
declaredArchitectureCount: null,
@@ -86,14 +100,17 @@ const parseLipoOutput = (output: string, operandPath?: string): LipoOutput => {
hidden: false,
cpu_type: null,
cpu_subtype: null,
cpu_type_code: null,
cpu_type_code: thinNumericName?.cpuType ?? null,
cpu_subtype_code: null,
cpu_subtype_base: null,
cpu_subtype_base: thinNumericName?.cpuSubtypeBase ?? null,
capabilities: null,
file_offset: null,
size: null,
alignment: null,
}),
...(thinNumericName === undefined
? {}
: { numericName: thinNumericName }),
fields: {
offset: { kind: "absent" },
size: { kind: "absent" },
@@ -152,25 +169,35 @@ const parseLipoOutput = (output: string, operandPath?: string): LipoOutput => {
];
},
);
const displayName = current.architecture
? name.replace(/ \(hidden\)$/u, "")
: (name.split(" is architecture: ").at(-1) ?? name);
const numericName = numericArchitectureName(displayName);
const subtype = cpuSubtypeFacts(current.cpusubtype, current.capabilities);
const pointerAuthAbi = pointerAuthenticationAbi(current.capabilities);
if (pointerAuthAbi !== undefined && subtype.code === null) {
admitFieldBytes(160);
limitations.push(
"lipo identified the pointer-authentication ABI class but did not establish its version.",
);
}
architectures.push({
...architectureSchema.parse({
name: name.includes(" is architecture: ")
? (name.split(" is architecture: ").at(-1) ?? name)
: name.replace(/ \(hidden\)$/u, ""),
name: displayName,
hidden: name.endsWith(" (hidden)"),
cpu_type: current.cputype ?? null,
cpu_subtype: current.cpusubtype ?? null,
cpu_type_code: cpuTypeCode(current.cputype),
cpu_subtype_code: cpuSubtypeCode(
current.cpusubtype,
current.capabilities,
),
cpu_subtype_base: cpuSubtypeBase(current.cpusubtype),
cpu_type_code:
cpuTypeCode(current.cputype) ?? numericName?.cpuType ?? null,
cpu_subtype_code: subtype.code,
cpu_subtype_base: subtype.base ?? numericName?.cpuSubtypeBase ?? null,
capabilities: current.capabilities ?? null,
file_offset: value(fields.offset),
size: value(fields.size),
alignment: value(fields.align),
}),
...(numericName === undefined ? {} : { numericName }),
...(pointerAuthAbi === undefined ? {} : { pointerAuthAbi }),
fields,
limitations,
});
@@ -238,6 +265,30 @@ const parseLipoOutput = (output: string, operandPath?: string): LipoOutput => {
};
};
/** Compare all CPU facts lipo actually declared with one structural slice. */
export const lipoDescribesCpu = (
row: LipoArchitecture,
cpuType: number | null,
cpuSubtype: number | null,
): boolean => {
const base = cpuSubtype === null ? null : machoCpuSubtypeBase(cpuSubtype);
return (
(cpuType === null ||
((row.cpu_type_code === null || row.cpu_type_code === cpuType) &&
(row.numericName === undefined ||
row.numericName.cpuType === cpuType) &&
(row.pointerAuthAbi === undefined ||
cpuType === CPU_TYPES.CPU_TYPE_ARM64))) &&
(cpuSubtype === null ||
((row.cpu_subtype_code === null || row.cpu_subtype_code === cpuSubtype) &&
(row.cpu_subtype_base === null || row.cpu_subtype_base === base) &&
(row.numericName === undefined ||
row.numericName.cpuSubtypeBase === base) &&
(row.pointerAuthAbi === undefined ||
cpuSubtype >>> 30 === (row.pointerAuthAbi === "KERNEL" ? 3 : 2))))
);
};
/** Classify expected lipo parse failures once for all command adapters. */
export const parseLipoOutputResult = (
output: string,
@@ -301,44 +352,65 @@ const ownCpuCode = (
const cpuTypeCode = (value: string | undefined): number | null => {
if (value === undefined) return null;
const numeric = unsigned32(value);
return numeric ?? ownCpuCode(CPU_TYPES, value) ?? null;
const decimal = /^\((-?\d+)\)$/u.exec(value)?.[1];
return decimal === undefined
? (unsigned32(value) ?? ownCpuCode(CPU_TYPES, value) ?? null)
: signedCpuType(decimal);
};
/** Normalize the subtype and its separately printed capability bits. */
const cpuSubtypeCode = (
/** A printed subtype base is distinct from the full subtype with its capability byte. */
const cpuSubtypeFacts = (
value: string | undefined,
capabilities: string | undefined,
): number | null => {
if (value === undefined) return null;
): { readonly base: number | null; readonly code: number | null } => {
if (value === undefined) return { base: null, code: null };
const numeric = unsigned32(value);
if (numeric !== null) return numeric;
const subtype = ownCpuCode(CPU_SUBTYPES, value);
if (subtype === undefined) return null;
if (value !== "CPU_SUBTYPE_ARM64E") {
// Recent lipo prints an empty capabilities line, even for LIB64 slices.
const bits = capabilityBits(capabilities);
return bits === null ? null : ((bits << 24) | subtype) >>> 0;
}
const version = /PTR_AUTH_VERSION\s+USERSPACE\s+(\d+)/u.exec(
capabilities ?? "",
)?.[1];
if (version === undefined) return null;
const parsedVersion = Number(version);
if (
!Number.isInteger(parsedVersion) ||
parsedVersion < 0 ||
parsedVersion > 15
)
return null;
return (0x80000000 | (parsedVersion << 24) | subtype) >>> 0;
if (numeric !== null)
return { base: machoCpuSubtypeBase(numeric), code: numeric };
const decimal = /^cpusubtype \((\d+)\)$/u.exec(value)?.[1];
const base =
decimal === undefined
? (ownCpuCode(CPU_SUBTYPES, value) ?? null)
: printedSubtypeBase(decimal);
const bits = capabilityBits(capabilities);
return {
base,
code: base === null || bits === null ? null : ((bits << 24) | base) >>> 0,
};
};
/** The subtype bits a lipo record names, without its capability byte. */
const cpuSubtypeBase = (value: string | undefined): number | null => {
if (value === undefined) return null;
const subtype = unsigned32(value) ?? ownCpuCode(CPU_SUBTYPES, value);
return subtype === undefined ? null : machoCpuSubtypeBase(subtype);
const pointerAuthenticationAbi = (
capabilities: string | undefined,
): LipoArchitecture["pointerAuthAbi"] => {
// cctools has emitted the same number for different version bits. Its
// KERNEL/USERSPACE choice still reads the two high ABI flags directly.
const abi = /^PTR_AUTH_VERSION\s+(USERSPACE|KERNEL)\s+\d+$/u.exec(
capabilities ?? "",
)?.[1];
return abi === "USERSPACE" || abi === "KERNEL" ? abi : undefined;
};
/** cctools uses signed decimal for CPU type and masks the subtype in both spellings. */
const numericArchitectureName = (
value: string,
): LipoArchitecture["numericName"] => {
const parts = /^\(cputype \((-?\d+)\) cpusubtype \((\d+)\)\)$/u.exec(value);
if (parts === null) return undefined;
const cpuType = signedCpuType(parts[1]!);
const cpuSubtypeBase = printedSubtypeBase(parts[2]!);
return cpuType === null || cpuSubtypeBase === null
? undefined
: { cpuType, cpuSubtypeBase };
};
const signedCpuType = (decimal: string): number | null => {
const value = Number(decimal);
return value >= -0x80000000 && value <= 0x7fffffff ? value >>> 0 : null;
};
const printedSubtypeBase = (decimal: string): number | null => {
const value = Number(decimal);
return value <= 0x00ffffff ? value : null;
};
/** lipo names the LIB64 capability and prints other capability bits in hex. */
+5 -2
View File
@@ -62,7 +62,7 @@ export interface PeCodeViewFixture {
readonly type?: "RSDS" | "NB10";
readonly guid?: string;
readonly age?: number;
readonly pdbPath?: string;
readonly pdbPath?: string | Buffer;
}
/** Build a bounded PE image with optional managed metadata or CodeView debug data. */
@@ -84,7 +84,10 @@ export const pe = (
const type = codeView.type ?? "RSDS";
const pdbPath = codeView.pdbPath ?? "app.pdb";
const age = codeView.age ?? 1;
const pathBuf = Buffer.from(`${pdbPath}\0`, "utf8");
const pathBuf =
typeof pdbPath === "string"
? Buffer.from(`${pdbPath}\0`, "utf8")
: Buffer.concat([pdbPath, Buffer.alloc(1)]);
if (type === "RSDS") {
codeViewData = Buffer.alloc(24 + pathBuf.length);
codeViewData.write("RSDS", 0, "ascii");
+37 -25
View File
@@ -3,14 +3,16 @@ import {
type FileMapping,
type ZeroFillMapping,
} from "./virtualFileMapping.js";
import type {
ElfFamilyMetadata,
HeaderArchitecture,
MipsElfMetadata,
PeCodeViewRecord,
RiscvElfMetadata,
UniversalMachOSlice,
UniversalMachOSliceIdentity,
import {
PE_CODEVIEW_PREFIX_BYTES,
type ElfFamilyMetadata,
type HeaderArchitecture,
type MipsElfMetadata,
type PeCodeViewPath,
type PeCodeViewRecord,
type RiscvElfMetadata,
type UniversalMachOSlice,
type UniversalMachOSliceIdentity,
} from "./binaryTargetTypes.js";
import { err, ok, type Result } from "./result.js";
import {
@@ -21,6 +23,7 @@ import {
import type { PeOptionalHeaderFacts } from "./peMachine.js";
import { readPeCoffHeader } from "./peCoffHeader.js";
import { readPeSectionHeader } from "./peSectionHeader.js";
import { isStrictUtf8 } from "./strictUtf8.js";
import { readElfFixedHeader } from "./elfFixedHeader.js";
import {
mzWindowsHeaderLayoutLimitation,
@@ -712,11 +715,12 @@ export const parseCodeViewData = (
buffer.length <= pathOffset
)
return undefined;
const end = buffer.indexOf(0, pathOffset);
if (end <= pathOffset || end >= sizeOfData) return undefined;
const pdbPath = buffer.toString("utf8", pathOffset, end);
const pdbFileName = pdbPath.split(/[/\\]/u).pop() ?? pdbPath;
if (magic === "RSDS" && sizeOfData >= 24 && buffer.length >= 24) {
const end = buffer
.subarray(0, Math.min(sizeOfData, PE_CODEVIEW_PREFIX_BYTES))
.indexOf(0, pathOffset);
if (end <= pathOffset) return undefined;
const path = decodeCodeViewPath(buffer.subarray(pathOffset, end), magic);
if (magic === "RSDS") {
const part1 = buffer.readUInt32LE(4).toString(16).padStart(8, "0");
const part2 = buffer.readUInt16LE(8).toString(16).padStart(4, "0");
const part3 = buffer.readUInt16LE(10).toString(16).padStart(4, "0");
@@ -724,13 +728,24 @@ export const parseCodeViewData = (
const part5 = buffer.subarray(14, 20).toString("hex");
const guid = `${part1}-${part2}-${part3}-${part4}-${part5}`;
const age = buffer.readUInt32LE(20);
return { pdbPath, pdbFileName, guid, age };
return { ...path, guid, age };
}
if (magic === "NB10") {
const age = buffer.readUInt32LE(12);
return { pdbPath, pdbFileName, guid: null, age };
}
return undefined;
return { ...path, guid: null, age: buffer.readUInt32LE(12) };
};
const decodeCodeViewPath = (bytes: Buffer, magic: string): PeCodeViewPath => {
// Microsoft's locator reads RSDS as UTF-8 and NB10 in the active ANSI code
// page. Without that code page, only ASCII NB10 text is unambiguous.
const textAvailable =
magic === "RSDS" ? isStrictUtf8(bytes) : bytes.every((byte) => byte < 0x80);
if (!textAvailable)
return {
pdbPath: null,
pdbFileName: null,
pdbPathBytesHex: bytes.toString("hex"),
};
const pdbPath = bytes.toString("utf8");
return { pdbPath, pdbFileName: pdbPath.split(/[/\\]/u).at(-1) ?? pdbPath };
};
/** Locate the debug directory RVA and size from a PE optional header. */
@@ -797,10 +812,7 @@ export const peRvaToFileOffset = (
return mapped.ok ? mapped.value : undefined;
};
/** CodeView RVA admission uses the same bounded prefix as target file reads. */
const PE_CODEVIEW_MAPPING_BYTES = 4096;
/** Interpret complete debug entries once; callers own directory and payload read bounds. */
/** Interpret complete debug entries once; callers own directory reads. */
export function* peCodeViewDataRanges(
directory: Buffer,
sectionTable: Buffer,
@@ -820,7 +832,7 @@ export function* peCodeViewDataRanges(
sectionTable,
numberOfSections,
sizeOfHeaders,
Math.min(declaredSize, PE_CODEVIEW_MAPPING_BYTES),
Math.min(declaredSize, PE_CODEVIEW_PREFIX_BYTES),
);
if (fileOffset !== undefined) yield { fileOffset, declaredSize };
}
@@ -926,7 +938,7 @@ export const inspectPeCodeViewFromBuffer = (
continue;
const codeViewData = fileBytes.subarray(
pointerToRawData,
Math.min(fileBytes.length, pointerToRawData + sizeOfData),
pointerToRawData + Math.min(sizeOfData, PE_CODEVIEW_PREFIX_BYTES),
);
const parsed = parseCodeViewData(codeViewData, sizeOfData);
if (parsed !== undefined) return ok(parsed);
+17 -4
View File
@@ -41,13 +41,26 @@ export interface ElfFamilyMetadata {
readonly hasInterpreter?: boolean;
}
/** Prefix shared by CodeView RVA mapping and both payload readers. */
export const PE_CODEVIEW_PREFIX_BYTES = 4096;
export type PeCodeViewPath =
| {
readonly pdbPath: string;
readonly pdbFileName: string;
}
| {
readonly pdbPath: null;
readonly pdbFileName: null;
/** Exact bytes before the record's NUL terminator, with unknown text decoding. */
readonly pdbPathBytesHex: string;
};
/** Referenced CodeView debug symbols from a PE debug directory. */
export interface PeCodeViewRecord {
readonly pdbPath: string;
readonly pdbFileName: string;
export type PeCodeViewRecord = PeCodeViewPath & {
readonly guid: string | null;
readonly age: number;
}
};
/** Families whose parsed target variant carries `ElfFamilyMetadata`. */
export const ELF_METADATA_ARCHITECTURES = [
+30 -3
View File
@@ -1,5 +1,6 @@
import { z } from "zod";
import { PE_CODEVIEW_PREFIX_BYTES } from "./binaryTargetTypes.js";
import { digestSchema } from "./digests.js";
import { evidenceLocationSchema, type EvidenceLocation } from "./evidence.js";
import {
@@ -193,9 +194,26 @@ const CHECK_TABLE = {
}
>;
const pdbPathBytesSchema = z.strictObject({
image_path: localPathStringSchema,
bytes_hex: z
.string()
.max(PE_CODEVIEW_PREFIX_BYTES * 2)
.regex(/^(?:[0-9a-f]{2})+$/u),
encoding: z.literal("unknown"),
});
export type ReleaseExposurePdbPathBytes = z.infer<typeof pdbPathBytesSchema>;
const observationSchema = z.strictObject({
counts: z.record(z.string().min(1), z.int().nonnegative()),
samples: z.array(z.string().min(1)).max(MAX_RELEASE_EXPOSURE_SAMPLES),
pdb_path_bytes: z
.array(pdbPathBytesSchema)
.min(1)
.max(MAX_RELEASE_EXPOSURE_SAMPLES)
.exactOptional()
.describe("CodeView locator bytes with unknown text encoding."),
});
const releaseExposureCheckSchema = z.strictObject({
@@ -375,6 +393,7 @@ export interface ReleaseExposureScan {
readonly examined: number;
readonly paths: readonly string[];
readonly image_paths?: readonly string[];
readonly path_bytes?: readonly ReleaseExposurePdbPathBytes[];
readonly failed: number;
};
readonly text_members: {
@@ -706,22 +725,30 @@ const companionCheck = (scan: ReleaseExposureScan): ReleaseExposureCheck => {
const pdbCheck = (scan: ReleaseExposureScan): ReleaseExposureCheck => {
const { pdb, coverage, target } = scan;
const rawPaths = pdb.path_bytes ?? [];
const paths = pdb.paths.length + rawPaths.length;
let status: Status;
if (pdb.paths.length > 0) status = "exposed";
if (paths > 0) status = "exposed";
else if (pdb.failed > 0 || coverage !== "complete") status = "unknown";
else if (pdb.examined === 0) status = "not_applicable";
else status = "not_observed";
const imagePaths = pdb.image_paths ?? [];
return makeCheck(
const check = makeCheck(
"native.pdb_path",
status,
status === "unknown" ? "inferred" : "observed",
{ examined: pdb.examined, paths: pdb.paths.length, failed: pdb.failed },
{ examined: pdb.examined, paths, failed: pdb.failed },
pdb.paths,
status === "exposed"
? findingLocations(imagePaths, target.selected_path)
: targetLocation(target.selected_path),
);
return rawPaths.length === 0
? check
: {
...check,
observation: { ...check.observation, pdb_path_bytes: [...rawPaths] },
};
};
const metadataStatus = (
+30 -2
View File
@@ -6,7 +6,7 @@ import {
type GhidraSessionInfo,
} from "./GhidraSessionValues.js";
const target: BinaryTarget = {
const target = {
path: "/fixture/public.exe",
sha256: "a".repeat(64),
kind: "executable",
@@ -21,7 +21,7 @@ const target: BinaryTarget = {
guid: "01234567-89ab-cdef-0123-456789abcdef",
age: 10,
},
};
} satisfies BinaryTarget;
const absentAttributes = {
file: null,
guid: null,
@@ -31,6 +31,34 @@ const absentAttributes = {
loaded: null,
};
it("preserves undecodable PE locator bytes apart from Ghidra's reported file", () => {
const caveats = ghidraPePdbLimitations(
{
...target,
codeView: {
pdbPath: null,
pdbFileName: null,
pdbPathBytesHex: "e92e706462",
guid: target.codeView?.guid ?? null,
age: 10,
},
},
{
...absentAttributes,
file: "é.pdb",
guid: target.codeView?.guid ?? null,
age: "a",
loaded: true,
},
);
expect(caveats).toHaveLength(2);
expect(caveats[0]).toContain("é.pdb");
expect(caveats[1]).toContain(
"path encoding unknown; original path bytes 0xe92e706462",
);
expect(caveats[1]).toContain("equivalence is not established");
});
it.each(["file", "guid", "age"] as const)(
"retains declared identity when only reported %s is omitted",
(attribute) => {
+20 -5
View File
@@ -16,6 +16,7 @@ const reportedPdbMatchesDeclaration = (
reported: NonNullable<GhidraSessionInfo["pdb"]>,
): boolean => {
if (
declared.pdbPath === null ||
reported.resource_limit?.omitted_attributes.some(
(attribute) =>
attribute === "file" || attribute === "guid" || attribute === "age",
@@ -50,6 +51,23 @@ const pdbLocatorFitsInlineBudget = (value: string): boolean => {
return jsonStringByteLength(value) <= PDB_LOCATOR_INLINE_BYTE_BUDGET;
};
const declaredPdbLocator = (record: PeCodeViewRecord): string => {
// Include JSON escaping in the inline budget before building that representation.
if (
record.pdbFileName !== null &&
pdbLocatorFitsInlineBudget(record.pdbFileName)
)
return JSON.stringify(record.pdbFileName);
const prefix = "(path encoding unknown; original path bytes 0x";
if (
record.pdbFileName === null &&
prefix.length + record.pdbPathBytesHex.length + 1 <=
PDB_LOCATOR_INLINE_BYTE_BUDGET
)
return `${prefix}${record.pdbPathBytesHex})`;
return `(declared locator${record.pdbFileName === null ? " with unknown path encoding" : ""} omitted from this inline caveat: ${PDB_LOCATOR_INLINE_BYTE_BUDGET}-byte resource budget)`;
};
/** Use reported Program facts first, retaining declared PE facts as a fallback. */
export const ghidraPePdbLimitations = (
target: BinaryTarget,
@@ -62,11 +80,8 @@ export const ghidraPePdbLimitations = (
(pdb !== undefined && reportedPdbMatchesDeclaration(target.codeView, pdb))
)
return reported;
const { pdbFileName, guid, age } = target.codeView;
// Include JSON escaping in the inline budget before allocating that representation.
const locator = pdbLocatorFitsInlineBudget(pdbFileName)
? JSON.stringify(pdbFileName)
: `(declared locator omitted from this inline caveat: ${PDB_LOCATOR_INLINE_BYTE_BUDGET}-byte resource budget)`;
const { guid, age } = target.codeView;
const locator = declaredPdbLocator(target.codeView);
const identity =
guid === null
? `age (decimal) ${age}`
+5 -10
View File
@@ -38,7 +38,6 @@ import type { MachoCommandNames } from "../domain/apple/machoCommandNames.js";
import type { ResolvedMachoSlice } from "./NativeMachoSelectedSlice.js";
import { reconcileMachoUuid } from "./parsers/machoUuid.js";
import { compareUnicodeCodePoints } from "../domain/unicodeCodePointOrder.js";
import { machoCpuSubtypeBase } from "../domain/apple/machoCpuIdentity.js";
import type {
MachoEncryptionFacts,
MachoSliceEncryption,
@@ -57,7 +56,10 @@ import {
} from "./NativeMachoCommandDiagnostics.js";
import { invariantViolation } from "../domain/internalInvariant.js";
import { NATIVE_COMMAND_OUTPUT_BUDGET_BYTES } from "../domain/native/nativeCommandOutput.js";
import type { LipoArchitecture } from "../domain/apple/lipo.js";
import {
lipoDescribesCpu,
type LipoArchitecture,
} from "../domain/apple/lipo.js";
interface NativeMachoObservation {
readonly result: JsonValue;
@@ -672,14 +674,7 @@ const lipoDescribesSlice = (
? format === "thin" && slice.container_file_offset === 0
: architecture.file_offset === slice.container_file_offset) &&
(architecture.size === null || architecture.size === slice.size) &&
(architecture.cpu_type_code === null ||
slice.cpu_type === null ||
architecture.cpu_type_code === slice.cpu_type) &&
(slice.cpu_subtype === null ||
(architecture.cpu_subtype_code === null
? architecture.cpu_subtype_base === null ||
architecture.cpu_subtype_base === machoCpuSubtypeBase(slice.cpu_subtype)
: architecture.cpu_subtype_code === slice.cpu_subtype));
lipoDescribesCpu(architecture, slice.cpu_type, slice.cpu_subtype);
const encryptionLimitation = (slice: MachoSliceEncryption): string[] => {
const name =
+5 -8
View File
@@ -1,4 +1,3 @@
import { machoCpuSubtypeBase } from "../domain/apple/machoCpuIdentity.js";
import {
readFatHeaderPrefix,
readFatSliceDeclarations,
@@ -8,7 +7,10 @@ import {
import { decodeLimit, malformedInput } from "../domain/parseFailure.js";
import type { MachoCommandNames } from "../domain/apple/machoCommandNames.js";
import type { NativeMachoSource } from "./NativeMachoSource.js";
import type { LipoArchitecture } from "../domain/apple/lipo.js";
import {
lipoDescribesCpu,
type LipoArchitecture,
} from "../domain/apple/lipo.js";
export interface ResolvedMachoSlice {
readonly offset: number;
@@ -76,12 +78,7 @@ export const resolveSelectedMachoSlice = async (
(selected.file_offset !== null &&
row.offset !== selected.file_offset) ||
(selected.size !== null && row.size !== selected.size) ||
(selected.cpu_type_code !== null &&
selected.cpu_type_code !== row.cpuType) ||
(selected.cpu_subtype_code !== null &&
selected.cpu_subtype_code !== row.cpuSubtype) ||
(selected.cpu_subtype_base !== null &&
selected.cpu_subtype_base !== machoCpuSubtypeBase(row.cpuSubtype)) ||
!lipoDescribesCpu(selected, row.cpuType, row.cpuSubtype) ||
(selected.alignment !== null &&
selected.alignment !== 2 ** row.alignmentExponent)
)
+32 -3
View File
@@ -1122,7 +1122,7 @@ describe("binary target I/O: explicit kinds and executable headers", () => {
path,
pe(0x8664, 64, 0x0002, false, {
type: "RSDS",
pdbPath: "C:\\build\\test.pdb",
pdbPath: "C:\\build\\café.pdb",
guid: "12345678-abcd-ef01-2345-6789abcdef01",
age: 3,
}),
@@ -1136,8 +1136,8 @@ describe("binary target I/O: explicit kinds and executable headers", () => {
format: "pe",
architecture: "x86_64",
codeView: {
pdbPath: "C:\\build\\test.pdb",
pdbFileName: "test.pdb",
pdbPath: "C:\\build\\café.pdb",
pdbFileName: "café.pdb",
guid: "12345678-abcd-ef01-2345-6789abcdef01",
age: 3,
},
@@ -1222,6 +1222,35 @@ describe("binary target I/O: explicit kinds and executable headers", () => {
});
});
it("retains NB10 path bytes whose original ANSI code page is unavailable", async () => {
const directory = await createTestTempDirectory("rea-target-");
const path = join(directory, "legacy.exe");
await writeFile(
path,
pe(0x014c, 64, 2, false, {
type: "NB10",
// A valid UTF-8 byte sequence does not identify NB10's ANSI code page.
pdbPath: Buffer.from("443a5cc3a92e706462", "hex"),
age: 7,
}),
);
const result = await parseBinaryTarget(path, {
cwd: directory,
hostArchitecture: "ia32",
});
if (!result.ok) throw result.error;
expect(result.value).toMatchObject({
format: "pe",
codeView: {
pdbPath: null,
pdbFileName: null,
pdbPathBytesHex: "443a5cc3a92e706462",
guid: null,
age: 7,
},
});
});
describe("app executable filename fidelity", () => {
it.each([" leading", "trailing ", " both "])(
"preserves executable filename whitespace in an XML plist: %j",
+11
View File
@@ -3,6 +3,7 @@ import { writeFile } from "node:fs/promises";
import { join } from "node:path";
import { deflateSync } from "node:zlib";
import { createHash } from "node:crypto";
import { pe } from "../../../src/domain/binaryTarget.fixture.js";
import { parseEvidence } from "../../../src/domain/evidence.js";
import { gpuCodeObjectsPartialSchema } from "../../../src/domain/gpu/gpuCodeObjects.js";
import { GpuCodeObjectsProvider } from "../../../src/gpu/GpuCodeObjectsProvider.js";
@@ -1260,6 +1261,16 @@ it("does not dispatch a high-bit-corrupted DOS signature to the PE parser", asyn
error: { _tag: "AnalysisUnsupportedTargetError" },
});
});
it("preserves the PE layout refusal at the GPU provider boundary", async () => {
const result = await inspect(pe(0x014c, 4));
expect(result).toMatchObject({
ok: false,
error: {
_tag: "AnalysisUnsupportedTargetError",
message: expect.stringContaining("overlapping PE header"),
},
});
});
it.each(["zlib", "zstd"] as const)(
"uses each legacy CCOB v1 %s stream boundary across alignment padding",
async (codec) => {
@@ -4,6 +4,7 @@ import { join } from "node:path";
import { expect } from "vitest";
import { RELEASE_EXPOSURE_TOOL_CONTRACTS } from "../../../src/contracts/releaseExposureToolContracts.js";
import { pe } from "../../../src/domain/binaryTarget.fixture.js";
import { createServer } from "../../../src/server/createServer.js";
import { createTestBinarySession } from "../../fixtures/binarySession.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
@@ -17,6 +18,59 @@ if (releaseExposureContract === undefined)
throw new Error("Missing release exposure contract");
const outputSchema = releaseExposureContract.outputSchema;
mcpTest(
"reports exact CodeView path bytes with unknown encoding",
async ({ mcp }) => {
const session = createTestBinarySession(() => {
throw new Error("Must not start a deep provider");
});
const client = await mcp.connect(
createServer({ kind: "session", session }),
);
try {
const definition = (await client.listTools()).tools.find(
(tool) => tool.name === "audit_release_exposure",
);
if (definition === undefined)
throw new Error("Missing advertised contract");
const root = await createTestTempDirectory("rea-release-codeview-");
const image = join(root, "app.exe");
await writeFile(
image,
pe(0x8664, 64, 2, false, {
pdbPath: Buffer.from("433a5ce92e706462", "hex"),
}),
);
const response = await client.callTool(
{ name: "audit_release_exposure", arguments: { path: image } },
{ toolDefinition: withCanonicalOutputSchema(definition) },
);
expect(response.isError).not.toBe(true);
const evidence = outputSchema.parse(response.structuredContent);
const finding = evidence.normalized_result.checks.find(
({ id }) => id === "native.pdb_path",
);
expect(finding).toMatchObject({
status: "exposed",
locations: [{ kind: "artifact-path", path: image }],
observation: {
counts: { examined: 1, paths: 1, failed: 0 },
samples: [],
pdb_path_bytes: [
{
image_path: image,
bytes_hex: "433a5ce92e706462",
encoding: "unknown",
},
],
},
});
} finally {
await session.close();
}
},
);
mcpTest(
"keeps lossy text unknown while retaining a visible marker",
async ({ mcp }) => {
@@ -412,6 +412,9 @@ describe("artifact Mach-O arm64e variant slices", () => {
const ARM64E_V1 = { type: 0x0100000c, subtype: 0x81000002 } as const;
// CPU_SUBTYPE_ARM64E_X1 (12) with the pointer-auth ABI bit, as in macOS 27 /bin/ls.
const ARM64E_X1 = { type: 0x0100000c, subtype: 0x8000000c } as const;
const numericX1 = "(cputype (16777228) cpusubtype (12))";
const userspaceX1 =
" cputype (16777228)\n cpusubtype cpusubtype (12)\n capabilities PTR_AUTH_VERSION USERSPACE 0";
const variantSlices = async (
cpu: { readonly type: number; readonly subtype: number },
lipo: (size: number) => string,
@@ -451,6 +454,18 @@ describe("artifact Mach-O arm64e variant slices", () => {
ARM64E_X1,
" cputype CPU_TYPE_ARM64\n cpusubtype unknown arm64 cpusubtype",
],
[
"arm64e",
ARM64E_V1,
" cputype CPU_TYPE_ARM64\n cpusubtype CPU_SUBTYPE_ARM64E\n capabilities PTR_AUTH_VERSION USERSPACE 0",
],
[numericX1, ARM64E_X1, userspaceX1],
[numericX1, { ...ARM64E_X1, subtype: 0x8100000c }, userspaceX1],
[
numericX1,
{ ...ARM64E_X1, subtype: 0xc100000c },
userspaceX1.replace("USERSPACE", "KERNEL"),
],
])(
"accepts lipo's %s name for the FAT arm64e slice",
async (name, fatCpu, cpu) => {
@@ -467,6 +482,33 @@ describe("artifact Mach-O arm64e variant slices", () => {
},
);
it.each([
{
reason: "architecture label",
name: "(cputype (16777228) cpusubtype (2))",
},
{ reason: "subtype field", subtype: "2" },
{ reason: "exact capabilities field", capabilities: "0x0" },
{ reason: "missing ABI flag", fatSubtype: 12 },
{ reason: "kernel ABI flag", fatSubtype: 0xc000000c },
])(
"refuses a conflicting numeric lipo $reason",
async ({
name = numericX1,
subtype = "12",
capabilities = "PTR_AUTH_VERSION USERSPACE 0",
fatSubtype = ARM64E_X1.subtype,
}) => {
await expect(
variantSlices(
{ ...ARM64E_X1, subtype: fatSubtype },
(size) =>
`architecture ${name}\n cputype (16777228)\n cpusubtype cpusubtype (${subtype})\n capabilities ${capabilities}\n offset 8192\n size ${String(size)}\n align 2^12 (4096)\n`,
),
).rejects.toMatchObject({ reason: "integrity" });
},
);
it.each([
["a plain arm64 slice", CPU.arm64, "8192"],
["a different offset", ARM64E_V1, "8193"],