Skip to content

fix(filesystem): check a listed directory before and after the read on Windows - #5622

Open
cliffhall wants to merge 1 commit into
v2/mainfrom
v2/fix/5600-filesystem-windows-listing-anchor
Open

cliffhall wants to merge 1 commit into
v2/mainfrom
v2/fix/5600-filesystem-windows-listing-anchor

Conversation

@cliffhall

Copy link
Copy Markdown
Member

Closes #5600

Description

On Windows a directory listing (list_directory, list_directory_with_sizes, directory_tree, search_files) had no protection against a directory swapped for a junction between validation and the read: the chdir anchor that holds on macOS and Linux proves nothing there (Node resolves . from the working-directory string, #5260), and unlike reads and writes a listing had no check of its own.

readDirectoryInPlace() now checks the listed directory on both sides of the read, on Windows only (issue option 2):

  • its last component is a directory (lstat reports a junction or directory symlink as a link);
  • its native real path is itself, so no component of the path is a link (validatePath returned the path from the same native realpath);
  • the directory has the same identity (volume serial + file id, BigInt lstat) before and after.

Anything else is refused with the existing "Access denied - a directory on the path changed during the operation".

What this does and does not guarantee. A swap that is in place when the read starts or when it ends is refused, which includes the simple case of a directory swapped after validation and left swapped. A swap made and undone between the two checks is not detected and still returns the outside directory's entry names. The window is narrowed, not closed, so the issue's first acceptance criterion ("never yields entries from outside") is met for a swap that persists, not for a swap-and-swap-back. Closing it needs handle-relative opens, which is native code (issue option 1); the maintainers ruled that out for this reference server on #5260, and this PR does not revisit it. The README's "Limit on Windows" entry now says exactly this for listings.

Issue option 3 (listing a readable-but-not-enterable directory through /proc/self/fd on Linux) is optional in the issue and is not in this PR.

Server Details

  • Server: filesystem
  • Changes to: the four listing tools' behavior on Windows (a new refusal), README, tests

Motivation and Context

Follow-up to GHSA-rq2p-q7c4-6g27 (published, fixed in v2.5.0), which anchored listings on macOS and Linux only. See #5600.

How Has This Been Tested?

The changed branch runs only on Windows, so the evidence that counts is the Test filesystem (Windows) CI job on this PR, which runs the whole suite on windows-latest:

  • __tests__/list-anchored.test.ts: the protocol-level swap tests (an MCP client over the in-memory transport; a directory swapped for a link right after validation realpath's it) were skipped on Windows and now run there, with a junction. Each of the four tools must refuse and must not return the outside directory's entry name.
  • __tests__/list-anchored-windows.test.ts (new): the check itself, on every host. On Windows it runs for real against junctions; elsewhere process.platform is set to win32 and the filesystem stays real, which is also how the Linux coverage gate sees the branch. Cases: nothing swapped; the directory is a link; a parent is a link (the leaf is a real directory, only the real path shows it); a swap staged from inside the read, of the directory and of a parent; another real directory taking the name during the read (identity).

Before/after, on macOS with process.platform set to win32: with pinned-directory.ts from v2/main, 5 of the new file's 7 tests fail (the outside directory is listed); with this change all pass.

No regression off Windows, Inspector CLI 2.12.0 against the built server, both eras (--protocol-era modern and legacy), on macOS:

  • tools/call list_directory path=<dir> → [DIR] sub
  • tools/call directory_tree path=<dir> → sub with child a.txt
  • tools/call search_files path=<dir> pattern=**/*.txt → <dir>/sub/a.txt

Not tested: an LLM client or the Inspector against a server running on Windows (no Windows host available to me), and a real concurrent racer. npm run local:gate exits 0.

Breaking Changes

None. No configuration change. On Windows, a listing of a directory that changed under it now fails with an error where it previously returned entries.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Protocol Documentation (not applicable: no protocol surface changes; the tools' schemas and annotations are untouched)
  • My changes follow MCP security best practices
  • I have updated the server's README accordingly
  • I have added a changeset (npm run changeset) if this changes what a TypeScript server publishes
  • I have tested this with an LLM client (not applicable: the change runs only on Windows and no Windows host was available; the Windows CI leg drives it through an MCP client, and the Inspector CLI shows no regression on macOS in both eras)
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have documented all environment variables and configuration options (not applicable: none added)

Additional context

  • inDirectory() is unchanged; the check is inside readDirectoryInPlace()'s action and in one helper at the end of the file.
  • The identity of the two checks is compared directly (dev and ino), not through isSameEntry: both are path stats, so its size-and-mtime fallback for a path-against-handle comparison on older libuv would only refuse a directory another process legitimately wrote to during the read.

🤖 Generated with Claude Code

…n Windows

On Windows a directory listing could not be anchored (the working directory
is a path string there) and had no check at all, so a directory swapped for a
junction after validation was listed. readDirectoryInPlace now checks the
listed directory on both sides of the read: its path must resolve to itself
(no junction or symlink on it) and name the same directory by identity, or
the listing is refused as a changed directory.

A swap still in place before or after the read is refused. One made and
undone between the two checks is not detected; closing that needs
handle-relative opens (native code, #5260), so the README states it as a
narrowed, not closed, limit.

The swap tests in list-anchored.test.ts now run on Windows too, with a
junction, and list-anchored-windows.test.ts covers the check on every host.

Closes #5600

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Signed-off-by: cliffhall <cliff@futurescale.com>
@cliffhall cliffhall added the v2 label Nov 18, 2026
@changeset-bot

changeset-bot Bot commented Nov 18, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 062b32a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
@modelcontextprotocol/server-filesystem Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@github-actions

Copy link
Copy Markdown
Contributor

filesystem: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 253abd53da59 (Merge 062b32a into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 16 0 0 1
Head 16 0 0 1

Updated by this run for 062b32a52fb8d6bfab96ae7085aeca6bae06eade.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Maintainer judgment is needed on residual swap-and-swap-back entry-name disclosure that falls short of #5600’s unconditional no-outside-entries criterion, and native Windows CI evidence still needs confirmation.

No open issues 🎉

What changed in this PR

Adds Windows-specific directory-listing checks to the filesystem server, addressing #5600 by rejecting persistent directory swaps. This narrows the race window but does not detect swaps made and undone between checks; macOS and Linux behavior remains unchanged.

Changes:

  • Checks directory type, canonical path, and identity before and after Windows listings.
  • Enables junction-swap protocol tests on Windows and adds focused checks for directory and parent replacements.
  • Documents the remaining Windows limitation and adds a patch changeset.
File Description
src/​filesystem/​README.md Explains listing checks and the remaining Windows race window.
src/​filesystem/​pinned-directory.ts Adds Windows directory validation and identity comparison around listings.
src/​filesystem/​__tests__/​list-anchored.test.ts Enables Windows junction-swap tests for all four listing tools.
src/​filesystem/​__tests__/​list-anchored-windows.test.ts Adds focused coverage for Windows checks and unchanged non-Windows behavior.
.changeset/​filesystem-windows-listing-check.md Records the filesystem patch and its security limitations.

Review effort: Balanced

@cliffhall

Copy link
Copy Markdown
Member Author

Copilot round 1: a clean round (no inline comments, no suppressed comments, "No open issues"), so the review loop ends here.

Its overview raises two points for the maintainer, answered here since they have no thread:

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[GHSA-rq2p-q7c4-6g27 follow-up] - filesystem: directory listings are not anchored on Windows

2 participants