feat(guardrails): add configurable fail-open, timeout, and app_user tracking to panw_prisma_airs guardrail

[jroberts2600]

Title

PANW Prisma AIRS guardrail enhancements

Add configurable fail-open/fail-closed behavior, timeout settings, and app_user metadata tracking. Includes security hardening, enhanced observability :unscanned header, and comprehensive test coverage (44/44 passing).
No breaking changes.

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have Added testing in the tests/litellm/ directory, Adding at least 1 test is a hard requirement - see details
• I have added a screenshot of my new test passing locally
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem

Type

🆕 New Feature
📖 Documentation
✅ Test

Changes

[x] Backward Compatible

Features:

1. Configurable Fail-Open/Fail-Closed Behavior

   • Add fallback_on_error config: "block" (fail-closed, default) or "allow" (fail-open)
   • Transient errors (timeout, network) respect fallback_on_error setting
   • Configuration errors (401/403) always block, even in fail-open mode

2. Configurable API Timeout

   • Add timeout parameter (1-60 seconds, default 10s)

3. Enhanced User Tracking

   • Add app_user metadata with priority chain: app_user > user > "litellm_user"

4. Enhanced Observability

   • Add :unscanned header for fail-open requests
   • Symmetric standard logging across all code paths

Documentation:

• Fail-open configuration guide and behavior matrix
• New configuration parameters (fallback_on_error, timeout)
• app_user metadata priority chain
• Regional endpoints (US, EU, India)
• Security warnings for fail-open mode

Testing:

Added 6 new tests for fail-open behavior and app_user priority
All 44 tests passing (100% pass rate)
Manually verified: fail-open, fail-closed, streaming, profile overrides

Test output screenshot:

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
litellm	Ready	Preview	Comment	Dec 10, 2025 8:40pm

[krrishdholakia]

@jroberts2600 on a subsequent pr, can you consider moving to apply_guardrails() instead of overriding the async_pre_call/async_post_call event hooks? this will allow your guardrails to work across all our unified endpoints (chat completions, anthropic v1/messages, responses api, embeddings, image gen, etc.), as we now do the work to extract the text per endpoint.

open to feedback either here/slack if you have any issues with it! https://join.slack.com/t/litellmossslack/shared_invite/zt-39nz7s4cm-V1VL5HTRDwkbpkpOy~MDhw