fsguard-mcp

一个文件系统 + git MCP 服务器，将每个操作都限制在允许的目录树内，基于符号链接解析后的路径包含，而不是字符串前缀匹配。

为什么会有这个项目

Anthropic 的官方文件系统和 git MCP 服务器（@modelcontextprotocol/server-filesystem，属于 modelcontextprotocol/servers 仓库，89.7k★）在十个月内，两个服务器之间出现了五个人口限制功能的 CVE，而这个模式仍然还在持续：

• CVE-2025-53109 / CVE-2025-53110（文件系统，CVSS 8.4/7.3）——“允许目录”检查用的朴素地是 startsWith() 前缀匹配，结果被符号链接以及仅仅共享字符串前缀的兄弟目录绕过（例如允许的 /home/user-safe 会把 /home/user-safe-evil），造成文件系统级的读/写，并且有一条已记录的 RCE 路径。

• CVE-2025-68143 / CVE-2025-68144 / CVE-2025-68145（git）——git_init 接受任意的未校验路径；git_diff / git_checkout 直接把用户可控的参数带给了 git 命令暂存（参数注入）；而 --repository 约束模式其实并没有真正校验 repo_path 仍留在受限目录里。

• CVE-2026-27735（git，，在本项目开始前约 4 个月发布）——通过 GitPython 的 repo.index.add() 实现的 git_add，对 ../ 风格路径没有强制限定在工作区边界以内，于是能暂存并泄露仓库之外的受贿文件。

• 已记录的 RCE 链：在可写目录里先 git_init → 写入恶意 .git/config（含 clean 过滤器） → 再配合 .gitattributes 应用该过滤器 → 然后 git_add 触发这个过滤器 → 任意 shell 被任意执行。

每一个修复的方法都是在那一个函数上缝上一个弦/前缀（string/prefix）检查。没有人把边界的使命挪到一个新的工具不可能忘记去调用的位置上——这正是第四个 CVE 在前三个被宣布“修复”后四个月还能落地同一个系统上的原因。

Related MCP server: Local Files MCP Server

fsguard-mcp 有不同的地方

1. 唯一的安全原语，处处复用。 每个工具——无论是文件系统还是 git——在执行任何操作之前，都先通过同一个 ConfinedRoot（见 confined_path.py）来解析它的目标路径。不会出现“某个新工具忘了加路径检查”的情况。

2. 基于符号链接解析和组件比较的包含，不是字符串匹配。 一个路径只有在其完全解析后的真实路径（每个符号链接都跟随）作为根目录自身真实路径的真实子路径时，才算是在根内。这个安全依赖解析后的 Path.is_relative_to() 来实现——绝不会用字符串给出的 startsWith()。仅此一条就关闭了 CVE-2025-53109/53110 的具体失败模式：当根被解析为 /allowed 后，/allowed-evil 不可能通过包含判断，因为比较的是路径的组件，不是字符串的前缀。

3. **为了让内容做事，绝不把请求转成 git 。 git 操作体现在全经过 dulwich ——一个纯 Python git 实现，它不派生子进程，也从不从用户可控内容构建 argv（任何内容关注操作都不会），并且更难能可贵的是，它根本不会执行 clean/smudge 过滤器——这正好是 RCE 链所依赖的。因此这里没有参数注入风险面，因为没有一份 argv 会被递给外部进程去读取/写入文件内容知识点。（dulwich 确实仍然会通过 subprocess.call() 运行存在的 pre-commit / commit-msg / post-commit hooks——那是真实的进程执行，但和内容过滤无关。git_commit 始终传 no_verify=True 来全部跳过它们，而没有依赖“夹心”代码恰好不会被执行。）

4. 写操作会同时校验父目录，不只是原本就存在的目标文件。 这补上的缺陷是：目标还不存在时（于是“该路径能否解析进出根内”查的是不存在的路径，不可做 symlink 解析），但它的父目录本身却是一条指到根目外部的符号链接。在任何“哪边父”之前，不存在的路径段会先做纯词法形式的目录 () 归一——将 .、.. 作为纯路径代数做折叠，至于这些东西是不是真的磁盘上不存在。之前的一个本版本里：先提供了输入的合法性（包含检查）再做归一化，然后在 Windows 上虽然省过了路规自己的 tests（因为 Windows 路径 API 会替你把 .. 直接规范化），在 Linux/macOS 则是可绕过的。现在修复的是，并已有针对该情况的专属测试——这也是这项目为什么看到窗外“我的机器上测试全绿”，会投以真正的怀疑。

5. .git/config 不能将操作重定向到目录根之外。 dulwich 会尊重仓库自己的 core.worktree 配置，而 commit 每个 git 操作每次都会从路径字符串内部重新打开 Repo。换句话说，调用者可以写一个 core.worktree 指向任何位置的 .git/config，之后所有的 git 工具都会静默地作用在受约束根之外——而这不会被“这一条路径”的校验发现（那这个检查只看限定到的仓库路径，永远不看 dulwich 已经默默把整个仓库挪到了哪里）。这个问题正是本仓库自己的第二轮安全审查中发现的一个真实攻击原语：只用这个服务器自身暴露出来的工具，就能完成读取、尤其是数据夹带。严重度比它要修掉的 CVE。可现在每个 git 工具都会直接拒绝配置里写有 core.worktree 的仓库，并且各自再次确认它真正实际打开的 Repo 所报告的工作路径，就是当时已校验的那个确认路径。

6. UNC 路径与跨驱动资质路径，在任何网络或磁盘触碰之前，就被拒掉。 例如解析 \\host\share\... 在 Windows 上会真的尝试 SMB 连接——Windows 还会让这个连接以服务器进程的身份进行认证，这就是“用 UNC 路径强制执行 NTLM 认证”凭据窃取手段的价值；除此之外，如果目标主机不可达，服务器还会阻塞进这段完整连接超时的时间段。现在，凡是与受限根、不同驱动ven /不同目标 host 相对的候选，超出任何文件系统/网络索引时，都先会用成本很低的字符串比较淘汰掉。同时，NTFS 设备数据流（例如 file.txt:hidden）也会被安排为拒绝排除——它们不会出现在目录列表里（不可见），却能绕过同一个路径字符串直接读写，而且可以伪造成某个只需要上下取消——Files.

工具

配置方式

pip install fsguard-mcp
export FSGUARD_ROOT="/path/to/the/one/directory/tree/this/server/may/touch"
fsguard-mcp

FSGUARD_ROOT 是必填的——没有默认值，服务器也绝不偷懒自己猜一个。把 MCP 客户端指向 fsguard-mcp 指令，并在其环境变量配置里设置 FSGUARD_ROOT'。

测试

pip install -e ".[dev]"
pytest tests/ -v

全部 68 个测试都是会自足（真实临时目录、通过的符号链接、真实 git 仓库），进一步不需要任何外部服务。

已知的限制

保证参与了存在后，然后进行一致性时间；也就是说两次操作之间有一个内在的启 TX 时间差（TOCTOU，time-of-check-to-time-of-use）。如果一辆有写权限的进程能写入受限根自身目录树，它原则上就可能在这个间隙里抓换 symlink（它是人类在内审中用一个可以工作的 PoC 验证过的）。真要在根的部分封死这类问题，只能 OS 级的原语（如 Linux 的 openat2(RESOLVE_BENEATH) 或真实的 mount 名字容器），而不是用可读的可移植 Python 脚本。所以本项目的承诺是“包含逻辑正确，每次使用前立即检查”，并不是“针对一个已经能在里面写内容的并发攻击者还不可侵”。

现状

v0.1.0，已 live 在 PyPI。68 个测试通过（是 unit 级，并且真实在 disk 上创建 symlink /创建仓库——并不是进程逻辑断字）。在首版的第一次 commit 之前通过了对付式的安全审查；两轮都找到真实可用的加载绕过（其中之一是在 POSIX 经过尚不存在的路径中构造 .. 逃逸，还有上文说到的 core.worktree 重定向，等等更小的发现）。现在它们都已修复——直接针对报告的攻击路径写的测试回归——，还对新发布 package 重新做了一次干净 pip install，并重新验证过。

许可证

MIT