feat: add filesystem path safety primitives

maxisbey · maxisbey · commit e5ecf50e642d · 2026-03-26T17:42:18.000Z
Adds `mcp.shared.path_security` with three standalone utilities for
defending against path-traversal attacks when URI template parameters
flow into filesystem operations:

- `contains_path_traversal()` — base-free component-level check for
  `..` escapes, handles both `/` and `\` separators
- `is_absolute_path()` — detects POSIX, Windows drive, and UNC
  absolute paths (which silently discard the base in `Path` joins)
- `safe_join()` — resolve-and-verify within a sandbox root; catches
  `..`, absolute injection, and symlink escapes

These are pure functions usable from both MCPServer and lowlevel
server implementations. `PathEscapeError(ValueError)` is raised by
`safe_join` on violation.
diff --git a/src/mcp/shared/path_security.py b/src/mcp/shared/path_security.py
@@ -0,0 +1,150 @@
+"""Filesystem path safety primitives for resource handlers.
+
+These functions help MCP servers defend against path-traversal attacks
+when extracted URI template parameters are used in filesystem
+operations. They are standalone utilities usable from both the
+high-level :class:`~mcp.server.mcpserver.MCPServer` and lowlevel server
+implementations.
+
+The canonical safe pattern::
+
+    from mcp.shared.path_security import safe_join
+
+    @mcp.resource("file://docs/{+path}")
+    def read_doc(path: str) -> str:
+        return safe_join("/data/docs", path).read_text()
+"""
+
+from pathlib import Path
+
+__all__ = ["PathEscapeError", "contains_path_traversal", "is_absolute_path", "safe_join"]
+
+
+class PathEscapeError(ValueError):
+    """Raised by :func:`safe_join` when the resolved path escapes the base."""
+
+
+def contains_path_traversal(value: str) -> bool:
+    r"""Check whether a value, treated as a relative path, escapes its origin.
+
+    This is a **base-free** check: it does not know the sandbox root, so
+    it detects only whether ``..`` components would move above the
+    starting point. Use :func:`safe_join` when you know the root — it
+    additionally catches symlink escapes and absolute-path injection.
+
+    The check is component-based: ``..`` is dangerous only as a
+    standalone path segment, not as a substring. Both ``/`` and ``\``
+    are treated as separators.
+
+    Example::
+
+        >>> contains_path_traversal("a/b/c")
+        False
+        >>> contains_path_traversal("../etc")
+        True
+        >>> contains_path_traversal("a/../../b")
+        True
+        >>> contains_path_traversal("a/../b")
+        False
+        >>> contains_path_traversal("1.0..2.0")
+        False
+        >>> contains_path_traversal("..")
+        True
+
+    Args:
+        value: A string that may be used as a filesystem path.
+
+    Returns:
+        ``True`` if the path would escape its starting directory.
+    """
+    depth = 0
+    for part in value.replace("\\", "/").split("/"):
+        if part == "..":
+            depth -= 1
+            if depth < 0:
+                return True
+        elif part and part != ".":
+            depth += 1
+    return False
+
+
+def is_absolute_path(value: str) -> bool:
+    r"""Check whether a value is an absolute filesystem path.
+
+    Absolute paths are dangerous when joined onto a base: in Python,
+    ``Path("/data") / "/etc/passwd"`` yields ``/etc/passwd`` — the
+    absolute right-hand side silently discards the base.
+
+    Detects POSIX absolute (``/foo``), Windows drive (``C:\foo``),
+    and Windows UNC/absolute (``\\server\share``, ``\foo``).
+
+    Example::
+
+        >>> is_absolute_path("relative/path")
+        False
+        >>> is_absolute_path("/etc/passwd")
+        True
+        >>> is_absolute_path("C:\\Windows")
+        True
+        >>> is_absolute_path("")
+        False
+
+    Args:
+        value: A string that may be used as a filesystem path.
+
+    Returns:
+        ``True`` if the path is absolute on any common platform.
+    """
+    if not value:
+        return False
+    if value[0] in ("/", "\\"):
+        return True
+    # Windows drive letter: C:, C:\, C:/
+    if len(value) >= 2 and value[1] == ":" and value[0].isalpha():
+        return True
+    return False
+
+
+def safe_join(base: str | Path, *parts: str) -> Path:
+    """Join path components onto a base, rejecting escapes.
+
+    Resolves the joined path and verifies it remains within ``base``.
+    This is the **gold-standard** check: it catches ``..`` traversal,
+    absolute-path injection, and symlink escapes that the base-free
+    checks cannot.
+
+    Example::
+
+        >>> safe_join("/data/docs", "readme.txt")
+        PosixPath('/data/docs/readme.txt')
+        >>> safe_join("/data/docs", "../../../etc/passwd")
+        Traceback (most recent call last):
+        ...
+        PathEscapeError: ...
+
+    Args:
+        base: The sandbox root. May be relative; it will be resolved.
+        parts: Path components to join. Each is checked for absolute
+            form before joining.
+
+    Returns:
+        The resolved path, guaranteed to be within ``base``.
+
+    Raises:
+        PathEscapeError: If any part is absolute, or if the resolved
+            path is not contained within the resolved base.
+    """
+    base_resolved = Path(base).resolve()
+
+    # Reject absolute parts up front: Path's / operator would silently
+    # discard everything to the left of an absolute component.
+    for part in parts:
+        if is_absolute_path(part):
+            raise PathEscapeError(f"Path component {part!r} is absolute; refusing to join onto {base_resolved}")
+
+    target = base_resolved.joinpath(*parts).resolve()
+
+    if not target.is_relative_to(base_resolved):
+        raise PathEscapeError(f"Path {target} escapes base {base_resolved}")
+
+    return target
diff --git a/tests/shared/test_path_security.py b/tests/shared/test_path_security.py
@@ -0,0 +1,142 @@
+"""Tests for filesystem path safety primitives."""
+
+from pathlib import Path
+
+import pytest
+
+from mcp.shared.path_security import (
+    PathEscapeError,
+    contains_path_traversal,
+    is_absolute_path,
+    safe_join,
+)
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [
+        # Safe: no traversal
+        ("a/b/c", False),
+        ("readme.txt", False),
+        ("", False),
+        (".", False),
+        ("./a/b", False),
+        # Safe: .. balanced by prior descent
+        ("a/../b", False),
+        ("a/b/../c", False),
+        ("a/b/../../c", False),
+        # Unsafe: net escape
+        ("..", True),
+        ("../etc", True),
+        ("../../etc/passwd", True),
+        ("a/../../b", True),
+        ("./../../etc", True),
+        # .. as substring, not component — safe
+        ("1.0..2.0", False),
+        ("foo..bar", False),
+        ("..foo", False),
+        ("foo..", False),
+        # Backslash separator
+        ("..\\etc", True),
+        ("a\\..\\..\\b", True),
+        ("a\\b\\c", False),
+        # Mixed separators
+        ("a/..\\..\\b", True),
+    ],
+)
+def test_contains_path_traversal(value: str, expected: bool):
+    assert contains_path_traversal(value) is expected
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [
+        # Relative
+        ("relative/path", False),
+        ("file.txt", False),
+        ("", False),
+        (".", False),
+        ("..", False),
+        # POSIX absolute
+        ("/", True),
+        ("/etc/passwd", True),
+        ("/a", True),
+        # Windows drive
+        ("C:", True),
+        ("C:\\Windows", True),
+        ("c:/foo", True),
+        ("Z:\\", True),
+        # Windows UNC / backslash-absolute
+        ("\\\\server\\share", True),
+        ("\\foo", True),
+        # Not a drive: digit before colon
+        ("1:foo", False),
+        # Colon not in position 1
+        ("ab:c", False),
+    ],
+)
+def test_is_absolute_path(value: str, expected: bool):
+    assert is_absolute_path(value) is expected
+
+
+def test_safe_join_simple(tmp_path: Path):
+    result = safe_join(tmp_path, "docs", "readme.txt")
+    assert result == tmp_path / "docs" / "readme.txt"
+
+
+def test_safe_join_resolves_relative_base(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+    monkeypatch.chdir(tmp_path)
+    result = safe_join(".", "file.txt")
+    assert result == tmp_path / "file.txt"
+
+
+def test_safe_join_rejects_dotdot_escape(tmp_path: Path):
+    with pytest.raises(PathEscapeError, match="escapes base"):
+        safe_join(tmp_path, "../../../etc/passwd")
+
+
+def test_safe_join_rejects_balanced_then_escape(tmp_path: Path):
+    with pytest.raises(PathEscapeError, match="escapes base"):
+        safe_join(tmp_path, "a/../../etc")
+
+
+def test_safe_join_allows_balanced_dotdot(tmp_path: Path):
+    result = safe_join(tmp_path, "a/../b")
+    assert result == tmp_path / "b"
+
+
+def test_safe_join_rejects_absolute_part(tmp_path: Path):
+    with pytest.raises(PathEscapeError, match="is absolute"):
+        safe_join(tmp_path, "/etc/passwd")
+
+
+def test_safe_join_rejects_absolute_in_later_part(tmp_path: Path):
+    with pytest.raises(PathEscapeError, match="is absolute"):
+        safe_join(tmp_path, "docs", "/etc/passwd")
+
+
+def test_safe_join_rejects_windows_drive(tmp_path: Path):
+    with pytest.raises(PathEscapeError, match="is absolute"):
+        safe_join(tmp_path, "C:\\Windows\\System32")
+
+
+def test_safe_join_rejects_symlink_escape(tmp_path: Path):
+    outside = tmp_path / "outside"
+    outside.mkdir()
+    sandbox = tmp_path / "sandbox"
+    sandbox.mkdir()
+    (sandbox / "escape").symlink_to(outside)
+
+    with pytest.raises(PathEscapeError, match="escapes base"):
+        safe_join(sandbox, "escape", "secret.txt")
+
+
+def test_safe_join_base_equals_target(tmp_path: Path):
+    # Joining nothing (or ".") should return the base itself
+    assert safe_join(tmp_path) == tmp_path
+    assert safe_join(tmp_path, ".") == tmp_path
+
+
+def test_path_escape_error_is_value_error():
+    with pytest.raises(ValueError):
+        safe_join("/tmp", "/etc")
