From 2e1929787f01a52a40f23ffa19ff4be89275dee2 Mon Sep 17 00:00:00 2001 From: albertbausili Date: Fri, 16 Oct 2026 09:27:44 +0200 Subject: [PATCH 1/4] fix(guardrails): use authenticated identity for direct evaluation --- .../proxy/guardrails/guardrail_endpoints.py | 31 ++++++++- .../guardrails/test_guardrail_endpoints.py | 66 ++++++++++++++++++- 2 files changed, 92 insertions(+), 5 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_endpoints.py b/litellm/proxy/guardrails/guardrail_endpoints.py index 94a9d7c2bdf..f2c553b52e7 100644 --- a/litellm/proxy/guardrails/guardrail_endpoints.py +++ b/litellm/proxy/guardrails/guardrail_endpoints.py @@ -13,7 +13,7 @@ from typing import TYPE_CHECKING, Any, Final, Literal, Protocol, TypeVar, Union, from urllib.parse import urlparse from fastapi import APIRouter, Depends, HTTPException, Request -from pydantic import BaseModel, ValidationError +from pydantic import BaseModel, TypeAdapter, ValidationError from litellm._logging import verbose_proxy_logger from litellm.constants import DEFAULT_MAX_RECURSE_DEPTH @@ -2318,6 +2318,26 @@ async def test_custom_code_guardrail( ) +_GUARDRAIL_METADATA_ADAPTER: Final = TypeAdapter(Mapping[str, object]) + + +def _metadata_fields(value: object) -> Mapping[str, object]: + try: + return _GUARDRAIL_METADATA_ADAPTER.validate_python(value) + except ValidationError: + return {} + + +def _guardrail_request_metadata(caller: object, proxy: object) -> Mapping[str, object]: + caller_fields: Final = tuple( + (key, value) for key, value in _metadata_fields(caller).items() if not key.startswith("user_api_key_") + ) + key_identity: Final = tuple( + (key, value) for key, value in _metadata_fields(proxy).items() if key.startswith("user_api_key_") + ) + return dict((*caller_fields, *key_identity)) + + def _execution_timeout_response(timeout: float) -> TestCustomCodeGuardrailResponse: return TestCustomCodeGuardrailResponse( success=False, @@ -2497,9 +2517,14 @@ async def apply_guardrail( if litellm_logging_obj is not None: _patch_logging_obj_for_guardrail(litellm_logging_obj, request) + metadata: Final = _guardrail_request_metadata(request.metadata, data.get("metadata")) request_data: Final[dict] = { - **({"messages": request.messages} if request.messages is not None else {}), - **({"metadata": request.metadata} if request.metadata is not None else {}), + key: value + for key, value in ( + ("messages", request.messages), + ("metadata", metadata if request.metadata is not None or metadata else None), + ) + if value is not None } _input_type: Final = _resolve_guardrail_input_type(active_guardrail, request.input_type) guardrailed_inputs: Final = await active_guardrail.apply_guardrail( diff --git a/tests/unit/proxy/guardrails/test_guardrail_endpoints.py b/tests/unit/proxy/guardrails/test_guardrail_endpoints.py index 13049093d6c..3d5087d6d1e 100644 --- a/tests/unit/proxy/guardrails/test_guardrail_endpoints.py +++ b/tests/unit/proxy/guardrails/test_guardrail_endpoints.py @@ -2127,7 +2127,7 @@ async def test_apply_guardrail_invokes_logging_pipeline(mocker): } -def _patch_apply_guardrail_env(mocker, guardrail_result): +def _patch_apply_guardrail_env(mocker, guardrail_result, processed_data=None): mock_guardrail = mocker.Mock() mock_guardrail.apply_guardrail = AsyncMock(return_value=guardrail_result) @@ -2140,7 +2140,7 @@ def _patch_apply_guardrail_env(mocker, guardrail_result): mock_logging_obj.model_call_details = {} mock_processor = mocker.Mock() mock_processor.common_processing_pre_call_logic = AsyncMock( - return_value=({"guardrail_name": "test-guardrail"}, mock_logging_obj) + return_value=(processed_data or {"guardrail_name": "test-guardrail"}, mock_logging_obj) ) mocker.patch( "litellm.proxy.common_request_processing.ProxyBaseLLMRequestProcessing", @@ -2211,6 +2211,68 @@ async def test_apply_guardrail_forwards_metadata_and_messages_together(mocker): ) +@pytest.mark.asyncio +async def test_apply_guardrail_replaces_caller_identity_with_the_authenticated_key(mocker): + """Identity fields come from the proxy's own sanitized metadata, never from + the caller, so a request cannot impersonate another key or probe its policy.""" + mock_guardrail = _patch_apply_guardrail_env( + mocker, + {"texts": ["ok"]}, + processed_data={ + "guardrail_name": "test-guardrail", + "metadata": { + "route": "/apply_guardrail", + "user_api_key_alias": "billing-app", + "user_api_key_user_id": "u-1", + }, + }, + ) + + request = ApplyGuardrailRequest( + guardrail_name="test-guardrail", + text="hello", + metadata={ + "forbidden_topics": ["tax"], + "user_api_key_alias": "someone-else", + "user_api_key_user_email": "victim@example.com", + }, + ) + await apply_guardrail( + fastapi_request=mocker.Mock(), + request=request, + user_api_key_dict=UserAPIKeyAuth(key_alias="billing-app", user_id="u-1"), + ) + + forwarded = mock_guardrail.apply_guardrail.await_args.kwargs["request_data"]["metadata"] + assert forwarded == { + "forbidden_topics": ["tax"], + "user_api_key_alias": "billing-app", + "user_api_key_user_id": "u-1", + } + + +@pytest.mark.asyncio +async def test_apply_guardrail_attaches_key_identity_when_caller_sends_no_metadata(mocker): + """A caller that sends no metadata still gets the authenticated identity + forwarded, the same shape every LLM route gives a guardrail.""" + mock_guardrail = _patch_apply_guardrail_env( + mocker, + {"texts": ["ok"]}, + processed_data={"guardrail_name": "test-guardrail", "metadata": {"user_api_key_alias": "billing-app"}}, + ) + + request = ApplyGuardrailRequest(guardrail_name="test-guardrail", text="hello") + await apply_guardrail( + fastapi_request=mocker.Mock(), + request=request, + user_api_key_dict=UserAPIKeyAuth(key_alias="billing-app"), + ) + + assert mock_guardrail.apply_guardrail.await_args.kwargs["request_data"] == { + "metadata": {"user_api_key_alias": "billing-app"} + } + + @pytest.mark.asyncio async def test_apply_guardrail_omits_metadata_when_not_sent(mocker): """Without metadata, request_data stays empty (backward-compatible).""" From d61c6c4d0de5983fa918ac158665b9553cb08d58 Mon Sep 17 00:00:00 2001 From: albertbausili Date: Fri, 16 Oct 2026 09:33:39 +0200 Subject: [PATCH 2/4] fix(guardrails): validate processed metadata before identity selection --- litellm/proxy/guardrails/guardrail_endpoints.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/litellm/proxy/guardrails/guardrail_endpoints.py b/litellm/proxy/guardrails/guardrail_endpoints.py index f2c553b52e7..c66fe78dbdb 100644 --- a/litellm/proxy/guardrails/guardrail_endpoints.py +++ b/litellm/proxy/guardrails/guardrail_endpoints.py @@ -2517,7 +2517,9 @@ async def apply_guardrail( if litellm_logging_obj is not None: _patch_logging_obj_for_guardrail(litellm_logging_obj, request) - metadata: Final = _guardrail_request_metadata(request.metadata, data.get("metadata")) + metadata: Final = _guardrail_request_metadata( + request.metadata, _GUARDRAIL_METADATA_ADAPTER.validate_python(data).get("metadata") + ) request_data: Final[dict] = { key: value for key, value in ( From ec2969f7fe7c70cb4486eb5e5424ee1d040f2505 Mon Sep 17 00:00:00 2001 From: Alessandro Pignati Date: Wed, 28 Oct 2026 23:45:22 +0100 Subject: [PATCH 3/4] fix(guardrails): reserve the bare user_api_key metadata field --- .../proxy/guardrails/guardrail_endpoints.py | 10 +++++-- .../guardrails/test_guardrail_endpoints.py | 28 +++++++++++++++++++ 2 files changed, 35 insertions(+), 3 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_endpoints.py b/litellm/proxy/guardrails/guardrail_endpoints.py index c66fe78dbdb..085c4aff5c2 100644 --- a/litellm/proxy/guardrails/guardrail_endpoints.py +++ b/litellm/proxy/guardrails/guardrail_endpoints.py @@ -2328,14 +2328,18 @@ def _metadata_fields(value: object) -> Mapping[str, object]: return {} +def _is_key_identity_field(key: str) -> bool: + return key == "user_api_key" or key.startswith("user_api_key_") + + def _guardrail_request_metadata(caller: object, proxy: object) -> Mapping[str, object]: caller_fields: Final = tuple( - (key, value) for key, value in _metadata_fields(caller).items() if not key.startswith("user_api_key_") + (key, value) for key, value in _metadata_fields(caller).items() if not _is_key_identity_field(key) ) key_identity: Final = tuple( - (key, value) for key, value in _metadata_fields(proxy).items() if key.startswith("user_api_key_") + (key, value) for key, value in _metadata_fields(proxy).items() if _is_key_identity_field(key) ) - return dict((*caller_fields, *key_identity)) + return MappingProxyType(dict((*caller_fields, *key_identity))) def _execution_timeout_response(timeout: float) -> TestCustomCodeGuardrailResponse: diff --git a/tests/unit/proxy/guardrails/test_guardrail_endpoints.py b/tests/unit/proxy/guardrails/test_guardrail_endpoints.py index 3d5087d6d1e..17487b846f8 100644 --- a/tests/unit/proxy/guardrails/test_guardrail_endpoints.py +++ b/tests/unit/proxy/guardrails/test_guardrail_endpoints.py @@ -2251,6 +2251,34 @@ async def test_apply_guardrail_replaces_caller_identity_with_the_authenticated_k } +@pytest.mark.asyncio +async def test_apply_guardrail_ignores_a_caller_supplied_user_api_key(mocker): + """The bare key field carries attribution as much as the prefixed ones, so a caller + cannot set it either.""" + mock_guardrail = _patch_apply_guardrail_env( + mocker, + {"texts": ["ok"]}, + processed_data={ + "guardrail_name": "test-guardrail", + "metadata": {"route": "/apply_guardrail", "user_api_key": "hash-of-the-real-key"}, + }, + ) + + request = ApplyGuardrailRequest( + guardrail_name="test-guardrail", + text="hello", + metadata={"forbidden_topics": ["tax"], "user_api_key": "hash-of-someone-else"}, + ) + await apply_guardrail( + fastapi_request=mocker.Mock(), + request=request, + user_api_key_dict=UserAPIKeyAuth(key_alias="billing-app", user_id="u-1"), + ) + + forwarded = mock_guardrail.apply_guardrail.await_args.kwargs["request_data"]["metadata"] + assert forwarded == {"forbidden_topics": ["tax"], "user_api_key": "hash-of-the-real-key"} + + @pytest.mark.asyncio async def test_apply_guardrail_attaches_key_identity_when_caller_sends_no_metadata(mocker): """A caller that sends no metadata still gets the authenticated identity From 8378cd84916a7758b0d9980bf2114ee5b5c1b95a Mon Sep 17 00:00:00 2001 From: Alessandro Pignati Date: Fri, 30 Oct 2026 11:30:45 +0100 Subject: [PATCH 4/4] fix(guardrails): hand /apply_guardrail guardrails metadata they can write to The metadata built from the authenticated key was a read-only mapping, so a guardrail that annotates it, as OpenAI moderation does, raised a TypeError and the endpoint answered 500. Return a plain dict. --- .../proxy/guardrails/guardrail_endpoints.py | 11 ++++-- .../guardrails/test_guardrail_endpoints.py | 36 +++++++++++++++++++ 2 files changed, 45 insertions(+), 2 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_endpoints.py b/litellm/proxy/guardrails/guardrail_endpoints.py index 0df2bdf28fe..c8657445d8d 100644 --- a/litellm/proxy/guardrails/guardrail_endpoints.py +++ b/litellm/proxy/guardrails/guardrail_endpoints.py @@ -2346,14 +2346,21 @@ def _is_key_identity_field(key: str) -> bool: return key == "user_api_key" or key.startswith("user_api_key_") -def _guardrail_request_metadata(caller: object, proxy: object) -> Mapping[str, object]: +def _guardrail_request_metadata( + caller: object, proxy: object +) -> dict[str, object]: # mutable-ok: guardrails annotate the metadata they are handed + """Caller metadata with the identity fields taken from the authenticated key. + + The result is handed to the guardrail as ``request_data["metadata"]``, which providers + write their own detection details into, so it cannot be a read-only mapping. + """ caller_fields: Final = tuple( (key, value) for key, value in _metadata_fields(caller).items() if not _is_key_identity_field(key) ) key_identity: Final = tuple( (key, value) for key, value in _metadata_fields(proxy).items() if _is_key_identity_field(key) ) - return MappingProxyType(dict((*caller_fields, *key_identity))) + return dict((*caller_fields, *key_identity)) def _execution_timeout_response(timeout: float) -> TestCustomCodeGuardrailResponse: diff --git a/tests/unit/proxy/guardrails/test_guardrail_endpoints.py b/tests/unit/proxy/guardrails/test_guardrail_endpoints.py index ac1a99b3ec9..325b7d7dd89 100644 --- a/tests/unit/proxy/guardrails/test_guardrail_endpoints.py +++ b/tests/unit/proxy/guardrails/test_guardrail_endpoints.py @@ -2291,6 +2291,42 @@ async def test_apply_guardrail_replaces_caller_identity_with_the_authenticated_k } +@pytest.mark.asyncio +async def test_apply_guardrail_hands_the_guardrail_metadata_it_can_write_to(mocker): + """Guardrails such as OpenAI moderation annotate the metadata they are given, so a + read-only mapping turns a normal evaluation into a 500.""" + mock_guardrail = _patch_apply_guardrail_env( + mocker, + {"texts": ["ok"]}, + processed_data={"guardrail_name": "test-guardrail", "metadata": {"user_api_key_alias": "billing-app"}}, + ) + + annotated: Final[list[object]] = [] # mutable-ok: records the metadata the guardrail was handed + + async def annotating_guardrail(**kwargs): + kwargs["request_data"]["metadata"]["moderation_model"] = "omni-moderation-latest" + annotated.append(kwargs["request_data"]["metadata"]) + return {"texts": ["ok"]} + + mock_guardrail.apply_guardrail = annotating_guardrail + + await apply_guardrail( + fastapi_request=mocker.Mock(), + request=ApplyGuardrailRequest( + guardrail_name="test-guardrail", text="hello", metadata={"forbidden_topics": ["tax"]} + ), + user_api_key_dict=UserAPIKeyAuth(key_alias="billing-app"), + ) + + assert annotated == [ + { + "forbidden_topics": ["tax"], + "user_api_key_alias": "billing-app", + "moderation_model": "omni-moderation-latest", + } + ] + + @pytest.mark.asyncio async def test_apply_guardrail_ignores_a_caller_supplied_user_api_key(mocker): """The bare key field carries attribution as much as the prefixed ones, so a caller