From 6803894e42e95d29e4c5d255da8b1e67b2a12396 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 20 Oct 2026 19:07:41 -0700 Subject: [PATCH 1/6] test(proxy): cover /health scoping for wildcard keys and team model allowlists --- .../health_endpoints/test_health_endpoints.py | 88 +++++++++++++++++++ 1 file changed, 88 insertions(+) diff --git a/tests/unit/proxy/health_endpoints/test_health_endpoints.py b/tests/unit/proxy/health_endpoints/test_health_endpoints.py index 950d1742d49..4c977bd4252 100644 --- a/tests/unit/proxy/health_endpoints/test_health_endpoints.py +++ b/tests/unit/proxy/health_endpoints/test_health_endpoints.py @@ -4248,6 +4248,94 @@ async def test_health_endpoint_keeps_a_team_only_public_name_off_a_team_less_key probe.assert_not_awaited() +_PROVIDER_PREFIXED_MODEL_LIST = [ + { + "model_name": "openai/gpt-5.4-nano", + "litellm_params": {"model": "openai/gpt-5.4-nano"}, + "model_info": {"id": "id-prefixed-nano"}, + }, + { + "model_name": "gpt-5.4-mini", + "litellm_params": {"model": "openai/gpt-5.4-mini"}, + "model_info": {"id": "id-mini"}, + }, +] +_PROVIDER_PREFIXED_CACHED_RESULTS = { + "healthy_endpoints": [ + {"model": "openai/gpt-5.4-nano", "model_id": "id-prefixed-nano"}, + {"model": "openai/gpt-5.4-mini", "model_id": "id-mini"}, + ], + "unhealthy_endpoints": [], + "healthy_count": 2, + "unhealthy_count": 0, +} +_PROVIDER_WILDCARD_KEY = UserAPIKeyAuth(api_key="hashed-test-key", models=["openai/*"]) +_RESTRICTED_TEAM_KEY = UserAPIKeyAuth( + api_key="hashed-test-key", models=[], team_id="team-a", team_models=["gpt-5.4-mini"] +) + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("caller", "expected_ids"), + [(_PROVIDER_WILDCARD_KEY, {"id-prefixed-nano"}), (_RESTRICTED_TEAM_KEY, {"id-mini"})], +) +async def test_health_endpoint_probes_the_deployments_auth_lets_the_key_request(caller, expected_ids): + probed = await _live_probed_model_ids(_PROVIDER_PREFIXED_MODEL_LIST, caller) + + assert probed == expected_ids + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("caller", "expected_ids"), + [(_PROVIDER_WILDCARD_KEY, ["id-prefixed-nano"]), (_RESTRICTED_TEAM_KEY, ["id-mini"])], +) +async def test_health_endpoint_returns_the_deployments_auth_lets_the_key_request_on_background_cache_path( + caller, expected_ids +): + from fastapi import Response + + from litellm.proxy.health_endpoints._health_endpoints import health_endpoint + + with _proxy_health_globals( + _PROVIDER_PREFIXED_MODEL_LIST, + _router_for(_PROVIDER_PREFIXED_MODEL_LIST), + use_background_health_checks=True, + health_check_results=_PROVIDER_PREFIXED_CACHED_RESULTS, + ): + result = await health_endpoint(response=Response(), user_api_key_dict=caller, model=None, model_id=None) + + assert [ep["model_id"] for ep in result["healthy_endpoints"]] == expected_ids + + +@pytest.mark.asyncio +@pytest.mark.parametrize("use_background_health_checks", [False, True]) +async def test_health_endpoint_refuses_a_deployment_the_team_allowlist_forbids(use_background_health_checks): + from fastapi import HTTPException, Response + + from litellm.proxy.health_endpoints._health_endpoints import health_endpoint + + with ( + _proxy_health_globals( + _PROVIDER_PREFIXED_MODEL_LIST, + _router_for(_PROVIDER_PREFIXED_MODEL_LIST), + use_background_health_checks=use_background_health_checks, + health_check_results=_PROVIDER_PREFIXED_CACHED_RESULTS, + ), + patch( # test-quality-ok: the probe must never run; the endpoint has no injection seam for it + "litellm.proxy.health_endpoints._health_endpoints._perform_health_check_and_save", new_callable=AsyncMock + ) as probe, + pytest.raises(HTTPException) as refused, + ): + await health_endpoint( + response=Response(), user_api_key_dict=_RESTRICTED_TEAM_KEY, model=None, model_id="id-prefixed-nano" + ) + + assert refused.value.status_code == 403 + probe.assert_not_awaited() + + def test_resolve_targeted_model_ids_lets_model_id_win_over_model(): resolve = _health_endpoints_module._resolve_targeted_model_ids From 3c862ef5ab400e6b7ceaa483a0f5665e71bc18c9 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Tue, 20 Oct 2026 19:43:13 -0700 Subject: [PATCH 2/6] fix(proxy): scope /health with the model access check auth runs on a request --- .../health_endpoints/_health_endpoints.py | 77 +++++++++++-------- .../health_endpoints/test_health_endpoints.py | 12 ++- 2 files changed, 56 insertions(+), 33 deletions(-) diff --git a/litellm/proxy/health_endpoints/_health_endpoints.py b/litellm/proxy/health_endpoints/_health_endpoints.py index 684f1619512..0028b704d0e 100644 --- a/litellm/proxy/health_endpoints/_health_endpoints.py +++ b/litellm/proxy/health_endpoints/_health_endpoints.py @@ -40,11 +40,11 @@ from litellm.proxy._types import ( ) from litellm.proxy.auth.auth_checks import ( _resolve_key_models_for_auth_check, # pyright: ignore[reportPrivateUsage] # the auth layer's sentinel resolution, reused so /health scopes exactly like a request + can_key_call_resolved_model, ) from litellm.proxy.auth.auth_utils import ( _BANNED_REQUEST_BODY_PARAMS, # pyright: ignore[reportPrivateUsage] # one canonical list, shared with the request-body check ) -from litellm.proxy.auth.model_checks import get_key_models from litellm.proxy.auth.user_api_key_auth import user_api_key_auth from litellm.proxy.common_utils import http_parsing_utils from litellm.proxy.db.db_lookup_gate import db_lookup_stall_tracker @@ -252,6 +252,7 @@ def get_callback_identifier(callback): router: Final = APIRouter() _OBJECT_MAPPING: Final = TypeAdapter(Mapping[str, object]) +_DEPLOYMENT_LIST: Final = TypeAdapter(tuple[object, ...]) services = ( Literal[ "slack_budget_alerts", @@ -1056,42 +1057,52 @@ def _strip_admin_only_fields_from_health_result(result: dict) -> dict: return out -def _health_accessible_model_names( - user_api_key_dict: UserAPIKeyAuth, llm_router: Router | None -) -> frozenset[str] | None: - """Model names the caller may health-check, or None when the key is unrestricted.""" +def _key_models_unrestricted(user_api_key_dict: UserAPIKeyAuth) -> bool: granted_models: Final = _resolve_key_models_for_auth_check(user_api_key_dict) - if not granted_models or SpecialModelNames.all_proxy_models.value in granted_models: - return None - if llm_router is None: - return frozenset(granted_models) - return frozenset( - get_key_models( - user_api_key_dict=user_api_key_dict, - proxy_model_list=llm_router.get_model_names(team_id=user_api_key_dict.team_id), - model_access_groups=llm_router.get_model_access_groups(), + return not granted_models or SpecialModelNames.all_proxy_models.value in granted_models + + +def _names_caller_may_request(deployment: object, team_id: str | None) -> frozenset[str]: + match deployment: + case { + "model_name": str(name), + "model_info": {"team_id": str(owner_team_id), "team_public_model_name": str(public_name)}, + } if owner_team_id == team_id: + return frozenset((name, public_name)) + case {"model_name": str(name)}: + return frozenset((name,)) + case _: + return frozenset() + + +async def _key_may_call_model(model_name: str, user_api_key_dict: UserAPIKeyAuth, llm_router: Router | None) -> bool: + try: + await can_key_call_resolved_model( + model=model_name, llm_model_list=None, valid_token=user_api_key_dict, llm_router=llm_router ) + except ProxyException: + return False + return True + + +async def _model_names_key_may_call( + llm_model_list: Sequence[object], user_api_key_dict: UserAPIKeyAuth, llm_router: Router | None +) -> frozenset[str]: + requested_names: Final = frozenset[str]().union( + *(_names_caller_may_request(deployment, user_api_key_dict.team_id) for deployment in llm_model_list) + ) + return frozenset( + [name for name in requested_names if await _key_may_call_model(name, user_api_key_dict, llm_router)] ) def _caller_may_probe_deployment( - deployment: Mapping[str, object], - allowed_models: frozenset[str] | None, - llm_router: Router | None, - team_id: str | None, - caller_is_admin: bool, + deployment: Mapping[str, object], callable_names: frozenset[str], team_id: str | None, caller_is_admin: bool ) -> bool: """Same deployment visibility rule as routing: another team's deployment is never in scope, team-less callers included.""" if not caller_is_admin and not Router.deployment_usable_by_team(deployment, team_id): return False - if allowed_models is None: - return True - if llm_router is None: - return deployment.get("model_name") in allowed_models - model: Final = dict(deployment) - return any( - llm_router.should_include_deployment(model_name=name, model=model, team_id=team_id) for name in allowed_models - ) + return not callable_names.isdisjoint(_names_caller_may_request(deployment, team_id)) def _resolve_targeted_model_ids( @@ -1315,13 +1326,19 @@ async def health_endpoint( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail={"error": "Model list not initialized"}, ) - allowed_models: Final = _health_accessible_model_names(user_api_key_dict, llm_router) - restrict_to_allowed_models: Final = not is_admin or allowed_models is not None + restrict_to_allowed_models: Final = not is_admin or not _key_models_unrestricted(user_api_key_dict) + callable_names: Final = ( + await _model_names_key_may_call( + _DEPLOYMENT_LIST.validate_python(llm_model_list), user_api_key_dict, llm_router + ) + if restrict_to_allowed_models + else frozenset[str]() + ) _llm_model_list: Final = [ m for m in copy.deepcopy(llm_model_list) if not restrict_to_allowed_models - or _caller_may_probe_deployment(m, allowed_models, llm_router, user_api_key_dict.team_id, is_admin) + or _caller_may_probe_deployment(m, callable_names, user_api_key_dict.team_id, is_admin) ] targeted_ids: Final = _resolve_targeted_model_ids(_llm_model_list, model, model_id, user_api_key_dict.team_id) if restrict_to_allowed_models and targeted_ids is not None and not targeted_ids: diff --git a/tests/unit/proxy/health_endpoints/test_health_endpoints.py b/tests/unit/proxy/health_endpoints/test_health_endpoints.py index 4c977bd4252..668f706b713 100644 --- a/tests/unit/proxy/health_endpoints/test_health_endpoints.py +++ b/tests/unit/proxy/health_endpoints/test_health_endpoints.py @@ -4259,14 +4259,20 @@ _PROVIDER_PREFIXED_MODEL_LIST = [ "litellm_params": {"model": "openai/gpt-5.4-mini"}, "model_info": {"id": "id-mini"}, }, + { + "model_name": "claude-haiku-5-5", + "litellm_params": {"model": "anthropic/claude-haiku-5-5"}, + "model_info": {"id": "id-haiku"}, + }, ] _PROVIDER_PREFIXED_CACHED_RESULTS = { "healthy_endpoints": [ {"model": "openai/gpt-5.4-nano", "model_id": "id-prefixed-nano"}, {"model": "openai/gpt-5.4-mini", "model_id": "id-mini"}, + {"model": "anthropic/claude-haiku-5-5", "model_id": "id-haiku"}, ], "unhealthy_endpoints": [], - "healthy_count": 2, + "healthy_count": 3, "unhealthy_count": 0, } _PROVIDER_WILDCARD_KEY = UserAPIKeyAuth(api_key="hashed-test-key", models=["openai/*"]) @@ -4278,7 +4284,7 @@ _RESTRICTED_TEAM_KEY = UserAPIKeyAuth( @pytest.mark.asyncio @pytest.mark.parametrize( ("caller", "expected_ids"), - [(_PROVIDER_WILDCARD_KEY, {"id-prefixed-nano"}), (_RESTRICTED_TEAM_KEY, {"id-mini"})], + [(_PROVIDER_WILDCARD_KEY, {"id-prefixed-nano", "id-mini"}), (_RESTRICTED_TEAM_KEY, {"id-mini"})], ) async def test_health_endpoint_probes_the_deployments_auth_lets_the_key_request(caller, expected_ids): probed = await _live_probed_model_ids(_PROVIDER_PREFIXED_MODEL_LIST, caller) @@ -4289,7 +4295,7 @@ async def test_health_endpoint_probes_the_deployments_auth_lets_the_key_request( @pytest.mark.asyncio @pytest.mark.parametrize( ("caller", "expected_ids"), - [(_PROVIDER_WILDCARD_KEY, ["id-prefixed-nano"]), (_RESTRICTED_TEAM_KEY, ["id-mini"])], + [(_PROVIDER_WILDCARD_KEY, ["id-prefixed-nano", "id-mini"]), (_RESTRICTED_TEAM_KEY, ["id-mini"])], ) async def test_health_endpoint_returns_the_deployments_auth_lets_the_key_request_on_background_cache_path( caller, expected_ids From 4f15b376b6b405e034592205fca33aa606a2e18e Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 14:57:28 -0700 Subject: [PATCH 3/6] fix(proxy): scope /health to the model group an allowed name routes to A key alias, team alias, or router model_group_alias lets auth admit a requested name by checking its target, so /health also kept the deployment under the requested name, one the key's requests never reach. Keep only the served model group each admitted name dispatches to, through the same alias layers /v1/models mirrors, and let alias_map read its own read-only output. --- .../proxy/common_utils/model_listing_utils.py | 7 +- .../health_endpoints/_health_endpoints.py | 40 +++++++-- .../health_endpoints/test_health_endpoints.py | 87 ++++++++++++++++++- 3 files changed, 124 insertions(+), 10 deletions(-) diff --git a/litellm/proxy/common_utils/model_listing_utils.py b/litellm/proxy/common_utils/model_listing_utils.py index 175432d1dc1..01bb00e80cb 100644 --- a/litellm/proxy/common_utils/model_listing_utils.py +++ b/litellm/proxy/common_utils/model_listing_utils.py @@ -216,7 +216,7 @@ def caller_alias_maps( def alias_map(aliases: object) -> Mapping[str, str]: try: - entries: Final = _ALIAS_ENTRIES.validate_python(aliases, strict=True) + entries: Final = _ALIAS_ENTRIES.validate_python(aliases) except ValidationError: return _NO_ALIASES return MappingProxyType( @@ -284,6 +284,11 @@ def _dispatch(model_id: str, layers: Sequence[_AliasLayer]) -> tuple[str, bool]: return reduce(_through_layer, layers, (model_id, False)) +def dispatched_model(model_id: str, aliases: CallerAliases) -> str: + target, _ = _dispatch(model_id, _alias_layers(aliases)) + return target + + def _lookup_id(name: str, lookup_by_response: Mapping[str, str], lookup_ids: Container[str]) -> str | None: if name in lookup_by_response: return lookup_by_response[name] diff --git a/litellm/proxy/health_endpoints/_health_endpoints.py b/litellm/proxy/health_endpoints/_health_endpoints.py index 3a0e51addee..fefa1acf32e 100644 --- a/litellm/proxy/health_endpoints/_health_endpoints.py +++ b/litellm/proxy/health_endpoints/_health_endpoints.py @@ -41,12 +41,15 @@ from litellm.proxy._types import ( from litellm.proxy.auth.auth_checks import ( _resolve_key_models_for_auth_check, # pyright: ignore[reportPrivateUsage] # the auth layer's sentinel resolution, reused so /health scopes exactly like a request can_key_call_resolved_model, + key_model_aliases_for_auth_check, + team_model_aliases_for_auth_check, ) from litellm.proxy.auth.auth_utils import ( _BANNED_REQUEST_BODY_PARAMS, # pyright: ignore[reportPrivateUsage] # one canonical list, shared with the request-body check ) from litellm.proxy.auth.user_api_key_auth import user_api_key_auth from litellm.proxy.common_utils import http_parsing_utils +from litellm.proxy.common_utils.model_listing_utils import CallerAliases, dispatched_model from litellm.proxy.db.db_lookup_gate import db_lookup_stall_tracker from litellm.proxy.db.exception_handler import PrismaDBExceptionHandler from litellm.proxy.db.health_check_latest import ( @@ -1085,24 +1088,47 @@ async def _key_may_call_model(model_name: str, user_api_key_dict: UserAPIKeyAuth return True -async def _model_names_key_may_call( +async def _caller_aliases(user_api_key_dict: UserAPIKeyAuth) -> CallerAliases: + from litellm.proxy.proxy_server import prisma_client, proxy_config, proxy_logging_obj + + router_settings: Final = await proxy_config.get_hierarchical_router_settings( + user_api_key_dict, prisma_client, proxy_logging_obj + ) + return CallerAliases( + team_model_aliases_for_auth_check(user_api_key_dict), + key_model_aliases_for_auth_check(user_api_key_dict), + router_settings.get("model_group_alias") if router_settings is not None else None, + ) + + +def _served_model_group(model_name: str, aliases: CallerAliases, llm_router: Router | None) -> str: + dispatched: Final = dispatched_model(model_name, aliases) + return llm_router.routable_model_group(dispatched) if llm_router is not None else dispatched + + +async def _model_groups_key_may_reach( llm_model_list: Sequence[object], user_api_key_dict: UserAPIKeyAuth, llm_router: Router | None ) -> frozenset[str]: requested_names: Final = frozenset[str]().union( *(_names_caller_may_request(deployment, user_api_key_dict.team_id) for deployment in llm_model_list) ) + aliases: Final = await _caller_aliases(user_api_key_dict) return frozenset( - [name for name in requested_names if await _key_may_call_model(name, user_api_key_dict, llm_router)] + [ + _served_model_group(name, aliases, llm_router) + for name in requested_names + if await _key_may_call_model(name, user_api_key_dict, llm_router) + ] ) def _caller_may_probe_deployment( - deployment: Mapping[str, object], callable_names: frozenset[str], team_id: str | None, caller_is_admin: bool + deployment: Mapping[str, object], reachable_groups: frozenset[str], team_id: str | None, caller_is_admin: bool ) -> bool: """Same deployment visibility rule as routing: another team's deployment is never in scope, team-less callers included.""" if not caller_is_admin and not Router.deployment_usable_by_team(deployment, team_id): return False - return not callable_names.isdisjoint(_names_caller_may_request(deployment, team_id)) + return not reachable_groups.isdisjoint(_names_caller_may_request(deployment, team_id)) def _resolve_targeted_model_ids( @@ -1327,8 +1353,8 @@ async def health_endpoint( detail={"error": "Model list not initialized"}, ) restrict_to_allowed_models: Final = not is_admin or not _key_models_unrestricted(user_api_key_dict) - callable_names: Final = ( - await _model_names_key_may_call( + reachable_groups: Final = ( + await _model_groups_key_may_reach( _DEPLOYMENT_LIST.validate_python(llm_model_list), user_api_key_dict, llm_router ) if restrict_to_allowed_models @@ -1338,7 +1364,7 @@ async def health_endpoint( m for m in copy.deepcopy(llm_model_list) if not restrict_to_allowed_models - or _caller_may_probe_deployment(m, callable_names, user_api_key_dict.team_id, is_admin) + or _caller_may_probe_deployment(m, reachable_groups, user_api_key_dict.team_id, is_admin) ] targeted_ids: Final = _resolve_targeted_model_ids(_llm_model_list, model, model_id, user_api_key_dict.team_id) if restrict_to_allowed_models and targeted_ids is not None and not targeted_ids: diff --git a/tests/unit/proxy/health_endpoints/test_health_endpoints.py b/tests/unit/proxy/health_endpoints/test_health_endpoints.py index f1b56296ed8..7af49169438 100644 --- a/tests/unit/proxy/health_endpoints/test_health_endpoints.py +++ b/tests/unit/proxy/health_endpoints/test_health_endpoints.py @@ -3771,7 +3771,10 @@ def test_clean_endpoint_data_never_displays_credential_fields(credential_field, async def _live_probed_model_ids( - model_list: Sequence[Mapping[str, object]], user_api_key_dict: UserAPIKeyAuth, model: str | None = None + model_list: Sequence[Mapping[str, object]], + user_api_key_dict: UserAPIKeyAuth, + model: str | None = None, + llm_router: Router | None = None, ) -> set[str]: from fastapi import Response @@ -3784,7 +3787,7 @@ async def _live_probed_model_ids( return {"healthy_endpoints": [], "unhealthy_endpoints": [], "healthy_count": 0, "unhealthy_count": 0} with ( - _proxy_health_globals(model_list, _router_for(model_list)), + _proxy_health_globals(model_list, llm_router or _router_for(model_list)), patch( # test-quality-ok: the model list handed to the probe is the assertion; no injection seam "litellm.proxy.health_endpoints._health_endpoints._perform_health_check_and_save", side_effect=fake_perform, @@ -4342,6 +4345,86 @@ async def test_health_endpoint_refuses_a_deployment_the_team_allowlist_forbids(u probe.assert_not_awaited() + +_KEY_ALIASED_AWAY_FROM_HAIKU = UserAPIKeyAuth( + api_key="hashed-test-key", models=["gpt-5.4-mini"], aliases={"claude-haiku-5-5": "gpt-5.4-mini"} +) +_TEAM_ALIASED_AWAY_FROM_HAIKU = UserAPIKeyAuth( + api_key="hashed-test-key", + models=["claude-haiku-5-5"], + team_id="team-a", + team_model_aliases={"claude-haiku-5-5": "gpt-5.4-mini"}, +) +_MINI_ONLY_KEY = UserAPIKeyAuth(api_key="hashed-test-key", models=["gpt-5.4-mini"]) +_ALIAS_SHADOW_CASES = [ + pytest.param(_KEY_ALIASED_AWAY_FROM_HAIKU, {}, id="key-alias"), + pytest.param(_TEAM_ALIASED_AWAY_FROM_HAIKU, {}, id="team-alias"), + pytest.param(_MINI_ONLY_KEY, {"claude-haiku-5-5": "gpt-5.4-mini"}, id="router-alias"), +] + + +def _router_with_aliases(model_group_alias: Mapping[str, str]) -> Router: + return Router(model_list=copy.deepcopy(_PROVIDER_PREFIXED_MODEL_LIST), model_group_alias=dict(model_group_alias)) + + +@pytest.mark.asyncio +@pytest.mark.parametrize(("caller", "model_group_alias"), _ALIAS_SHADOW_CASES) +async def test_health_endpoint_probes_the_deployment_an_alias_sends_the_key_to_not_the_one_it_shadows( + caller, model_group_alias +): + probed = await _live_probed_model_ids( + _PROVIDER_PREFIXED_MODEL_LIST, caller, llm_router=_router_with_aliases(model_group_alias) + ) + + assert probed == {"id-mini"} + + +@pytest.mark.asyncio +@pytest.mark.parametrize(("caller", "model_group_alias"), _ALIAS_SHADOW_CASES) +async def test_health_endpoint_returns_the_deployment_an_alias_sends_the_key_to_on_background_cache_path( + caller, model_group_alias +): + from fastapi import Response + + from litellm.proxy.health_endpoints._health_endpoints import health_endpoint + + with _proxy_health_globals( + _PROVIDER_PREFIXED_MODEL_LIST, + _router_with_aliases(model_group_alias), + use_background_health_checks=True, + health_check_results=_PROVIDER_PREFIXED_CACHED_RESULTS, + ): + result = await health_endpoint(response=Response(), user_api_key_dict=caller, model=None, model_id=None) + + assert [ep["model_id"] for ep in result["healthy_endpoints"]] == ["id-mini"] + + +@pytest.mark.asyncio +@pytest.mark.parametrize("use_background_health_checks", [False, True]) +async def test_health_endpoint_refuses_the_deployment_a_key_alias_shadows(use_background_health_checks): + from fastapi import HTTPException, Response + + from litellm.proxy.health_endpoints._health_endpoints import health_endpoint + + with ( + _proxy_health_globals( + _PROVIDER_PREFIXED_MODEL_LIST, + _router_for(_PROVIDER_PREFIXED_MODEL_LIST), + use_background_health_checks=use_background_health_checks, + health_check_results=_PROVIDER_PREFIXED_CACHED_RESULTS, + ), + patch( # test-quality-ok: the probe must never run; the endpoint has no injection seam for it + "litellm.proxy.health_endpoints._health_endpoints._perform_health_check_and_save", new_callable=AsyncMock + ) as probe, + pytest.raises(HTTPException) as refused, + ): + await health_endpoint( + response=Response(), user_api_key_dict=_KEY_ALIASED_AWAY_FROM_HAIKU, model=None, model_id="id-haiku" + ) + + assert refused.value.status_code == 403 + probe.assert_not_awaited() + def test_resolve_targeted_model_ids_lets_model_id_win_over_model(): resolve = _health_endpoints_module._resolve_targeted_model_ids From e9e76077d9203264e29c843451fd01332e0bc9cc Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 16:08:00 -0700 Subject: [PATCH 4/6] test(proxy): cover /health skipping a deployment that has no model name for a restricted key --- .../health_endpoints/test_health_endpoints.py | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/tests/unit/proxy/health_endpoints/test_health_endpoints.py b/tests/unit/proxy/health_endpoints/test_health_endpoints.py index 7af49169438..c97c1d0805e 100644 --- a/tests/unit/proxy/health_endpoints/test_health_endpoints.py +++ b/tests/unit/proxy/health_endpoints/test_health_endpoints.py @@ -4345,7 +4345,6 @@ async def test_health_endpoint_refuses_a_deployment_the_team_allowlist_forbids(u probe.assert_not_awaited() - _KEY_ALIASED_AWAY_FROM_HAIKU = UserAPIKeyAuth( api_key="hashed-test-key", models=["gpt-5.4-mini"], aliases={"claude-haiku-5-5": "gpt-5.4-mini"} ) @@ -4425,6 +4424,20 @@ async def test_health_endpoint_refuses_the_deployment_a_key_alias_shadows(use_ba assert refused.value.status_code == 403 probe.assert_not_awaited() + +@pytest.mark.asyncio +async def test_health_endpoint_never_probes_a_deployment_without_a_model_name_for_a_restricted_key(): + nameless_deployment = {"litellm_params": {"model": "openai/gpt-5.4-mini"}, "model_info": {"id": "id-nameless"}} + + probed = await _live_probed_model_ids( + [*_PROVIDER_PREFIXED_MODEL_LIST, nameless_deployment], + _MINI_ONLY_KEY, + llm_router=_router_for(_PROVIDER_PREFIXED_MODEL_LIST), + ) + + assert probed == {"id-mini"} + + def test_resolve_targeted_model_ids_lets_model_id_win_over_model(): resolve = _health_endpoints_module._resolve_targeted_model_ids From 8d9eab02fc409e89208be19ef4808f4ad650e588 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 19:18:42 -0700 Subject: [PATCH 5/6] fix(health): show deployments reached through wildcard and alias allowlists, and by id when an alias shadows the name --- .../health_endpoints/_health_endpoints.py | 144 +++++++++++++++--- litellm/router.py | 6 +- .../health_endpoints/test_health_endpoints.py | 110 ++++++++++++- 3 files changed, 233 insertions(+), 27 deletions(-) diff --git a/litellm/proxy/health_endpoints/_health_endpoints.py b/litellm/proxy/health_endpoints/_health_endpoints.py index fefa1acf32e..f9e8fc69824 100644 --- a/litellm/proxy/health_endpoints/_health_endpoints.py +++ b/litellm/proxy/health_endpoints/_health_endpoints.py @@ -7,7 +7,9 @@ import secrets import time import traceback from collections.abc import Iterable, Mapping, Sequence +from dataclasses import dataclass from datetime import datetime, timedelta, timezone +from itertools import chain, groupby from types import MappingProxyType from typing import Final, Literal, TypedDict @@ -81,6 +83,7 @@ from litellm.router_utils.clientside_credential_handler import ( _ADMIN_CONFIG_FIELDS_TO_CLEAR_ON_BASE_OVERRIDE, # pyright: ignore[reportPrivateUsage] # one canonical list, shared with the router path clientside_credential_keys, ) +from litellm.router_utils.common_utils import resolve_model_group_alias from litellm.secret_managers.main import get_secret_bool from litellm.types.proxy.litellm_pre_call_utils import RedactedDict, SecretFields from litellm.types.router import reject_server_owned_wif_fields @@ -255,7 +258,7 @@ def get_callback_identifier(callback): router: Final = APIRouter() _OBJECT_MAPPING: Final = TypeAdapter(Mapping[str, object]) -_DEPLOYMENT_LIST: Final = TypeAdapter(tuple[object, ...]) +_OBJECTS: Final = TypeAdapter(tuple[object, ...]) services = ( Literal[ "slack_budget_alerts", @@ -1101,34 +1104,139 @@ async def _caller_aliases(user_api_key_dict: UserAPIKeyAuth) -> CallerAliases: ) -def _served_model_group(model_name: str, aliases: CallerAliases, llm_router: Router | None) -> str: +def _model_auth_checks(model_name: str, aliases: CallerAliases) -> str: + return resolve_model_group_alias(aliases.router, model_name) or model_name + + +def _deployment_id(deployment: object) -> str | None: + match deployment: + case {"model_info": {"id": str(model_id)}}: + return model_id + case _: + return None + + +def _granted_names(user_api_key_dict: UserAPIKeyAuth) -> frozenset[str]: + grants: Final = ( + *_OBJECTS.validate_python(user_api_key_dict.models), + *_OBJECTS.validate_python(user_api_key_dict.team_models), + ) + return frozenset(name for name in grants if isinstance(name, str)) + + +def _served_group(model_name: str, aliases: CallerAliases, llm_router: Router | None) -> str: dispatched: Final = dispatched_model(model_name, aliases) return llm_router.routable_model_group(dispatched) if llm_router is not None else dispatched -async def _model_groups_key_may_reach( - llm_model_list: Sequence[object], user_api_key_dict: UserAPIKeyAuth, llm_router: Router | None -) -> frozenset[str]: - requested_names: Final = frozenset[str]().union( - *(_names_caller_may_request(deployment, user_api_key_dict.team_id) for deployment in llm_model_list) +def _name_id_pairs(deployment: object, team_id: str | None) -> tuple[tuple[str, str], ...]: + model_id: Final = _deployment_id(deployment) + if model_id is None: + return () + return tuple((name, model_id) for name in _names_caller_may_request(deployment, team_id) | {model_id}) + + +def _ids_by_requested_name(llm_model_list: Sequence[object], team_id: str | None) -> Mapping[str, frozenset[str]]: + pairs: Final = sorted(chain.from_iterable(_name_id_pairs(deployment, team_id) for deployment in llm_model_list)) + return MappingProxyType( + {name: frozenset(model_id for _, model_id in group) for name, group in groupby(pairs, key=lambda pair: pair[0])} ) - aliases: Final = await _caller_aliases(user_api_key_dict) + + +def _ids_serving_group( + group: str, + ids_by_name: Mapping[str, frozenset[str]], + user_api_key_dict: UserAPIKeyAuth, + llm_router: Router | None, +) -> frozenset[str]: + named: Final = ids_by_name.get(group) + if named is not None or llm_router is None: + return named or frozenset() + routed: Final = llm_router.get_routable_deployments( + group, {"metadata": {"user_api_key_team_id": user_api_key_dict.team_id}} + ) + return frozenset(model_id for model_id in map(_deployment_id, routed) if model_id is not None) + + +async def _names_key_may_request( + names: Iterable[str], aliases: CallerAliases, user_api_key_dict: UserAPIKeyAuth, llm_router: Router | None +) -> frozenset[str]: return frozenset( [ - _served_model_group(name, aliases, llm_router) - for name in requested_names - if await _key_may_call_model(name, user_api_key_dict, llm_router) + name + for name in names + if await _key_may_call_model(_model_auth_checks(name, aliases), user_api_key_dict, llm_router) ] ) +def _ids_serving( + groups: Iterable[str], + ids_by_name: Mapping[str, frozenset[str]], + user_api_key_dict: UserAPIKeyAuth, + llm_router: Router | None, +) -> frozenset[str]: + return frozenset[str]().union( + *(_ids_serving_group(group, ids_by_name, user_api_key_dict, llm_router) for group in groups) + ) + + +def _shadowed_ids( + llm_model_list: Sequence[object], admitted_names: frozenset[str], reached_ids: frozenset[str], team_id: str | None +) -> frozenset[str]: + ids_of_admitted_names: Final = ( + _deployment_id(deployment) + for deployment in llm_model_list + if not admitted_names.isdisjoint(_names_caller_may_request(deployment, team_id)) + ) + return frozenset(model_id for model_id in ids_of_admitted_names if model_id is not None) - reached_ids + + +@dataclass(frozen=True, slots=True) +class _ReachableDeployments: + model_ids: frozenset[str] + groups: frozenset[str] + + def include(self, deployment: object, team_id: str | None) -> bool: + model_id: Final = _deployment_id(deployment) + if model_id is None: + return not self.groups.isdisjoint(_names_caller_may_request(deployment, team_id)) + return model_id in self.model_ids + + +_NOTHING_REACHABLE: Final = _ReachableDeployments(frozenset(), frozenset()) + + +async def _deployments_key_may_reach( + llm_model_list: Sequence[object], user_api_key_dict: UserAPIKeyAuth, llm_router: Router | None +) -> _ReachableDeployments: + aliases: Final = await _caller_aliases(user_api_key_dict) + candidate_names: Final = _granted_names(user_api_key_dict).union( + *(_names_caller_may_request(deployment, user_api_key_dict.team_id) for deployment in llm_model_list) + ) + admitted_names: Final = await _names_key_may_request(candidate_names, aliases, user_api_key_dict, llm_router) + groups: Final = frozenset(_served_group(name, aliases, llm_router) for name in admitted_names) + ids_by_name: Final = _ids_by_requested_name(llm_model_list, user_api_key_dict.team_id) + reached_ids: Final = _ids_serving(groups, ids_by_name, user_api_key_dict, llm_router) + admitted_ids: Final = await _names_key_may_request( + _shadowed_ids(llm_model_list, admitted_names, reached_ids, user_api_key_dict.team_id), + aliases, + user_api_key_dict, + llm_router, + ) + id_groups: Final = frozenset(_served_group(model_id, aliases, llm_router) for model_id in admitted_ids) + return _ReachableDeployments( + reached_ids | _ids_serving(id_groups, ids_by_name, user_api_key_dict, llm_router), groups + ) + + def _caller_may_probe_deployment( - deployment: Mapping[str, object], reachable_groups: frozenset[str], team_id: str | None, caller_is_admin: bool + deployment: Mapping[str, object], reachable: _ReachableDeployments, team_id: str | None, caller_is_admin: bool ) -> bool: """Same deployment visibility rule as routing: another team's deployment is never in scope, team-less callers included.""" if not caller_is_admin and not Router.deployment_usable_by_team(deployment, team_id): return False - return not reachable_groups.isdisjoint(_names_caller_may_request(deployment, team_id)) + return reachable.include(deployment, team_id) def _resolve_targeted_model_ids( @@ -1353,18 +1461,16 @@ async def health_endpoint( detail={"error": "Model list not initialized"}, ) restrict_to_allowed_models: Final = not is_admin or not _key_models_unrestricted(user_api_key_dict) - reachable_groups: Final = ( - await _model_groups_key_may_reach( - _DEPLOYMENT_LIST.validate_python(llm_model_list), user_api_key_dict, llm_router - ) + reachable: Final = ( + await _deployments_key_may_reach(_OBJECTS.validate_python(llm_model_list), user_api_key_dict, llm_router) if restrict_to_allowed_models - else frozenset[str]() + else _NOTHING_REACHABLE ) _llm_model_list: Final = [ m for m in copy.deepcopy(llm_model_list) if not restrict_to_allowed_models - or _caller_may_probe_deployment(m, reachable_groups, user_api_key_dict.team_id, is_admin) + or _caller_may_probe_deployment(m, reachable, user_api_key_dict.team_id, is_admin) ] targeted_ids: Final = _resolve_targeted_model_ids(_llm_model_list, model, model_id, user_api_key_dict.team_id) if restrict_to_allowed_models and targeted_ids is not None and not targeted_ids: diff --git a/litellm/router.py b/litellm/router.py index 5b18d36316f..a96419c739f 100644 --- a/litellm/router.py +++ b/litellm/router.py @@ -14694,9 +14694,11 @@ class Router: """ return [m for m in self.model_list if m["litellm_params"]["model"] == model] - def get_routable_deployments(self, model: str) -> tuple[DeploymentTypedDict, ...]: + def get_routable_deployments( + self, model: str, request_kwargs: Mapping[str, object] | None = None + ) -> tuple[DeploymentTypedDict, ...]: try: - _, candidates = self._common_checks_available_deployment(model=model, request_kwargs={}) # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType] # its signature leaves input and the result untyped + _, candidates = self._common_checks_available_deployment(model=model, request_kwargs=request_kwargs or {}) # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType] # its signature leaves input and the result untyped except (litellm.BadRequestError, ValueError): return () if isinstance(candidates, dict): diff --git a/tests/unit/proxy/health_endpoints/test_health_endpoints.py b/tests/unit/proxy/health_endpoints/test_health_endpoints.py index c97c1d0805e..37b97079905 100644 --- a/tests/unit/proxy/health_endpoints/test_health_endpoints.py +++ b/tests/unit/proxy/health_endpoints/test_health_endpoints.py @@ -4289,7 +4289,9 @@ _RESTRICTED_TEAM_KEY = UserAPIKeyAuth( ("caller", "expected_ids"), [(_PROVIDER_WILDCARD_KEY, {"id-prefixed-nano", "id-mini"}), (_RESTRICTED_TEAM_KEY, {"id-mini"})], ) -async def test_health_endpoint_probes_the_deployments_auth_lets_the_key_request(caller, expected_ids): +async def test_health_endpoint_probes_the_deployments_auth_lets_the_key_request( + caller: UserAPIKeyAuth, expected_ids: set[str] +): probed = await _live_probed_model_ids(_PROVIDER_PREFIXED_MODEL_LIST, caller) assert probed == expected_ids @@ -4301,7 +4303,7 @@ async def test_health_endpoint_probes_the_deployments_auth_lets_the_key_request( [(_PROVIDER_WILDCARD_KEY, ["id-prefixed-nano", "id-mini"]), (_RESTRICTED_TEAM_KEY, ["id-mini"])], ) async def test_health_endpoint_returns_the_deployments_auth_lets_the_key_request_on_background_cache_path( - caller, expected_ids + caller: UserAPIKeyAuth, expected_ids: list[str] ): from fastapi import Response @@ -4320,7 +4322,7 @@ async def test_health_endpoint_returns_the_deployments_auth_lets_the_key_request @pytest.mark.asyncio @pytest.mark.parametrize("use_background_health_checks", [False, True]) -async def test_health_endpoint_refuses_a_deployment_the_team_allowlist_forbids(use_background_health_checks): +async def test_health_endpoint_refuses_a_deployment_the_team_allowlist_forbids(use_background_health_checks: bool): from fastapi import HTTPException, Response from litellm.proxy.health_endpoints._health_endpoints import health_endpoint @@ -4369,7 +4371,7 @@ def _router_with_aliases(model_group_alias: Mapping[str, str]) -> Router: @pytest.mark.asyncio @pytest.mark.parametrize(("caller", "model_group_alias"), _ALIAS_SHADOW_CASES) async def test_health_endpoint_probes_the_deployment_an_alias_sends_the_key_to_not_the_one_it_shadows( - caller, model_group_alias + caller: UserAPIKeyAuth, model_group_alias: Mapping[str, str] ): probed = await _live_probed_model_ids( _PROVIDER_PREFIXED_MODEL_LIST, caller, llm_router=_router_with_aliases(model_group_alias) @@ -4381,7 +4383,7 @@ async def test_health_endpoint_probes_the_deployment_an_alias_sends_the_key_to_n @pytest.mark.asyncio @pytest.mark.parametrize(("caller", "model_group_alias"), _ALIAS_SHADOW_CASES) async def test_health_endpoint_returns_the_deployment_an_alias_sends_the_key_to_on_background_cache_path( - caller, model_group_alias + caller: UserAPIKeyAuth, model_group_alias: Mapping[str, str] ): from fastapi import Response @@ -4400,7 +4402,7 @@ async def test_health_endpoint_returns_the_deployment_an_alias_sends_the_key_to_ @pytest.mark.asyncio @pytest.mark.parametrize("use_background_health_checks", [False, True]) -async def test_health_endpoint_refuses_the_deployment_a_key_alias_shadows(use_background_health_checks): +async def test_health_endpoint_refuses_the_deployment_a_key_alias_shadows(use_background_health_checks: bool): from fastapi import HTTPException, Response from litellm.proxy.health_endpoints._health_endpoints import health_endpoint @@ -4438,6 +4440,102 @@ async def test_health_endpoint_never_probes_a_deployment_without_a_model_name_fo assert probed == {"id-mini"} +@pytest.mark.asyncio +async def test_health_endpoint_never_probes_the_deployment_a_keys_router_alias_sends_it_to_but_forbids(): + caller = UserAPIKeyAuth( + api_key="hashed-test-key", + models=["gpt-5.4-mini", "openai/gpt-5.4-nano"], + router_settings={"model_group_alias": {"gpt-5.4-mini": "claude-haiku-5-5"}}, + ) + + probed = await _live_probed_model_ids(_PROVIDER_PREFIXED_MODEL_LIST, caller) + + assert probed == {"id-prefixed-nano"} + + +_WILDCARD_DEPLOYMENT = {"model_name": "openai/*", "litellm_params": {"model": "openai/*"}, "model_info": {"id": "id-wild"}} +_CATCH_ALL_DEPLOYMENT = {"model_name": "*", "litellm_params": {"model": "*"}, "model_info": {"id": "id-star"}} +_TEAM_WILDCARD_DEPLOYMENT = { + "model_name": "openai-wild_team-a_7c1e", + "litellm_params": {"model": "openai/*"}, + "model_info": {"id": "id-team-wild", "team_id": "team-a", "team_public_model_name": "openai/*"}, +} + + +def _team_key(team_models: list[str], team_model_aliases: Mapping[str, str] | None = None) -> UserAPIKeyAuth: + return UserAPIKeyAuth( + api_key="hashed-test-key", + models=[], + team_id="team-a", + team_models=team_models, + team_model_aliases=dict(team_model_aliases) if team_model_aliases is not None else None, + ) + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("model_list", "model_group_alias", "caller", "expected_ids"), + [ + pytest.param( + [_WILDCARD_DEPLOYMENT, _PROVIDER_PREFIXED_MODEL_LIST[2]], + {}, + _team_key(["openai/gpt-5.4-nano"]), + {"id-wild"}, + id="team-name-served-by-provider-wildcard", + ), + pytest.param( + [_TEAM_WILDCARD_DEPLOYMENT, _PROVIDER_PREFIXED_MODEL_LIST[2]], + {}, + _team_key(["openai/gpt-5.4-nano"]), + {"id-team-wild"}, + id="team-name-served-by-teams-own-wildcard", + ), + pytest.param( + [_CATCH_ALL_DEPLOYMENT], + {}, + _team_key(["gpt-5.4-mini"]), + {"id-star"}, + id="team-name-served-by-catch-all", + ), + pytest.param( + _PROVIDER_PREFIXED_MODEL_LIST, + {"gpt-4": "gpt-5.4-mini"}, + _team_key(["gpt-4"]), + {"id-mini"}, + id="team-allows-router-alias", + ), + pytest.param( + _PROVIDER_PREFIXED_MODEL_LIST, + {}, + _team_key(["my-alias"], {"my-alias": "gpt-5.4-mini"}), + {"id-mini"}, + id="team-allows-team-alias", + ), + pytest.param( + _PROVIDER_PREFIXED_MODEL_LIST, + {"claude-haiku-5-5": "gpt-5.4-mini"}, + UserAPIKeyAuth(api_key="hashed-test-key", models=[]), + {"id-prefixed-nano", "id-mini", "id-haiku"}, + id="unrestricted-key-calls-shadowed-deployment-by-id", + ), + ], +) +async def test_health_endpoint_probes_every_deployment_the_callers_allowed_names_route_to( + model_list: Sequence[Mapping[str, object]], + model_group_alias: Mapping[str, str], + caller: UserAPIKeyAuth, + expected_ids: set[str], +): + llm_router = Router( + model_list=copy.deepcopy([dict(deployment) for deployment in model_list]), + model_group_alias=dict(model_group_alias), + ) + + probed = await _live_probed_model_ids(model_list, caller, llm_router=llm_router) + + assert probed == expected_ids + + def test_resolve_targeted_model_ids_lets_model_id_win_over_model(): resolve = _health_endpoints_module._resolve_targeted_model_ids From 7fe9c7c205fe8cd65f9fafd486d9d010fd8796bf Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 21:22:48 -0700 Subject: [PATCH 6/6] chore(router): drop should_include_deployment from the outside-use allowlist now that /health no longer calls it --- tests/code_coverage_tests/router_surface_allowlist.json | 1 - 1 file changed, 1 deletion(-) diff --git a/tests/code_coverage_tests/router_surface_allowlist.json b/tests/code_coverage_tests/router_surface_allowlist.json index 428fd9b4011..cf945d2e7c2 100644 --- a/tests/code_coverage_tests/router_surface_allowlist.json +++ b/tests/code_coverage_tests/router_surface_allowlist.json @@ -132,7 +132,6 @@ "schedule_acompletion", "search_tools", "serve_through_request_logging", - "should_include_deployment", "split_request_priority", "team_model_to_deployment_indices", "team_pattern_routers",