diff --git a/litellm/proxy/auth/master_key_policy.py b/litellm/proxy/auth/master_key_policy.py index eeb7d3ee72a..f8fcd7d9b8e 100644 --- a/litellm/proxy/auth/master_key_policy.py +++ b/litellm/proxy/auth/master_key_policy.py @@ -1,22 +1,46 @@ -from typing import Final +from typing import Final, Literal + +from typing_extensions import assert_never INSECURE_MASTER_KEYS: Final = frozenset({"sk-1234"}) +InsecureMasterKeyReason = Literal["example_key", "missing"] + +_ALTERNATIVE_AUTH_SETTINGS: Final = ("enable_jwt_auth", "enable_oauth2_auth", "enable_oauth2_proxy_auth") + + +def alternative_auth_enabled(general_settings: dict) -> bool: + return any(general_settings.get(k, False) for k in _ALTERNATIVE_AUTH_SETTINGS) + + +def insecure_master_key_reason( + master_key: str | None, alternative_auth_enabled: bool +) -> InsecureMasterKeyReason | None: + if master_key in INSECURE_MASTER_KEYS: + return "example_key" + if (master_key is None or master_key == "") and not alternative_auth_enabled: + return "missing" + return None + def insecure_master_key_warning(master_key: str | None, alternative_auth_enabled: bool) -> str | None: - if master_key in INSECURE_MASTER_KEYS: - return ( - "LITELLM_MASTER_KEY is set to the example key 'sk-1234' from the docs. " - "Anyone who has read the docs can administer this gateway, and publicly reachable " - "gateways using this key have been compromised. Set a strong random master key " - "(e.g. `python -c \"import secrets; print('sk-' + secrets.token_urlsafe(32))\"`). " - "A future release will refuse to start with this key." - ) - if (master_key is None or master_key == "") and not alternative_auth_enabled: - return ( - "No master key is set (LITELLM_MASTER_KEY or general_settings.master_key). " - "Every request to this proxy is accepted without authentication, including " - 'admin routes. Set a strong random master key (e.g. `python -c "import secrets; ' - "print('sk-' + secrets.token_urlsafe(32))\"`) before exposing it to a network." - ) - return None + match insecure_master_key_reason(master_key, alternative_auth_enabled): + case "example_key": + return ( + "LITELLM_MASTER_KEY is set to the example key 'sk-1234' from the docs. " + "Anyone who has read the docs can administer this gateway, and publicly reachable " + "gateways using this key have been compromised. Set a strong random master key " + "(e.g. `python -c \"import secrets; print('sk-' + secrets.token_urlsafe(32))\"`). " + "A future release will refuse to start with this key." + ) + case "missing": + return ( + "No master key is set (LITELLM_MASTER_KEY or general_settings.master_key). " + "Every request to this proxy is accepted without authentication, including " + 'admin routes. Set a strong random master key (e.g. `python -c "import secrets; ' + "print('sk-' + secrets.token_urlsafe(32))\"`) before exposing it to a network." + ) + case None: + return None + case _ as unreachable: + assert_never(unreachable) diff --git a/litellm/proxy/health_endpoints/_health_endpoints.py b/litellm/proxy/health_endpoints/_health_endpoints.py index bf527e1e868..475780cb005 100644 --- a/litellm/proxy/health_endpoints/_health_endpoints.py +++ b/litellm/proxy/health_endpoints/_health_endpoints.py @@ -39,6 +39,11 @@ from litellm.proxy._types import ( 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.master_key_policy import ( + InsecureMasterKeyReason, + alternative_auth_enabled, + insecure_master_key_reason, +) from litellm.proxy.auth.user_api_key_auth import user_api_key_auth from litellm.proxy.db.exception_handler import PrismaDBExceptionHandler from litellm.proxy.db.health_check_latest import LatestHealthCheckRow @@ -1639,6 +1644,12 @@ def _show_env_credential_login_warning() -> bool: return is_env_credential_login_enabled(general_settings) +def _insecure_master_key_reason() -> InsecureMasterKeyReason | None: + from litellm.proxy.proxy_server import general_settings, master_key + + return insecure_master_key_reason(master_key, alternative_auth_enabled=alternative_auth_enabled(general_settings)) + + async def _get_health_readiness_details( response: Response | None = None, ) -> dict[str, Any]: @@ -1681,6 +1692,7 @@ async def _get_health_readiness_details( is_detailed_debug: Final = verbose_logger.isEnabledFor(logging.DEBUG) show_no_redis_warning: Final = await _show_no_redis_warning() show_env_credential_login_warning: Final = _show_env_credential_login_warning() + insecure_master_key_reason: Final = _insecure_master_key_reason() # check DB if prisma_client is not None: # if db passed in, check if it's connected @@ -1709,6 +1721,7 @@ async def _get_health_readiness_details( "is_detailed_debug": is_detailed_debug, "show_no_redis_warning": show_no_redis_warning, "show_env_credential_login_warning": show_env_credential_login_warning, + "insecure_master_key_reason": insecure_master_key_reason, } else: return { @@ -1722,6 +1735,7 @@ async def _get_health_readiness_details( "is_detailed_debug": is_detailed_debug, "show_no_redis_warning": show_no_redis_warning, "show_env_credential_login_warning": show_env_credential_login_warning, + "insecure_master_key_reason": insecure_master_key_reason, } except Exception as e: raise HTTPException(status_code=503, detail=f"Service Unhealthy ({e})") diff --git a/litellm/proxy/proxy_server.py b/litellm/proxy/proxy_server.py index 805c61d4697..b16e09b8948 100644 --- a/litellm/proxy/proxy_server.py +++ b/litellm/proxy/proxy_server.py @@ -324,7 +324,7 @@ from litellm.proxy.auth.auth_utils import ( from litellm.proxy.auth.fallback_model_access import router_fallback_access_check from litellm.proxy.auth.handle_jwt import JWTHandler from litellm.proxy.auth.litellm_license import AUTO_ROUTER_LICENSE_REMEDY, LicenseCheck -from litellm.proxy.auth.master_key_policy import insecure_master_key_warning +from litellm.proxy.auth.master_key_policy import alternative_auth_enabled, insecure_master_key_warning from litellm.proxy.auth.model_checks import ( expand_wildcard_deployments_for_model_info, get_all_fallbacks, @@ -1160,11 +1160,8 @@ async def proxy_startup_event(app: FastAPI) -> AsyncGenerator[None, None]: if isinstance(worker_config, dict): await initialize(**worker_config) - _alternative_auth_enabled: Final = any( - general_settings.get(k, False) for k in ("enable_jwt_auth", "enable_oauth2_auth", "enable_oauth2_proxy_auth") - ) _insecure_master_key_warning: Final = insecure_master_key_warning( - master_key, alternative_auth_enabled=_alternative_auth_enabled + master_key, alternative_auth_enabled=alternative_auth_enabled(general_settings) ) if _insecure_master_key_warning is not None: verbose_proxy_logger.warning(_insecure_master_key_warning) diff --git a/tests/test_litellm/proxy/auth/test_master_key_policy.py b/tests/test_litellm/proxy/auth/test_master_key_policy.py index 6b118994cba..3f069e380c4 100644 --- a/tests/test_litellm/proxy/auth/test_master_key_policy.py +++ b/tests/test_litellm/proxy/auth/test_master_key_policy.py @@ -1,5 +1,22 @@ from litellm.litellm_core_utils.secret_redaction import redact_string -from litellm.proxy.auth.master_key_policy import insecure_master_key_warning +from litellm.proxy.auth.master_key_policy import insecure_master_key_reason, insecure_master_key_warning + + +def test_insecure_master_key_reason_for_example_key(): + assert insecure_master_key_reason("sk-1234", alternative_auth_enabled=False) == "example_key" + + +def test_insecure_master_key_reason_for_missing_key(): + assert insecure_master_key_reason(None, alternative_auth_enabled=False) == "missing" + assert insecure_master_key_reason("", alternative_auth_enabled=False) == "missing" + + +def test_insecure_master_key_reason_none_for_strong_key(): + assert insecure_master_key_reason("sk-strong-random-key", alternative_auth_enabled=False) is None + + +def test_insecure_master_key_reason_none_with_alternative_auth(): + assert insecure_master_key_reason(None, alternative_auth_enabled=True) is None def test_insecure_master_key_warning_returned_for_example_key(): diff --git a/tests/test_litellm/proxy/health_endpoints/test_health_endpoints.py b/tests/test_litellm/proxy/health_endpoints/test_health_endpoints.py index 527d46931fe..c8e47c0f02a 100644 --- a/tests/test_litellm/proxy/health_endpoints/test_health_endpoints.py +++ b/tests/test_litellm/proxy/health_endpoints/test_health_endpoints.py @@ -1357,6 +1357,39 @@ def test_health_readiness_details_reports_env_credential_login_warning(monkeypat assert response.json()["show_env_credential_login_warning"] is expected_warning +@pytest.mark.parametrize( + "master_key, general_settings, expected_reason", + [ + ("sk-1234", {}, "example_key"), + (None, {}, "missing"), + ("", {}, "missing"), + (None, {"enable_jwt_auth": True}, None), + ("sk-strong-random-key", {}, None), + ], +) +def test_health_readiness_details_reports_insecure_master_key_reason( + monkeypatch, master_key, general_settings, expected_reason +): + """ + The Admin UI banner is driven by this field: it must be "example_key" while + the docs example key is configured, "missing" when no master key is set and + no alternative auth replaces it, and null when the configured key is strong. + """ + app = FastAPI() + app.include_router(_health_endpoints_module.router) + app.dependency_overrides[user_api_key_auth] = lambda: UserAPIKeyAuth(user_role=LitellmUserRoles.PROXY_ADMIN) + client = TestClient(app) + + monkeypatch.setattr("litellm.proxy.proxy_server.prisma_client", None) + monkeypatch.setattr("litellm.proxy.proxy_server.master_key", master_key) + monkeypatch.setattr("litellm.proxy.proxy_server.general_settings", general_settings) + + response = client.get("/health/readiness/details") + + assert response.status_code == 200, response.text + assert response.json()["insecure_master_key_reason"] == expected_reason + + def test_health_readiness_allows_explicit_legacy_public_details(monkeypatch): """ Operators can explicitly preserve the legacy public readiness payload. diff --git a/ui/litellm-dashboard/src/app/(dashboard)/hooks/healthReadiness/useHealthReadinessDetails.ts b/ui/litellm-dashboard/src/app/(dashboard)/hooks/healthReadiness/useHealthReadinessDetails.ts index 44d9092df34..e76c894fd8f 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/hooks/healthReadiness/useHealthReadinessDetails.ts +++ b/ui/litellm-dashboard/src/app/(dashboard)/hooks/healthReadiness/useHealthReadinessDetails.ts @@ -15,6 +15,7 @@ export interface HealthReadinessDetailsResponse { is_detailed_debug?: boolean; show_no_redis_warning?: boolean; show_env_credential_login_warning?: boolean; + insecure_master_key_reason?: "example_key" | "missing" | null; } const fetchHealthReadinessDetails = async (accessToken: string): Promise => { diff --git a/ui/litellm-dashboard/src/app/(dashboard)/layout.tsx b/ui/litellm-dashboard/src/app/(dashboard)/layout.tsx index fa6df7f176a..0152ec90d28 100644 --- a/ui/litellm-dashboard/src/app/(dashboard)/layout.tsx +++ b/ui/litellm-dashboard/src/app/(dashboard)/layout.tsx @@ -11,6 +11,7 @@ import { useRouter, useSearchParams } from "next/navigation"; import { DebugWarningBanner } from "@/components/DebugWarningBanner"; import { NoRedisWarningBanner } from "@/components/NoRedisWarningBanner"; import { EnvCredentialLoginWarningBanner } from "@/components/EnvCredentialLoginWarningBanner"; +import { InsecureMasterKeyWarningBanner } from "@/components/InsecureMasterKeyWarningBanner"; import { LicenseExpiryBanner } from "@/components/LicenseExpiryBanner"; import { UserBanner } from "@/components/UserBanner"; import { uiHref } from "@/utils/uiHref"; @@ -115,6 +116,7 @@ function DashboardShell({ children }: { children: React.ReactNode }) { +
@@ -135,6 +137,7 @@ function DashboardShell({ children }: { children: React.ReactNode }) { +
{children}
diff --git a/ui/litellm-dashboard/src/components/InsecureMasterKeyWarningBanner.test.tsx b/ui/litellm-dashboard/src/components/InsecureMasterKeyWarningBanner.test.tsx new file mode 100644 index 00000000000..3c6ad94c8ed --- /dev/null +++ b/ui/litellm-dashboard/src/components/InsecureMasterKeyWarningBanner.test.tsx @@ -0,0 +1,50 @@ +import { renderWithProviders, screen } from "../../tests/test-utils"; +import { vi } from "vitest"; +import { InsecureMasterKeyWarningBanner } from "./InsecureMasterKeyWarningBanner"; +import type { HealthReadinessDetailsResponse } from "@/app/(dashboard)/hooks/healthReadiness/useHealthReadinessDetails"; +import type { UseQueryResult } from "@tanstack/react-query"; + +vi.mock("@/app/(dashboard)/hooks/healthReadiness/useHealthReadinessDetails", () => ({ + useHealthReadinessDetails: vi.fn(), +})); + +import { useHealthReadinessDetails } from "@/app/(dashboard)/hooks/healthReadiness/useHealthReadinessDetails"; + +const mockDetails = (data: Partial | undefined) => { + vi.mocked(useHealthReadinessDetails).mockReturnValue({ data } as UseQueryResult); +}; + +describe("InsecureMasterKeyWarningBanner", () => { + it("should warn when the proxy reports the docs example key", () => { + mockDetails({ status: "healthy", insecure_master_key_reason: "example_key" }); + renderWithProviders(); + expect(screen.getByRole("alert")).toBeInTheDocument(); + expect(screen.getByText("The master key is the docs example key sk-1234")).toBeInTheDocument(); + }); + + it("should warn when the proxy reports no master key", () => { + mockDetails({ status: "healthy", insecure_master_key_reason: "missing" }); + renderWithProviders(); + expect(screen.getByRole("alert")).toBeInTheDocument(); + expect(screen.getByText("No master key is set")).toBeInTheDocument(); + expect(screen.getByText(/accepted without authentication/)).toBeInTheDocument(); + }); + + it("should render nothing when the configured key is strong", () => { + mockDetails({ status: "healthy", insecure_master_key_reason: null }); + const { container } = renderWithProviders(); + expect(container).toBeEmptyDOMElement(); + }); + + it("should render nothing when readiness details are unavailable", () => { + mockDetails(undefined); + const { container } = renderWithProviders(); + expect(container).toBeEmptyDOMElement(); + }); + + it("should pass the access token to the readiness hook", () => { + mockDetails(undefined); + renderWithProviders(); + expect(useHealthReadinessDetails).toHaveBeenCalledWith("my-token"); + }); +}); diff --git a/ui/litellm-dashboard/src/components/InsecureMasterKeyWarningBanner.tsx b/ui/litellm-dashboard/src/components/InsecureMasterKeyWarningBanner.tsx new file mode 100644 index 00000000000..27d6f927d47 --- /dev/null +++ b/ui/litellm-dashboard/src/components/InsecureMasterKeyWarningBanner.tsx @@ -0,0 +1,52 @@ +"use client"; + +import React from "react"; +import { TriangleAlert } from "lucide-react"; +import { useHealthReadinessDetails } from "@/app/(dashboard)/hooks/healthReadiness/useHealthReadinessDetails"; + +const BANNER_CONTENT = { + example_key: { + title: "The master key is the docs example key sk-1234", + body: ( + <> + Anyone who has read the LiteLLM docs can administer this gateway. Generate a strong random key, set it as{" "} + LITELLM_MASTER_KEY (or{" "} + general_settings.master_key), and restart the proxy. + + ), + }, + missing: { + title: "No master key is set", + body: ( + <> + Every request to this proxy is accepted without authentication, including admin routes. Set{" "} + LITELLM_MASTER_KEY (or{" "} + general_settings.master_key) to a strong random key and restart the proxy. + + ), + }, +} as const; + +export const InsecureMasterKeyWarningBanner: React.FC<{ accessToken: string | null }> = ({ accessToken }) => { + const { data: healthData } = useHealthReadinessDetails(accessToken); + const reason = healthData?.insecure_master_key_reason; + + if (reason == null) { + return null; + } + + const { title, body } = BANNER_CONTENT[reason]; + + return ( +
+
+ ); +};