diff --git a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py index 25c47aacf0f9..f96350500db0 100644 --- a/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py +++ b/litellm/proxy/_experimental/mcp_server/mcp_server_manager.py @@ -41,6 +41,7 @@ MCP_TOOL_LISTING_TIMEOUT, ) from litellm.exceptions import BlockedPiiEntityError, GuardrailRaisedException +from litellm.litellm_core_utils.url_utils import SSRFError, async_safe_get from litellm.experimental_mcp_client.client import MCPClient, MCPSigV4Auth from litellm.llms.custom_httpx.http_handler import get_async_httpx_client from litellm.proxy._experimental.mcp_server.auth.user_api_key_auth_mcp import ( @@ -1499,6 +1500,47 @@ async def get_prompt_from_server( ) return await client.get_prompt(get_prompt_request_params) + @staticmethod + def _is_same_authority_metadata_url(url: str, server_url: str) -> bool: + """ + Whether ``url`` shares scheme, host, and port with ``server_url``. + + Same-authority metadata URLs are produced by our well-known discovery + construction and by resource servers that publish protected-resource + metadata on the resource origin. These must keep working for + administrator-configured internal MCP servers, so they are fetched + directly. Cross-origin URLs are fetched through ``async_safe_get``. + """ + try: + target = urlparse(url) + base = urlparse(server_url) + except Exception: + return False + + if target.scheme not in ("http", "https") or not target.hostname: + return False + + target_port = target.port or (443 if target.scheme == "https" else 80) + base_port = base.port or (443 if base.scheme == "https" else 80) + return ( + base.scheme == target.scheme + and (base.hostname or "").lower() == target.hostname.lower() + and base_port == target_port + ) + + async def _fetch_oauth_discovery_url(self, url: str, server_url: str) -> Any: + client = get_async_httpx_client( + llm_provider=httpxSpecialProvider.MCP, + params={"timeout": MCP_METADATA_TIMEOUT}, + ) + if self._is_same_authority_metadata_url(url, server_url): + # Same-authority URLs may point at administrator-configured + # internal MCP servers. Do not run them through user URL + # validation, but also do not follow redirects because the + # redirect target would not inherit the same-authority guarantee. + return await client.get(url, follow_redirects=False) + return await async_safe_get(client, url) + async def _descovery_metadata( self, server_url: str, @@ -1514,7 +1556,7 @@ async def _descovery_metadata( resource_scopes, ) = await self._attempt_well_known_discovery(server_url) metadata = await self._fetch_authorization_server_metadata( - authorization_servers + authorization_servers, server_url ) if ( metadata is None @@ -1555,7 +1597,7 @@ async def _descovery_metadata( authorization_servers, resource_scopes, ) = await self._fetch_oauth_metadata_from_resource( - resource_metadata_url + resource_metadata_url, server_url ) else: ( @@ -1576,7 +1618,7 @@ async def _descovery_metadata( if authorization_servers: metadata = await self._fetch_authorization_server_metadata( - authorization_servers + authorization_servers, server_url ) preferred_scopes = scopes or resource_scopes @@ -1616,19 +1658,26 @@ def _parse_www_authenticate_header( return resource_metadata_url, scopes async def _fetch_oauth_metadata_from_resource( - self, resource_metadata_url: str + self, resource_metadata_url: str, server_url: str ) -> Tuple[List[str], Optional[List[str]]]: if not resource_metadata_url: return [], None try: - client = get_async_httpx_client( - llm_provider=httpxSpecialProvider.MCP, - params={"timeout": MCP_METADATA_TIMEOUT}, + response = await self._fetch_oauth_discovery_url( + resource_metadata_url, server_url ) - response = await client.get(resource_metadata_url) response.raise_for_status() data = response.json() + except SSRFError as exc: + verbose_logger.warning( + "MCP OAuth discovery: refusing to fetch resource metadata from %s " + "(rejected by SSRF guard for server %s): %s", + resource_metadata_url, + server_url, + exc, + ) + return [], None except Exception as exc: # pragma: no cover - network issues verbose_logger.debug( "Failed to fetch MCP OAuth metadata from %s: %s", @@ -1677,23 +1726,25 @@ async def _attempt_well_known_discovery( ( authorization_servers, scopes, - ) = await self._fetch_oauth_metadata_from_resource(url) + ) = await self._fetch_oauth_metadata_from_resource(url, server_url) if authorization_servers: return authorization_servers, scopes return [], None async def _fetch_authorization_server_metadata( - self, authorization_servers: List[str] + self, authorization_servers: List[str], server_url: str ) -> Optional[MCPOAuthMetadata]: for issuer in authorization_servers: - metadata = await self._fetch_single_authorization_server_metadata(issuer) + metadata = await self._fetch_single_authorization_server_metadata( + issuer, server_url + ) if metadata is not None: return metadata return None async def _fetch_single_authorization_server_metadata( - self, issuer_url: str + self, issuer_url: str, server_url: str ) -> Optional[MCPOAuthMetadata]: try: parsed = urlparse(issuer_url) @@ -1721,13 +1772,18 @@ async def _fetch_single_authorization_server_metadata( for url in candidate_urls: try: - client = get_async_httpx_client( - llm_provider=httpxSpecialProvider.MCP, - params={"timeout": MCP_METADATA_TIMEOUT}, - ) - response = await client.get(url) + response = await self._fetch_oauth_discovery_url(url, server_url) response.raise_for_status() data = response.json() + except SSRFError as exc: + verbose_logger.warning( + "MCP OAuth discovery: refusing to fetch authorization-server " + "metadata from %s (rejected by SSRF guard for server %s): %s", + url, + server_url, + exc, + ) + continue except Exception as exc: # pragma: no cover - network issues verbose_logger.debug( "Failed to fetch authorization metadata from %s: %s", diff --git a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py index 8614cb3ba727..6cbdcd282086 100644 --- a/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py +++ b/tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py @@ -4,6 +4,7 @@ import os import sys from datetime import datetime +from typing import Any, Dict from unittest.mock import AsyncMock, MagicMock, patch import pytest @@ -719,7 +720,8 @@ async def test_fetch_oauth_metadata_from_resource_returns_servers_and_scopes(sel return_value=mock_client, ): servers, scopes = await manager._fetch_oauth_metadata_from_resource( - "https://protected.example.com/.well-known/oauth" + "https://protected.example.com/.well-known/oauth", + "https://protected.example.com/mcp", ) assert servers == [ @@ -772,7 +774,8 @@ async def test_descovery_metadata_probes_well_known_when_server_does_not_challen mock_well_known.assert_awaited_once_with("http://localhost:8001/mcp") mock_fetch_auth.assert_awaited_once_with( - ["https://login.microsoftonline.com/test-tenant-id/v2.0"] + ["https://login.microsoftonline.com/test-tenant-id/v2.0"], + "http://localhost:8001/mcp", ) assert result is mock_metadata assert result.scopes == ["api://some-scope/.default"] @@ -784,7 +787,7 @@ async def test_fetch_single_authorization_server_metadata_supports_azure_issuer_ manager = MCPServerManager() issuer = "https://login.microsoftonline.com/test-tenant-id/v2.0" - def build_response(url: str): + def build_response(url: str, **kwargs): mock_response = MagicMock() if url == f"{issuer}/.well-known/openid-configuration": mock_response.json.return_value = { @@ -810,7 +813,12 @@ def build_response(url: str): "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", return_value=mock_client, ): - result = await manager._fetch_single_authorization_server_metadata(issuer) + # The Azure issuer is cross-origin against the server_url — use + # the issuer itself as server_url so the test exercises the + # well-known fetch logic without needing real DNS. + result = await manager._fetch_single_authorization_server_metadata( + issuer, issuer + ) assert result is not None assert ( @@ -846,7 +854,9 @@ async def test_fetch_single_authorization_server_metadata_derives_azure_metadata "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", return_value=mock_client, ): - result = await manager._fetch_single_authorization_server_metadata(issuer) + result = await manager._fetch_single_authorization_server_metadata( + issuer, issuer + ) assert result is not None assert ( @@ -910,7 +920,7 @@ def raise_http_error(): ): result = await manager._descovery_metadata(server_url) - mock_fetch_auth.assert_awaited_once_with(["https://example.com"]) + mock_fetch_auth.assert_awaited_once_with(["https://example.com"], server_url) assert result is mock_metadata assert result.scopes == ["read"] @@ -2947,5 +2957,359 @@ def test_id_and_name_keys_pointing_at_same_server_union_tools(self): assert sorted(result["uuid-a"]) == ["read_file", "write_file"] +class TestOAuthDiscoverySSRFGuard: + """SSRF guard for the OAuth metadata discovery follow-up fetches. + + The vulnerability: a malicious MCP server returns a ``WWW-Authenticate`` + header pointing at an attacker-chosen ``resource_metadata`` URL, then a + PRM JSON whose ``authorization_servers[0]`` points at internal/loopback + addresses, coercing the proxy into making blind GETs to cloud-metadata + services, internal admin panels, or loopback debug endpoints. + """ + + @staticmethod + def _patch_resolves(monkeypatch, mapping): + """Patch ``socket.getaddrinfo`` for a deterministic SSRF-guard test. + + ``mapping`` is ``{hostname: [ip-string, ...]}``; unknown hosts raise + ``gaierror`` (treated as "unresolvable" -> blocked by async_safe_get). + """ + import socket as _socket + + def fake_getaddrinfo(host, port, *args, **kwargs): + if host not in mapping: + raise _socket.gaierror(f"unknown host {host}") + family = _socket.AF_INET + return [ + (family, _socket.SOCK_STREAM, 0, "", (ip, port)) for ip in mapping[host] + ] + + monkeypatch.setattr( + "litellm.litellm_core_utils.url_utils.socket.getaddrinfo", + fake_getaddrinfo, + ) + + def test_same_authority_url_is_direct_fetch_eligible(self): + # Same scheme + host + port skips DNS entirely — the well-known + # endpoint construction in _attempt_well_known_discovery always + # produces same-authority URLs against the admin's server_url. + assert MCPServerManager._is_same_authority_metadata_url( + "https://example.com/.well-known/oauth-protected-resource", + "https://example.com/mcp", + ) + + def test_same_host_different_port_uses_safe_fetch_path(self): + assert not MCPServerManager._is_same_authority_metadata_url( + "https://example.com:9999/.well-known/oauth-protected-resource", + "https://example.com/mcp", + ) + + @pytest.mark.parametrize( + "ip", + [ + "127.0.0.1", # loopback + "10.0.0.5", # RFC1918 + "172.16.0.1", # RFC1918 + "192.168.1.1", # RFC1918 + "169.254.169.254", # AWS / Azure / GCP IMDS + "100.100.100.200", # Alibaba Cloud metadata + "0.0.0.0", # unspecified + "::1", # IPv6 loopback + "fe80::1", # IPv6 link-local + "fc00::1", # IPv6 ULA + ], + ) + @pytest.mark.asyncio + async def test_cross_origin_blocked_when_resolves_to_unsafe_ip( + self, monkeypatch, ip + ): + self._patch_resolves(monkeypatch, {"attacker.example.com": [ip]}) + manager = MCPServerManager() + + mock_client = MagicMock() + mock_client.get = AsyncMock() + + with patch( + "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", + return_value=mock_client, + ): + result = await manager._fetch_single_authorization_server_metadata( + "https://attacker.example.com", + "https://legit-mcp.example.com/mcp", + ) + + assert result is None + mock_client.get.assert_not_called() + + @pytest.mark.asyncio + async def test_cross_origin_allowed_when_resolves_to_public_ip(self, monkeypatch): + self._patch_resolves( + monkeypatch, {"login.microsoftonline.com": ["20.190.151.7"]} + ) + manager = MCPServerManager() + + mock_response = MagicMock() + mock_response.is_redirect = False + mock_response.raise_for_status = MagicMock() + mock_response.json.return_value = { + "authorization_servers": ["https://login.microsoftonline.com/tenant/v2.0"], + "scopes_supported": ["mcp.read"], + } + + mock_client = MagicMock() + mock_client.get = AsyncMock(return_value=mock_response) + + with patch( + "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", + return_value=mock_client, + ): + servers, scopes = await manager._fetch_oauth_metadata_from_resource( + "https://login.microsoftonline.com/tenant/v2.0/.well-known/openid-configuration", + "https://atlassian-mcp.example.com/mcp", + ) + + assert servers == ["https://login.microsoftonline.com/tenant/v2.0"] + assert scopes == ["mcp.read"] + mock_client.get.assert_awaited_once() + assert mock_client.get.await_args.kwargs["follow_redirects"] is False + assert ( + mock_client.get.await_args.kwargs["headers"]["Host"] + == "login.microsoftonline.com" + ) + + @pytest.mark.asyncio + async def test_cross_origin_blocked_when_unresolvable(self, monkeypatch): + self._patch_resolves(monkeypatch, {}) + manager = MCPServerManager() + + mock_client = MagicMock() + mock_client.get = AsyncMock() + + with patch( + "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", + return_value=mock_client, + ): + servers, scopes = await manager._fetch_oauth_metadata_from_resource( + "https://nope.example.invalid/.well-known/oauth-authorization-server", + "https://legit-mcp.example.com/mcp", + ) + + assert servers == [] + assert scopes is None + mock_client.get.assert_not_called() + + @pytest.mark.asyncio + async def test_non_http_scheme_is_not_safe(self): + manager = MCPServerManager() + mock_client = MagicMock() + mock_client.get = AsyncMock() + + with patch( + "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", + return_value=mock_client, + ): + servers, scopes = await manager._fetch_oauth_metadata_from_resource( + "file:///etc/passwd", + "https://example.com/mcp", + ) + result = await manager._fetch_single_authorization_server_metadata( + "gopher://example.com/", + "https://example.com/mcp", + ) + + assert servers == [] + assert scopes is None + assert result is None + mock_client.get.assert_not_called() + + @pytest.mark.asyncio + async def test_dual_resolution_blocked_if_any_ip_unsafe(self, monkeypatch): + # If the attacker controls a DNS record returning multiple A records, + # one of which is private, async_safe_get rejects before any network call. + self._patch_resolves( + monkeypatch, {"dual-stack.example.com": ["8.8.8.8", "127.0.0.1"]} + ) + manager = MCPServerManager() + + mock_client = MagicMock() + mock_client.get = AsyncMock() + + with patch( + "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", + return_value=mock_client, + ): + servers, scopes = await manager._fetch_oauth_metadata_from_resource( + "https://dual-stack.example.com/.well-known/oauth-authorization-server", + "https://legit-mcp.example.com/mcp", + ) + + assert servers == [] + assert scopes is None + mock_client.get.assert_not_called() + + @pytest.mark.asyncio + async def test_fetch_oauth_metadata_refuses_unsafe_url(self, monkeypatch): + # End-to-end: a malicious WWW-Authenticate redirecting to a loopback + # resource_metadata URL must not produce a network call. + self._patch_resolves(monkeypatch, {"attacker.example.com": ["127.0.0.1"]}) + manager = MCPServerManager() + + mock_client = MagicMock() + mock_client.get = AsyncMock() + + with patch( + "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", + return_value=mock_client, + ): + servers, scopes = await manager._fetch_oauth_metadata_from_resource( + "https://attacker.example.com/meta", + "https://legit-mcp.example.com/mcp", + ) + + assert servers == [] + assert scopes is None + mock_client.get.assert_not_called() + + @pytest.mark.asyncio + async def test_empty_getaddrinfo_result_blocks_url(self, monkeypatch): + # POSIX doesn't strictly forbid an empty success-list from getaddrinfo. + # async_safe_get must fail closed rather than making a network call. + monkeypatch.setattr( + "litellm.litellm_core_utils.url_utils.socket.getaddrinfo", + lambda *a, **k: [], + ) + manager = MCPServerManager() + + mock_client = MagicMock() + mock_client.get = AsyncMock() + + with patch( + "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", + return_value=mock_client, + ): + servers, scopes = await manager._fetch_oauth_metadata_from_resource( + "https://no-records.example.com/.well-known/oauth-authorization-server", + "https://legit-mcp.example.com/mcp", + ) + + assert servers == [] + assert scopes is None + mock_client.get.assert_not_called() + + @pytest.mark.asyncio + async def test_cross_origin_redirect_is_revalidated(self, monkeypatch): + self._patch_resolves( + monkeypatch, + { + "provider.example.com": ["8.8.8.8"], + "127.0.0.1": ["127.0.0.1"], + }, + ) + manager = MCPServerManager() + + redirect_response = MagicMock() + redirect_response.is_redirect = True + redirect_response.headers = {"location": "http://127.0.0.1/admin"} + + mock_client = MagicMock() + mock_client.get = AsyncMock(return_value=redirect_response) + + with patch( + "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", + return_value=mock_client, + ): + result = await manager._fetch_single_authorization_server_metadata( + "https://provider.example.com", + "https://legit-mcp.example.com/mcp", + ) + + assert result is None + assert mock_client.get.await_count == 3 + + @pytest.mark.asyncio + async def test_same_authority_fetch_does_not_follow_redirects(self): + # Same-authority URLs may be internal admin-configured MCP servers, so + # they are fetched directly. Redirects are still disabled because a + # Location target would not inherit the same-authority guarantee. + manager = MCPServerManager() + + mock_response = MagicMock() + mock_response.json.return_value = { + "authorization_servers": ["https://auth.example.com"], + } + mock_response.raise_for_status = MagicMock() + + captured_kwargs: Dict[str, Any] = {} + + async def fake_get(url, **kwargs): + captured_kwargs.update(kwargs) + return mock_response + + mock_client = MagicMock() + mock_client.get = AsyncMock(side_effect=fake_get) + + with patch( + "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", + return_value=mock_client, + ): + await manager._fetch_oauth_metadata_from_resource( + "https://protected.example.com/.well-known/oauth", + "https://protected.example.com/mcp", + ) + assert captured_kwargs.get("follow_redirects") is False + + @pytest.mark.asyncio + async def test_same_authority_auth_server_fetch_does_not_follow_redirects(self): + # Same redirect-bypass concern for the authorization-server fetch path. + manager = MCPServerManager() + + mock_response = MagicMock() + mock_response.json.return_value = { + "authorization_endpoint": "https://provider.example.com/authorize", + "token_endpoint": "https://provider.example.com/token", + } + mock_response.raise_for_status = MagicMock() + + captured_kwargs: Dict[str, Any] = {} + + async def fake_get(url, **kwargs): + captured_kwargs.update(kwargs) + return mock_response + + mock_client = MagicMock() + mock_client.get = AsyncMock(side_effect=fake_get) + + with patch( + "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", + return_value=mock_client, + ): + await manager._fetch_single_authorization_server_metadata( + "https://provider.example.com", + "https://provider.example.com", + ) + assert captured_kwargs.get("follow_redirects") is False + + @pytest.mark.asyncio + async def test_fetch_authorization_server_refuses_unsafe_issuer(self, monkeypatch): + # Mirrors the GHSA-mrfv repro: PRM lists a loopback issuer URL. + self._patch_resolves(monkeypatch, {"attacker.example.com": ["127.0.0.1"]}) + manager = MCPServerManager() + + mock_client = MagicMock() + mock_client.get = AsyncMock() + + with patch( + "litellm.proxy._experimental.mcp_server.mcp_server_manager.get_async_httpx_client", + return_value=mock_client, + ): + result = await manager._fetch_single_authorization_server_metadata( + "http://attacker.example.com:19999", + "https://legit-mcp.example.com/mcp", + ) + + assert result is None + mock_client.get.assert_not_called() + + if __name__ == "__main__": pytest.main([__file__])