From ab1b9e35d0e64bcc67b3d9dd1b5c72af2422c60f Mon Sep 17 00:00:00 2001 From: Husnain Maroof Date: Mon, 9 Nov 2026 17:16:13 +0500 Subject: [PATCH] fix(entropy)!: own selected Windows path spelling at admission (#9393) * fix(evidence)!: keep one Evidence identity across Windows path case On Windows, an existing caller path now takes its filesystem spelling when that spelling differs from the resolved path by letter case alone. One file spelled `C:\Temp\x.bin`, `c:\temp\x.bin` or `C:\TEMP\X.BIN` produces one `parameters.path`, `normalized_result` path and `evidence_id`, matching the existing separator and `.` folding. `caller_input_path` keeps the input. Links, junctions, `subst` drives, 8.3 short names and paths that do not exist yet keep the caller spelling, so no link is followed and requested output names keep their case. BREAKING CHANGE: Windows Evidence produced from a path spelled in a case other than its filesystem spelling now gets a different `evidence_id`. Fixes #9373 Co-Authored-By: Claude Opus 5.5 * fix(entropy): keep Windows casing lookup optional * ci(entropy): select Windows identity verification --------- Co-authored-by: Claude Opus 5.5 Co-authored-by: morluto <76467478+morluto@users.noreply.github.com> --- .github/workflows/ci.yml | 1 + docs/guides/native/binary-diagnostics.md | 6 ++ scripts/ci/scopes.mjs | 3 + .../ByteEntropyService.test.ts | 28 ++++++++ .../binaryDiagnostics/ByteEntropyService.ts | 56 ++++++++++----- .../byteEntropyWindowsIdentity.test.ts | 72 +++++++++++++++++++ tests/boundary/filesystem/callerPath.test.ts | 13 ++++ .../boundary/filesystem/ciChangeScope.test.ts | 8 +++ 8 files changed, 168 insertions(+), 19 deletions(-) create mode 100644 tests/acceptance/byteEntropyWindowsIdentity.test.ts diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index d32237206e..50a843fb81 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -924,6 +924,7 @@ jobs: tests/process-global/filesystemSnapshotFallbackCancellation.test.ts tests/boundary/filesystem/typescriptCompiler.test.ts tests/boundary/filesystem/releaseProposal.test.ts + tests/acceptance/byteEntropyWindowsIdentity.test.ts tests/boundary/filesystem/binaryTarget.test.ts src/contracts/sessionPathInputs.test.ts tests/boundary/filesystem/directAnalysisSnapshotReplay.test.ts diff --git a/docs/guides/native/binary-diagnostics.md b/docs/guides/native/binary-diagnostics.md index 269ba021b2..193f5501b0 100644 --- a/docs/guides/native/binary-diagnostics.md +++ b/docs/guides/native/binary-diagnostics.md @@ -272,6 +272,12 @@ regular files only and rejects symbolic links. ## Byte entropy triage +Entropy admission preserves the caller's spelling in `caller_input_path`. On +Windows, the selected regular file's case-only filesystem spelling is used +consistently in committed paths through both CLI and MCP. Symlink, junction and +short-name aliases are not replaced with a different path. General path +normalization remains lexical and does not probe source-discovered paths. + `inspect_byte_entropy` / `inspect-byte-entropy` profiles any local regular file without an analysis engine, execution, extraction or network access. diff --git a/scripts/ci/scopes.mjs b/scripts/ci/scopes.mjs index 4eae115ee2..167f5fb837 100644 --- a/scripts/ci/scopes.mjs +++ b/scripts/ci/scopes.mjs @@ -182,6 +182,9 @@ const PATH_SCOPES = { // Four-host installed-package matrix and the Windows curated lane. package: [ ...WINDOWS_EXECUTABLE_SELECTION_INPUTS, + // Selected-file spelling requires the real Windows identity workflow. + "src/application/binaryDiagnostics/ByteEntropyService.ts", + "tests/acceptance/byteEntropyWindowsIdentity.test.ts", // Both host compilers must be exercised when their installation, options, // or entrypoints change; Linux's accelerated checker cannot stand in for Go. "scripts/run-typescript.*", diff --git a/src/application/binaryDiagnostics/ByteEntropyService.test.ts b/src/application/binaryDiagnostics/ByteEntropyService.test.ts index c0f2a5fd45..0fa02b0660 100644 --- a/src/application/binaryDiagnostics/ByteEntropyService.test.ts +++ b/src/application/binaryDiagnostics/ByteEntropyService.test.ts @@ -623,3 +623,31 @@ it.each([false, true])( expect(result.error.cleanupIncomplete).toBe(false); }, ); + +it("reads an admitted file even when Windows casing lookup is unavailable", async () => { + const root = await createTestTempDirectory("rea-entropy-casing-unavailable-"); + const path = join(root, "readable.bin"); + await writeFile(path, Buffer.from([1, 2, 3, 4])); + // The injected descriptor represents a readable share while the optional + // host spelling lookup has no path on this filesystem. + const selected = join(root, "share-selection.bin"); + const platform = vi + .spyOn(process, "platform", "get") + .mockReturnValue("win32"); + const service = new ByteEntropyService({ + stat: ((...args: Parameters) => + stat(path, args[1])) as typeof stat, + open: async () => open(path, "r"), + }); + try { + const result = await service.inspect({ path: selected }); + if (!result.ok) throw result.error; + expect(result.value.normalized_result).toMatchObject({ + artifact: { bytes: 4 }, + }); + expect(result.value.caller_input_path).toBe(selected); + } finally { + await service.close(); + platform.mockRestore(); + } +}); diff --git a/src/application/binaryDiagnostics/ByteEntropyService.ts b/src/application/binaryDiagnostics/ByteEntropyService.ts index a845e45b58..ae5cc1f564 100644 --- a/src/application/binaryDiagnostics/ByteEntropyService.ts +++ b/src/application/binaryDiagnostics/ByteEntropyService.ts @@ -1,6 +1,7 @@ +import { absoluteCallerPath } from "../../filesystem/callerPath.js"; import { createHash } from "node:crypto"; import { constants } from "node:fs"; -import { open, stat } from "node:fs/promises"; +import { open, realpath, stat } from "node:fs/promises"; import type { ExecutionOptions } from "../AnalysisProvider.js"; import { BYTE_ENTROPY_PROVIDER } from "../../domain/investigationProviders.js"; import { AnalysisError } from "../../domain/analysisErrorBase.js"; @@ -12,7 +13,11 @@ import { AnalysisInputError, AnalysisResourceConstraintError, } from "../../domain/analysisErrorCore.js"; -import { createEvidence, type Evidence } from "../../domain/evidence.js"; +import { + createEvidence, + withEvidenceCallerInputPath, + type Evidence, +} from "../../domain/evidence.js"; import { byteEntropySchema, computeBlockEntropy, @@ -103,25 +108,30 @@ export class ByteEntropyService { options?.signal, ); if (!parsed.ok) return parsed; - const input = parsed.value; + let input = parsed.value; + const callerInputPath = input.path; + input = { ...input, path: absoluteCallerPath(input.path) }; const evidenceFromReport = (report: ByteEntropy): Evidence => - createEvidence( - { path: input.path, format: "file", sha256: report.artifact.sha256 }, - BYTE_ENTROPY_PROVIDER, - { - operation: OPERATION, - parameters: { - path: input.path, - block_size: input.block_size, - offset: input.offset, - ...(input.length === undefined ? {} : { length: input.length }), + withEvidenceCallerInputPath( + createEvidence( + { path: input.path, format: "file", sha256: report.artifact.sha256 }, + BYTE_ENTROPY_PROVIDER, + { + operation: OPERATION, + parameters: { + path: input.path, + block_size: input.block_size, + offset: input.offset, + ...(input.length === undefined ? {} : { length: input.length }), + }, + result: report, + rawResult: null, + confidence: "observed", + limitations: report.limitations, + locations: [{ kind: "artifact-path", path: input.path }], }, - result: report, - rawResult: null, - confidence: "observed", - limitations: report.limitations, - locations: [{ kind: "artifact-path", path: input.path }], - }, + ), + callerInputPath, ); // Cleanup errors erase the callback's generic type. Validate their completed // value before publishing it as this operation's observation. @@ -176,6 +186,14 @@ export class ByteEntropyService { const before = await this.files.stat(input.path, { bigint: true }); if (!before.isFile()) throw invalid("path", "Expected a regular file."); admitted = true; + // Only an admitted selected file may consult filesystem spelling. Do not + // replace symlink/junction/8.3 aliases or touch source-derived paths. + if (process.platform === "win32") { + const canonical = await realpath(input.path).catch(() => undefined); + assertArtifactReadActive(options?.signal); + if (canonical?.toLowerCase() === input.path.toLowerCase()) + input = { ...input, path: canonical }; + } const file = await this.files.open( input.path, constants.O_RDONLY | constants.O_NONBLOCK, diff --git a/tests/acceptance/byteEntropyWindowsIdentity.test.ts b/tests/acceptance/byteEntropyWindowsIdentity.test.ts new file mode 100644 index 0000000000..c0f979a8d3 --- /dev/null +++ b/tests/acceptance/byteEntropyWindowsIdentity.test.ts @@ -0,0 +1,72 @@ +import { Client, InMemoryTransport } from "@modelcontextprotocol/client"; +import { createServer } from "../../src/server/createServer.js"; +import { createTestBinarySession } from "../fixtures/binarySession.js"; +import { realpath, writeFile } from "node:fs/promises"; +import { join } from "node:path"; +import { describe, expect } from "vitest"; +import { createTestTempDirectory } from "../fixtures/temporaryDirectory.js"; +import { cliTest } from "../support/cli/cliFixture.js"; +import { ByteEntropyService } from "../../src/application/binaryDiagnostics/ByteEntropyService.js"; +import { parseEvidence } from "../../src/domain/evidence.js"; + +describe.skipIf(process.platform !== "win32")( + "Windows selected-file spelling", + () => { + cliTest( + "shares entropy identity across service/MCP admission and CLI case spellings", + async ({ cli }) => { + const root = await realpath( + await createTestTempDirectory("rea-EntropyCase-"), + ); + const path = join(root, "Sample.BIN"); + await writeFile(path, Buffer.from([1, 2, 3, 4])); + const service = new ByteEntropyService(); + const session = createTestBinarySession(() => { + throw new Error("No analysis provider should start"); + }); + const server = createServer({ kind: "session", session }); + const client = new Client({ name: "entropy-case", version: "1" }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + await server.connect(serverTransport); + await client.connect(clientTransport); + try { + const ids = new Set(); + for (const spelling of [ + path, + path.toUpperCase(), + path.toLowerCase(), + path.replaceAll("\\", "/"), + `${root}\\.\\Sample.BIN`, + ]) { + const direct = await service.inspect({ path: spelling }); + if (!direct.ok) throw direct.error; + const fromCli = await cli.run({ + arguments: ["inspect-byte-entropy", spelling, "--json"], + }); + expect(fromCli.exitCode, fromCli.stderr).toBe(0); + const evidence = parseEvidence(fromCli.json); + const response = await client.callTool({ + name: "inspect_byte_entropy", + arguments: { path: spelling }, + }); + expect(response.isError).not.toBe(true); + const mcpEvidence = parseEvidence(response.structuredContent); + ids.add(mcpEvidence.evidence_id); + expect(mcpEvidence.caller_input_path).toBe(spelling); + ids.add(evidence.evidence_id); + ids.add(direct.value.evidence_id); + expect(direct.value.caller_input_path).toBe(spelling); + expect(evidence.caller_input_path).toBe(spelling); + } + expect(ids.size).toBe(1); + } finally { + await client.close(); + await server.close(); + await session.close(); + await service.close(); + } + }, + ); + }, +); diff --git a/tests/boundary/filesystem/callerPath.test.ts b/tests/boundary/filesystem/callerPath.test.ts index 38e755ef69..aa7cbfd53d 100644 --- a/tests/boundary/filesystem/callerPath.test.ts +++ b/tests/boundary/filesystem/callerPath.test.ts @@ -71,3 +71,16 @@ it("normalizes separator spellings of absolute Windows paths (#4707)", () => { ]) expect(absoluteCallerPath(spelling, win32)).toBe("C:\\Users\\u\\h.exe"); }); + +it("keeps unselected Windows share paths lexical", () => { + expect( + absoluteCallerPath("\\\\unselected-server\\share\\Source.JS", { + platform: "win32", + }), + ).toBe("\\\\unselected-server\\share\\Source.JS"); + expect( + absoluteCallerPath("C:\\CaseSensitive\\Different.js", { + platform: "win32", + }), + ).toBe("C:\\CaseSensitive\\Different.js"); +}); diff --git a/tests/boundary/filesystem/ciChangeScope.test.ts b/tests/boundary/filesystem/ciChangeScope.test.ts index dbbc598740..01606fa7df 100644 --- a/tests/boundary/filesystem/ciChangeScope.test.ts +++ b/tests/boundary/filesystem/ciChangeScope.test.ts @@ -832,6 +832,14 @@ it.each([ { code: true, runtime: true, package: true }, ], ["src/adb/AdbConfiguration.ts", { code: true, runtime: true, package: true }], + [ + "src/application/binaryDiagnostics/ByteEntropyService.ts", + { code: true, runtime: true, package: true }, + ], + [ + "tests/acceptance/byteEntropyWindowsIdentity.test.ts", + { code: true, runtime: true, package: true }, + ], [ "src/apktool/ApktoolConfiguration.ts", { code: true, runtime: true, package: true },