BerriAI/litellm · critical · CiscoAIDefenseGuardrailMissingSecrets

Cisco AI Defense API key is required. Set `CISCO_AI_DEFENSE_

Error message

Cisco AI Defense API key is required. Set `CISCO_AI_DEFENSE_API_KEY` in the environment or pass `api_key` in the guardrail config.

What it means

CiscoAIDefenseGuardrailMissingSecrets is raised from the Cisco AI Defense guardrail constructor when both the api_key parameter and the CISCO_AI_DEFENSE_API_KEY environment variable are empty. The guardrail needs the key to authenticate every inspection request to the Cisco AI Defense API (header-based auth), so it refuses to initialize rather than skip scanning.

Source

Thrown at litellm/proxy/guardrails/guardrail_hooks/cisco_ai_defense/cisco_ai_defense.py:151

        self,
        guardrail_name: str | None = "cisco-ai-defense",
        api_key: str | None = None,
        api_base: str | None = None,
        inspection_type: str | None = None,
        inspect_path: str | None = None,
        enabled_rules: Sequence[object] | None = None,
        integration_profile_id: str | None = None,
        integration_profile_version: str | None = None,
        integration_tenant_id: str | None = None,
        integration_type: str | None = None,
        on_flagged_action: str | None = None,
        fallback_on_error: str | None = None,
        timeout: float | None = None,
        **kwargs: Any,
    ) -> None:
        resolved_api_key: Final = api_key or os.environ.get("CISCO_AI_DEFENSE_API_KEY")
        if not resolved_api_key:
            raise CiscoAIDefenseGuardrailMissingSecrets(
                "Cisco AI Defense API key is required. Set "
                "`CISCO_AI_DEFENSE_API_KEY` in the environment or pass "
                "`api_key` in the guardrail config."
            )
        self.api_key: str = resolved_api_key

        self.api_base: str = (api_base or os.environ.get("CISCO_AI_DEFENSE_API_BASE") or CISCO_DEFAULT_API_BASE).rstrip(
            "/"
        )

        self.inspection_type: str = self._resolve_choice(
            value=inspection_type,
            env_var="CISCO_AI_DEFENSE_INSPECTION_TYPE",
            allowed=SUPPORTED_INSPECTION_TYPES,
            default=DEFAULT_INSPECTION_TYPE,
            setting_name="inspection_type",
        )

View on GitHub (pinned to 77b7c6c40c)

Solutions

Export CISCO_AI_DEFENSE_API_KEY in the environment where litellm proxy runs and restart it.
Or set api_key: in the guardrail's litellm_params (supports os.environ/... and secret-manager references).
Confirm the exact name and that the value is non-empty in the running process (e.g., check the service's environment dump).
If using a secret manager, verify the reference resolves (litellm logs secret resolution failures at startup).

Example fix

# before
guardrails:
  - guardrail_name: cisco-ai-defense
    litellm_params:
      guardrail: cisco_ai_defense

# after
#   export CISCO_AI_DEFENSE_API_KEY=<key from Cisco AI Defense console>
guardrails:
  - guardrail_name: cisco-ai-defense
    litellm_params:
      guardrail: cisco_ai_defense
      api_key: os.environ/CISCO_AI_DEFENSE_API_KEY

Defensive patterns

Strategy: validation

Validate before calling

import os
from litellm import get_secret_str
if not (get_secret_str("CISCO_AI_DEFENSE_API_KEY") or os.environ.get("CISCO_AI_DEFENSE_API_KEY")):
    raise SystemExit("CISCO_AI_DEFENSE_API_KEY missing — proxy cannot start cisco guardrail")

Prevention

Add a startup preflight that asserts every configured guardrail's required env keys are present.
Store keys in a secret manager and reference them from config so environments can't drift.
Name-seed alerts: any ValueError from guardrail init should page the on-call (proxy is down).

When it happens

Trigger: Configuring a guardrail entry with guardrail: cisco_ai_defense but omitting api_key while CISCO_AI_DEFENSE_API_KEY is unset in the proxy's process environment; secret-manager references that resolve to None; key defined only in a .env file that the deployment method does not load.

Common situations: CI/staging environments missing the Cisco key; Docker Compose forgetting to pass the env through; the variable named with the older/different convention (e.g., CISCO_API_KEY) so it silently resolves empty.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/839295c2b51f020a. Report an issue: GitHub.