diff --git a/docs/my-website/docs/proxy/guardrails/panw_prisma_airs.md b/docs/my-website/docs/proxy/guardrails/panw_prisma_airs.md index 53f8a03f5bb..e3273a01c17 100644 --- a/docs/my-website/docs/proxy/guardrails/panw_prisma_airs.md +++ b/docs/my-website/docs/proxy/guardrails/panw_prisma_airs.md @@ -206,6 +206,7 @@ Expected successful response: | `mode` | No | When to run the guardrail | `pre_call` | | `fallback_on_error` | No | Action when PANW API is unavailable: `"block"` (fail-closed, default) or `"allow"` (fail-open). Config errors always block. | `block` | | `timeout` | No | PANW API call timeout in seconds (1-60) | `10.0` | +| `violation_message_template` | No | Custom template for error message when request is blocked. Supports `{guardrail_name}`, `{category}`, `{action_type}`, `{default_message}` placeholders. | - | ### Regional Endpoints @@ -449,6 +450,33 @@ LiteLLM does not alter or configure your PANW security profile. To change what c The guardrail is **fail-closed** by default - if the PANW API is unavailable, requests are blocked to ensure no unscanned content reaches your LLM. This provides maximum security. ::: +### Custom Violation Messages + +You can customize the error message returned to the user when a request is blocked by configuring the `violation_message_template` parameter. This is useful for providing user-friendly feedback instead of technical details. + +```yaml +guardrails: + - guardrail_name: "panw-custom-message" + litellm_params: + guardrail: panw_prisma_airs + api_key: os.environ/PANW_PRISMA_AIRS_API_KEY + # Simple message + violation_message_template: "Your request was blocked by our AI Security Policy." + + - guardrail_name: "panw-detailed-message" + litellm_params: + guardrail: panw_prisma_airs + api_key: os.environ/PANW_PRISMA_AIRS_API_KEY + # Message with placeholders + violation_message_template: "{action_type} blocked due to {category} violation. Please contact support." +``` + +**Supported Placeholders:** +- `{guardrail_name}`: Name of the guardrail (e.g. "panw-custom-message") +- `{category}`: Violation category (e.g. "malicious", "injection", "dlp") +- `{action_type}`: "Prompt" or "Response" +- `{default_message}`: The original technical error message + ### Fail-Open Configuration By default, the PANW guardrail operates in **fail-closed** mode for maximum security. If the PANW API is unavailable (timeout, rate limit, network error), requests are blocked. You can configure **fail-open** mode for high-availability scenarios where service continuity is critical. diff --git a/litellm/proxy/guardrails/guardrail_hooks/panw_prisma_airs/panw_prisma_airs.py b/litellm/proxy/guardrails/guardrail_hooks/panw_prisma_airs/panw_prisma_airs.py index 02e481acddd..b98eeff99d6 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/panw_prisma_airs/panw_prisma_airs.py +++ b/litellm/proxy/guardrails/guardrail_hooks/panw_prisma_airs/panw_prisma_airs.py @@ -62,6 +62,7 @@ def __init__( app_name: Optional[str] = None, fallback_on_error: Literal["block", "allow"] = "block", timeout: float = 10.0, + violation_message_template: Optional[str] = None, **kwargs, ): """Initialize PANW Prisma AIRS guardrail handler.""" @@ -77,6 +78,7 @@ def __init__( default_on=default_on, mask_request_content=_mask_request_content, mask_response_content=_mask_response_content, + violation_message_template=violation_message_template, **kwargs, ) @@ -489,7 +491,18 @@ def _build_error_detail( detection_key = "response_detected" if is_response else "prompt_detected" category = scan_result.get("category", "unknown") - error_msg = f"{action_type} blocked by PANW Prisma AI Security policy (Category: {category})" + default_msg = f"{action_type} blocked by PANW Prisma AI Security policy (Category: {category})" + + # Use custom violation message template if configured + error_msg = self.render_violation_message( + default=default_msg, + context={ + "guardrail_name": self.guardrail_name, + "category": category, + "action_type": action_type, + "default_message": default_msg, + }, + ) error_detail = { "error": { diff --git a/litellm/proxy/guardrails/guardrail_initializers.py b/litellm/proxy/guardrails/guardrail_initializers.py index 66b41005c4e..639aebf45c9 100644 --- a/litellm/proxy/guardrails/guardrail_initializers.py +++ b/litellm/proxy/guardrails/guardrail_initializers.py @@ -217,6 +217,7 @@ def initialize_panw_prisma_airs(litellm_params, guardrail): app_name=getattr(litellm_params, "app_name", None), fallback_on_error=getattr(litellm_params, "fallback_on_error", "block"), timeout=float(getattr(litellm_params, "timeout", 10.0)), + violation_message_template=litellm_params.violation_message_template, ) litellm.logging_callback_manager.add_litellm_callback(_panw_callback)