From 73bc95d23f8ef1ad5c5b29a6e811b9bf85d02853 Mon Sep 17 00:00:00 2001 From: N0zoM1z0 <161784452+N0zoM1z0@users.noreply.github.com> Date: Wed, 11 Nov 2026 00:19:42 +0000 Subject: [PATCH] feat(ntfs): decode resident MFT file names after fixups Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com> --- docs/specs/native/ntfs-mft/spec.md | 12 ++- src/domain/windows/ntfsMft.test.ts | 34 +++++++ src/domain/windows/ntfsMft.ts | 153 ++++++++++++++++++++++++----- 3 files changed, 170 insertions(+), 29 deletions(-) diff --git a/docs/specs/native/ntfs-mft/spec.md b/docs/specs/native/ntfs-mft/spec.md index fa9b4e9038..7eb482f691 100644 --- a/docs/specs/native/ntfs-mft/spec.md +++ b/docs/specs/native/ntfs-mft/spec.md @@ -32,9 +32,11 @@ its own. `limit` failure with its boundary. - Return the first 32 decoded record headers with their source offsets and the number of omitted headers. Aggregate counts cover the full parsed stream. -- Parse only the records' headers and fixups. Attributes, filenames, data - streams and the `$UsnJrnl:$J` journal are not decoded in this step, so no path, - file size, file reference correlation or change history is claimed. +- Restore verified sector trailers in a per-record scratch buffer before + scanning attributes. The domain decoder retains resident `$FILE_NAME` + names, namespaces, parent references and source offsets. Report incomplete + coverage when the walk cannot finish or an attribute list may refer to + extensions. The inventory does not yet expose the individual names. ## Acceptance @@ -47,5 +49,5 @@ Inventory tests cover the root occurrence's metadata and the coverage status when a fixup fails, and classification tests cover several file names for the same bytes. -Not covered in this step: real `$MFT` files written by a Windows host, USN -journal records, attribute decoding, and any correlation between the two. +Pending verification with real `$MFT` files written by a Windows host. USN +journal records and correlation remain future steps. diff --git a/src/domain/windows/ntfsMft.test.ts b/src/domain/windows/ntfsMft.test.ts index 470000ad96..12418fd709 100644 --- a/src/domain/windows/ntfsMft.test.ts +++ b/src/domain/windows/ntfsMft.test.ts @@ -232,6 +232,40 @@ describe("MFT fixup coverage", () => { ); }, ); + it("decodes a FILE_NAME across a restored sector trailer without changing the source bytes", () => { + const bytes = recordOf(); + const view = new DataView(bytes.buffer); + const attribute = 416; + const value = attribute + 24; + view.setUint16(20, attribute, true); + view.setUint32(24, 528, true); + view.setUint32(attribute, 0x30, true); + view.setUint32(attribute + 4, 104, true); + view.setUint32(attribute + 16, 76, true); + view.setUint16(attribute + 20, 24, true); + view.setBigUint64(value, 0x1234_0000_0000_0005n, true); + bytes.set([5, 1], value + 64); + bytes.set(Buffer.from("names", "utf16le"), value + 66); + view.setUint16(50, view.getUint16(510, true), true); + view.setUint16(510, view.getUint16(48, true), true); + view.setUint32(520, 0xffff_ffff, true); + const original = bytes.slice(); + + const parsed = parseMftImage(bytes); + if (!parsed.ok) throw new Error(parsed.error.message); + expect(parsed.value.records[0]).toMatchObject({ + fileNameCoverage: "complete", + fileNames: [ + { + fileOffset: value, + parent: { recordNumber: 5, sequenceNumber: 0x1234 }, + namespace: 1, + name: "names", + }, + ], + }); + expect(bytes).toEqual(original); + }); it("keeps a record whose sector trailer is not the sequence number, and reports it", () => { const parsed = parseMftImage( diff --git a/src/domain/windows/ntfsMft.ts b/src/domain/windows/ntfsMft.ts index e274acb695..cec24d8054 100644 --- a/src/domain/windows/ntfsMft.ts +++ b/src/domain/windows/ntfsMft.ts @@ -82,6 +82,13 @@ const decodeMftFileReference = (reference: bigint): MftFileReference => ({ sequenceNumber: Number(reference >> 48n), }); +export interface MftFileName { + readonly fileOffset: number; + readonly parent: MftFileReference; + readonly namespace: number; + readonly name: string; +} + export interface MftRecord { /** Zero-based ordinal of this record in the stream. */ readonly index: number; @@ -108,11 +115,14 @@ export interface MftRecord { readonly recordNumberMatchesSlot: boolean | null; /** `$LogFile` sequence number as recorded; no log is read. */ readonly logFileSequenceNumber: string; - /** Declared offset of the first attribute; no attribute decoding follows yet. */ + /** Declared offset of the first attribute. */ readonly firstAttributeOffset: number; /** Declared id of the next attribute; no attribute decoding follows yet. */ readonly nextAttributeId: number; readonly fixups: MftRecordFixups; + readonly fileNames: readonly MftFileName[]; + /** An incomplete scan can still retain names from the valid prefix. */ + readonly fileNameCoverage: "complete" | "incomplete"; } export interface MftInventory { @@ -136,7 +146,10 @@ export interface MftMetadata { readonly fixup_mismatch_count: number; readonly fixup_unverified_record_count: number; readonly truncated_tail_bytes: number; - readonly record_headers: readonly MftRecord[]; + readonly record_headers: readonly Omit< + MftRecord, + "fileNames" | "fileNameCoverage" + >[]; readonly omitted_record_headers: number; } @@ -210,13 +223,8 @@ export const hasMftFileRecordHeader = (prefix: Uint8Array): boolean => { }; /** - * Parse FILE record headers and verify their update-sequence fixups. - * - * Only the record structure is established: attributes, their names, the - * filenames and the USN journal are left to later steps, so no path, timestamp - * or file identity beyond the record itself is claimed. A record whose fixup - * does not match keeps its header facts, because the stream still declares it, - * and the mismatch is reported on the record and counted in the metadata. + * Parse FILE record headers and resident file names. A record with failed + * fixups keeps its header facts; its attributes are left unread. */ export const parseMftImage = ( bytes: Uint8Array, @@ -257,6 +265,8 @@ const scanMft = ( let extensionCount = 0; let mismatchCount = 0; let unverifiedCount = 0; + const restored = Buffer.allocUnsafe(recordBytes); + let incompleteNames = 0; let invalidSlots = 0; let invalidExtents = 0; let inconsistentRecordNumbers = 0; @@ -277,7 +287,7 @@ const scanMft = ( if (!isRecordSize(declaredRecordBytes)) break; continue; } - const record = readRecord(bytes, offset, offset / recordBytes, recordBytes); + const record = readRecord(bytes, offset, restored); retainedRecords?.push(record); if (recordHeaders.length < MFT_INLINE_HEADER_LIMIT) recordHeaders.push(record); @@ -293,6 +303,7 @@ const scanMft = ( unverifiedCount += 1; if (record.recordNumberMatchesSlot === false) inconsistentRecordNumbers += 1; + if (record.fileNameCoverage === "incomplete") incompleteNames += 1; if (!record.extentValid) { invalidExtents += 1; firstInvalidExtentOffset ??= offset; @@ -328,6 +339,11 @@ const scanMft = ( `${String(unverifiedCount)} record(s) carry an invalid or incomplete update sequence array; their sector trailers were not fully verified`, ); + if (incompleteNames > 0) + limitations.push( + `File name coverage is incomplete for ${String(incompleteNames)} record(s)`, + ); + const metadata: MftMetadata = { kind: "ntfs-mft", record_bytes: recordBytes, @@ -338,7 +354,10 @@ const scanMft = ( fixup_mismatch_count: mismatchCount, fixup_unverified_record_count: unverifiedCount, truncated_tail_bytes: truncatedTailBytes, - record_headers: recordHeaders, + record_headers: recordHeaders.map( + ({ fileNames: _fileNames, fileNameCoverage: _coverage, ...header }) => + header, + ), omitted_record_headers: recordCount - recordHeaders.length, }; @@ -348,9 +367,10 @@ const scanMft = ( const readRecord = ( bytes: Uint8Array, fileOffset: number, - index: number, - recordBytes: number, + restored: Buffer, ): MftRecord => { + const recordBytes = restored.length; + const index = fileOffset / recordBytes; const record = bytes.subarray(fileOffset, fileOffset + recordBytes); const view = new DataView( record.buffer, @@ -372,12 +392,35 @@ const readRecord = ( RECORD_HEADER.firstAttributeOffset, true, ); - const usaLayoutValid = updateSequenceArrayFits( usaOffset, fixups.entries, recordBytes / FIXUP_SECTOR_BYTES, ); + const extentValid = + totalBytes === recordBytes && + usedBytes >= NTFS_MFT_MIN_RECORD_BYTES && + usedBytes % 8 === 0 && + usedBytes <= totalBytes && + firstAttributeOffset % 8 === 0 && + firstAttributeOffset >= NTFS_MFT_MIN_RECORD_BYTES && + firstAttributeOffset + 4 <= usedBytes && + (!usaLayoutValid || + firstAttributeOffset >= usaOffset + fixups.entries * 2); + const fileNames: MftFileName[] = []; + const completeNames = + fixups.verifiedSectors === recordBytes / FIXUP_SECTOR_BYTES && + extentValid && + readFileNames( + record, + view, + restored, + firstAttributeOffset, + usedBytes, + fileOffset, + fileNames, + ); + const declaredRecordNumber = usaLayoutValid && usaOffset >= RECORD_HEADER_WITH_NUMBER_BYTES ? view.getUint32(RECORD_HEADER.recordNumber, true) @@ -393,16 +436,7 @@ const readRecord = ( directory: (flags & FILE_RECORD_IS_DIRECTORY) !== 0, usedBytes, totalBytes, - extentValid: - totalBytes === recordBytes && - usedBytes >= NTFS_MFT_MIN_RECORD_BYTES && - usedBytes % 8 === 0 && - usedBytes <= totalBytes && - firstAttributeOffset % 8 === 0 && - firstAttributeOffset >= NTFS_MFT_MIN_RECORD_BYTES && - firstAttributeOffset + 4 <= usedBytes && - (!usaLayoutValid || - firstAttributeOffset >= usaOffset + fixups.entries * 2), + extentValid, baseRecordReference: baseRecordReference === 0n ? null @@ -416,9 +450,80 @@ const readRecord = ( firstAttributeOffset, nextAttributeId: view.getUint16(RECORD_HEADER.nextAttributeId, true), fixups, + fileNames, + fileNameCoverage: completeNames ? "complete" : "incomplete", }; }; +const ATTRIBUTE_END = 0xffff_ffff; +const ATTRIBUTE_LIST = 0x20; +const ATTRIBUTE_FILE_NAME = 0x30; +const RESIDENT_HEADER_BYTES = 24; +const FILE_NAME_HEADER_BYTES = 66; + +const readFileNames = ( + record: Uint8Array, + raw: DataView, + restored: Buffer, + firstAttributeOffset: number, + usedBytes: number, + fileOffset: number, + names: MftFileName[], +): boolean => { + restored.set(record.subarray(0, usedBytes)); + const usaOffset = raw.getUint16(RECORD_HEADER.updateSequenceOffset, true); + for ( + let end = FIXUP_SECTOR_BYTES; + end <= usedBytes + 1; + end += FIXUP_SECTOR_BYTES + ) + restored.writeUInt16LE( + raw.getUint16(usaOffset + 2 * (end / FIXUP_SECTOR_BYTES), true), + end - 2, + ); + + let hasAttributeList = false; + for (let offset = firstAttributeOffset; offset + 4 <= usedBytes;) { + const type = restored.readUInt32LE(offset); + if (type === ATTRIBUTE_END) return !hasAttributeList; + if (offset + RESIDENT_HEADER_BYTES > usedBytes) return false; + const length = restored.readUInt32LE(offset + 4); + const form = restored.readUInt8(offset + 8); + const headerBytes = form === 0 ? RESIDENT_HEADER_BYTES : 64; + if ( + form > 1 || + length < headerBytes || + length % 8 !== 0 || + offset + length > usedBytes + ) + return false; + if (type === ATTRIBUTE_LIST) hasAttributeList = true; + if (type === ATTRIBUTE_FILE_NAME) { + if (form !== 0) return false; + const valueLength = restored.readUInt32LE(offset + 16); + const valueOffset = restored.readUInt16LE(offset + 20); + if ( + valueOffset < headerBytes || + valueLength < FILE_NAME_HEADER_BYTES || + valueOffset + valueLength > length + ) + return false; + const value = offset + valueOffset; + const nameBytes = restored.readUInt8(value + 64) * 2; + if (FILE_NAME_HEADER_BYTES + nameBytes > valueLength) return false; + const nameStart = value + FILE_NAME_HEADER_BYTES; + names.push({ + fileOffset: fileOffset + value, + parent: decodeMftFileReference(restored.readBigUInt64LE(value)), + namespace: restored.readUInt8(value + 65), + name: restored.toString("utf16le", nameStart, nameStart + nameBytes), + }); + } + offset += length; + } + return false; +}; + /** * Each sector's last two bytes are replaced on disk by the update sequence * number; the array's first entry is that number and the rest are the saved