fix(guardrails): check namespace and nameless tools and relax tool_choice in tool permission rewrite

This commit is contained in:
mateo-berri 2026-10-28 18:51:24 -07:00
parent 993c368c55
commit 69dae9682e
4 changed files with 401 additions and 67 deletions

View file

@ -1,13 +1,13 @@
import json
import re
from collections.abc import AsyncGenerator, AsyncIterable, Mapping, Sequence
from typing import Any, Final, Literal, TypedDict
from itertools import chain
from typing import Any, Final, Literal, TypeAlias, TypedDict
from fastapi import HTTPException
from pydantic import TypeAdapter
from typing_extensions import ReadOnly, Required
from litellm import ChatCompletionToolParam
from litellm._logging import verbose_proxy_logger
from litellm.caching.dual_cache import DualCache
from litellm.completion_extras.litellm_responses_transformation.transformation import (
@ -49,6 +49,8 @@ GUARDRAIL_NAME: Final = "tool_permission"
_RESPONSES_CALL_TYPES: Final = frozenset({"responses", "aresponses", "_aresponses_websocket"})
_DECODED_ARGUMENTS: Final = TypeAdapter(object)
_REQUEST_DATA: Final = TypeAdapter(object)
_OPTIONAL_REQUEST_LIST: Final = TypeAdapter(list[object] | None)
_ToolTarget: TypeAlias = tuple[str | None, str | None]
def _object_mapping(value: object) -> Mapping[str, object] | None:
@ -67,6 +69,67 @@ def _function_tool_name(tool: object) -> str | None:
return name if isinstance(name, str) else None
def _non_empty_string(value: object) -> str | None:
return value if isinstance(value, str) and value else None
def _request_tool_names(tool: object) -> tuple[str, ...]:
fields: Final = _object_mapping(tool)
custom: Final = (
_object_mapping(fields.get("custom")) if fields is not None and fields.get("type") == "custom" else None
)
custom_name: Final = _non_empty_string(custom.get("name")) if custom is not None else None
return anthropic_tool_names(tool) + ((custom_name,) if custom_name is not None else ())
def _namespace_members(tool: object) -> Sequence[object]:
fields: Final = _object_mapping(tool)
members: Final = (
_object_list(fields.get("tools")) if fields is not None and fields.get("type") == "namespace" else None
)
return members or ()
def _namespace_member_target(namespace: str | None, member: object) -> _ToolTarget | None:
fields: Final = _object_mapping(member)
if fields is None:
return None
member_type: Final = _non_empty_string(fields.get("type"))
name: Final = _non_empty_string(fields.get("name"))
qualified: Final = name is not None and namespace is not None and member_type != "custom"
return (f"{namespace}__{name}" if qualified else name, member_type)
def _allowed_tool_entries(tool_choice: Mapping[str, object]) -> Sequence[object] | None:
if tool_choice.get("type") != "allowed_tools":
return None
nested: Final = _object_mapping(tool_choice.get("allowed_tools"))
return _object_list((nested if nested is not None else tool_choice).get("tools"))
def _with_allowed_tool_entries(tool_choice: Mapping[str, object], entries: list[object]) -> dict[str, object]:
nested: Final = _object_mapping(tool_choice.get("allowed_tools"))
if nested is None:
return {**tool_choice, "tools": entries}
return {**tool_choice, "allowed_tools": {**nested, "tools": entries}}
def _is_denied_target(
target: _ToolTarget, denied_targets: frozenset[_ToolTarget], denied_names: frozenset[str]
) -> bool:
return target in denied_targets or target[0] in denied_names
def _none_tool_choice(tool_choice: object) -> object:
choice: Final = _object_mapping(tool_choice)
return {"type": "none"} if choice is not None and choice.get("type") in ("tool", "any") else "none"
def _requires_a_tool(tool_choice: object) -> bool:
choice: Final = _object_mapping(tool_choice)
return tool_choice == "required" or (choice is not None and choice.get("type") == "any")
class _ToolPermissionRuleFields(TypedDict, total=False):
"""The config-file shape a :class:`ToolPermissionRule` is built from."""
@ -618,34 +681,34 @@ class ToolPermissionGuardrail(CustomGuardrail):
if not any(_is_tool_use_block(block) for block in kept_blocks):
response["stop_reason"] = "end_turn" # rebind-ok: dropping every tool_use ends the turn
def _get_request_tool_targets(
self, tool: object, call_type: CallTypesLiteral
) -> tuple[tuple[str, str | None], ...]:
def _get_request_tool_targets(self, tool: object, call_type: CallTypesLiteral) -> tuple[_ToolTarget, ...]:
members: Final = _namespace_members(tool)
if members:
namespace: Final = _non_empty_string(self._get_mapping_value(tool, "name"))
member_targets: Final = (_namespace_member_target(namespace, member) for member in members)
return tuple(target for target in member_targets if target is not None)
tool_type: Final = self._get_mapping_value(tool, "type")
normalized_type: Final = (
tool_type if call_type in _RESPONSES_CALL_TYPES or tool_type not in (None, "custom") else "function"
)
return tuple((name, normalized_type) for name in anthropic_tool_names(tool))
names: Final = _request_tool_names(tool)
if names:
return tuple((name, normalized_type) for name in names)
return ((None, normalized_type),) if isinstance(tool_type, str) else ()
def _get_legacy_function_name(self, function: object) -> str | None:
return self._get_mapping_value(function, "name")
def _get_named_tool_choice(self, data: Mapping[str, object]) -> str | None:
tool_choice: Final = data.get("tool_choice")
def _get_named_tool_choice(self, tool_choice: object) -> str | None:
if not tool_choice or tool_choice in ("auto", "none", "required"):
return None
if isinstance(tool_choice, str):
return tool_choice
if self._get_mapping_value(tool_choice, "type") not in ("tool", "function"):
if self._get_mapping_value(tool_choice, "type") not in ("tool", "function", "custom"):
return None
function_name: Final = self._get_mapping_value(self._get_mapping_value(tool_choice, "function"), "name")
return function_name or self._get_mapping_value(tool_choice, "name")
@staticmethod
def _is_anthropic_tool_choice(data: Mapping[str, object]) -> bool:
tool_choice: Final = _object_mapping(data.get("tool_choice"))
return tool_choice is not None and tool_choice.get("type") == "tool"
def _get_named_function_call(self, data: dict) -> str | None:
function_call: Final = data.get("function_call")
if not function_call or function_call in ("auto", "none"):
@ -654,8 +717,8 @@ class ToolPermissionGuardrail(CustomGuardrail):
return function_call
return self._get_mapping_value(function_call, "name")
def _collect_request_tools(self, data: dict, call_type: CallTypesLiteral) -> list[tuple[str, str | None]]:
request_tools: Final[list[tuple[str, str | None]]] = []
def _collect_request_tools(self, data: dict, call_type: CallTypesLiteral) -> list[_ToolTarget]:
request_tools: Final[list[_ToolTarget]] = []
for tool in data.get("tools") or []:
request_tools.extend(self._get_request_tool_targets(tool, call_type))
@ -666,7 +729,7 @@ class ToolPermissionGuardrail(CustomGuardrail):
request_tools.append((function_name, "function"))
for forced_tool_name in (
self._get_named_tool_choice(data),
self._get_named_tool_choice(_REQUEST_DATA.validate_python(data.get("tool_choice"))),
self._get_named_function_call(data),
):
if forced_tool_name is not None:
@ -677,51 +740,101 @@ class ToolPermissionGuardrail(CustomGuardrail):
return request_tools
def _tool_names_in(self, tools: Sequence[object], call_type: CallTypesLiteral) -> frozenset[str]:
targets: Final = chain.from_iterable(self._get_request_tool_targets(tool, call_type) for tool in tools)
return frozenset(name for name, _ in targets if name is not None)
def _kept_tools(
self,
tool: object,
denied_targets: frozenset[_ToolTarget],
denied_names: frozenset[str],
call_type: CallTypesLiteral,
) -> tuple[object, ...]:
members: Final = _namespace_members(tool)
fields: Final = _object_mapping(tool)
if not members or fields is None:
targets: Final = self._get_request_tool_targets(tool, call_type)
denied: Final = any(_is_denied_target(target, denied_targets, denied_names) for target in targets)
return () if denied else (tool,)
namespace: Final = _non_empty_string(fields.get("name"))
kept_members: Final = [
member
for member in members
if not _is_denied_target(
_namespace_member_target(namespace, member) or (None, None), denied_targets, denied_names
)
]
if not kept_members:
return ()
return (tool,) if len(kept_members) == len(members) else ({**fields, "tools": kept_members},)
def _rewritten_tool_choice(self, tool_choice: object, removed_names: frozenset[str], tools_remain: bool) -> object:
named: Final = self._get_named_tool_choice(tool_choice)
if named is not None and named in removed_names:
return _none_tool_choice(tool_choice)
choice: Final = _object_mapping(tool_choice)
allowed: Final = _allowed_tool_entries(choice) if choice is not None else None
if choice is not None and allowed is not None:
kept: Final = [
entry for entry in allowed if not any(name in removed_names for name in _request_tool_names(entry))
]
return _with_allowed_tool_entries(choice, kept) if kept and tools_remain else _none_tool_choice(choice)
if not tools_remain and (named is not None or _requires_a_tool(tool_choice)):
return _none_tool_choice(tool_choice)
return tool_choice
def _modify_request_with_permission_errors(
self,
data: dict,
denied_tool_names: list[str],
denied_targets: frozenset[_ToolTarget],
call_type: CallTypesLiteral,
):
"""
Modify the request to replace denied tool_calls blocks with error results
Args:
data: The model request to modify
denied_tools: List of (tool_use, error) tuples for denied tools
Remove denied tools from the request, and relax any tool_choice that would still require one
"""
if not denied_tool_names:
if not denied_targets:
return data
verbose_proxy_logger.info("Blocking %s unauthorized tool uses", len(denied_tool_names))
verbose_proxy_logger.info("Blocking %s unauthorized tool uses", len(denied_targets))
# Create a mapping of tool_use_id to error result
error_tool_names: Final = set()
for tool_use in denied_tool_names:
error_tool_names.add(tool_use)
denied_names: Final = frozenset(name for name, _ in denied_targets if name is not None)
tools: Final = _OPTIONAL_REQUEST_LIST.validate_python(data.get("tools"))
kept_tools: Final = (
None
if tools is None
else list(
chain.from_iterable(self._kept_tools(tool, denied_targets, denied_names, call_type) for tool in tools)
)
)
if kept_tools is not None:
data["tools"] = kept_tools
tools: Final[list[ChatCompletionToolParam] | None] = data.get("tools")
if tools is not None:
data["tools"] = [
tool for tool in tools if not any(name in error_tool_names for name in anthropic_tool_names(tool))
]
functions: Final = _OPTIONAL_REQUEST_LIST.validate_python(data.get("functions"))
kept_functions: Final = (
None
if functions is None
else [function for function in functions if self._get_legacy_function_name(function) not in denied_names]
)
if kept_functions is not None:
data["functions"] = kept_functions
functions: Final = data.get("functions")
if functions is not None:
data["functions"] = [
function for function in functions if self._get_legacy_function_name(function) not in error_tool_names
]
named_tool_choice: Final = self._get_named_tool_choice(data)
if named_tool_choice in error_tool_names:
data["tool_choice"] = {"type": "none"} if self._is_anthropic_tool_choice(data) else "none"
removed_names: Final = denied_names | (
self._tool_names_in(tools, call_type) - self._tool_names_in(kept_tools, call_type)
if tools is not None and kept_tools is not None
else frozenset()
)
tool_choice: Final = _REQUEST_DATA.validate_python(data.get("tool_choice"))
if tool_choice is not None:
data["tool_choice"] = self._rewritten_tool_choice(
tool_choice, removed_names, bool(kept_tools) or bool(kept_functions)
)
named_function_call: Final = self._get_named_function_call(data)
if named_function_call in error_tool_names:
if named_function_call in denied_names:
data["function_call"] = "none"
messages: Final = without_tool_search_items_loading(
_REQUEST_DATA.validate_python(data), frozenset(denied_tool_names)
)
messages: Final = without_tool_search_items_loading(_REQUEST_DATA.validate_python(data), denied_names)
if messages is not None:
data["messages"] = messages # rebind-ok: rewrite mode edits the request in place
@ -836,25 +949,25 @@ class ToolPermissionGuardrail(CustomGuardrail):
)
return data
# Check permissions for each tool
denied_tool_names: Final = []
for tool_name, tool_type in new_tools:
is_allowed, _, message = self._check_tool_permission(tool_name, tool_type)
decisions: Final = tuple((target, self._check_tool_permission(*target)) for target in new_tools)
denied: Final = tuple(
(target, message)
for target, (is_allowed, _, message) in decisions
if not is_allowed and message is not None
)
for _, message in denied:
verbose_proxy_logger.info("Tool Permission Guardrail: %s", message)
if denied and self.on_disallowed_action == "block":
raise HTTPException(
status_code=400,
detail={
"error": "Violated guardrail policy",
"detection_message": denied[0][1],
},
)
if not is_allowed and message is not None:
verbose_proxy_logger.info("Tool Permission Guardrail: %s", message)
if self.on_disallowed_action == "block":
raise HTTPException(
status_code=400,
detail={
"error": "Violated guardrail policy",
"detection_message": message,
},
)
denied_tool_names.append(tool_name)
if denied_tool_names:
data = self._modify_request_with_permission_errors(data, denied_tool_names)
if denied:
self._modify_request_with_permission_errors(data, frozenset(target for target, _ in denied), call_type)
verbose_proxy_logger.debug("Tool Permission Guardrail Pre-Call Hook: All tools allowed")

View file

@ -2048,7 +2048,7 @@ _WS_FRAME: Final = TypeAdapter(dict[str, object])
_GUARDRAIL_INFORMATION: Final = TypeAdapter(list[dict[str, object]])
_PII_TOKENS: Final = TypeAdapter(dict[str, str])
_GUARDRAIL_INFORMATION_KEY: Final = "standard_logging_guardrail_information"
_GUARDED_FRAME_FIELDS: Final = ("input", "instructions", "tools")
_GUARDED_FRAME_FIELDS: Final = ("input", "instructions", "tools", "tool_choice")
_CLIENT_METADATA_KEYS: Final = ("metadata", "litellm_metadata")
# the guardrail list is merged from key, team and the admission frame; a later frame cannot shrink it
_CLIENT_GUARDRAIL_SELECTORS: Final = ("guardrails", "guardrail_config", "policies")
@ -2092,7 +2092,7 @@ def _responses_ws_frame_guard(
nested: Final = frame_obj.get("response")
if isinstance(nested, dict) and any(key in frame_obj for key in _GUARDED_FRAME_FIELDS):
raise ValueError(
"response.create carries input, instructions or tools both at the top level and under response"
"response.create carries input, instructions, tools or tool_choice both at the top level and under response"
)
body: Final = _WS_FRAME.validate_python(nested) if isinstance(nested, dict) else frame_obj
frame_data: Final = {

View file

@ -1362,6 +1362,202 @@ class TestToolPermissionGuardrailAnthropicMessages:
assert [tool["name"] for tool in result["tools"]] == ["Bash"]
assert result["tool_choice"] == expected_tool_choice
def _pre_call(
self,
rules: list[dict[str, str]],
on_disallowed_action: Literal["block", "rewrite"],
default_action: Literal["allow", "deny"] = "allow",
) -> ToolPermissionGuardrail:
return ToolPermissionGuardrail(
guardrail_name=f"request-shapes-{on_disallowed_action}",
rules=rules,
default_action=default_action,
on_disallowed_action=on_disallowed_action,
event_hook=GuardrailEventHooks.pre_call,
default_on=True,
)
async def _run_pre_call(
self, guardrail: ToolPermissionGuardrail, data: dict[str, object], call_type: CallTypesLiteral
) -> dict[str, object]:
return await guardrail.async_pre_call_hook(
user_api_key_dict=UserAPIKeyAuth(),
cache=DualCache(default_in_memory_ttl=1),
data=data,
call_type=call_type,
)
def _namespace(self, *member_names: str) -> dict[str, object]:
return {
"type": "namespace",
"name": "mcp__everything",
"tools": [{"type": "function", "name": name, "parameters": {"type": "object"}} for name in member_names],
}
@pytest.mark.asyncio
async def test_pre_call_blocks_a_denied_tool_inside_a_responses_namespace(self) -> None:
guardrail = self._pre_call(
[{"id": "deny_sum", "tool_name": r"^mcp__everything__get_sum$", "decision": "deny"}], "block"
)
data = {"model": "gpt-5", "input": "add 2 and 3", "tools": [self._namespace("echo", "get_sum")]}
with pytest.raises(HTTPException) as excinfo:
await self._run_pre_call(guardrail, data, "responses")
assert excinfo.value.detail["detection_message"] == "Tool 'mcp__everything__get_sum' denied by rule 'deny_sum'"
@pytest.mark.asyncio
async def test_pre_call_rewrite_drops_denied_namespace_members_and_empty_namespaces(self) -> None:
guardrail = self._pre_call([{"id": "deny_sum", "tool_name": r"^.*get_sum$", "decision": "deny"}], "rewrite")
partly_denied = {**self._namespace("echo", "get_sum"), "name": "mcp__kept"}
data = {"model": "gpt-5", "input": "add", "tools": [partly_denied, self._namespace("get_sum")]}
result = await self._run_pre_call(guardrail, data, "responses")
assert result["tools"] == [{**partly_denied, "tools": partly_denied["tools"][:1]}]
@pytest.mark.asyncio
@pytest.mark.parametrize(
("rule", "tool", "call_type", "detection_message"),
[
(
{"id": "deny_mcp", "tool_type": r"^mcp$", "decision": "deny"},
{"type": "mcp", "server_label": "weather", "server_url": "https://mcp.example.com"},
"responses",
"Tool 'mcp' denied by rule 'deny_mcp'",
),
(
{"id": "allow_bash", "tool_name": r"^Bash$", "decision": "allow"},
{"type": "mcp_toolset", "mcp_server_name": "weather"},
"anthropic_messages",
"Tool 'mcp_toolset' denied by default action",
),
(
{"id": "deny_read", "tool_name": r"^Read$", "decision": "deny"},
{"type": "custom", "custom": {"name": "Read"}},
"acompletion",
"Tool 'Read' denied by rule 'deny_read'",
),
],
ids=["responses_mcp_by_type", "anthropic_mcp_toolset_by_default", "chat_custom_nested_name"],
)
async def test_pre_call_checks_tools_that_carry_no_top_level_name(
self, rule: dict[str, str], tool: dict[str, object], call_type: CallTypesLiteral, detection_message: str
) -> None:
guardrail = self._pre_call([rule], "block", default_action="deny")
data = {"model": "m", "messages": [{"role": "user", "content": "hi"}], "input": "hi", "tools": [tool]}
with pytest.raises(HTTPException) as excinfo:
await self._run_pre_call(guardrail, data, call_type)
assert excinfo.value.detail["detection_message"] == detection_message
@pytest.mark.asyncio
async def test_pre_call_passes_a_tool_no_rule_could_ever_match(self) -> None:
guardrail = self._pre_call(self.rules, "block", default_action="deny")
data = {"model": "gemini-3", "messages": [{"role": "user", "content": "hi"}], "tools": [{"googleSearch": {}}]}
result = await self._run_pre_call(guardrail, data, "acompletion")
assert result["tools"] == [{"googleSearch": {}}]
@pytest.mark.asyncio
@pytest.mark.parametrize(
("tools", "tool_choice", "call_type", "expected_tool_choice"),
[
(
[{"type": "custom", "name": "Bash"}, {"type": "custom", "name": "Read"}],
{"type": "custom", "name": "Read"},
"responses",
"none",
),
(
[{"type": "function", "name": "Bash"}, {"type": "function", "name": "Read"}],
{
"type": "allowed_tools",
"mode": "required",
"tools": [{"type": "function", "name": "Read"}, {"type": "function", "name": "Bash"}],
},
"responses",
{"type": "allowed_tools", "mode": "required", "tools": [{"type": "function", "name": "Bash"}]},
),
(
[{"type": "function", "name": "Bash"}, {"type": "function", "name": "Read"}],
{"type": "allowed_tools", "mode": "required", "tools": [{"type": "function", "name": "Read"}]},
"responses",
"none",
),
(
[
{"type": "function", "function": {"name": "Bash"}},
{"type": "function", "function": {"name": "Read"}},
],
{
"type": "allowed_tools",
"allowed_tools": {"mode": "auto", "tools": [{"type": "function", "function": {"name": "Read"}}]},
},
"acompletion",
"none",
),
(
[{"name": "Read", "input_schema": {"type": "object"}}],
{"type": "any"},
"anthropic_messages",
{"type": "none"},
),
(
[
{"name": "Bash", "input_schema": {"type": "object"}},
{"name": "Read", "input_schema": {"type": "object"}},
],
{"type": "any"},
"anthropic_messages",
{"type": "any"},
),
],
ids=[
"responses_custom_choice",
"responses_allowed_tools_keeps_the_rest",
"responses_allowed_tools_all_denied",
"chat_allowed_tools_all_denied",
"anthropic_any_with_no_tools_left",
"anthropic_any_with_a_tool_left",
],
)
async def test_pre_call_rewrite_leaves_no_tool_choice_that_needs_a_removed_tool(
self,
tools: list[dict[str, object]],
tool_choice: dict[str, object],
call_type: CallTypesLiteral,
expected_tool_choice: dict[str, object] | str,
) -> None:
guardrail = self._pre_call(self.rules, "rewrite")
data = {
"model": "m",
"messages": [{"role": "user", "content": "hi"}],
"tools": tools,
"tool_choice": tool_choice,
}
result = await self._run_pre_call(guardrail, data, call_type)
assert result["tool_choice"] == expected_tool_choice
@pytest.mark.asyncio
async def test_pre_call_rewrite_relaxes_a_choice_for_a_tool_a_type_rule_removed(self) -> None:
guardrail = self._pre_call([{"id": "deny_custom", "tool_type": r"^custom$", "decision": "deny"}], "rewrite")
data = {
"model": "gpt-5",
"input": "patch it",
"tools": [{"type": "function", "name": "Bash"}, {"type": "custom", "name": "apply_patch"}],
"tool_choice": {"type": "custom", "name": "apply_patch"},
}
result = await self._run_pre_call(guardrail, data, "responses")
assert result["tools"] == [{"type": "function", "name": "Bash"}]
assert result["tool_choice"] == "none"
@pytest.mark.asyncio
async def test_denied_anthropic_tool_use_is_blocked(self):
response = self._response({"type": "text", "text": "reading"}, self._tool_use("Read"))

View file

@ -2179,6 +2179,31 @@ class TestResponsesWSFirstFrameModelAuth:
"response": {"input": "hi [guarded]", "tools": tools[:1]},
}
@pytest.mark.asyncio
@pytest.mark.parametrize("nested", [True, False])
async def test_frame_guard_forwards_the_tool_choice_a_guardrail_rewrote(self, nested: bool):
from litellm.proxy.response_api_endpoints.endpoints import _responses_ws_frame_guard
async def pre_call_hook(user_api_key_dict, data, call_type, guardrails_only):
return {**data, "tools": [], "tool_choice": "none"}
proxy_logging_obj = MagicMock()
proxy_logging_obj.pre_call_hook = AsyncMock(side_effect=pre_call_hook)
guard = _responses_ws_frame_guard(
{"model": "gpt-4o-mini", "litellm_metadata": {}}, MagicMock(), proxy_logging_obj, MagicMock()
)
body = {
"input": "hi",
"tools": [{"type": "function", "name": "a"}],
"tool_choice": {"type": "function", "name": "a"},
}
frame = {"type": "response.create", "response": body} if nested else {"type": "response.create", **body}
guarded = json.loads((await guard(json.dumps(frame))).frame)
sent = guarded["response"] if nested else guarded
assert (sent["tools"], sent["tool_choice"]) == ([], "none")
@pytest.mark.asyncio
async def test_frame_guard_strips_the_proxy_owned_metadata_keys_a_client_sends(self):
from litellm.proxy.response_api_endpoints.endpoints import _responses_ws_frame_guard