fsguard-mcp 0.1.0__tar.gz

fsguard_mcp-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/
+.env
+dist/
+build/

fsguard_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: fsguard-mcp
+Version: 0.1.0
+Summary: Filesystem + git MCP server confined by symlink-resolved path containment, not string prefix matching.
+Author: Berkant Acun
+License: MIT
+Keywords: filesystem,git,mcp,model-context-protocol,sandbox,security
+Requires-Python: >=3.10
+Requires-Dist: dulwich>=0.22.0
+Requires-Dist: mcp>=1.2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fsguard-mcp
+
+A filesystem + git MCP server that confines every operation to an allowed
+directory tree using **symlink-resolved path containment**, not string
+prefix matching.
+
+## Why this exists
+
+Anthropic's own official filesystem and git MCP servers (`@modelcontextprotocol/server-filesystem`, part of `modelcontextprotocol/servers`, 89.7k★) have carried **five separate path-confinement CVEs across two servers in ten months**, and the pattern is still active:
+
+- **CVE-2025-53109 / CVE-2025-53110** (filesystem, CVSS 8.4/7.3) — the "allowed directory" check used naive `startsWith()` prefix matching, defeated by symlinks and by sibling directories that merely *share a string prefix* (e.g. an allowed `/home/user-safe` also matches `/home/user-safe-evil`), giving filesystem-wide read/write and a documented RCE path.
+- **CVE-2025-68143 / CVE-2025-68144 / CVE-2025-68145** (git) — `git_init` accepted arbitrary unvalidated paths, `git_diff`/`git_checkout` passed user-controlled arguments straight to the `git` CLI (argument injection), and `--repository`-confined mode didn't actually verify `repo_path` stayed inside the confined directory.
+- **CVE-2026-27735** (git, disclosed ~2 months before this project started) — `git_add`, implemented via GitPython's `repo.index.add()`, doesn't enforce working-tree boundaries for `../`-style paths, allowing staging and exfiltrating files outside the repo.
+- A documented RCE chain: `git_init` in a writable directory → a malicious `.git/config` with a "clean" filter → a `.gitattributes` that applies it → `git_add` triggers the filter → arbitrary shell command runs.
+
+Every one of these was patched with *another string/prefix check bolted onto that one function*. Nobody moved the boundary enforcement to a place a new tool can't simply forget to include — which is exactly how the fourth CVE landed four months after the first three were "fixed."
+
+## How fsguard-mcp is different
+
+1. **One safety primitive, used everywhere.** Every tool — filesystem or git — resolves its target path through the same `ConfinedRoot` (see `confined_path.py`) before doing anything else. There's no per-tool path check to forget.
+2. **Symlink-resolved, component-based containment — not string matching.** A path is only inside the root if its *fully resolved* real path (every symlink followed) is a real ancestor-relative subpath of the root's *own* resolved real path, checked with `Path.is_relative_to()` on resolved paths — never `startswith()` on a string. This alone closes CVE-2025-53109/53110's exact failure mode: `/allowed-evil` cannot pass a containment check against a resolved root of `/allowed`, because path-component comparison isn't string-prefix comparison.
+3. **No shelling out to `git` for content, ever.** Git operations run through `dulwich` — a pure-Python git implementation with no subprocess and no argv built from user input for anything content-related, and (critically) **no clean/smudge filter execution**, which is what the documented RCE chain depends on. There is no argument-injection surface here because there's no argument list being handed to an external process for reading/writing file content. (dulwich *does* still run `pre-commit`/`commit-msg`/`post-commit` hooks via `subprocess.call()` if they exist — real process execution, unrelated to content filtering. `git_commit` always passes `no_verify=True` to skip them categorically, rather than relying on them happening not to be runnable.)
+4. **Write operations validate the parent directory too**, not just an existing target — closing the class of bug where a target doesn't exist yet (so "does this path resolve inside the root" was checked against a path that doesn't exist, and therefore couldn't be symlink-resolved) but its parent directory is itself a symlink pointing outside. Non-existent path segments are lexically normalized (`.`/`..` collapsed as pure path algebra) *before* any of this, independent of what happens to exist on disk — an earlier version of this project checked containment before normalizing, which happened to pass all its tests on Windows (whose path APIs normalize `..` for you) while being bypassable on Linux/macOS. It's fixed now, and there are tests for the exact case, but it's the reason this project treats "the test suite is green on my machine" with real suspicion.
+5. **`.git/config` can't redirect operations outside the root.** dulwich honors a repo's own `core.worktree` config entry, and every git operation re-opens a `Repo` from a path string internally — so a caller could write a `.git/config` with `core.worktree` pointing anywhere, and every subsequent git tool would silently operate outside the confined root, invisible to the per-path check (which only ever sees the confined repo directory, never wherever dulwich actually redirected itself to). This was found in this project's own second-round security review — a real read/exfiltration primitive using nothing but this server's own exposed tools, more severe than any CVE it was built to fix. Every git tool now refuses to open a repo whose config sets `core.worktree` at all, and independently re-verifies that the `Repo` object it actually opened reports its working path as the exact directory that was validated.
+6. **UNC paths and cross-drive paths are rejected before touching the network or disk at all.** Resolving a `\\host\share\...` path makes Windows actually attempt an SMB connection — and Windows will try to authenticate that connection as the server process, which is the "forced NTLM auth via UNC path" credential-theft technique, on top of blocking the server for a full connection timeout against an unreachable host. A candidate anchored on a different drive or host than the confined root is now rejected by a cheap string comparison, before any filesystem or network call. NTFS Alternate Data Streams (`file.txt:hidden`) are also rejected outright — they're invisible to directory listings but fully readable/writable through the same path string, and can forge the absence of Windows' download-warning "Mark of the Web."
+
+## Tools
+
+| Tool | Does |
+|---|---|
+| `fs_read(path)` | Read a text file |
+| `fs_write(path, content)` | Create or overwrite a text file |
+| `fs_list(path=".")` | List a directory's entries |
+| `fs_search(pattern, path=".")` | Find files matching a glob pattern, recursively |
+| `fs_move(source, destination)` | Move/rename a file |
+| `git_init_repo(repo_path)` | Initialize a git repository |
+| `git_repo_status(repo_path=".")` | Staged/unstaged/untracked files |
+| `git_stage(repo_path, paths)` | Stage files |
+| `git_commit_repo(repo_path, message, author)` | Commit staged changes |
+| `git_diff_repo(repo_path=".", staged=False)` | Show a diff |
+| `git_log_repo(repo_path=".", max_entries=10)` | Show commit history |
+
+## Setup
+
+```bash
+pip install fsguard-mcp
+export FSGUARD_ROOT="/path/to/the/one/directory/tree/this/server/may/touch"
+fsguard-mcp
+```
+
+`FSGUARD_ROOT` is required — there is no default, and the server refuses to guess one. Point your MCP client at the `fsguard-mcp` command with `FSGUARD_ROOT` set in its env config.
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+All 68 tests are self-contained (real temp directories, real symlinks, real git repos) — no external services needed.
+
+## Known limitation
+
+Containment is checked, then a filesystem operation runs — there is an inherent TOCTOU (time-of-check-to-time-of-use) gap between the two. A concurrent process with write access to the confined root's own tree could in principle swap a symlink in that window (verified with a working proof-of-concept during review). Closing this fully needs an OS-level primitive (e.g. Linux `openat2(RESOLVE_BENEATH)`, a real mount namespace) rather than anything achievable in portable Python; this project's guarantee is "correct containment logic, checked immediately before use," not "immune to a concurrent attacker who can already write inside the root."
+
+## Status
+
+68 passing tests (unit-level, with real symlinks and real git repos created on disk — not just string-logic assertions). Went through two rounds of adversarial security review before its first commit; both found real, working bypasses (a `..`-traversal escape through not-yet-existing paths on POSIX, and the `core.worktree` redirection above, among smaller findings) that are now fixed and covered by tests written directly against the reported exploit. Not yet published to PyPI.
+
+## License
+
+MIT

fsguard_mcp-0.1.0/README.md

@@ -0,0 +1,72 @@
+# fsguard-mcp
+
+A filesystem + git MCP server that confines every operation to an allowed
+directory tree using **symlink-resolved path containment**, not string
+prefix matching.
+
+## Why this exists
+
+Anthropic's own official filesystem and git MCP servers (`@modelcontextprotocol/server-filesystem`, part of `modelcontextprotocol/servers`, 89.7k★) have carried **five separate path-confinement CVEs across two servers in ten months**, and the pattern is still active:
+
+- **CVE-2025-53109 / CVE-2025-53110** (filesystem, CVSS 8.4/7.3) — the "allowed directory" check used naive `startsWith()` prefix matching, defeated by symlinks and by sibling directories that merely *share a string prefix* (e.g. an allowed `/home/user-safe` also matches `/home/user-safe-evil`), giving filesystem-wide read/write and a documented RCE path.
+- **CVE-2025-68143 / CVE-2025-68144 / CVE-2025-68145** (git) — `git_init` accepted arbitrary unvalidated paths, `git_diff`/`git_checkout` passed user-controlled arguments straight to the `git` CLI (argument injection), and `--repository`-confined mode didn't actually verify `repo_path` stayed inside the confined directory.
+- **CVE-2026-27735** (git, disclosed ~2 months before this project started) — `git_add`, implemented via GitPython's `repo.index.add()`, doesn't enforce working-tree boundaries for `../`-style paths, allowing staging and exfiltrating files outside the repo.
+- A documented RCE chain: `git_init` in a writable directory → a malicious `.git/config` with a "clean" filter → a `.gitattributes` that applies it → `git_add` triggers the filter → arbitrary shell command runs.
+
+Every one of these was patched with *another string/prefix check bolted onto that one function*. Nobody moved the boundary enforcement to a place a new tool can't simply forget to include — which is exactly how the fourth CVE landed four months after the first three were "fixed."
+
+## How fsguard-mcp is different
+
+1. **One safety primitive, used everywhere.** Every tool — filesystem or git — resolves its target path through the same `ConfinedRoot` (see `confined_path.py`) before doing anything else. There's no per-tool path check to forget.
+2. **Symlink-resolved, component-based containment — not string matching.** A path is only inside the root if its *fully resolved* real path (every symlink followed) is a real ancestor-relative subpath of the root's *own* resolved real path, checked with `Path.is_relative_to()` on resolved paths — never `startswith()` on a string. This alone closes CVE-2025-53109/53110's exact failure mode: `/allowed-evil` cannot pass a containment check against a resolved root of `/allowed`, because path-component comparison isn't string-prefix comparison.
+3. **No shelling out to `git` for content, ever.** Git operations run through `dulwich` — a pure-Python git implementation with no subprocess and no argv built from user input for anything content-related, and (critically) **no clean/smudge filter execution**, which is what the documented RCE chain depends on. There is no argument-injection surface here because there's no argument list being handed to an external process for reading/writing file content. (dulwich *does* still run `pre-commit`/`commit-msg`/`post-commit` hooks via `subprocess.call()` if they exist — real process execution, unrelated to content filtering. `git_commit` always passes `no_verify=True` to skip them categorically, rather than relying on them happening not to be runnable.)
+4. **Write operations validate the parent directory too**, not just an existing target — closing the class of bug where a target doesn't exist yet (so "does this path resolve inside the root" was checked against a path that doesn't exist, and therefore couldn't be symlink-resolved) but its parent directory is itself a symlink pointing outside. Non-existent path segments are lexically normalized (`.`/`..` collapsed as pure path algebra) *before* any of this, independent of what happens to exist on disk — an earlier version of this project checked containment before normalizing, which happened to pass all its tests on Windows (whose path APIs normalize `..` for you) while being bypassable on Linux/macOS. It's fixed now, and there are tests for the exact case, but it's the reason this project treats "the test suite is green on my machine" with real suspicion.
+5. **`.git/config` can't redirect operations outside the root.** dulwich honors a repo's own `core.worktree` config entry, and every git operation re-opens a `Repo` from a path string internally — so a caller could write a `.git/config` with `core.worktree` pointing anywhere, and every subsequent git tool would silently operate outside the confined root, invisible to the per-path check (which only ever sees the confined repo directory, never wherever dulwich actually redirected itself to). This was found in this project's own second-round security review — a real read/exfiltration primitive using nothing but this server's own exposed tools, more severe than any CVE it was built to fix. Every git tool now refuses to open a repo whose config sets `core.worktree` at all, and independently re-verifies that the `Repo` object it actually opened reports its working path as the exact directory that was validated.
+6. **UNC paths and cross-drive paths are rejected before touching the network or disk at all.** Resolving a `\\host\share\...` path makes Windows actually attempt an SMB connection — and Windows will try to authenticate that connection as the server process, which is the "forced NTLM auth via UNC path" credential-theft technique, on top of blocking the server for a full connection timeout against an unreachable host. A candidate anchored on a different drive or host than the confined root is now rejected by a cheap string comparison, before any filesystem or network call. NTFS Alternate Data Streams (`file.txt:hidden`) are also rejected outright — they're invisible to directory listings but fully readable/writable through the same path string, and can forge the absence of Windows' download-warning "Mark of the Web."
+
+## Tools
+
+| Tool | Does |
+|---|---|
+| `fs_read(path)` | Read a text file |
+| `fs_write(path, content)` | Create or overwrite a text file |
+| `fs_list(path=".")` | List a directory's entries |
+| `fs_search(pattern, path=".")` | Find files matching a glob pattern, recursively |
+| `fs_move(source, destination)` | Move/rename a file |
+| `git_init_repo(repo_path)` | Initialize a git repository |
+| `git_repo_status(repo_path=".")` | Staged/unstaged/untracked files |
+| `git_stage(repo_path, paths)` | Stage files |
+| `git_commit_repo(repo_path, message, author)` | Commit staged changes |
+| `git_diff_repo(repo_path=".", staged=False)` | Show a diff |
+| `git_log_repo(repo_path=".", max_entries=10)` | Show commit history |
+
+## Setup
+
+```bash
+pip install fsguard-mcp
+export FSGUARD_ROOT="/path/to/the/one/directory/tree/this/server/may/touch"
+fsguard-mcp
+```
+
+`FSGUARD_ROOT` is required — there is no default, and the server refuses to guess one. Point your MCP client at the `fsguard-mcp` command with `FSGUARD_ROOT` set in its env config.
+
+## Testing
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+All 68 tests are self-contained (real temp directories, real symlinks, real git repos) — no external services needed.
+
+## Known limitation
+
+Containment is checked, then a filesystem operation runs — there is an inherent TOCTOU (time-of-check-to-time-of-use) gap between the two. A concurrent process with write access to the confined root's own tree could in principle swap a symlink in that window (verified with a working proof-of-concept during review). Closing this fully needs an OS-level primitive (e.g. Linux `openat2(RESOLVE_BENEATH)`, a real mount namespace) rather than anything achievable in portable Python; this project's guarantee is "correct containment logic, checked immediately before use," not "immune to a concurrent attacker who can already write inside the root."
+
+## Status
+
+68 passing tests (unit-level, with real symlinks and real git repos created on disk — not just string-logic assertions). Went through two rounds of adversarial security review before its first commit; both found real, working bypasses (a `..`-traversal escape through not-yet-existing paths on POSIX, and the `core.worktree` redirection above, among smaller findings) that are now fixed and covered by tests written directly against the reported exploit. Not yet published to PyPI.
+
+## License
+
+MIT

fsguard_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "fsguard-mcp"
+version = "0.1.0"
+description = "Filesystem + git MCP server confined by symlink-resolved path containment, not string prefix matching."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Berkant Acun" }]
+keywords = ["mcp", "model-context-protocol", "filesystem", "git", "security", "sandbox"]
+dependencies = [
+    "mcp>=1.2.0",
+    "dulwich>=0.22.0",
+]
+
+[project.scripts]
+fsguard-mcp = "fsguard_mcp.server:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fsguard_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

fsguard_mcp-0.1.0/src/fsguard_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""fsguard-mcp — filesystem + git MCP server confined by symlink-resolved
+path containment, not string prefix matching."""
+
+__version__ = "0.1.0"

fsguard_mcp-0.1.0/src/fsguard_mcp/confined_path.py

@@ -0,0 +1,169 @@
+"""
+The core safety primitive: symlink-resolved, component-based path
+containment. Every filesystem and git tool goes through this before
+touching disk — see README.md for why.
+
+The failure mode this fixes: CVE-2025-53109/53110 used `startsWith()`
+string-prefix matching on a path to decide if it was "inside" the
+allowed directory. That's defeated two ways: (1) a symlink inside the
+allowed root whose target is outside it — the string check never
+resolves the symlink, so it never sees the real destination; (2) a
+sibling directory that merely shares a string prefix with the allowed
+root (an allowed `/safe` also string-matches `/safe-evil`), which has
+nothing to do with actual containment.
+
+The fix here is to always resolve the candidate path through the real
+filesystem (following every symlink) and then compare using path
+*component* containment (`Path.is_relative_to()`), never string
+comparison. Two paths that share characters but differ in even one
+path component are never "contained" by this check, symlink or not.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+class PathEscapeError(ValueError):
+    """Raised when a path would resolve outside the confined root."""
+
+
+class ConfinedRoot:
+    """Confines all path resolution to a single directory tree."""
+
+    def __init__(self, root: str | Path) -> None:
+        resolved = Path(root).resolve(strict=True)
+        if not resolved.is_dir():
+            raise NotADirectoryError(f"Confined root is not a directory: {resolved}")
+        if resolved.parent == resolved:
+            # A drive root (C:\) or the POSIX root (/) itself — "confined"
+            # to one of these is not confinement at all. Almost always a
+            # misconfigured or forgotten FSGUARD_ROOT, not an intentional
+            # choice, and worth failing loudly rather than silently
+            # granting effectively unrestricted access.
+            raise ValueError(
+                f"Refusing to use a filesystem root as the confined root: {resolved}"
+            )
+        self.root = resolved
+
+    def resolve(self, candidate: str | Path, *, must_exist: bool = True) -> Path:
+        """Resolve `candidate` (relative to the root, or absolute) and
+        verify it's contained in the root after following every symlink.
+
+        must_exist=True (the default, for reads and anything that must
+        already exist) requires the full path to exist and resolves it
+        directly.
+
+        must_exist=False (for write targets that may not exist yet)
+        walks up to the nearest existing ancestor, resolves *that*
+        through any symlinks, and reattaches the non-existent tail —
+        so a symlinked parent directory pointing outside the root is
+        still caught, even though the final target itself is new.
+
+        Raises PathEscapeError if the resolved path is not the root
+        itself or a real descendant of it.
+        """
+        candidate_path = Path(candidate)
+        self._reject_alternate_data_streams(candidate_path)
+
+        combined = candidate_path if candidate_path.is_absolute() else (self.root / candidate_path)
+
+        # Cheap, filesystem-free rejection of anything anchored on a
+        # different drive or UNC host than the confined root — checked
+        # *before* anything below ever calls .exists()/.resolve(), which
+        # would otherwise make the OS actually attempt an SMB connection
+        # to an attacker-supplied \\host\share path. That's not just an
+        # escape risk: Windows will try to authenticate that connection
+        # as the server process, which is the textbook "forced NTLM auth
+        # via UNC path" credential-theft technique — and even a merely
+        # unreachable host blocks this synchronous server for the length
+        # of a full SMB connection timeout. A relative candidate always
+        # inherits the root's own drive here, so this never affects
+        # ordinary use.
+        if combined.drive.lower() != self.root.drive.lower():
+            raise PathEscapeError(
+                f"Path is anchored on a different drive or host than the confined root: {candidate!r}"
+            )
+
+        # The containment check always uses the missing-leaf-safe walk,
+        # whether or not the caller requires the path to exist — this is
+        # deliberate: it means "is this path allowed" and "does this
+        # path exist" are two separate questions, checked in that order,
+        # so a plain missing file surfaces as FileNotFoundError instead
+        # of being misreported as a security violation.
+        resolved = self._resolve_allowing_missing_leaf(combined)
+
+        if not self._is_contained(resolved):
+            raise PathEscapeError(
+                f"Path resolves outside the confined root {self.root}: {candidate!r} -> {resolved}"
+            )
+
+        if must_exist and not resolved.exists():
+            raise FileNotFoundError(f"Path does not exist: {candidate}")
+
+        return resolved
+
+    def _reject_alternate_data_streams(self, candidate_path: Path) -> None:
+        # NTFS Alternate Data Streams use "name:stream" syntax. A stream
+        # is invisible to iterdir()/rglob() (so fs_list/fs_search would
+        # never show it) but fully readable and writable through the
+        # same path string — enough to hide content from directory
+        # listings, or to write a ":Zone.Identifier" stream that forges
+        # the absence of Windows' "Mark of the Web" on a file. Reject any
+        # ':' outside the drive-letter position in any path component.
+        for i, part in enumerate(candidate_path.parts):
+            if i == 0 and candidate_path.drive:
+                continue  # e.g. "C:\\" itself, not a stream
+            if ":" in part:
+                raise PathEscapeError(
+                    f"Path component contains ':' (possible alternate data stream): {part!r}"
+                )
+
+    def _resolve_allowing_missing_leaf(self, combined: Path) -> Path:
+        # Step 1 — lexical normalization, BEFORE touching the
+        # filesystem at all. This is not optional: walking up to the
+        # nearest *existing* ancestor by repeatedly taking .parent
+        # treats a literal ".." component as just another path segment
+        # to pop, not as "go up a level" — so a not-yet-existing tail
+        # like "does/not/exist/../../../../outside.txt" would keep its
+        # ".." tokens completely uninterpreted, and the later
+        # containment check (a lexical comparison of path components)
+        # would see them as harmless extra segments still "under" the
+        # root, even though the real filesystem — once mkdir/move
+        # actually creates each missing ancestor — resolves them right
+        # out of the confined root. os.path.normpath() collapses "."
+        # and ".." purely as path algebra, with no filesystem access,
+        # so this can never depend on what happens to exist on disk.
+        normalized = Path(os.path.normpath(str(combined)))
+
+        # Step 2 — walk up the now ".."-free path to the nearest
+        # existing ancestor, resolve *that* through any symlinks, and
+        # reattach the (already-normalized, so safe to rejoin literally)
+        # missing tail. This is what catches a symlinked parent
+        # directory pointing outside the root even for a brand new file.
+        existing = normalized
+        missing_tail: list[str] = []
+        while not existing.exists():
+            if existing.parent == existing:
+                raise PathEscapeError(f"No existing ancestor found for: {combined}")
+            missing_tail.insert(0, existing.name)
+            existing = existing.parent
+
+        if missing_tail and not existing.is_dir():
+            # The nearest existing ancestor is a file, not a directory —
+            # e.g. candidate was "some-file.txt/nonsense/more.txt". Not a
+            # containment issue, but a file can't have children, so this
+            # is never a valid path; raise a clear error here rather than
+            # returning a nonsensical resolved path and letting a later
+            # OS-level call fail with a confusing error instead.
+            raise NotADirectoryError(f"Not a directory: {existing}")
+
+        resolved = existing.resolve(strict=True)
+        for part in missing_tail:
+            resolved = resolved / part
+        return resolved
+
+    def _is_contained(self, resolved: Path) -> bool:
+        # is_relative_to() already returns True when resolved == self.root.
+        return resolved.is_relative_to(self.root)

fsguard_mcp-0.1.0/src/fsguard_mcp/fs.py

@@ -0,0 +1,84 @@
+"""
+Filesystem tool functions. Every one resolves its path(s) through the
+passed-in ConfinedRoot before touching disk — there is deliberately no
+way to call these with a raw, unvalidated path, so a future function
+added here can't forget the check the way CVE-2026-27735 did for git.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import shutil
+
+from .confined_path import ConfinedRoot, PathEscapeError
+
+
+def fs_read_file(root: ConfinedRoot, path: str) -> str:
+    resolved = root.resolve(path, must_exist=True)
+    if resolved.is_dir():
+        raise IsADirectoryError(f"Not a file: {path}")
+    return resolved.read_text(encoding="utf-8")
+
+
+def fs_write_file(root: ConfinedRoot, path: str, content: str) -> None:
+    resolved = root.resolve(path, must_exist=False)
+    resolved.parent.mkdir(parents=True, exist_ok=True)
+    resolved.write_text(content, encoding="utf-8")
+
+
+def fs_list_directory(root: ConfinedRoot, path: str = ".") -> list[dict]:
+    resolved = root.resolve(path, must_exist=True)
+    if not resolved.is_dir():
+        raise NotADirectoryError(f"Not a directory: {path}")
+    return [
+        {"name": entry.name, "type": "directory" if entry.is_dir() else "file"}
+        for entry in sorted(resolved.iterdir(), key=lambda e: e.name)
+    ]
+
+
+def fs_move_file(root: ConfinedRoot, source: str, destination: str) -> None:
+    resolved_source = root.resolve(source, must_exist=True)
+    resolved_destination = root.resolve(destination, must_exist=False)
+    if resolved_destination.is_dir():
+        # shutil.move's "move *into* an existing directory" behavior
+        # would silently relocate the file to destination/<basename>
+        # instead of the literal destination path the caller asked
+        # for — reject instead of surprising the caller about where
+        # the file actually landed.
+        raise IsADirectoryError(
+            f"Destination already exists as a directory: {destination}"
+        )
+    resolved_destination.parent.mkdir(parents=True, exist_ok=True)
+    shutil.move(str(resolved_source), str(resolved_destination))
+
+
+def fs_search_files(root: ConfinedRoot, pattern: str, path: str = ".") -> list[str]:
+    resolved = root.resolve(path, must_exist=True)
+    if not resolved.is_dir():
+        raise NotADirectoryError(f"Not a directory: {path}")
+
+    # Deliberately os.walk(followlinks=False) rather than Path.rglob():
+    # not descending into symlinked subdirectories is a guarantee this
+    # project needs to hold, not an incidental default — rglob's
+    # symlink behavior has differed across Python versions, and this
+    # project supports 3.10+, so relying on "whichever pathlib happens
+    # to be installed does the safe thing" isn't good enough here.
+    matches = []
+    for dirpath, dirnames, filenames in os.walk(str(resolved), followlinks=False):
+        for name in filenames:
+            if fnmatch.fnmatch(name, pattern):
+                candidate = os.path.join(dirpath, name)
+                try:
+                    # Re-validate every match through the root anyway —
+                    # keeps the same "everything goes through
+                    # ConfinedRoot" invariant as every other tool. Only
+                    # a path-escape or an OS-level access problem should
+                    # exclude a match — anything else is a real bug and
+                    # should surface, not vanish into a silently shorter
+                    # result list.
+                    resolved_candidate = root.resolve(candidate, must_exist=True)
+                except (PathEscapeError, OSError):
+                    continue
+                matches.append(str(resolved_candidate.relative_to(root.root)))
+    return sorted(matches)

fsguard_mcp-0.1.0/src/fsguard_mcp/git_ops.py

@@ -0,0 +1,156 @@
+"""
+Git tool functions, built on dulwich — a pure-Python git implementation
+with no subprocess-based content filtering and no argv built from user
+input, instead of shelling out to the `git` binary the way the official
+git MCP server does.
+
+Why that matters here specifically: CVE-2025-68144 was argument
+injection because user-controlled values were passed straight into a
+`git` CLI invocation, and the documented RCE chain (`git_init` in a
+writable dir -> a malicious `.git/config` clean filter -> `.gitattributes`
+applies it -> `git_add` triggers the filter -> arbitrary shell command)
+depends entirely on an external `git` process being invoked to run that
+filter. dulwich's blob-normalizer path used by add/checkin doesn't shell
+out, so that specific chain is closed. Two things dulwich *does* still do
+that this module explicitly guards against:
+
+1. **`core.worktree` redirection.** `.git/config` can contain a
+   `core.worktree` entry that dulwich honors on `Repo.open()`, and every
+   `porcelain.*` call re-opens a `Repo` from whatever path string it's
+   given — internally, not something a caller can intercept. Since
+   `.git/config` is just a text file inside the confined root,
+   `fs_write` (which has no special handling for `.git/*`) lets a caller
+   write one, and *every git tool in this module* would then silently
+   operate against an arbitrary directory outside the confined root
+   without the containment check ever seeing it — a full read/write
+   escape using nothing but this server's own exposed tools. `_open_repo`
+   below refuses any `.git/config` containing `core.worktree`, and
+   independently double-checks that the `Repo` it actually opened
+   reports its working path as the exact directory that was validated.
+2. **Hooks.** `porcelain.commit()` runs `pre-commit`/`commit-msg`/
+   `post-commit` hooks via `subprocess.call()` if they exist and are
+   executable at `.git/hooks/*` — real process execution, unrelated to
+   content filtering. `git_commit` below always passes `no_verify=True`
+   to skip them categorically, rather than relying on them happening to
+   not be runnable.
+
+Every path this module touches — the repo itself, and every path handed
+to git_add — is also validated through the same ConfinedRoot used by
+fs.py. This is the direct fix for CVE-2026-27735, where GitPython's
+`repo.index.add()` didn't enforce working-tree boundaries for `../`
+paths: here, each path is resolved and checked against the confined
+root *before* it's handed to dulwich at all.
+"""
+
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+from dulwich import porcelain
+from dulwich.repo import Repo
+
+from .confined_path import ConfinedRoot
+
+
+class NotAGitRepositoryError(ValueError):
+    pass
+
+
+class UnsafeRepositoryError(ValueError):
+    """Raised when a repo's own .git/config tries to redirect operations
+    outside the confined root — see module docstring, point 1."""
+
+
+def git_init(root: ConfinedRoot, repo_path: str) -> dict:
+    resolved = root.resolve(repo_path, must_exist=False)
+    resolved.mkdir(parents=True, exist_ok=True)
+    porcelain.init(str(resolved))
+    return {"initialized": str(resolved.relative_to(root.root)) or "."}
+
+
+def _open_repo(root: ConfinedRoot, repo_path: str) -> Repo:
+    resolved = root.resolve(repo_path, must_exist=True)
+    if not (resolved / ".git").exists():
+        raise NotAGitRepositoryError(f"Not a git repository: {repo_path}")
+
+    config_path = resolved / ".git" / "config"
+    if config_path.is_file():
+        config_text = config_path.read_text(encoding="utf-8", errors="replace")
+        if "worktree" in config_text.lower():
+            raise UnsafeRepositoryError(
+                f"Refusing to operate on {repo_path}: its .git/config sets "
+                "core.worktree, which can redirect git operations outside "
+                "the confined root."
+            )
+
+    repo = Repo(str(resolved))
+    # Defense in depth beyond the text check above: confirm dulwich's own
+    # notion of the working path, after fully opening and parsing the
+    # config, is still exactly the directory we validated — not
+    # wherever some other config mechanism might have pointed it.
+    actual_path = Path(repo.path).resolve()
+    if actual_path != resolved:
+        repo.close()
+        raise UnsafeRepositoryError(
+            f"Refusing to operate on {repo_path}: dulwich resolved its "
+            f"working path to {actual_path}, not the confined {resolved}."
+        )
+    return repo
+
+
+def git_status(root: ConfinedRoot, repo_path: str = ".") -> dict:
+    repo = _open_repo(root, repo_path)
+    status = porcelain.status(repo)
+    staged = {
+        kind: [p.decode() if isinstance(p, bytes) else p for p in paths]
+        for kind, paths in status.staged.items()
+        if paths
+    }
+    return {
+        "staged": staged,
+        "unstaged": [p.decode() if isinstance(p, bytes) else p for p in status.unstaged],
+        "untracked": [p.decode() if isinstance(p, bytes) else p for p in status.untracked],
+    }
+
+
+def git_add(root: ConfinedRoot, repo_path: str, paths: list[str]) -> dict:
+    """Stage files. Every path is resolved and validated against the
+    confined root — not just against the repo directory — before being
+    handed to dulwich. See module docstring for the CVE this fixes."""
+    repo = _open_repo(root, repo_path)
+    repo_dir = Path(repo.path)
+    validated: list[str] = []
+    for p in paths:
+        candidate = repo_dir / p
+        root.resolve(candidate, must_exist=True)  # raises PathEscapeError if it escapes
+        validated.append(p)
+    porcelain.add(repo, paths=validated)
+    return {"added": validated}
+
+
+def git_commit(root: ConfinedRoot, repo_path: str, message: str, author: str) -> dict:
+    repo = _open_repo(root, repo_path)
+    author_bytes = author.encode("utf-8")
+    sha = porcelain.commit(
+        repo,
+        message=message,
+        author=author_bytes,
+        committer=author_bytes,
+        no_verify=True,  # never run pre-commit/commit-msg/post-commit hooks
+    )
+    return {"commit": sha.decode("ascii")}
+
+
+def git_diff(root: ConfinedRoot, repo_path: str = ".", staged: bool = False) -> str:
+    repo = _open_repo(root, repo_path)
+    buf = io.BytesIO()
+    porcelain.diff(repo, staged=staged, outstream=buf)
+    return buf.getvalue().decode("utf-8", errors="replace")
+
+
+def git_log(root: ConfinedRoot, repo_path: str = ".", max_entries: int = 10) -> str:
+    repo = _open_repo(root, repo_path)
+    buf = io.StringIO()
+    porcelain.log(repo, max_entries=max_entries, outstream=buf)
+    return buf.getvalue()