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 },