mirror of
https://github.com/BerriAI/litellm.git
synced 2026-11-16 09:22:22 +00:00
Merge 661aa8cf0a into 17d1f58336
This commit is contained in:
commit
05b84ec0c3
7 changed files with 203 additions and 2 deletions
|
|
@ -65,6 +65,10 @@ from litellm.exceptions import (
|
|||
|
||||
GUARDRAIL_SESSIONS_TARGET: Final = "guardrail_sessions"
|
||||
|
||||
MCP_SERVER_GUARDRAILS_KEY: Final = "mcp_server_guardrails"
|
||||
|
||||
_MCP_SERVER_SCOPED_HOOKS: Final = frozenset({GuardrailEventHooks.pre_mcp_call, GuardrailEventHooks.post_mcp_call})
|
||||
|
||||
# Per-process secret tagging each recorded marker. The deployment hook only
|
||||
# honors markers carrying this token, so a caller cannot forge the metadata
|
||||
# field to suppress a guardrail on the direct-SDK path that never reaches the
|
||||
|
|
@ -1199,6 +1203,9 @@ class CustomGuardrail(CustomLogger):
|
|||
if self._suppressed_by_auto_router_compression():
|
||||
return False
|
||||
|
||||
if self._attached_to_mcp_server(cast(object, data), event_type): # cast-ok: untyped data param
|
||||
return self._event_hook_is_event_type(event_type)
|
||||
|
||||
requested_guardrails: Final = self.get_guardrail_from_metadata(data)
|
||||
disable_global_guardrail: Final = self.get_disable_global_guardrail(data)
|
||||
opted_out_global_guardrails: Final = self.get_opted_out_global_guardrails_from_metadata(data)
|
||||
|
|
@ -1262,6 +1269,12 @@ class CustomGuardrail(CustomLogger):
|
|||
return mode_tag_result and self.stream_scope_allows(cast(object, data), event_type) # cast-ok: data
|
||||
return self.stream_scope_allows(cast(object, data), event_type) # cast-ok: data param
|
||||
|
||||
def _attached_to_mcp_server(self, data: object, event_type: GuardrailEventHooks) -> bool:
|
||||
if event_type not in _MCP_SERVER_SCOPED_HOOKS or not isinstance(data, Mapping):
|
||||
return False
|
||||
server_guardrails: Final = cast(Mapping[str, object], data).get(MCP_SERVER_GUARDRAILS_KEY) # cast-ok: data
|
||||
return isinstance(server_guardrails, list) and self.guardrail_name in server_guardrails
|
||||
|
||||
def _event_hook_is_event_type(self, event_type: GuardrailEventHooks) -> bool:
|
||||
"""
|
||||
Returns True if the event_hook is the same as the event_type
|
||||
|
|
|
|||
|
|
@ -73,6 +73,7 @@ from litellm.constants import (
|
|||
MCP_UPSTREAM_SESSION_SHUTDOWN_TIMEOUT_SECONDS,
|
||||
)
|
||||
from litellm.exceptions import BlockedPiiEntityError, GuardrailRaisedException
|
||||
from litellm.integrations.custom_guardrail import MCP_SERVER_GUARDRAILS_KEY
|
||||
from litellm.litellm_core_utils.url_utils import SSRFError, async_safe_get
|
||||
from litellm.llms.custom_httpx.http_handler import get_async_httpx_client
|
||||
from litellm.mcp_client.client import (
|
||||
|
|
@ -434,6 +435,7 @@ class MCPServerConfig(TypedDict, total=False):
|
|||
allowed_tools: _StringList
|
||||
disallowed_tools: _StringList
|
||||
allowed_params: _ToolParamMap
|
||||
guardrails: _StringList
|
||||
access_groups: _StringList
|
||||
static_headers: _StringMap
|
||||
env_vars: _EnvVarList
|
||||
|
|
@ -2817,6 +2819,7 @@ class MCPServerManager:
|
|||
disallowed_tools=server_config.get("disallowed_tools", None),
|
||||
allowed_params=server_config.get("allowed_params", None),
|
||||
pinned_tools=server_config.get("pinned_tools", None),
|
||||
guardrails=server_config.get("guardrails", None),
|
||||
access_groups=server_config.get("access_groups", None),
|
||||
static_headers=server_config.get("static_headers", None),
|
||||
env_vars=server_config.get("env_vars", None),
|
||||
|
|
@ -6293,6 +6296,7 @@ class MCPServerManager:
|
|||
and proxy_logging_obj.has_pre_call_guardrails(
|
||||
TypeAdapter(Mapping[str, object]).validate_python(initial_data.get("metadata") or {}),
|
||||
event_type=GuardrailEventHooks.pre_mcp_call,
|
||||
server_guardrails=server.guardrails or (),
|
||||
)
|
||||
else tool
|
||||
)
|
||||
|
|
@ -6311,6 +6315,7 @@ class MCPServerManager:
|
|||
else {}
|
||||
),
|
||||
"litellm_logging_obj": litellm_logging_obj,
|
||||
MCP_SERVER_GUARDRAILS_KEY: list(server.guardrails or ()),
|
||||
}
|
||||
|
||||
try:
|
||||
|
|
|
|||
|
|
@ -55,6 +55,7 @@ from litellm.constants import (
|
|||
MAXIMUM_TRACEBACK_LINES_TO_LOG,
|
||||
MCP_TOOL_LISTING_TIMEOUT,
|
||||
)
|
||||
from litellm.integrations.custom_guardrail import MCP_SERVER_GUARDRAILS_KEY
|
||||
from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
|
||||
from litellm.proxy._types import (
|
||||
UserAPIKeyAuth,
|
||||
|
|
@ -2447,6 +2448,7 @@ async def _execute_mcp_tool(
|
|||
original_auth=user_api_key_auth,
|
||||
guardrail_auth=effective_guardrail_auth,
|
||||
request_data=kwargs,
|
||||
server_guardrails=tuple(mcp_server.guardrails or ()),
|
||||
),
|
||||
wire_compat=wire_compat,
|
||||
input_responses=input_responses,
|
||||
|
|
@ -2545,6 +2547,7 @@ async def _execute_mcp_tool(
|
|||
original_auth=user_api_key_auth,
|
||||
guardrail_auth=effective_guardrail_auth,
|
||||
request_data=kwargs,
|
||||
server_guardrails=tuple(mcp_server.guardrails or ()) if mcp_server is not None else (),
|
||||
)
|
||||
|
||||
|
||||
|
|
@ -2554,6 +2557,7 @@ def _guarded_progress_callback(
|
|||
original_auth: UserAPIKeyAuth | None,
|
||||
guardrail_auth: UserAPIKeyAuth | None,
|
||||
request_data: Mapping[str, object],
|
||||
server_guardrails: tuple[str, ...] = (),
|
||||
) -> ProgressCallback | None:
|
||||
if callback is None:
|
||||
return None
|
||||
|
|
@ -2569,6 +2573,7 @@ def _guarded_progress_callback(
|
|||
original_auth=original_auth,
|
||||
guardrail_auth=guardrail_auth,
|
||||
request_data=request_data,
|
||||
server_guardrails=server_guardrails,
|
||||
)
|
||||
filtered: Final = TextContent.model_validate(checked.content[0]).text
|
||||
except Exception: # noqa: BLE001 # any guardrail failure must withhold unverified progress text
|
||||
|
|
@ -2586,6 +2591,7 @@ async def _run_post_mcp_call_guardrails(
|
|||
original_auth: UserAPIKeyAuth | None,
|
||||
guardrail_auth: UserAPIKeyAuth | None,
|
||||
request_data: Mapping[str, object],
|
||||
server_guardrails: tuple[str, ...] = (),
|
||||
) -> CallToolResult:
|
||||
"""Run ``post_mcp_call`` guardrails over an executed tool result.
|
||||
|
||||
|
|
@ -2604,6 +2610,7 @@ async def _run_post_mcp_call_guardrails(
|
|||
request_data_for_hook: Final = (
|
||||
litellm_logging_obj.model_call_details if litellm_logging_obj is not None else dict(request_data)
|
||||
)
|
||||
request_data_for_hook[MCP_SERVER_GUARDRAILS_KEY] = list(server_guardrails)
|
||||
return await proxy_logging_obj.post_mcp_call_hook(
|
||||
response=result,
|
||||
request_data=request_data_for_hook,
|
||||
|
|
@ -2674,6 +2681,7 @@ async def _run_post_mcp_call_guardrails(
|
|||
**resolved_auth_metadata,
|
||||
"guardrails": list(merged_guardrails),
|
||||
},
|
||||
MCP_SERVER_GUARDRAILS_KEY: list(server_guardrails),
|
||||
}
|
||||
return await proxy_logging_obj.post_mcp_call_hook(
|
||||
response=result,
|
||||
|
|
|
|||
|
|
@ -145,6 +145,7 @@ from litellm.exceptions import (
|
|||
SensitiveDataRouteException,
|
||||
)
|
||||
from litellm.integrations.custom_guardrail import (
|
||||
MCP_SERVER_GUARDRAILS_KEY,
|
||||
CustomGuardrail,
|
||||
ModifyResponseException,
|
||||
)
|
||||
|
|
@ -2878,6 +2879,7 @@ class ProxyLogging:
|
|||
self,
|
||||
request_metadata: Mapping[str, object],
|
||||
event_type: GuardrailEventHooks = GuardrailEventHooks.pre_call,
|
||||
server_guardrails: Sequence[str] = (),
|
||||
) -> bool:
|
||||
"""
|
||||
Whether anything configured would inspect the content of a request carrying this metadata.
|
||||
|
|
@ -2895,7 +2897,7 @@ class ProxyLogging:
|
|||
caps: Final = ProxyLogging.callback_capabilities()
|
||||
if caps.has_content_enforcer:
|
||||
return True
|
||||
probe: Final = {"metadata": dict(request_metadata)}
|
||||
probe: Final = {"metadata": dict(request_metadata), MCP_SERVER_GUARDRAILS_KEY: list(server_guardrails)}
|
||||
return any(
|
||||
isinstance(callback, CustomGuardrail) and callback.should_run_guardrail(data=probe, event_type=event_type)
|
||||
for callback in caps.resolved_callbacks
|
||||
|
|
|
|||
|
|
@ -112,6 +112,7 @@ class MCPServer(LiteLLMBaseModel):
|
|||
tool_name_to_display_name: dict[str, str] | None = None
|
||||
tool_name_to_description: dict[str, str] | None = None
|
||||
pinned_tools: dict[str, PinnedMCPTool] | None = None
|
||||
guardrails: list[str] | None = None
|
||||
allowed_params: dict[str, list[str]] | None = None # map of tool names to allowed parameter lists
|
||||
static_headers: dict[str, str] | None = None # static headers to forward to the MCP server
|
||||
# Admin-configured env vars. Each entry is {name, value, scope, description}.
|
||||
|
|
|
|||
139
tests/unit/proxy/mcp_server/test_mcp_server_guardrails.py
Normal file
139
tests/unit/proxy/mcp_server/test_mcp_server_guardrails.py
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
"""Per-MCP-server ``guardrails``: a server's listed guardrails run for its tool calls only."""
|
||||
|
||||
from typing import Final, cast
|
||||
from unittest.mock import AsyncMock, MagicMock, patch
|
||||
|
||||
import pytest
|
||||
from mcp.types import CallToolResult, TextContent
|
||||
|
||||
from litellm.integrations.custom_guardrail import MCP_SERVER_GUARDRAILS_KEY, CustomGuardrail
|
||||
from litellm.proxy.mcp_server import operations
|
||||
from litellm.proxy.mcp_server.mcp_server_manager import MCPServerManager
|
||||
from litellm.proxy.utils import ProxyLogging
|
||||
from litellm.types.guardrails import GuardrailEventHooks
|
||||
from litellm.types.mcp import MCPAuth, MCPTransport
|
||||
from litellm.types.mcp_server.mcp_server_manager import MCPServer
|
||||
|
||||
SCOPED: Final = "scoped-guardrail"
|
||||
|
||||
|
||||
def _guardrail(mode: GuardrailEventHooks, default_on: bool = False) -> CustomGuardrail:
|
||||
return CustomGuardrail(guardrail_name=SCOPED, event_hook=mode, default_on=default_on)
|
||||
|
||||
|
||||
def _server(guardrails: list[str] | None) -> MCPServer:
|
||||
return MCPServer(
|
||||
server_id="tickets-id",
|
||||
name="tickets",
|
||||
server_name="tickets",
|
||||
url="https://example.com/mcp",
|
||||
transport=MCPTransport.http,
|
||||
auth_type=MCPAuth.none,
|
||||
guardrails=guardrails,
|
||||
)
|
||||
|
||||
|
||||
@pytest.mark.parametrize("hook", [GuardrailEventHooks.pre_mcp_call, GuardrailEventHooks.post_mcp_call])
|
||||
def test_listed_guardrail_runs_for_its_server_without_default_on(hook: GuardrailEventHooks) -> None:
|
||||
assert _guardrail(hook).should_run_guardrail({MCP_SERVER_GUARDRAILS_KEY: [SCOPED]}, hook) is True
|
||||
|
||||
|
||||
@pytest.mark.parametrize("server_guardrails", [[], ["other"]])
|
||||
def test_unlisted_guardrail_does_not_run_on_another_server(server_guardrails: list[str]) -> None:
|
||||
guardrail: Final = _guardrail(GuardrailEventHooks.pre_mcp_call)
|
||||
data: Final = {MCP_SERVER_GUARDRAILS_KEY: server_guardrails}
|
||||
assert guardrail.should_run_guardrail(data, GuardrailEventHooks.pre_mcp_call) is False
|
||||
|
||||
|
||||
def test_listed_guardrail_still_honours_its_mode() -> None:
|
||||
guardrail: Final = _guardrail(GuardrailEventHooks.post_mcp_call)
|
||||
data: Final = {MCP_SERVER_GUARDRAILS_KEY: [SCOPED]}
|
||||
assert guardrail.should_run_guardrail(data, GuardrailEventHooks.pre_mcp_call) is False
|
||||
|
||||
|
||||
def test_server_list_is_ignored_outside_mcp_events() -> None:
|
||||
guardrail: Final = CustomGuardrail(guardrail_name=SCOPED, event_hook=GuardrailEventHooks.pre_call)
|
||||
data: Final = {MCP_SERVER_GUARDRAILS_KEY: [SCOPED]}
|
||||
assert guardrail.should_run_guardrail(data, GuardrailEventHooks.pre_call) is False
|
||||
|
||||
|
||||
def test_server_listing_overrides_key_opt_out() -> None:
|
||||
guardrail: Final = _guardrail(GuardrailEventHooks.pre_mcp_call, default_on=True)
|
||||
data: Final = {MCP_SERVER_GUARDRAILS_KEY: [SCOPED], "metadata": {"disable_global_guardrail": True}}
|
||||
assert guardrail.should_run_guardrail(data, GuardrailEventHooks.pre_mcp_call) is True
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_config_guardrails_are_loaded_onto_the_server(
|
||||
config_only_mcp_manager_factory: type[MCPServerManager],
|
||||
) -> None:
|
||||
manager: Final = config_only_mcp_manager_factory()
|
||||
await manager.load_servers_from_config(
|
||||
{"tickets": {"url": "https://example.com/mcp", "transport": "http", "guardrails": [SCOPED]}}
|
||||
)
|
||||
servers: Final = [s for s in manager.config_mcp_servers.values() if s.name == "tickets"]
|
||||
assert [s.guardrails for s in servers] == [[SCOPED]]
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize(("listed", "expected"), [([SCOPED], [SCOPED]), (None, [])])
|
||||
async def test_pre_call_tool_check_passes_server_guardrails(listed: list[str] | None, expected: list[str]) -> None:
|
||||
manager: Final = MCPServerManager()
|
||||
proxy_logging: Final = MagicMock(spec=ProxyLogging)
|
||||
proxy_logging.create_mcp_request_object_from_kwargs = MagicMock(return_value=MagicMock())
|
||||
proxy_logging.convert_mcp_to_llm_format = MagicMock(return_value={"model": "fake"})
|
||||
seen_data: Final[list[dict[str, object]]] = []
|
||||
seen_server_guardrails: Final[list[object]] = []
|
||||
|
||||
def has_pre_call_guardrails(*_args: object, **kwargs: object) -> bool:
|
||||
seen_server_guardrails.append(kwargs["server_guardrails"])
|
||||
return False
|
||||
|
||||
async def pre_call_hook(**kwargs: object) -> None:
|
||||
seen_data.append(cast(dict[str, object], kwargs["data"]))
|
||||
|
||||
proxy_logging.has_pre_call_guardrails = has_pre_call_guardrails
|
||||
proxy_logging.pre_call_hook = pre_call_hook
|
||||
proxy_logging.enforce_mcp_server_rate_limits = AsyncMock()
|
||||
|
||||
with (
|
||||
patch.object(manager, "check_allowed_or_banned_tools", return_value=True),
|
||||
patch.object(manager, "check_tool_permission_for_key_team", new_callable=AsyncMock),
|
||||
patch.object(manager, "validate_allowed_params"),
|
||||
):
|
||||
await manager.pre_call_tool_check(
|
||||
name="get_ticket",
|
||||
arguments={},
|
||||
server_name="tickets",
|
||||
user_api_key_auth=None,
|
||||
proxy_logging_obj=proxy_logging,
|
||||
server=_server(listed),
|
||||
)
|
||||
|
||||
assert [d[MCP_SERVER_GUARDRAILS_KEY] for d in seen_data] == [expected]
|
||||
assert seen_server_guardrails == [listed or ()]
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_post_call_guardrails_receive_server_guardrails() -> None:
|
||||
result: Final = CallToolResult(content=[TextContent(type="text", text="ok")])
|
||||
proxy_logging: Final = MagicMock(spec=ProxyLogging)
|
||||
seen_request_data: Final[list[dict[str, object]]] = []
|
||||
|
||||
async def post_mcp_call_hook(**kwargs: object) -> CallToolResult:
|
||||
seen_request_data.append(cast(dict[str, object], kwargs["request_data"]))
|
||||
return result
|
||||
|
||||
proxy_logging.post_mcp_call_hook = post_mcp_call_hook
|
||||
|
||||
with patch("litellm.proxy.proxy_server.proxy_logging_obj", proxy_logging):
|
||||
await operations._run_post_mcp_call_guardrails( # pyright: ignore[reportPrivateUsage]
|
||||
result=result,
|
||||
litellm_logging_obj=None,
|
||||
original_auth=None,
|
||||
guardrail_auth=None,
|
||||
request_data={MCP_SERVER_GUARDRAILS_KEY: ["forged"]},
|
||||
server_guardrails=(SCOPED,),
|
||||
)
|
||||
|
||||
assert [d[MCP_SERVER_GUARDRAILS_KEY] for d in seen_request_data] == [[SCOPED]]
|
||||
|
|
@ -33,6 +33,7 @@ from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, LATEST_HANDSHAKE_VERS
|
|||
from pydantic import JsonValue, TypeAdapter
|
||||
from starlette.types import Message, Receive, Scope, Send
|
||||
|
||||
from litellm.integrations.custom_guardrail import MCP_SERVER_GUARDRAILS_KEY
|
||||
from litellm.proxy._types import (
|
||||
LiteLLM_MCPServerTable,
|
||||
MCPTransport,
|
||||
|
|
@ -11089,6 +11090,35 @@ class TestOboPreflightScopedToAllowedServers:
|
|||
)
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
@pytest.mark.parametrize(("listed", "expected"), [(["scoped-guardrail"], ["scoped-guardrail"]), (None, [])])
|
||||
async def test_call_mcp_tool_hands_server_guardrails_to_post_mcp_call_hook(listed, expected):
|
||||
from litellm.proxy.mcp_server.server import call_mcp_tool
|
||||
from litellm.types.mcp_server.mcp_server_manager import MCPServer
|
||||
|
||||
server = MCPServer(
|
||||
server_id="tickets-id",
|
||||
name="tickets",
|
||||
alias="tickets",
|
||||
server_name="tickets",
|
||||
url="https://example.com/mcp",
|
||||
transport=MCPTransport.http,
|
||||
mcp_info={"server_name": "tickets"},
|
||||
guardrails=listed,
|
||||
)
|
||||
proxy_logging_mock = _mock_mcp_proxy_logging()
|
||||
|
||||
with _managed_tool_returning(server, _call_tool_result(False, "ok"), proxy_logging_mock):
|
||||
await call_mcp_tool(
|
||||
name="tickets-get_ticket",
|
||||
arguments={},
|
||||
user_api_key_auth=UserAPIKeyAuth(api_key="test-key", user_id="test-user"),
|
||||
litellm_logging_obj=_mock_mcp_logging_obj(),
|
||||
)
|
||||
|
||||
assert proxy_logging_mock.post_mcp_call_hook.await_args.kwargs["request_data"][MCP_SERVER_GUARDRAILS_KEY] == expected
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_post_mcp_call_guardrails_return_the_rewritten_result():
|
||||
"""The result a post_mcp_call guardrail rewrote must be what the caller sends back."""
|
||||
|
|
@ -11147,7 +11177,10 @@ async def test_post_mcp_call_guardrails_run_without_a_logging_object():
|
|||
|
||||
assert returned is masked_result
|
||||
proxy_logging_mock.post_mcp_call_hook.assert_awaited_once()
|
||||
assert proxy_logging_mock.post_mcp_call_hook.await_args.kwargs["request_data"] == {"name": "fetch_record"}
|
||||
assert proxy_logging_mock.post_mcp_call_hook.await_args.kwargs["request_data"] == {
|
||||
"name": "fetch_record",
|
||||
MCP_SERVER_GUARDRAILS_KEY: [],
|
||||
}
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue