From 985fa2fac939d0da5de31d59a4df055d90df1cd8 Mon Sep 17 00:00:00 2001 From: XiaoBinGan <35291372+XiaoBinGan@users.noreply.github.com> Date: Thu, 12 Nov 2026 18:54:16 +0800 Subject: [PATCH] fix(pe): keep pefile's unrounded raw offset for a sub-page section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `createPefileReadCompatibility` models pefile's section reads so an import hash is published only when both readers see the same bytes. Its layout gate rejected any section whose `PointerToRawData` was not 512-aligned — but pefile 2024.8.26's `get_PointerToRawData_adj()` skips that rounding when `SectionAlignment < 0x1000` and `PointerToRawData == VirtualAddress`, the `LdrpWx86FormatVirtualImage` layout ntoskrnl-era drivers use. The gate already modelled the sub-page case two lines above (`SectionAlignment < 0x1000 ? FileAlignment : SectionAlignment`), then rejected it against an absolute 512 rule — and `docs/pe-imports.md` scopes the withhold to an incomplete table or a different row sequence, not to a file offset. Measured on a minimal image with `SectionAlignment = FileAlignment = 0x80` and `.idata` at RVA 0x300 == file offset 0x300: | | before | after | | --- | --- | --- | | coverage | `complete` | `complete` | | issues | `[]` | `[]` | | `imphash.md5` | `null` | `92cef6cc91a85825f3c8a0516517c66f` | The withheld hash is the only thing that differed: both readers were already reading the same bytes. The exception is exact rather than approximate — a section with the same sub-page alignment whose `PointerToRawData` differs from its `VirtualAddress` still withholds, because pefile does round it there. That case is the second new test. pefile's current `master` broadened the condition to every sub-page image; this matches the 2024.8.26 revision the module documents, which is the narrower and safer rule. `tests/fixtures/binaryDiagnostics/peImports.ts` takes an optional `layout`, so the shared builder produces the geometry instead of a test hand-encoding a second image. Its default is unchanged — `SectionAlignment`/`FileAlignment` are written only when supplied, so every existing fixture keeps its exact bytes. `src/native/pe` — 265 passing. Restoring the absolute 512 rule fails the sub-page case. --- src/native/pe/PeImportParser.test.ts | 49 ++++++++++++++ src/native/pe/PefileReadCompatibility.ts | 10 ++- tests/fixtures/binaryDiagnostics/peImports.ts | 64 +++++++++++++++---- 3 files changed, 111 insertions(+), 12 deletions(-) diff --git a/src/native/pe/PeImportParser.test.ts b/src/native/pe/PeImportParser.test.ts index 0dc813cfe6..9049ab75fd 100644 --- a/src/native/pe/PeImportParser.test.ts +++ b/src/native/pe/PeImportParser.test.ts @@ -258,6 +258,55 @@ it("withholds the hash beyond pefile's section parser capacity", async () => { expect(report.imphash.reason).toMatch(/mapping|compatibility/u); }); +it("hashes a sub-page-aligned section pefile reads at its unrounded offset", async () => { + // SectionAlignment == FileAlignment == 0x80 with .idata at RVA 0x300 == file offset 0x300: + // pefile 2024.8.26 keeps PointerToRawData unrounded when it equals VirtualAddress + // (LdrpWx86FormatVirtualImage), so both readers see the same bytes and the hash is provable. + const report = await parse( + peImportImage({ + bits: 64, + layout: { + sectionRva: 0x300, + sectionOffset: 0x300, + headerBytes: 0x200, + sectionAlignment: 0x80, + fileAlignment: 0x80, + }, + }), + ); + expect(report.imports[0]?.functions.map((row) => row.name)).toEqual([ + "GetProcAddress", + "ExitProcess", + ]); + expect(report.coverage.status).toBe("complete"); + expect(report.issues).toEqual([]); + expect(report.imphash.reason).toBeNull(); + expect(report.imphash.md5).toBe( + createHash("md5") + .update("kernel32.getprocaddress,kernel32.exitprocess", "utf8") + .digest("hex"), + ); +}); + +it("still withholds the hash when a sub-page section rounds to a different offset", async () => { + // Same sub-page alignment, but PointerToRawData 0x380 differs from VirtualAddress 0x400, so + // pefile does round it and the native mapping is not the one pefile reads. + const report = await parse( + peImportImage({ + bits: 64, + layout: { + sectionRva: 0x400, + sectionOffset: 0x380, + headerBytes: 0x200, + sectionAlignment: 0x80, + fileAlignment: 0x80, + }, + }), + ); + expect(report.coverage.status).toBe("complete"); + expect(report.imphash.md5).toBeNull(); + expect(report.imphash.reason).toMatch(/mapping|compatibility/u); +}); it.each([false, true])( "withholds the hash when pefile stops at an earlier section (suspicious: %s)", async (suspicious) => { diff --git a/src/native/pe/PefileReadCompatibility.ts b/src/native/pe/PefileReadCompatibility.ts index 101efb2487..36f928dbee 100644 --- a/src/native/pe/PefileReadCompatibility.ts +++ b/src/native/pe/PefileReadCompatibility.ts @@ -32,6 +32,14 @@ export const createPefileReadCompatibility = ( section.raw_size === 0 && section.raw_offset === 0 && section.characteristics === 0; + // pefile 2024.8.26 `get_PointerToRawData_adj()` skips the 512-byte rounding below the page + // size when the section's `PointerToRawData` equals its `VirtualAddress` — the + // `LdrpWx86FormatVirtualImage` layout ntoskrnl-era drivers use, where `SectionAlignment` and + // `FileAlignment` are both sub-page and the two values coincide. The gate models + // `adjust_PointerToRawData`, so it has to model that exception too, or such an image loses + // its hash while both readers are already reading the same bytes. + const unroundedRawOffset = + image.pe_section_alignment < 0x1000 && section.raw_offset === start; const sectionWarnings = Number(section.raw_offset + section.raw_size > fileBytes) + Number(Math.floor(section.raw_offset / 512) * 512 > fileBytes) + @@ -45,7 +53,7 @@ export const createPefileReadCompatibility = ( emptyHeader || sectionWarnings >= 3 || (alignment > 0 && start % alignment !== 0) || - section.raw_offset % 0x200 !== 0 || + (!unroundedRawOffset && section.raw_offset % 0x200 !== 0) || start < previousEnd ) layoutAgrees = false; diff --git a/tests/fixtures/binaryDiagnostics/peImports.ts b/tests/fixtures/binaryDiagnostics/peImports.ts index d09ff99295..fa0c493e06 100644 --- a/tests/fixtures/binaryDiagnostics/peImports.ts +++ b/tests/fixtures/binaryDiagnostics/peImports.ts @@ -8,6 +8,36 @@ const SPLIT_GAP_BYTES = 0x200; export const peImportFixtureOffset = (rva: number): number => rva - SECTION_RVA + SECTION_OFFSET; +interface PeImportLayout { + readonly sectionRva: number; + readonly sectionOffset: number; + readonly headerBytes: number; + /** Written only when supplied; the default fixtures leave both fields zero. */ + readonly sectionAlignment?: number | undefined; + readonly fileAlignment?: number | undefined; +} + +const peImportLayout = ( + requested: Partial | undefined, +): PeImportLayout => ({ + sectionRva: requested?.sectionRva ?? SECTION_RVA, + sectionOffset: requested?.sectionOffset ?? SECTION_OFFSET, + headerBytes: requested?.headerBytes ?? HEADER_BYTES, + sectionAlignment: requested?.sectionAlignment, + fileAlignment: requested?.fileAlignment, +}); + +const writePeImportAlignments = ( + bytes: Buffer, + optional: number, + layout: PeImportLayout, +): void => { + if (layout.sectionAlignment !== undefined) + bytes.writeUInt32LE(layout.sectionAlignment, optional + 32); + if (layout.fileAlignment !== undefined) + bytes.writeUInt32LE(layout.fileAlignment, optional + 36); +}; + type PeImportFixtureFunction = | { readonly name: string; readonly hint?: number } | { readonly ordinal: number }; @@ -35,9 +65,20 @@ export const peImportImage = ( readonly delayDirectory?: boolean; readonly sectionBytes?: number; readonly splitAt?: number; + /** + * Section geometry, when the image must not use the default one. + * + * `sectionAlignment`/`fileAlignment` are written only when supplied; the default fixtures + * leave those optional-header fields zero, and changing that would rewrite their bytes. + */ + readonly layout?: Partial; } = {}, ): Buffer => { const sectionBytes = options.sectionBytes ?? SECTION_BYTES; + const layout = peImportLayout(options.layout); + const sectionRva = layout.sectionRva; + const sectionOffset = layout.sectionOffset; + const headerBytes = layout.headerBytes; const bits = options.bits ?? 64; const dlls = options.dlls ?? [ { @@ -49,7 +90,7 @@ export const peImportImage = ( }, ]; const delayDlls = options.delayDlls ?? []; - const bytes = Buffer.alloc(SECTION_OFFSET + sectionBytes); + const bytes = Buffer.alloc(sectionOffset + sectionBytes); const wide = bits === 64; const thunkSize = wide ? 8 : 4; bytes.write("MZ", 0, "ascii"); @@ -65,21 +106,22 @@ export const peImportImage = ( if (wide) bytes.writeBigUInt64LE(0x180000000n, optional + 24); else bytes.writeUInt32LE(0x10000000, optional + 28); bytes.writeUInt32LE(16, optional + directoriesAt - 4); - bytes.writeUInt32LE(HEADER_BYTES, optional + 60); + bytes.writeUInt32LE(headerBytes, optional + 60); + writePeImportAlignments(bytes, optional, layout); const section = optional + optionalSize; bytes.write(".idata", section, "ascii"); bytes.writeUInt32LE(sectionBytes, section + 8); - bytes.writeUInt32LE(SECTION_RVA, section + 12); + bytes.writeUInt32LE(sectionRva, section + 12); bytes.writeUInt32LE(sectionBytes, section + 16); - bytes.writeUInt32LE(SECTION_OFFSET, section + 20); + bytes.writeUInt32LE(sectionOffset, section + 20); bytes.writeUInt32LE(0x40000040, section + 36); - const at = (rva: number) => rva - SECTION_RVA + SECTION_OFFSET; + const at = (rva: number) => rva - sectionRva + sectionOffset; const writeThunk = (rva: number, value: bigint): void => { if (wide) bytes.writeBigUInt64LE(value, at(rva)); else bytes.writeUInt32LE(Number(value), at(rva)); }; - let cursor = SECTION_RVA; + let cursor = sectionRva; const place = (size: number): number => { const rva = cursor; cursor += size; @@ -152,18 +194,18 @@ export const peImportImage = ( if (options.splitAt === undefined) return bytes; const head = options.splitAt; const tail = sectionBytes - head; - const moved = SECTION_OFFSET + sectionBytes + SPLIT_GAP_BYTES; + const moved = sectionOffset + sectionBytes + SPLIT_GAP_BYTES; const split = Buffer.alloc(moved + tail); - bytes.copy(split, 0, 0, SECTION_OFFSET + head); - split.fill(0xcc, SECTION_OFFSET + head, moved); - bytes.copy(split, moved, SECTION_OFFSET + head); + bytes.copy(split, 0, 0, sectionOffset + head); + split.fill(0xcc, sectionOffset + head, moved); + bytes.copy(split, moved, sectionOffset + head); split.writeUInt16LE(2, 134); split.writeUInt32LE(head, section + 8); split.writeUInt32LE(head, section + 16); const second = section + 40; split.write(".idata2", second, "ascii"); split.writeUInt32LE(tail, second + 8); - split.writeUInt32LE(SECTION_RVA + head, second + 12); + split.writeUInt32LE(sectionRva + head, second + 12); split.writeUInt32LE(tail, second + 16); split.writeUInt32LE(moved, second + 20); split.writeUInt32LE(0x40000040, second + 36);