Skip to content

fix(git): refuse a Windows junction in a Git directory that leads outside --repository - #5628

Open
cliffhall wants to merge 1 commit into
v2/mainfrom
v2/fix/5520-git-windows-junction
Open

cliffhall wants to merge 1 commit into
v2/mainfrom
v2/fix/5520-git-windows-junction

Conversation

@cliffhall

@cliffhall cliffhall commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

Closes #5520

Description

Under --repository, the server walks each Git directory it opens and refuses a symbolic link that resolves outside the allowed repository (#5514). A Windows directory junction slipped past that: to Python a junction is not a symbolic link (os.DirEntry.is_symlink() is false for one and is_dir() is true), so the walk took its "ordinary directory" arm, resolved the junction and walked its target without ever asking where that target was. Git follows a junction the way it follows a link.

_check_git_dir_contents now resolves every directory entry, not only symbolic links, and holds the result to the same boundary: inside the allowed repository or inside the Git directory being walked, otherwise the repository is refused with the existing "uses '…', which is outside the allowed repository" error. An ordinary directory resolves to itself and passes. A junction that stays inside is walked where it resolves, so what it leads to is checked too; one whose target is gone is not walked (before, the scan of the missing target failed the call).

The issue suggested detecting junctions with is_junction() on Python 3.12+ and a reparse-point attribute check on 3.10 and 3.11. Judging every directory by where it resolves needs no detection, so there is one code path for every supported Python and platform, no Windows-only branch for the Linux coverage gate to excuse, and a non-junction reparse point that redirects a directory (a volume mount point, say) is held to the boundary as well.

Server Details

  • Server: git
  • Changes to: the --repository confinement check (_check_git_dir_contents in src/git/src/mcp_server_git/server.py); README; tests. No tool, schema or description changes.

Motivation and Context

#5520, the follow-up left open by GHSA-q74p-4wrc-q7w6 under "Not covered by this fix". Windows only; POSIX hosts were not affected.

How Has This Been Tested?

Tests (src/git/tests/test_junction.py, new, all through the real server and an in-memory client):

  • Real junctions made with mklink /J, Windows only, so they run on the Test git (Windows) CI leg: a junction at .git/objects or .git/refs leading outside is refused; a junction that stays inside is followed and a second junction behind it leading outside is refused; junctions that stay inside (and a hooks junction, and a cycle) are accepted; a dangling junction inside is not walked; a dangling junction outside is refused.
  • The same three scenarios on every platform with junction-like entries: os.scandir is wrapped so a directory symlink answers as a junction does (is_symlink() false, is_dir() true). These are what the Linux coverage gate sees.

Failing without the fix: on POSIX, with server.py restored from v2/main, the three junction-like tests fail (the two "leading outside" cases and "followed and checked") and pass with the fix.

On Windows, from CI (Python 3.10, the version the leg pins):

  • This branch, Test git (Windows): tests\test_junction.py .........., all 10 pass, none skipped, the real-junction tests included.
  • The same tests with server.py restored from v2/main, on a throwaway branch where the tests expected to fail were marked xfail (strict for the refusal tests, so the job would have failed had any passed), Test git (Windows): tests\test_junction.py xxxxxx..xx, 8 xfailed. Every real-junction refusal test and both dangling-junction tests fail without the fix; only the two "stay inside" acceptance tests pass, as they should. That branch had no PR and is deleted.

Not exercised on Windows: Python 3.12 and later, since the leg runs only the pinned 3.10. The change does not branch on the Python version.

Clients (macOS, where a junction cannot exist, so these show the unchanged behavior of the rewritten walk, not the Windows case): a server started with --repository <allowed>, where <allowed>/.git/extra is a directory link that stays inside and <allowed>/nested/.git/refs is a directory link to another repository's refs.

  • Inspector CLI, --protocol-era legacy and --protocol-era modern, tools/call git_status:
    • repo_path=<allowed> → "isError":false, Repository status:\nOn branch main … in both eras (the modern result carries _meta io.modelcontextprotocol/serverInfo).
    • repo_path=<allowed>/nested → "isError":true, Repository path '<allowed>/nested' uses '<other>/.git/refs', which is outside the allowed repository '<allowed>' in both eras.
  • LLM client: Claude Code 2.1.327, headless (claude -p --mcp-config … --strict-mcp-config); the era cannot be selected or read from this client. Prompt: "Call the git_status tool of the git server twice: once with repo_path <allowed> and once with repo_path <allowed>/nested …". It reported the first call succeeded (Repository status:) and the second failed with the same "outside the allowed repository" error.

npm run local:gate exits 0; src/mcp_server_git/server.py stays at 100% lines and branches.

Breaking Changes

None for client configuration. On Windows, a repository whose Git directory holds a junction leading outside the --repository it is served under is now refused; that is the fix.

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 tool's error result is unchanged in shape)
  • 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 (not applicable: a Python server)
  • I have tested this with an LLM client
  • 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

@SalyyS1 prototyped a fix for this on the issue (an _is_junction helper using is_junction() with a reparse-point fallback, with mklink /J tests). This PR takes a different route in the walk, but the idea of exercising real junctions with mklink /J on the Windows leg is theirs. Thank you.

🤖 Generated with Claude Code

…side --repository

The walk of a git directory judged only symbolic links by where they
resolve. A Windows directory junction is not a symbolic link to Python
(DirEntry.is_symlink() is false, is_dir() true), so the walk entered its
target as an ordinary directory without checking where that was, and git
follows a junction as it follows a link.

Every directory entry is now resolved and held to the same boundary as a
link. An ordinary directory resolves to itself and passes, so no junction
detection is needed, which keeps one code path for Python 3.10 through
3.12+ (is_junction() exists only from 3.12). A dangling junction is no
longer walked.

Closes #5520

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

⚠️ No Changeset found

Latest commit: 7660d00

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

@github-actions

Copy link
Copy Markdown
Contributor

git: MCP interface diff

Base: 7f383a8e0f34 (Merge pull request #5597 from modelcontextprotocol/changeset-release/v2/main)
Head: the build in this checkout, at 2470dcf94f7a (Merge 7660d00 into 7f383a8)

Diffed because it was named (--server).

✅ No interface changes detected.

Tools Prompts Resources Resource templates
Base 14 2 0 0
Head 14 2 0 0

Updated by this run for 7660d0061605489e6b637d6adfd3e4a811218f68.

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

This Windows filesystem security-boundary change needs maintainer confirmation that native real- and dangling-junction tests pass, since Windows CI was still running and POSIX substitutes cannot validate native reparse-point behavior.

No open issues 🎉

What changed in this PR

This PR closes #5520 by extending the Git server’s --repository confinement check to reject Windows directory junctions that lead outside the permitted boundary.

Changes:

  • Checks the resolved destination of every directory entry and walks permitted targets while avoiding cycles and missing targets.
  • Adds real Windows junction tests and cross-platform junction-like regression tests.
  • Documents junction restrictions and the existing hooks exception.
File Description
src/​git/​tests/​test_junction.py Adds coverage for escaping, permitted, cyclic, and dangling junctions.
src/​git/​src/​mcp_server_git/​server.py Applies repository boundary checks to resolved directory entries.
src/​git/​README.md Documents Windows junction handling under --repository.

Review effort: Balanced

@cliffhall

Copy link
Copy Markdown
Member Author

Copilot round 1: clean, no findings and no suppressed comments, so the review loop ends here.

Its one note asked for confirmation that the native junction tests pass on Windows, which was still running at the time. They do: on this branch tests\test_junction.py runs all 10 tests on Test git (Windows) and all pass, and with the fix reverted 8 of them fail there (both runs are linked in the PR body under "How Has This Been Tested?").

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.

git: refuse a Windows junction in a Git directory that leads outside --repository

2 participants