fix(mcp): keep guardrail-blocked tool inputs out of spend logs

execute_mcp_tool stamps mcp_tool_call_metadata (with the raw tool
arguments) on the request logger, and the /mcp, /mcp-rest and /mcp/proxy
entry points snapshot the request body into
litellm_params["proxy_server_request"], both before pre_call_tool_check
runs the pre_mcp_call guardrails. A guardrail's result only rebound the
local arguments, so with store_prompts_in_spend_logs on the raw inputs
were stored on the spend log row, including the failure row of a call
the guardrail blocked.

pre_call_tool_check now rewrites both logged copies once the guardrails
have answered. When a guardrail raises, the logged arguments become
{"[redacted]": "blocked by guardrail"} and the exception is re-raised
unchanged. When a guardrail modifies the arguments, the modified ones
are logged. A request body whose arguments wrap the real tool's (the
/mcp/proxy virtual tool) gets {"[redacted]": "modified by guardrail"}
instead of being rewritten in place.

The request_data handed to post_call_failure_hook callbacks also carried
the raw arguments, on the REST and /mcp paths through
fire_mcp_tool_call_failure_logging and _fire_mcp_tool_call_logging, and
on the /mcp/proxy failure path. Those now take arguments from the
logger's recorded request body, so callbacks see the same scrubbed value
as the spend log
This commit is contained in:
Joshua Hoblitt 2026-10-23 11:22:23 -07:00
parent 1e6dc81769
commit 72115d0837
5 changed files with 239 additions and 19 deletions

View file

@ -7,6 +7,7 @@ This is a Proxy
"""
import asyncio
import copy
import datetime
import hashlib
import json
@ -1873,6 +1874,56 @@ def _record_mcp_guardrail_evaluations(
verbose_logger.warning("Failed to record MCP guardrail evaluation for logging: %s", e)
MCP_GUARDRAIL_BLOCKED_ARGUMENTS_PLACEHOLDER: Final[Mapping[str, str]] = MappingProxyType(
{"[redacted]": "blocked by guardrail"}
)
MCP_GUARDRAIL_MODIFIED_ARGUMENTS_PLACEHOLDER: Final[Mapping[str, str]] = MappingProxyType(
{"[redacted]": "modified by guardrail"}
)
def _replace_logged_mcp_tool_arguments(
litellm_logging_obj: "LiteLLMLoggingObj | None",
original_arguments: Mapping[str, object],
logged_arguments: Mapping[str, object],
mismatch_placeholder: Mapping[str, object],
) -> None:
"""Point every spend-log copy of a tool call's inputs at ``logged_arguments``.
``mcp_tool_call_metadata`` and ``litellm_params["proxy_server_request"]`` are both filled
with the raw arguments before the ``pre_mcp_call`` guardrails run. A request body whose
``arguments`` are not the tool's own (the ``/mcp/proxy`` virtual tool wraps them) gets
``mismatch_placeholder`` instead of being rewritten in place.
"""
if litellm_logging_obj is None:
return
try:
model_call_details: Final = litellm_logging_obj.model_call_details
metadata: Final = model_call_details.get("mcp_tool_call_metadata")
if isinstance(metadata, dict) and "arguments" in metadata:
metadata["arguments"] = dict(logged_arguments)
litellm_params: Final = model_call_details.get("litellm_params")
proxy_server_request: Final = (
cast(dict[str, object], litellm_params).get("proxy_server_request") # cast-ok: litellm_params is str-keyed
if isinstance(litellm_params, dict)
else None
)
if not isinstance(proxy_server_request, dict):
return
request_record: Final = cast(dict[str, object], proxy_server_request) # cast-ok: rewritten in place, shared
body: Final = request_record.get("body")
if isinstance(body, Mapping) and "arguments" in body:
body_fields: Final = TypeAdapter(Mapping[str, object]).validate_python(body)
request_record["body"] = {
**body_fields,
"arguments": dict(
logged_arguments if body_fields["arguments"] == original_arguments else mismatch_placeholder
),
}
except Exception as e: # noqa: BLE001 # runs on the block path; must not replace the guardrail's error
verbose_logger.error("Failed to scrub guardrailed MCP tool arguments from logging: %s", e)
def _mcp_discovery_cache_ttl() -> float:
raw: Final = os.environ.get("LITELLM_MCP_DISCOVERY_CACHE_TTL", "60")
try:
@ -6208,13 +6259,23 @@ class MCPServerManager:
synthetic_llm_data: Final = proxy_logging_obj.convert_mcp_to_llm_format(mcp_request_obj, pre_hook_kwargs)
synthetic_llm_data["litellm_logging_obj"] = litellm_logging_obj
# Snapshot before the hooks run: a guardrail may rewrite ``arguments`` in place.
original_arguments: Final = copy.deepcopy(arguments)
try:
# Use standard pre_call_hook
modified_data: Final = await proxy_logging_obj.pre_call_hook(
user_api_key_dict=checked_auth,
data=synthetic_llm_data,
call_type=CallTypes.call_mcp_tool.value,
)
try:
modified_data: Final = await proxy_logging_obj.pre_call_hook(
user_api_key_dict=checked_auth,
data=synthetic_llm_data,
call_type=CallTypes.call_mcp_tool.value,
)
except BaseException:
_replace_logged_mcp_tool_arguments(
litellm_logging_obj,
original_arguments,
MCP_GUARDRAIL_BLOCKED_ARGUMENTS_PLACEHOLDER,
MCP_GUARDRAIL_BLOCKED_ARGUMENTS_PLACEHOLDER,
)
raise
await proxy_logging_obj.enforce_mcp_server_rate_limits(checked_auth, server)
if modified_data:
# Convert response back to MCP format and apply modifications
@ -6225,6 +6286,14 @@ class MCPServerManager:
hook_result["arguments"] = modified_kwargs["arguments"]
if modified_kwargs.get("extra_headers"):
hook_result["extra_headers"] = modified_kwargs["extra_headers"]
logged_arguments: Final[object] = hook_result.get("arguments", arguments)
if logged_arguments != original_arguments and isinstance(logged_arguments, Mapping):
_replace_logged_mcp_tool_arguments(
litellm_logging_obj,
original_arguments,
TypeAdapter(Mapping[str, object]).validate_python(logged_arguments),
MCP_GUARDRAIL_MODIFIED_ARGUMENTS_PLACEHOLDER,
)
except (
BlockedPiiEntityError,

View file

@ -393,11 +393,10 @@ async def _log_virtual_mcp_tool_failure(
request_logging_obj.post_call_failure_hook
)
await failure_hook(
request_data={
"name": name,
"arguments": arguments,
"litellm_logging_obj": failure_logging_obj,
},
request_data=_failure_hook_request_data(
failure_logging_obj,
{"name": name, "arguments": arguments, "litellm_logging_obj": failure_logging_obj},
),
original_exception=exc,
user_api_key_dict=user_api_key_auth,
route="/mcp/call_tool",
@ -2742,6 +2741,30 @@ def suppress_completed_success_logging(logging_obj: LiteLLMLoggingObj) -> None:
logging_obj.mark_logging_complete(event_type="async_success")
def _failure_hook_request_data(
logging_obj: LiteLLMLoggingObj | None, request_data: Mapping[str, object]
) -> dict[str, object]: # mutable-ok: post_call_failure_hook callbacks write into request_data
"""``request_data`` for ``post_call_failure_hook`` callbacks, minus credential fields.
``arguments`` is taken from the logger's recorded request body, which ``pre_call_tool_check``
replaces once a ``pre_mcp_call`` guardrail has blocked or rewritten the tool inputs, so the
raw values the caller sent do not reach the callbacks.
"""
sanitized: Final = {key: value for key, value in request_data.items() if key not in _MCP_CREDENTIAL_REQUEST_FIELDS}
litellm_params: Final[object] = (
logging_obj.model_call_details.get("litellm_params") if logging_obj is not None else None
)
proxy_server_request: Final = _mapping_field(litellm_params, "proxy_server_request")
logged_arguments: Final = _mapping_field(_mapping_field(proxy_server_request, "body"), "arguments")
if "arguments" not in sanitized or logged_arguments is None:
return sanitized
return {**sanitized, "arguments": logged_arguments}
def _mapping_field(value: object, key: str) -> object:
return TypeAdapter(Mapping[str, object]).validate_python(value).get(key) if isinstance(value, Mapping) else None
async def _fire_mcp_tool_call_logging(
logging_obj: LiteLLMLoggingObj,
result: CallToolResult,
@ -2797,11 +2820,8 @@ async def _fire_mcp_tool_call_logging(
return result
if proxy_logging_obj:
sanitized_request_data: Final = {
key: value for key, value in (request_data or {}).items() if key not in _MCP_CREDENTIAL_REQUEST_FIELDS
}
await proxy_logging_obj.post_call_failure_hook(
request_data=sanitized_request_data,
request_data=_failure_hook_request_data(logging_obj, request_data or {}),
original_exception=tool_error,
user_api_key_dict=user_api_key_auth,
route="/mcp/call_tool",
@ -2835,11 +2855,8 @@ async def fire_mcp_tool_call_failure_logging(
if isinstance(exception, MCPUpstreamAuthError) or not proxy_logging_obj or user_api_key_auth is None:
return
sanitized_request_data: Final = {
key: value for key, value in request_data.items() if key not in _MCP_CREDENTIAL_REQUEST_FIELDS
}
await proxy_logging_obj.post_call_failure_hook(
request_data=sanitized_request_data,
request_data=_failure_hook_request_data(logging_obj, request_data),
original_exception=exception,
user_api_key_dict=user_api_key_auth,
route="/mcp/call_tool",

View file

@ -45,6 +45,7 @@ class _RecordingLoggingObj:
self._order = order
self.failure_calls = 0
self.async_failure_calls = 0
self.model_call_details: dict[str, object] = {}
def failure_handler(self, *_args, **_kwargs) -> None:
self.failure_calls += 1

View file

@ -91,6 +91,7 @@ from litellm.llms.custom_httpx.http_handler import AsyncHTTPHandler
import litellm
from litellm.integrations.custom_guardrail import CustomGuardrail
import litellm.llms as litellm_llms
from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
from litellm.proxy.utils import ProxyLogging
from litellm.types.guardrails import GuardrailEventHooks
from litellm.types.integrations.slack_alerting import AlertType
@ -21606,3 +21607,89 @@ class TestMCPUpstreamRateLimitRetry:
assert exc_info.value.fault == ServerListFault(tag="upstream_error", status_code=429)
assert list_tools_page.await_count == 2
RAW_TOOL_ARGUMENTS: Final = {"text": "deploy with glpat-Xq7rT2mPz9Lk4vB8nWc3"}
MASKED_TOOL_ARGUMENTS: Final = {"text": "deploy with [MASKED]"}
BLOCKED_TOOL_ARGUMENTS: Final = {"[redacted]": "blocked by guardrail"}
class _CredentialGuardrail(CustomGuardrail):
def __init__(self, outcome: Literal["block", "mask", "pass"]) -> None:
super().__init__(guardrail_name="credential-guardrail", event_hook="pre_mcp_call", default_on=True)
self.outcome = outcome
async def async_pre_call_hook(self, user_api_key_dict, cache, data, call_type):
if self.outcome == "block":
raise HTTPException(status_code=400, detail="credential detected")
if self.outcome == "mask":
return {**data, "modified_arguments": dict(MASKED_TOOL_ARGUMENTS)}
return data
def _tool_call_logger(body_arguments: dict[str, object]) -> LiteLLMLoggingObj:
logging_obj: Final = LiteLLMLoggingObj(
model="MCP: echo",
messages=[],
stream=False,
call_type="call_mcp_tool",
start_time=datetime(2026, 1, 1),
litellm_call_id="call-1",
function_id="fn-1",
)
logging_obj.model_call_details["mcp_tool_call_metadata"] = {"name": "echo", "arguments": dict(RAW_TOOL_ARGUMENTS)}
logging_obj.model_call_details["litellm_params"] = {
"proxy_server_request": {"body": {"name": "echo", "arguments": body_arguments}}
}
return logging_obj
async def _run_guardrailed_tool_check(
monkeypatch: pytest.MonkeyPatch, outcome: Literal["block", "mask", "pass"], logging_obj: LiteLLMLoggingObj
) -> None:
monkeypatch.setattr(litellm, "callbacks", [_CredentialGuardrail(outcome)])
call: Final = MCPServerManager().pre_call_tool_check(
name="echo",
arguments=dict(RAW_TOOL_ARGUMENTS),
server_name="echo",
user_api_key_auth=UserAPIKeyAuth(),
proxy_logging_obj=ProxyLogging(user_api_key_cache=DualCache()),
server=MCPServer(server_id="echo", name="echo", server_name="echo", transport=MCPTransport.http),
litellm_logging_obj=logging_obj,
)
if outcome != "block":
await call
return
with pytest.raises(HTTPException):
await call
@pytest.mark.asyncio
@pytest.mark.parametrize(
("outcome", "logged"),
[("block", BLOCKED_TOOL_ARGUMENTS), ("mask", MASKED_TOOL_ARGUMENTS), ("pass", RAW_TOOL_ARGUMENTS)],
)
async def test_pre_call_tool_check_logs_only_the_arguments_the_guardrail_let_through(monkeypatch, outcome, logged):
logging_obj: Final = _tool_call_logger(dict(RAW_TOOL_ARGUMENTS))
await _run_guardrailed_tool_check(monkeypatch, outcome, logging_obj)
details: Final = logging_obj.model_call_details
assert details["mcp_tool_call_metadata"]["arguments"] == logged
assert details["litellm_params"]["proxy_server_request"]["body"] == {"name": "echo", "arguments": logged}
@pytest.mark.asyncio
@pytest.mark.parametrize(
("outcome", "logged_body_arguments"),
[("block", BLOCKED_TOOL_ARGUMENTS), ("mask", {"[redacted]": "modified by guardrail"})],
)
async def test_pre_call_tool_check_replaces_a_wrapping_request_body_with_a_placeholder(
monkeypatch, outcome, logged_body_arguments
):
logging_obj: Final = _tool_call_logger({"tool_id": "echo", "arguments": dict(RAW_TOOL_ARGUMENTS)})
await _run_guardrailed_tool_check(monkeypatch, outcome, logging_obj)
body: Final = logging_obj.model_call_details["litellm_params"]["proxy_server_request"]["body"]
assert body["arguments"] == logged_body_arguments

View file

@ -4,6 +4,7 @@ from typing import Final, Literal
from unittest.mock import AsyncMock, patch
import pytest
from fastapi import HTTPException
from mcp.server.context import ServerRequestContext
from mcp.types import GetPromptRequest, GetPromptRequestParams, GetPromptResult
from mcp.types import Tool as MCPTool
@ -2035,3 +2036,48 @@ async def test_discovery_optional_probes_use_remaining_listing_budget(delay, mon
else:
assert entered.is_set()
assert cleaned.is_set()
class _FailureHookArguments(CustomLogger):
def __init__(self) -> None:
super().__init__()
self.seen: list[object] = []
async def async_post_call_failure_hook(self, request_data, original_exception, user_api_key_dict, traceback_str=None):
self.seen.append(request_data.get("arguments"))
@pytest.mark.asyncio
async def test_failure_hooks_see_the_guardrail_logged_arguments_not_the_raw_ones(monkeypatch):
from datetime import datetime
from litellm.litellm_core_utils.litellm_logging import Logging as LiteLLMLoggingObj
from litellm.proxy import proxy_server
blocked: Final = {"[redacted]": "blocked by guardrail"}
raw: Final = {"text": "deploy with glpat-Xq7rT2mPz9Lk4vB8nWc3"}
callback: Final = _FailureHookArguments()
monkeypatch.setattr(litellm, "callbacks", [callback])
monkeypatch.setattr(proxy_server, "proxy_logging_obj", ProxyLogging(user_api_key_cache=DualCache()))
logging_obj: Final = LiteLLMLoggingObj(
model="MCP: echo",
messages=[],
stream=False,
call_type="call_mcp_tool",
start_time=datetime(2026, 1, 1),
litellm_call_id="call-1",
function_id="fn-1",
)
logging_obj.model_call_details["litellm_params"] = {
"proxy_server_request": {"body": {"name": "echo", "arguments": blocked}}
}
await operations.fire_mcp_tool_call_failure_logging(
logging_obj,
HTTPException(status_code=400, detail="credential detected"),
datetime(2026, 1, 1),
UserAPIKeyAuth(),
{"name": "echo", "arguments": raw, "litellm_logging_obj": logging_obj},
)
assert callback.seen == [blocked]