Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

6.7 KB
Raw Blame
"""
Network guards for remote MCP servers (SSRF protection).

Two postures, because the two kinds of server carry different trust:

**Deployment servers** (an administrator's ``mcp.json``) keep the original,
permissive rules. A self-hosted deployment legitimately runs MCP servers on
localhost or its own LAN, and the administrator already has host access, so the
guard only has to stop *accidental* dangerous targets: link-local /
cloud-metadata ranges (169.254.0.0/16 — 169.254.169.254 is the classic
credential-theft target — and fe80::/10) plus the 0.0.0.0/8 "this network"
range.

**Self-service servers** (a user's own, ``strict=True``) additionally lose
loopback and private ranges. The request is made by the *app process*, which
holds every provider API key and shares a network with PocketBase and the
sandbox runner; a URL a user supplies must not be able to aim it inward. An explicit
``allow_private_network`` selection can use RFC1918 addresses only for an
origin approved in the administrator-owned registry; metadata and loopback
remain blocked for self-service callers. This
is what makes per-user MCP configuration safe to offer at all.

Validation is deliberately re-run at connect time, not only when a server is
saved: a check that happens once at save time is defeated by a DNS record that
changes afterwards.
"""

from __future__ import annotations

import ipaddress
import socket
from urllib.parse import urlparse

_BLOCKED_NETWORKS = [
    ipaddress.ip_network("0.0.0.0/8"),
    ipaddress.ip_network("169.254.0.0/16"),  # link-local / cloud metadata
    ipaddress.ip_network("fe80::/10"),
    ipaddress.ip_network("fd00:ec2::254/128"),
    ipaddress.ip_network("100.100.100.200/32"),
    ipaddress.ip_network("::/128"),  # link-local v6
]

# Additionally blocked for user-supplied URLs: everything that points back at
# the deployment itself or its private network.
_STRICT_EXTRA_NETWORKS = [
    ipaddress.ip_network("127.0.0.0/8"),
    ipaddress.ip_network("10.0.0.0/8"),
    ipaddress.ip_network("172.16.0.0/12"),
    ipaddress.ip_network("192.168.0.0/16"),
    ipaddress.ip_network("100.64.0.0/10"),  # carrier-grade NAT / tailscale
    ipaddress.ip_network("::1/128"),
    ipaddress.ip_network("fc00::/7"),  # unique-local v6
]


def _normalize_addr(
    addr: ipaddress.IPv4Address | ipaddress.IPv6Address,
) -> ipaddress.IPv4Address | ipaddress.IPv6Address:
    """Normalize IPv6-mapped IPv4 addresses (``::ffff:169.254.x.x``) to IPv4."""
    if isinstance(addr, ipaddress.IPv6Address) and addr.ipv4_mapped is not None:
        return addr.ipv4_mapped
    return addr


def _is_blocked(
    addr: ipaddress.IPv4Address | ipaddress.IPv6Address,
    *,
    strict: bool,
) -> bool:
    normalized = _normalize_addr(addr)
    networks = _BLOCKED_NETWORKS + (_STRICT_EXTRA_NETWORKS if strict else [])
    return any(normalized in net for net in networks)


def validate_mcp_url(
    url: str, *, strict: bool = False, trusted_origin: str | None = None
) -> tuple[bool, str]:
    """Validate a remote MCP server URL: scheme, hostname, resolved IPs.

    ``strict`` applies the self-service posture (see the module docstring): a
    user-supplied URL may not resolve to loopback or a private range.

    Returns ``(ok, error_message)``; ``error_message`` is empty when ok.
    """
    try:
        parsed = urlparse(url)
    except Exception as exc:
        return False, str(exc)

    if parsed.scheme not in ("http", "https"):
        return False, f"Only http/https allowed, got {parsed.scheme or 'none'!r}"
    try:
        _ = parsed.port
    except ValueError as exc:
        return False, str(exc)
    hostname = parsed.hostname
    if not hostname:
        return False, "Missing hostname"

    if parsed.username or parsed.password or parsed.fragment:
        return False, "MCP URLs must not contain embedded credentials or fragments"
    private_allowed = trusted_origin is not None and mcp_origin(url) == trusted_origin
    try:
        infos = socket.getaddrinfo(hostname, None, socket.AF_UNSPEC, socket.SOCK_STREAM)
    except socket.gaierror:
        return False, f"Cannot resolve hostname: {hostname}"

    resolved = False
    for info in infos:
        try:
            addr = ipaddress.ip_address(info[4][0])
        except ValueError:
            continue
        resolved = True
        normalized = _normalize_addr(addr)
        approved_rfc1918 = private_allowed and any(normalized in network for network in _RFC1918)
        if _is_blocked(addr, strict=False) or (
            _is_blocked(addr, strict=strict) and not approved_rfc1918
        ):
            return False, (
                f"Blocked: {hostname} resolves to a disallowed address ({addr}). "
                "A server you configure yourself must be reachable on the public internet."
                if strict
                else f"Blocked: {hostname} resolves to link-local/metadata address {addr}"
            )
    return (True, "") if resolved else (False, "No usable address resolved for this MCP host")


async def validate_mcp_url_async(
    url: str, *, strict: bool = False, trusted_origin: str | None = None
) -> tuple[bool, str]:
    """:func:`validate_mcp_url` off the event loop.

    The check resolves DNS with a blocking call, which on a slow or dead
    resolver stalls for seconds. On the event loop that is not one slow request
    — it is every request in the process, so any caller already inside async
    code uses this.
    """
    import asyncio

    return await asyncio.to_thread(
        validate_mcp_url, url, strict=strict, trusted_origin=trusted_origin
    )


__all__ = ["validate_mcp_url", "validate_mcp_url_async"]


_RFC1918 = tuple(
    ipaddress.ip_network(value) for value in ("10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16")
)


def mcp_origin(url: str) -> str:
    parsed = urlparse(url)
    if (
        parsed.scheme not in {"http", "https"}
        or not parsed.hostname
        or parsed.username
        or parsed.password
    ):
        raise ValueError(
            "A trusted MCP origin must be an http(s) server without embedded credentials"
        )
    host = parsed.hostname.casefold().rstrip(".")
    if ":" in host:
        host = f"[{host}]"
    port = parsed.port or (443 if parsed.scheme == "https" else 80)
    return f"{parsed.scheme}://{host}:{port}"


def approved_private_origin(url: str) -> str | None:
    """An admin-owned server approval grants only its exact scheme/host/port."""
    from deeptutor.services.mcp.config import load_mcp_config

    origin = mcp_origin(url)
    for cfg in load_mcp_config().servers.values():
        if not cfg.allow_private_network or cfg.resolved_type() not in {"sse", "streamableHttp"}:
            continue
        try:
            if mcp_origin(cfg.url) == origin:
                return origin
        except ValueError:
            continue
    return None