From 45fb345a3228faaef281c6180ff3a208451dcf3b Mon Sep 17 00:00:00 2001 From: Tin Date: Thu, 29 Oct 2026 14:19:56 -0700 Subject: [PATCH] fix(admin-mcp): align permissions with registered HTTP routes --- litellm/proxy/admin_mcp.py | 75 +++++++++++------ litellm/proxy/auth/route_checks.py | 19 +++-- tests/unit/proxy/test_admin_mcp.py | 128 ++++++++++++++++++++++++++--- 3 files changed, 179 insertions(+), 43 deletions(-) diff --git a/litellm/proxy/admin_mcp.py b/litellm/proxy/admin_mcp.py index 035c3cebded..32576ea8113 100644 --- a/litellm/proxy/admin_mcp.py +++ b/litellm/proxy/admin_mcp.py @@ -1,13 +1,13 @@ import os import re -from collections.abc import AsyncGenerator, Mapping +from collections.abc import AsyncGenerator, Iterator, Mapping from contextlib import asynccontextmanager from contextvars import ContextVar -from fnmatch import fnmatchcase from typing import Final -from urllib.parse import urlsplit +from urllib.parse import unquote, urlsplit from fastapi import FastAPI, HTTPException, Request +from fastapi.routing import APIRoute from pydantic import TypeAdapter from starlette.datastructures import Headers from starlette.routing import Mount @@ -71,38 +71,65 @@ def _admin_route_allowed(auth: UserAPIKeyAuth, request: Request, method: str, pa return True -def _admin_route_intersects(template: str, grant: str) -> bool: - template_parts: Final = template.strip("/").split("/") - grant_parts: Final = grant.strip("/").split("/") - for segment, allowed in zip(template_parts, grant_parts): - if allowed == "*": - return True - if segment.startswith("{") and segment.endswith("}"): +def _admin_routes(request: Request) -> Iterator[tuple[tuple[str, str], APIRoute]]: + app: Final = request.app + if not isinstance(app, FastAPI): + return + for route in app.routes: + if not isinstance(route, APIRoute): continue - if not fnmatchcase(segment, allowed): - return False - return len(grant_parts) <= len(template_parts) + for method in route.methods: + yield (method, route.path_format), route -def _admin_tool_visible(auth: UserAPIKeyAuth, request: Request, method: str, path: str) -> bool: - if _admin_route_allowed(auth, request, method, path): +def _admin_grant_paths(route: APIRoute, grant: str) -> Iterator[str]: + if route.path_regex.fullmatch(grant) is not None: + yield grant + prefix: Final = grant[:-1] if grant.endswith("*") else grant + "/" + representative: Final = re.sub(r"\{[^}]+\}", "_", route.path_format) + # A matching suffix supplies the rest of a concrete route for prefix grants, + # including grants ending inside a static segment or a path parameter. + for candidate in (prefix + representative[offset:] for offset in range(len(representative) + 1)): + if route.path_regex.fullmatch(candidate) is not None: + yield candidate + + +def _admin_grant_allowed(auth: UserAPIKeyAuth, request: Request, method: str, route: APIRoute, grant: str) -> bool: + return any(_admin_route_allowed(auth, request, method, path) for path in _admin_grant_paths(route, grant)) + + +def _admin_tool_visible(auth: UserAPIKeyAuth, request: Request, method: str, route: APIRoute) -> bool: + try: + RouteChecks.check_route_enabled(route.path) + except HTTPException: + return False + if _admin_route_allowed(auth, request, method, route.path): return True grants: Final = _ROUTE_GRANTS.validate_python(getattr(auth, "allowed_routes", None) or ()) - return "{" in path and any(_admin_route_intersects(path, grant) for grant in grants if grant.startswith("/")) + return bool(route.param_convertors) and any( + _admin_grant_allowed(auth, request, method, route, grant) for grant in grants if grant.startswith("/") + ) def get_admin_mcp_permissions( auth: UserAPIKeyAuth, request: Request, tool: str | None = None, path: str | None = None ) -> AdminMCPPermissions: - from litellm_admin_mcp.catalog import ( # pyright: ignore[reportMissingTypeStubs] # connector has no py.typed marker - BY_NAME, - OPERATIONS, - ) + try: + from litellm_admin_mcp.catalog import ( # pyright: ignore[reportMissingTypeStubs] # connector has no py.typed marker + BY_NAME, + OPERATIONS, + ) + except ImportError as exc: + raise HTTPException( + status_code=503, detail="Admin MCP permissions require the admin-mcp dependency group (Python 3.12+)" + ) from exc + routes: Final = dict(_admin_routes(request)) allowed: Final = tuple( operation.name for operation in OPERATIONS - if _admin_tool_visible(auth, request, operation.method, operation.path) + if (route := routes.get((operation.method, operation.path))) is not None + and _admin_tool_visible(auth, request, operation.method, route) ) if tool is None: return AdminMCPPermissions(tools=allowed) @@ -111,8 +138,10 @@ def get_admin_mcp_permissions( return AdminMCPPermissions(tools=allowed, action_allowed=False) if path is None: return AdminMCPPermissions(tools=allowed, action_allowed=True) - action_allowed: Final = RouteChecks.check_route_access(path, (operation.path,)) and _admin_route_allowed( - auth, request, operation.method, path + registered: Final = routes[(operation.method, operation.path)] + decoded_path: Final = unquote(path) + action_allowed: Final = registered.path_regex.fullmatch(decoded_path) is not None and _admin_route_allowed( + auth, request, operation.method, decoded_path ) return AdminMCPPermissions(tools=allowed, action_allowed=action_allowed) diff --git a/litellm/proxy/auth/route_checks.py b/litellm/proxy/auth/route_checks.py index 74e4c4c6d11..a35168ebb82 100644 --- a/litellm/proxy/auth/route_checks.py +++ b/litellm/proxy/auth/route_checks.py @@ -110,14 +110,7 @@ _TOKEN_COUNTING_ACTION: Final = "countTokens" class RouteChecks: @staticmethod - def should_call_route( - route: str, - valid_token: UserAPIKeyAuth, - request: Request | None = None, - ): - """ - Check if management route is disabled and raise exception - """ + def check_route_enabled(route: str) -> None: try: from litellm_enterprise.proxy.auth.route_checks import EnterpriseRouteChecks @@ -127,6 +120,16 @@ class RouteChecks: except Exception: pass + @staticmethod + def should_call_route( + route: str, + valid_token: UserAPIKeyAuth, + request: Request | None = None, + ): + """ + Check if management route is disabled and raise exception + """ + RouteChecks.check_route_enabled(route) # Check if Virtual Key is allowed to call the route - Applies to all Roles RouteChecks.is_virtual_key_allowed_to_call_route(route=route, valid_token=valid_token, request=request) return True diff --git a/tests/unit/proxy/test_admin_mcp.py b/tests/unit/proxy/test_admin_mcp.py index 1638ada46f5..0bebc9141e1 100644 --- a/tests/unit/proxy/test_admin_mcp.py +++ b/tests/unit/proxy/test_admin_mcp.py @@ -577,34 +577,138 @@ async def test_oauth2_proxy_auth_preserves_native_identity_and_peer_trust( assert "list_keys" in {tool["name"] for tool in response.json()["result"]["tools"]} +@pytest.fixture +def permissions_request() -> Request: + return Request({"type": "http", "method": "GET", "path": "/user/info", "headers": [], "app": proxy_server.app}) + + +@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+") @pytest.mark.parametrize( "routes,session,can_write", - [(None, False, True), ([], False, True), (["management_routes"], False, True), - (["info_routes"], False, False), (["llm_api_routes"], False, False), (None, True, True), (["info_routes"], True, False)], + [ + (None, False, True), + ([], False, True), + (["management_routes"], False, True), + (["info_routes"], False, False), + (["llm_api_routes"], False, False), + (None, True, True), + (["info_routes"], True, False), + ], ) def test_admin_mcp_uses_credential_routes_without_removing_full_access( - routes: list[str] | None, session: bool, can_write: bool + routes: list[str] | None, session: bool, can_write: bool, permissions_request: Request ) -> None: auth: Final = UserAPIKeyAuth( - user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=routes, is_session_token=session, + user_id="admin", + user_role=LitellmUserRoles.PROXY_ADMIN, + allowed_routes=routes, + is_session_token=session, ) - request: Final = Request({"type": "http", "method": "GET", "path": "/user/info", "headers": []}) - permissions: Final = get_admin_mcp_permissions(auth, request, "create_key", "/key/generate") + permissions: Final = get_admin_mcp_permissions(auth, permissions_request, "create_key", "/key/generate") assert permissions.action_allowed is can_write assert ("create_key" in permissions.tools) is can_write +@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+") @pytest.mark.parametrize("grant", ["/team/team-a/callback", "/team/team-a/*"]) -def test_admin_mcp_checks_the_concrete_resource_even_when_the_tool_is_visible(grant: str) -> None: +def test_admin_mcp_checks_the_concrete_resource_even_when_the_tool_is_visible( + grant: str, permissions_request: Request +) -> None: auth: Final = UserAPIKeyAuth( - user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=["/user/info", grant], + user_id="admin", + user_role=LitellmUserRoles.PROXY_ADMIN, + allowed_routes=["/user/info", grant], metadata={"is_session_token": True, "user_role": "proxy_admin"}, ) - request: Final = Request({"type": "http", "method": "GET", "path": "/user/info", "headers": []}) - own: Final = get_admin_mcp_permissions(auth, request, "get_team_callbacks", "/team/team-a/callback") - other: Final = get_admin_mcp_permissions(auth, request, "get_team_callbacks", "/team/team-b/callback") - wrong_route: Final = get_admin_mcp_permissions(auth, request, "get_team_callbacks", "/key/generate") + own: Final = get_admin_mcp_permissions(auth, permissions_request, "get_team_callbacks", "/team/team-a/callback") + other: Final = get_admin_mcp_permissions(auth, permissions_request, "get_team_callbacks", "/team/team-b/callback") + wrong_route: Final = get_admin_mcp_permissions(auth, permissions_request, "get_team_callbacks", "/key/generate") assert "get_team_callbacks" in own.tools assert own.action_allowed is True assert other.action_allowed is False assert wrong_route.action_allowed is False + + +@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+") +@pytest.mark.parametrize("grant", ["/team/org/team-a/callback", "/team/org/team-a/*", "/team/org/team-a/call*"]) +def test_admin_mcp_authorizes_slashes_using_the_registered_route(grant: str, permissions_request: Request) -> None: + auth: Final = UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=["/user/info", grant]) + own: Final = get_admin_mcp_permissions(auth, permissions_request, "get_team_callbacks", "/team/org/team-a/callback") + other: Final = get_admin_mcp_permissions( + auth, permissions_request, "get_team_callbacks", "/team/org/team-b/callback" + ) + assert "get_team_callbacks" in own.tools + assert own.action_allowed is True + assert other.action_allowed is False + + +@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+") +@pytest.mark.parametrize( + "grant,path", + [ + ("/team/team a/callback", "/team/team%20a/callback"), + ("/team/org/team-a/callback", "/team/org%2Fteam-a/callback"), + ("/team/team%2Fa/callback", "/team/team%252Fa/callback"), + ], +) +def test_admin_mcp_decodes_the_action_path_once(grant: str, path: str, permissions_request: Request) -> None: + auth: Final = UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=["/user/info", grant]) + own: Final = get_admin_mcp_permissions(auth, permissions_request, "get_team_callbacks", path) + other: Final = get_admin_mcp_permissions(auth, permissions_request, "get_team_callbacks", "/team/other/callback") + assert own.action_allowed is True + assert other.action_allowed is False + + +@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+") +@pytest.mark.parametrize("grant", ["/te?m/*", "/[t]eam/*", "/te*m/*"]) +def test_admin_mcp_does_not_invent_glob_permissions(grant: str, permissions_request: Request) -> None: + auth: Final = UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=["/user/info", grant]) + permissions: Final = get_admin_mcp_permissions( + auth, permissions_request, "get_team_callbacks", "/team/team-a/callback" + ) + assert "get_team_callbacks" not in permissions.tools + assert permissions.action_allowed is False + + +@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+") +def test_admin_mcp_discovery_respects_disabled_management_routes( + permissions_request: Request, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setattr(proxy_server, "premium_user", True) + monkeypatch.setenv("DISABLE_ADMIN_ENDPOINTS", "true") + auth: Final = UserAPIKeyAuth( + user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=["/user/info", "/key/key-a/reset_spend"] + ) + permissions: Final = get_admin_mcp_permissions( + auth, permissions_request, "reset_key_spend", "/key/key-a/reset_spend" + ) + assert permissions.tools == () + assert permissions.action_allowed is False + + +@pytest.mark.skipif(sys.version_info < (3, 12), reason="Admin MCP requires Python 3.12+") +def test_admin_mcp_preserves_http_prefix_grants(permissions_request: Request) -> None: + auth: Final = UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN, allowed_routes=["/user/info", "/key/list"]) + own: Final = get_admin_mcp_permissions(auth, permissions_request, "reset_key_spend", "/key/list/reset_spend") + other: Final = get_admin_mcp_permissions(auth, permissions_request, "reset_key_spend", "/key/other/reset_spend") + assert "reset_key_spend" in own.tools + assert own.action_allowed is True + assert other.action_allowed is False + + +@pytest.mark.asyncio +async def test_user_info_explains_missing_admin_mcp_dependency( + permissions_request: Request, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setitem(sys.modules, "litellm_admin_mcp.catalog", None) + auth: Final = UserAPIKeyAuth(user_id="admin", user_role=LitellmUserRoles.PROXY_ADMIN) + with pytest.raises(ProxyException, match="admin-mcp dependency group") as exc: + await internal_user_endpoints.user_info( + request=permissions_request, + user_id=None, + user_api_key_dict=auth, + admin_mcp=True, + mcp_tool=None, + mcp_path=None, + ) + assert exc.value.code == "503"