fix(ghidra): report unapplied PE CodeView PDB limitation (#2283)

* fix(ghidra): report unapplied PE CodeView PDB limitation (#2259)

When Ghidra analyzes a PE target that references companion debug symbols
in its CodeView (IMAGE_DEBUG_TYPE_CODEVIEW / RSDS or NB10) debug directory,
Ghidra's headless analyzer cannot automatically locate or apply the companion
PDB from isolated runtime directories without companion admission. Procedure
names remain analysis-generated (FUN_<address>).

Parse CodeView debug metadata (RSDS GUID/age and NB10 age) during PE target
resolution, and report an Evidence limitation informing callers and agents
that referenced debug symbols were not applied and procedure names are
analysis-generated.

Fixes #2259

* test(pe): group CodeView header coverage separately

* fix(ghidra): avoid contradictory PDB limitations

* fix(android): make DEX descriptor pattern portable

* fix(ci): isolate Linux Hopper process fixture inventory

* fix(comparison): recheck historical calls-only changes (#2223)

* fix(comparison): preserve incomplete function call evidence

Keep missing, unknown, partial and unresolved call relationships unknown in function comparisons and reconstruction claims. Aggregate IDA caller and callee coverage without overwriting uncertainty.

Validate with 144 focused tests, typecheck/lint, docs checks and test discovery. Real providers were not verified; the full headless IDA session suite requires unavailable Windows native controls.

* fix(comparison): recheck historical calls-only changes

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>

* style: format identity comparison and IDA runner

---------

Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
Co-authored-by: Lucien <164857476+dakjdakd@users.noreply.github.com>
This commit is contained in:
Tufail Akram
2026-10-14 02:56:26 +08:00
committed by GitHub
co-authored by morluto Lucien
parent 4481f86188
commit 729ca2ab6a
9 changed files with 607 additions and 7 deletions
+172 -1
View File
@@ -3,6 +3,7 @@ import type {
ElfFamilyMetadata,
HeaderArchitecture,
MipsElfMetadata,
PeCodeViewRecord,
RiscvElfMetadata,
UniversalMachOSlice,
} from "./binaryTargetTypes.js";
@@ -50,6 +51,7 @@ export type ExecutableMetadata =
| "shared-library"
| "non-executable";
readonly managed: boolean;
readonly codeView?: PeCodeViewRecord;
};
/**
@@ -257,7 +259,8 @@ const parseMz = (
);
if (windowsHeader.signature !== "PE")
return err("invalid or truncated Windows executable header in MZ image");
return parsePeRecord(bytes.subarray(offset));
const codeView = parsePeCodeViewFromBuffer(bytes, offset);
return parsePeRecord(bytes.subarray(offset), codeView);
}
const parsed = parseDosMzHeader(bytes, fileSize, signatureAtOffset);
return parsed.ok
@@ -272,6 +275,7 @@ const parseMz = (
/** Parse a bounded PE signature, COFF record, and optional header without I/O. */
export const parsePeRecord = (
record: Buffer,
codeView: PeCodeViewRecord | undefined,
): Result<ExecutableMetadata, string> => {
if (
record.length < 24 ||
@@ -305,9 +309,176 @@ export const parsePeRecord = (
? "application"
: "shared-library",
managed: managed.value,
...(codeView !== undefined ? { codeView } : {}),
});
};
/** Parse CodeView record data (RSDS or NB10) from raw data bytes. */
export const parseCodeViewData = (
buffer: Buffer,
sizeOfData: number,
): PeCodeViewRecord | undefined => {
if (sizeOfData < 16 || buffer.length < 16) return undefined;
const magic = buffer.subarray(0, 4).toString("binary");
const pathOffset = magic === "RSDS" ? 24 : magic === "NB10" ? 16 : undefined;
if (
pathOffset === undefined ||
sizeOfData <= pathOffset ||
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 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");
const part4 = buffer.subarray(12, 14).toString("hex");
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 };
}
if (magic === "NB10") {
const age = buffer.readUInt32LE(12);
return { pdbPath, pdbFileName, guid: null, age };
}
return undefined;
};
/** Locate the debug directory RVA and size from a PE optional header. */
export const peDebugDirectoryEntry = (
optionalHeader: Buffer,
):
| {
readonly debugRva: number;
readonly debugSize: number;
readonly sizeOfHeaders: number;
}
| undefined => {
if (optionalHeader.length < 2) return undefined;
const magic = optionalHeader.readUInt16LE(0);
if (magic !== 0x10b && magic !== 0x20b) return undefined;
const directoryOffset = magic === 0x20b ? 112 : 96;
const directoryCountOffset = directoryOffset - 4;
if (optionalHeader.length < directoryCountOffset + 4) return undefined;
const directoryCount = optionalHeader.readUInt32LE(directoryCountOffset);
if (directoryCount <= 6) return undefined;
const debugEntryOffset = directoryOffset + 6 * 8;
if (optionalHeader.length < debugEntryOffset + 8) return undefined;
const debugRva = optionalHeader.readUInt32LE(debugEntryOffset);
const debugSize = optionalHeader.readUInt32LE(debugEntryOffset + 4);
if (debugRva === 0 || debugSize < 28) return undefined;
return {
debugRva,
debugSize,
sizeOfHeaders: optionalHeader.readUInt32LE(60),
};
};
/** Translate an RVA to an absolute file offset using the PE section table. */
export const peRvaToFileOffset = (
rva: number,
sectionTable: Buffer,
numberOfSections: number,
sizeOfHeaders: number,
size = 1,
): number | undefined => {
if (rva < sizeOfHeaders && size <= sizeOfHeaders - rva) return rva;
for (let i = 0; i < numberOfSections; i++) {
const offset = i * 40;
if (sectionTable.length < offset + 40) break;
const virtualAddress = sectionTable.readUInt32LE(offset + 12);
const sizeOfRawData = sectionTable.readUInt32LE(offset + 16);
const pointerToRawData = sectionTable.readUInt32LE(offset + 20);
if (
pointerToRawData > 0 &&
rva >= virtualAddress &&
rva - virtualAddress < sizeOfRawData &&
size <= sizeOfRawData - (rva - virtualAddress)
) {
return pointerToRawData + (rva - virtualAddress);
}
}
return undefined;
};
/** Parse CodeView metadata from a bounded in-memory PE image buffer. */
export const parsePeCodeViewFromBuffer = (
fileBytes: Buffer,
peOffset: number,
): PeCodeViewRecord | undefined => {
if (fileBytes.length < peOffset + 24) return undefined;
const numberOfSections = fileBytes.readUInt16LE(peOffset + 6);
const optionalHeaderSize = fileBytes.readUInt16LE(peOffset + 20);
if (
optionalHeaderSize > 4096 ||
fileBytes.length < peOffset + 24 + optionalHeaderSize
)
return undefined;
const optionalHeader = fileBytes.subarray(
peOffset + 24,
peOffset + 24 + optionalHeaderSize,
);
const debugDir = peDebugDirectoryEntry(optionalHeader);
if (debugDir === undefined) return undefined;
const sectionTableOffset = peOffset + 24 + optionalHeaderSize;
const sectionTableSize = numberOfSections * 40;
if (fileBytes.length < sectionTableOffset + sectionTableSize)
return undefined;
const sectionTable = fileBytes.subarray(
sectionTableOffset,
sectionTableOffset + sectionTableSize,
);
const debugFileOffset = peRvaToFileOffset(
debugDir.debugRva,
sectionTable,
numberOfSections,
debugDir.sizeOfHeaders,
Math.min(debugDir.debugSize, 4096),
);
if (debugFileOffset === undefined || fileBytes.length < debugFileOffset + 28)
return undefined;
const maxDebugBytes = Math.min(
debugDir.debugSize,
fileBytes.length - debugFileOffset,
);
const numEntries = Math.floor(maxDebugBytes / 28);
for (let j = 0; j < numEntries; j++) {
const entryOffset = debugFileOffset + j * 28;
const type = fileBytes.readUInt32LE(entryOffset + 12);
if (type !== 2) continue; // IMAGE_DEBUG_TYPE_CODEVIEW
const sizeOfData = fileBytes.readUInt32LE(entryOffset + 16);
let pointerToRawData = fileBytes.readUInt32LE(entryOffset + 24);
if (pointerToRawData === 0) {
const addressOfRawData = fileBytes.readUInt32LE(entryOffset + 20);
const mapped = peRvaToFileOffset(
addressOfRawData,
sectionTable,
numberOfSections,
debugDir.sizeOfHeaders,
Math.min(sizeOfData, 4096),
);
if (mapped === undefined) continue;
pointerToRawData = mapped;
}
if (
sizeOfData < 16 ||
fileBytes.length < pointerToRawData + Math.min(sizeOfData, 24)
)
continue;
const codeViewData = fileBytes.subarray(
pointerToRawData,
Math.min(fileBytes.length, pointerToRawData + sizeOfData),
);
const parsed = parseCodeViewData(codeViewData, sizeOfData);
if (parsed !== undefined) return parsed;
}
return undefined;
};
const peManagedStatus = (
optionalHeader: Buffer,
architecture: BinaryArchitecture,