From da1f029c2fd20b0d2bedf52a55503424d524de39 Mon Sep 17 00:00:00 2001 From: N0zoM1z0 <161784452+N0zoM1z0@users.noreply.github.com> Date: Wed, 11 Nov 2026 00:40:43 +0000 Subject: [PATCH] fix(artifacts): admit MFT captures through CLI and MCP Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com> --- docs/specs/native/ntfs-mft/spec.md | 4 +- src/application/BinaryTargetResolver.ts | 3 + .../binary/TargetFormatVocabularies.test.ts | 1 + .../ArtifactGraphConstruction.test.ts | 14 +++- .../inventory/ArtifactGraphConstruction.ts | 4 +- src/domain/analysisSnapshot.ts | 1 + src/domain/binaryTargetTypes.ts | 3 +- src/domain/liveBinaryTargetSummary.ts | 1 + src/domain/windows/ntfsMft.ts | 52 ++++++++++---- tests/boundary/mcp/ntfsMftAdmission.test.ts | 72 +++++++++++++++++++ 10 files changed, 134 insertions(+), 21 deletions(-) create mode 100644 tests/boundary/mcp/ntfsMftAdmission.test.ts diff --git a/docs/specs/native/ntfs-mft/spec.md b/docs/specs/native/ntfs-mft/spec.md index 20e5839d64..cd0e81d8da 100644 --- a/docs/specs/native/ntfs-mft/spec.md +++ b/docs/specs/native/ntfs-mft/spec.md @@ -15,8 +15,8 @@ its own. ## Requirements -- Recognize a `$MFT` stream by the `FILE` signature of its first record, under - any file name, and route it to a dedicated artifact reader. +- Recognize a `$MFT` stream by a plausible first `FILE` record header under + any file name. CLI and MCP target admission route it to the artifact reader. - Validate each FILE record header: the `FILE` signature, sequence number, flags, used and total byte counts, base record reference, and the update-sequence array's offset, count and array bounds. diff --git a/src/application/BinaryTargetResolver.ts b/src/application/BinaryTargetResolver.ts index 68845303df..819d7acf20 100644 --- a/src/application/BinaryTargetResolver.ts +++ b/src/application/BinaryTargetResolver.ts @@ -97,6 +97,7 @@ import { isDfuSeFile, } from "../domain/firmware/dfuse.js"; import { hasFitImagesNode } from "../domain/firmware/fitImage.js"; +import { hasMftFileRecordHeader } from "../domain/windows/ntfsMft.js"; import { locateEspFlashLayout, type EspFlashSelection, @@ -816,6 +817,7 @@ const detectArtifactFormat = async ( }); if (esp === "esp-image") return "esp-image"; if (hasFitImagesNode(magic)) return "fit"; + if (hasMftFileRecordHeader(magic)) return "ntfs-mft"; // Binary plists, including keyed archives, often use other extensions. if (hasBinaryPlistSignature(magic)) return "plist"; const named = namedArtifactFormat(lower); @@ -899,6 +901,7 @@ const isArchiveFormat = ( "dfuse", "esp-flash-image", "fit", + "ntfs-mft", ].includes(format); /** Whether the leading bytes begin any executable header family, valid or not. */ diff --git a/src/application/binary/TargetFormatVocabularies.test.ts b/src/application/binary/TargetFormatVocabularies.test.ts index 299093c9d1..476111853e 100644 --- a/src/application/binary/TargetFormatVocabularies.test.ts +++ b/src/application/binary/TargetFormatVocabularies.test.ts @@ -135,6 +135,7 @@ const TARGETS: TargetFixtures = { espFlash: { selected: true, flashOffset: null, partitionTableOffset: null }, }, fit: { ...archive, format: "fit" }, + "ntfs-mft": { ...archive, format: "ntfs-mft" }, plist: { ...artifact, format: "plist" }, javascript: { ...artifact, format: "javascript" }, "source-map": { ...artifact, format: "source-map" }, diff --git a/src/artifacts/inventory/ArtifactGraphConstruction.test.ts b/src/artifacts/inventory/ArtifactGraphConstruction.test.ts index f475e0c105..f10a6fbd28 100644 --- a/src/artifacts/inventory/ArtifactGraphConstruction.test.ts +++ b/src/artifacts/inventory/ArtifactGraphConstruction.test.ts @@ -576,9 +576,10 @@ it("classifies nested UF2 by block magics and DfuSe by prefix and suffix", () => ).toMatchObject({ format: "file" }); }); -it("classifies a $MFT stream by its FILE record signature, under any name", () => { +it("classifies a $MFT stream by its FILE record header, under any name", () => { const mft = Buffer.alloc(2_048); mft.write("FILE", 0, "latin1"); + mft.writeUInt32LE(1024, 28); for (const path of ["evidence/$MFT", "evidence/mft.raw", "evidence/records"]) expect(classifyArtifactBytesAtPath(path, mft)).toEqual({ kind: "executable", @@ -586,6 +587,17 @@ it("classifies a $MFT stream by its FILE record signature, under any name", () = }); }); +it("leaves plain content beginning with FILE unclassified as MFT", () => { + const text = Buffer.from( + "FILE is a plain text prefix, not an NTFS record header", + ); + expect( + classifyArtifactBytesAtPath("evidence/readme.txt", text), + ).toMatchObject({ + format: "file", + }); +}); + it("classifies a FIT by a /images node within the first 4 KiB", () => { const images = [{ name: "kernel", data: Buffer.from("kernel") }]; const late = devicetreeFixture({ diff --git a/src/artifacts/inventory/ArtifactGraphConstruction.ts b/src/artifacts/inventory/ArtifactGraphConstruction.ts index 1ef1bb46f3..a493327d90 100644 --- a/src/artifacts/inventory/ArtifactGraphConstruction.ts +++ b/src/artifacts/inventory/ArtifactGraphConstruction.ts @@ -11,7 +11,7 @@ import { recognizeEspImage } from "../../domain/firmware/espImage.js"; import { hasUf2Block } from "../../domain/firmware/uf2.js"; import { isDfuSeFile } from "../../domain/firmware/dfuse.js"; import { hasFitImagesNode } from "../../domain/firmware/fitImage.js"; -import { hasMftFileRecordSignature } from "../../domain/windows/ntfsMft.js"; +import { hasMftFileRecordHeader } from "../../domain/windows/ntfsMft.js"; import type { ArtifactClassificationEvidence } from "../ArtifactClassificationProbe.js"; import { asarHeaderAdmissionFailure } from "../AsarHeader.js"; import { hasDestinationPath } from "../ArtifactPaths.js"; @@ -623,7 +623,7 @@ export const classifyArtifactBytes = ( return "dfuse"; if (recognizeEspImage(prefix, fileSize) === "esp-image") return "esp-image"; if (hasFitImagesNode(prefix)) return "fit"; - if (hasMftFileRecordSignature(prefix)) return "ntfs-mft"; + if (hasMftFileRecordHeader(prefix)) return "ntfs-mft"; if (hasBinaryPlistSignature(prefix)) return "plist"; if (hasXmlPlistSignature(prefix)) return "plist"; const fatFormat = classifyFatArtifact(evidence, fileSize); diff --git a/src/domain/analysisSnapshot.ts b/src/domain/analysisSnapshot.ts index 42d4894415..91c24cfe8a 100644 --- a/src/domain/analysisSnapshot.ts +++ b/src/domain/analysisSnapshot.ts @@ -86,6 +86,7 @@ const formatSchema = z.enum([ "dfuse", "esp-flash-image", "fit", + "ntfs-mft", "plist", "javascript", "source-map", diff --git a/src/domain/binaryTargetTypes.ts b/src/domain/binaryTargetTypes.ts index 22e6f3e848..755912e203 100644 --- a/src/domain/binaryTargetTypes.ts +++ b/src/domain/binaryTargetTypes.ts @@ -302,7 +302,8 @@ export type BinaryTarget = | "esp-image" | "uf2" | "dfuse" - | "fit"; + | "fit" + | "ntfs-mft"; }) | (BinaryTargetIdentity & NonExecutableMetadata & { diff --git a/src/domain/liveBinaryTargetSummary.ts b/src/domain/liveBinaryTargetSummary.ts index 45b6d9c0da..06ba951fc7 100644 --- a/src/domain/liveBinaryTargetSummary.ts +++ b/src/domain/liveBinaryTargetSummary.ts @@ -83,6 +83,7 @@ export const liveBinaryTargetSummaryVariants = [ "uf2", "dfuse", "fit", + "ntfs-mft", ]), architecture: z.null(), }), diff --git a/src/domain/windows/ntfsMft.ts b/src/domain/windows/ntfsMft.ts index a1c9232b8c..415919112e 100644 --- a/src/domain/windows/ntfsMft.ts +++ b/src/domain/windows/ntfsMft.ts @@ -5,17 +5,12 @@ import type { } from "../firmware/regionDecoder.js"; /** An NTFS FILE record begins with this signature. */ -export const MFT_FILE_RECORD_MAGIC = "FILE"; -export const MFT_FILE_RECORD_MAGIC_BYTES = 4; +const MFT_FILE_RECORD_MAGIC = "FILE"; +const MFT_FILE_RECORD_MAGIC_BYTES = 4; /** The shortest header worth reading: a FILE record header ends at `nextAttributeId`. */ const NTFS_MFT_MIN_RECORD_BYTES = 42; -/** - * The `FILE` signature at file offset 0. An MFT stream is a run of fixed-size - * FILE records, so the first record's signature is the recognition fact; - * whether every record parses is the reader's question, not classification's. - */ -export const hasMftFileRecordSignature = (prefix: Uint8Array): boolean => +const hasMftFileRecordSignature = (prefix: Uint8Array): boolean => prefix.length >= MFT_FILE_RECORD_MAGIC_BYTES && text(prefix.subarray(0, MFT_FILE_RECORD_MAGIC_BYTES)) === MFT_FILE_RECORD_MAGIC; @@ -166,6 +161,39 @@ const isRecordSize = (bytes: number): boolean => bytes <= MFT_MAX_RECORD_BYTES && (bytes & (bytes - 1)) === 0; +const updateSequenceArrayFits = ( + offset: number, + entries: number, + sectors: number, +): boolean => + entries >= USA_MIN_ENTRIES && + entries <= sectors + 1 && + offset >= NTFS_MFT_MIN_RECORD_BYTES && + offset % 2 === 0 && + offset + entries * 2 <= FIXUP_SECTOR_BYTES - 2; + +/** Recognize a FILE header without requiring its trailers or attributes to verify. */ +export const hasMftFileRecordHeader = (prefix: Uint8Array): boolean => { + if ( + prefix.length < NTFS_MFT_MIN_RECORD_BYTES || + !hasMftFileRecordSignature(prefix) + ) + return false; + const view = new DataView( + prefix.buffer, + prefix.byteOffset, + prefix.byteLength, + ); + return ( + isRecordSize(view.getUint32(RECORD_HEADER.totalBytes, true)) || + updateSequenceArrayFits( + view.getUint16(RECORD_HEADER.updateSequenceOffset, true), + view.getUint16(RECORD_HEADER.updateSequenceCount, true), + MFT_DEFAULT_RECORD_BYTES / FIXUP_SECTOR_BYTES, + ) + ); +}; + /** * Parse FILE record headers and verify their update-sequence fixups. * @@ -350,13 +378,7 @@ const verifyFixups = ( // Entry 0 holds the sequence number, so sector n's saved trailer is entry n+1. const coveredSectors = Math.max(0, usaCount - 1); - if ( - usaCount < USA_MIN_ENTRIES || - coveredSectors > sectors || - usaOffset < NTFS_MFT_MIN_RECORD_BYTES || - usaOffset % 2 !== 0 || - usaOffset + usaCount * 2 > FIXUP_SECTOR_BYTES - 2 - ) + if (!updateSequenceArrayFits(usaOffset, usaCount, sectors)) return { sequenceNumber: 0, entries: usaCount, diff --git a/tests/boundary/mcp/ntfsMftAdmission.test.ts b/tests/boundary/mcp/ntfsMftAdmission.test.ts new file mode 100644 index 0000000000..bcd46c86e7 --- /dev/null +++ b/tests/boundary/mcp/ntfsMftAdmission.test.ts @@ -0,0 +1,72 @@ +import { writeFile } from "node:fs/promises"; +import { join } from "node:path"; + +import { expect } from "vitest"; + +import { createBinarySession } from "../../../src/composition/binary.js"; +import { parseConfig } from "../../../src/config/parseConfig.js"; +import { artifactInspectionResultSchema } from "../../../src/domain/artifactInspection.js"; +import { parseEvidence } from "../../../src/domain/evidence.js"; +import { silentLogger } from "../../../src/logger.js"; +import { createServer } from "../../../src/server/createServer.js"; +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; +import { mcpTest } from "../../support/mcp/mcpFixture.js"; +import { serveCli } from "../cli/cliServeHarness.js"; + +const expectMftInventory = (value: unknown): void => { + const evidence = parseEvidence(value); + const inspection = artifactInspectionResultSchema.parse( + evidence.normalized_result, + ); + const inventory = inspection.substeps[0]?.evidence.normalized_result; + expect(inventory?.manifest.root_format).toBe("ntfs-mft"); + expect(inventory?.occurrences[0]?.format_metadata).toMatchObject({ + kind: "ntfs-mft", + record_count: 1, + fixup_unverified_record_count: 0, + }); +}; + +mcpTest( + "admits an MFT capture by signature through CLI and MCP", + async ({ mcp, onTestFinished }) => { + const root = await createTestTempDirectory("rea-ntfs-mft-admission-"); + const path = join(root, "capture.bin"); + const record = Buffer.alloc(1024); + record.write("FILE"); + record.writeUInt16LE(42, 4); + record.writeUInt16LE(3, 6); + record.writeUInt16LE(1, 16); + record.writeUInt32LE(56, 24); + record.writeUInt32LE(1024, 28); + record.writeUInt16LE(5, 42); + record.writeUInt16LE(5, 510); + record.writeUInt16LE(5, 1022); + await writeFile(path, record); + + const cli = await serveCli(["inspect-artifact", path, "--json"]); + expect(cli.exitCode, cli.stdout).toBe(0); + expectMftInventory(JSON.parse(cli.stdout)); + + const configured = parseConfig({ REA_ANALYSIS_PROVIDER: "auto" }); + if (!configured.ok) throw configured.error; + const session = createBinarySession(configured.value, silentLogger, {}); + onTestFinished(async () => { + await session.close(); + }); + const client = await mcp.connect( + createServer({ kind: "session", session }), + ); + const opened = await client.callTool({ + name: "open_binary", + arguments: { path }, + }); + expect(opened.isError, JSON.stringify(opened.content)).not.toBe(true); + const inspected = await client.callTool({ + name: "inspect_artifact", + arguments: {}, + }); + expect(inspected.isError, JSON.stringify(inspected.content)).not.toBe(true); + expectMftInventory(inspected.structuredContent); + }, +);