Add Noma guardrails v2 based on custom guardrails

[TomAlon]

Relevant issues

Pre-Submission checklist

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

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

CI (LiteLLM team)

CI status guideline:

• 50-55 passing tests: main is stable with minor issues.
• 45-49 passing tests: acceptable but needs attention
• <= 40 passing tests: unstable; be careful with your merges and assess the risk.

• Branch creation CI run
  Link:

• CI run for the last commit
  Link:

• Merge / cherry-pick CI run
  Links:

Type

🆕 New Feature

Changes

Adding Noma guardrails V2, based on custom guardrails

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Feb 23, 2026 8:31am

[greptile-apps]

Greptile Summary

This PR adds a new noma_v2 guardrail integration based on the CustomGuardrail.apply_guardrail pattern, deprecating the legacy noma guardrail. The v2 implementation sends the full request payload (including model_call_details from the logging object) to a new Noma endpoint (/litellm/guardrail) and supports three response actions: NONE, BLOCKED, and GUARDRAIL_INTERVENED. A migration path is provided via a use_v2: true flag on the existing guardrail: noma configuration.

• Security concern: _build_scan_payload includes model_call_details (which contains the LLM provider api_key) in the payload sent to the external Noma API — this is a key leak risk that should be addressed before merging.
• Documentation mismatch: The docs claim application_id falls back to x-noma-application-id header and user_api_key_alias, but the code only resolves from dynamic params and the configured value. The test suite explicitly confirms these fallbacks are absent.
• Good test coverage with mock-only tests covering configuration, all three action types, fail-open/fail-closed behavior, monitor mode, and application ID resolution.
• Clean integration with the existing guardrail registry and type system.

Confidence Score: 2/5

• This PR has a security concern where LLM provider API keys may be leaked to the external Noma API endpoint via model_call_details.
• The core guardrail logic is well-structured and follows existing patterns, but the API key leakage via model_call_details sent to an external endpoint is a significant security concern that should be resolved before merging. The documentation also inaccurately describes application_id fallback behavior that doesn't exist in the code.
• Pay close attention to litellm/proxy/guardrails/guardrail_hooks/noma/noma_v2.py (API key leakage) and docs/my-website/docs/proxy/guardrails/noma_security.md (inaccurate application_id fallback docs).

Important Files Changed

Filename	Overview
litellm/proxy/guardrails/guardrail_hooks/noma/noma_v2.py	New Noma v2 guardrail implementation. Security concern: _build_scan_payload includes model_call_details (which contains the provider api_key) in the payload sent to the external Noma API.
docs/my-website/docs/proxy/guardrails/noma_security.md	Documentation for Noma v2 guardrails. The application_id fallback description doesn't match the v2 implementation behavior.
litellm/proxy/guardrails/guardrail_hooks/noma/init.py	Adds v2 initialization, use_v2 migration toggle, and registry entries. Clean implementation following existing patterns.
litellm/proxy/guardrails/guardrail_hooks/noma/noma.py	Minor change adding a deprecation warning for the legacy Noma guardrail. Clean implementation.
litellm/types/guardrails.py	Adds NOMA_V2 enum and use_v2 field to NomaGuardrailConfigModel. Consistent with existing patterns.
litellm/types/proxy/guardrails/guardrail_hooks/noma.py	Adds NomaV2GuardrailConfigModel and use_v2 field to existing config model. Clean implementation.
tests/test_litellm/proxy/guardrails/guardrail_hooks/test_noma_v2.py	Comprehensive mock-only test suite for Noma v2 guardrail. Good coverage of configuration, actions, failure modes, and application ID resolution.
tests/test_litellm/proxy/guardrails/guardrail_hooks/test_noma.py	Adds deprecation warning test and v2 migration routing test to existing Noma test suite. Tests are mock-only.
tests/test_litellm/proxy/guardrails/test_guardrail_registry.py	Adds registry resolution test for noma/noma_v2 entries. Clean mock-only test.

Sequence Diagram

sequenceDiagram
    participant Client
    participant LiteLLM Proxy
    participant NomaV2Guardrail
    participant Noma API

    Client->>LiteLLM Proxy: Chat completion request
    LiteLLM Proxy->>NomaV2Guardrail: apply_guardrail(inputs, request_data, "request")
    NomaV2Guardrail->>NomaV2Guardrail: Resolve application_id (dynamic > configured)
    NomaV2Guardrail->>NomaV2Guardrail: _build_scan_payload()
    NomaV2Guardrail->>NomaV2Guardrail: _sanitize_payload_for_transport()
    NomaV2Guardrail->>Noma API: POST /litellm/guardrail (sanitized payload)
    Noma API-->>NomaV2Guardrail: {action: NONE|BLOCKED|GUARDRAIL_INTERVENED, ...}

    alt action = NONE
        NomaV2Guardrail-->>LiteLLM Proxy: Return original inputs
    else action = BLOCKED
        NomaV2Guardrail-->>LiteLLM Proxy: Raise NomaBlockedMessage (HTTP 400)
    else action = GUARDRAIL_INTERVENED
        NomaV2Guardrail->>NomaV2Guardrail: Update texts/images/tools/tool_calls from response
        NomaV2Guardrail-->>LiteLLM Proxy: Return modified inputs
    end

    NomaV2Guardrail->>NomaV2Guardrail: _add_guardrail_observability()
    LiteLLM Proxy-->>Client: Response (or 400 if blocked)

Loading

_{Last reviewed commit: 19d8ea2}

[greptile-apps]

_{9 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[shivamrawat1]

@greptile re-review after the fixes

[greptile-apps]

Greptile Summary

This PR adds a new noma_v2 guardrail integration built on the CustomGuardrail.apply_guardrail interface, alongside a migration path (use_v2: true) from the legacy noma guardrail. The v2 implementation communicates with a new Noma endpoint (/litellm/guardrail), supports three response actions (NONE, BLOCKED, GUARDRAIL_INTERVENED), and includes proper observability, fail-open/closed semantics, and monitor mode.

• Adds NomaV2Guardrail class implementing apply_guardrail with action-based response handling, payload sanitization, and configurable monitor_mode / block_failures
• Deprecates legacy noma guardrail with a runtime DeprecationWarning and provides use_v2: true migration toggle
• Registers noma_v2 in the guardrail initializer and class registries
• Adds NomaV2GuardrailConfigModel for UI config and use_v2 field to NomaGuardrailConfigModel / LitellmParams
• Comprehensive mock-only test suite (481 lines) covering configuration, auth paths, action handling, application ID resolution, and error scenarios
• Prior review flagged: model_call_details (containing LLM provider api_key) is included in the payload sent to the external Noma endpoint — the author should address this
• Prior review flagged: Docs claim application_id falls back to x-noma-application-id header and user_api_key_alias, but the code does not implement these fallbacks

Confidence Score: 3/5

• This PR is generally safe to merge but has an unresolved security concern about API key exposure in payloads sent to an external endpoint.
• The code is well-structured, follows existing guardrail patterns, and has thorough test coverage. However, the previously flagged API key leak in model_call_details remains unresolved, and the docs-vs-code mismatch for application_id fallbacks needs attention. The core guardrail logic is sound with proper error handling and fail-open/closed support.
• Pay close attention to litellm/proxy/guardrails/guardrail_hooks/noma/noma_v2.py (API key in model_call_details sent externally) and docs/my-website/docs/proxy/guardrails/noma_security.md (inaccurate fallback documentation).

Important Files Changed

Filename	Overview
litellm/proxy/guardrails/guardrail_hooks/noma/noma_v2.py	New Noma v2 guardrail implementation. Well-structured with proper error handling, observability, and sanitization. Sends model_call_details (including api_key) to external endpoint (flagged in prior thread). One potential issue with _sanitize_payload_for_transport silently returning empty dict on failure.
litellm/proxy/guardrails/guardrail_hooks/noma/init.py	Adds v2 initialization and registry entries. Clean migration path with use_v2 toggle. Correct routing logic for both direct noma_v2 and migration noma + use_v2=True.
litellm/proxy/guardrails/guardrail_hooks/noma/noma.py	Minimal changes: adds deprecation warning on legacy guardrail construction. Clean implementation with global flag to avoid repeated warnings.
litellm/types/guardrails.py	Adds NOMA_V2 to SupportedGuardrailIntegrations enum and use_v2 field to NomaGuardrailConfigModel. The use_v2 field propagates to all guardrails via LitellmParams inheritance but is harmless due to extra="allow" pattern.
litellm/types/proxy/guardrails/guardrail_hooks/noma.py	Adds NomaV2GuardrailConfigModel for UI config and use_v2 field to existing NomaGuardrailConfigModel. Properly inherits from GuardrailConfigModel. Clean and consistent with other guardrail patterns.
docs/my-website/docs/proxy/guardrails/noma_security.md	Documentation for v2 guardrails with migration guide. Contains inaccurate description of application_id fallback behavior (flagged in prior thread).
tests/test_litellm/proxy/guardrails/guardrail_hooks/test_noma_v2.py	Comprehensive test suite covering configuration, authentication, action handling, application ID resolution, monitor mode, and fail-open/closed behavior. All tests use mocks, no real network calls.
tests/test_litellm/proxy/guardrails/guardrail_hooks/test_noma.py	Adds tests for deprecation warning and v2 migration routing via use_v2=True. Uses mocks appropriately, no real network calls.
tests/test_litellm/proxy/guardrails/test_guardrail_registry.py	Adds registry resolution test for noma/noma_v2. Removes unnecessary print statements. Clean and focused.

Flowchart

flowchart TD
    A[Incoming Request] --> B{guardrail config}
    B -->|"guardrail: noma_v2"| C[initialize_guardrail_v2]
    B -->|"guardrail: noma + use_v2: true"| C
    B -->|"guardrail: noma"| D[initialize_guardrail legacy]

    C --> E[NomaV2Guardrail.apply_guardrail]
    E --> F[Resolve application_id<br>dynamic_params → config → None]
    F --> G[_build_scan_payload<br>inputs + request_data + logging_obj]
    G --> H[_sanitize_payload_for_transport]
    H --> I[POST /litellm/guardrail]
    I --> J{Response action}
    J -->|NONE| K[Return original inputs<br>status: success]
    J -->|GUARDRAIL_INTERVENED| L[Update texts/images/tools/tool_calls<br>status: guardrail_intervened]
    J -->|BLOCKED| M[Raise NomaBlockedMessage<br>status: guardrail_intervened]
    J -->|monitor_mode=true| N[Force action=NONE<br>Return original inputs]
    I -->|Error + block_failures=true| O[Raise exception]
    I -->|Error + block_failures=false| P[Return original inputs<br>fail-open]

    D --> Q[NomaGuardrail legacy flow<br>DeprecationWarning emitted]

Loading

_{Last reviewed commit: 19d8ea2}

[greptile-apps]

_{9 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[TomAlon]

@greptile re-review

[greptile-apps]

Greptile Summary

This PR adds a new noma_v2 guardrail integration based on the CustomGuardrail.apply_guardrail pattern, alongside a deprecation path for the legacy noma guardrail.

• Introduces NomaV2Guardrail class that implements apply_guardrail with three action modes: NONE (pass-through), BLOCKED (raise NomaBlockedMessage), and GUARDRAIL_INTERVENED (modify input fields like texts, images, tools, tool_calls)
• Adds noma_v2 as a new SupportedGuardrailIntegrations enum value with its own initializer and class registry entries
• Provides a use_v2: true migration toggle on the legacy noma guardrail for gradual migration
• Adds deprecation warning to the legacy NomaGuardrail constructor
• Adds NomaV2GuardrailConfigModel for UI configuration and deepcopy-based request data isolation
• Comprehensive mock-only test suite covering configuration, all action paths, application ID resolution, monitor mode, and fail-open/closed behavior
• Documentation updated with v2 section and deprecation notice, though legacy heading hierarchy needs attention

Confidence Score: 4/5

• This PR is safe to merge with minor documentation fixes recommended.
• The v2 implementation follows established patterns (CustomGuardrail.apply_guardrail), has comprehensive mock-only tests, clean error handling with configurable fail-open/closed behavior, and proper registry integration. The main prior concern (API key leakage via model_call_details) was already flagged. Remaining issues are stylistic (doc heading hierarchy, action error distinguishability).
• docs/my-website/docs/proxy/guardrails/noma_security.md has a heading hierarchy issue. litellm/proxy/guardrails/guardrail_hooks/noma/noma_v2.py has the previously-flagged API key leakage concern and a minor error-distinguishability suggestion.

Important Files Changed

Filename	Overview
litellm/proxy/guardrails/guardrail_hooks/noma/noma_v2.py	New v2 guardrail implementation with clean architecture using apply_guardrail pattern. Uses deepcopy for request data isolation, has proper error handling with fail-open/fail-closed modes, and sanitization for transport. Previous review threads flagged API key leakage via model_call_details — still present.
litellm/proxy/guardrails/guardrail_hooks/noma/noma.py	Adds deprecation warning for legacy noma guardrail using a module-level flag. Clean implementation with proper stacklevel and one-time warning behavior.
litellm/proxy/guardrails/guardrail_hooks/noma/init.py	Adds noma_v2 registration in both initializer and class registries. Includes use_v2 migration toggle routing from legacy noma to v2. Clean implementation.
litellm/types/guardrails.py	Adds NOMA_V2 enum value and use_v2 field to NomaGuardrailConfigModel. Changes are minimal and correctly integrated into the LitellmParams MRO chain.
litellm/types/proxy/guardrails/guardrail_hooks/noma.py	Adds NomaV2GuardrailConfigModel for UI config, adds use_v2 to legacy config. Clean type definitions inheriting from GuardrailConfigModel.
tests/test_litellm/proxy/guardrails/guardrail_hooks/test_noma_v2.py	Comprehensive mock-only tests covering configuration, action behaviors (NONE, BLOCKED, GUARDRAIL_INTERVENED), application ID resolution, monitor mode, fail-open/closed, and serialization. All tests properly mock network calls.
tests/test_litellm/proxy/guardrails/guardrail_hooks/test_noma.py	Adds deprecation warning test and use_v2 routing test to existing legacy guardrail tests. All properly mocked.
tests/test_litellm/proxy/guardrails/test_guardrail_registry.py	Adds registry resolution test verifying both noma and noma_v2 entries exist. Removes print statements from existing tests.
docs/my-website/docs/proxy/guardrails/noma_security.md	Adds deprecation notice, v2 documentation section with config examples and environment variables. Has a heading hierarchy issue where legacy subsections are at the same level as the legacy section header.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[LiteLLM Proxy Request] --> B{Guardrail Config}
    B -->|"guardrail: noma_v2"| C[NomaV2Guardrail.apply_guardrail]
    B -->|"guardrail: noma + use_v2: true"| C
    B -->|"guardrail: noma"| D[Legacy NomaGuardrail]
    
    C --> E[Build Scan Payload]
    E --> F["deepcopy(request_data) + sanitize"]
    F --> G["POST /litellm/guardrail → Noma API"]
    
    G --> H{monitor_mode?}
    H -->|true| I["action = NONE (pass-through)"]
    H -->|false| J{Response Action}
    
    J -->|NONE| I
    J -->|BLOCKED| K[Raise NomaBlockedMessage]
    J -->|GUARDRAIL_INTERVENED| L[Update inputs: texts, images, tools, tool_calls]
    J -->|Invalid/Missing| M{block_failures?}
    
    G -->|Network Error| M
    M -->|true| N[Raise Exception]
    M -->|false| O[Return original inputs]
    
    I --> P[Return processed inputs]
    L --> P
    P --> Q[Add observability logging]
    K --> Q
    N --> Q
    O --> Q

Loading

_{Last reviewed commit: 8ad877c}

[greptile-apps]

_{9 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Broken heading hierarchy for legacy section

The new ## Noma guardrails (Legacy) header on line 16 is immediately followed by the pre-existing ## Quick Start on line 18. Since both are ## headings, the rendered docs sidebar will show "Quick Start" as a sibling of "Noma guardrails (Legacy)" rather than a child. All legacy subsections (Quick Start, Supported Params, Environment Variables, etc.) should be demoted by one level so they nest under the legacy header.

Suggested change

	## Noma guardrails (Legacy)
	## Quick Start
	## Noma guardrails (Legacy)
	### Quick Start

[greptile-apps]

Invalid action silently passes through when block_failures=False

When the Noma API returns a response with an unrecognized or missing action field, _resolve_action_from_response raises ValueError("Noma v2 response missing valid action"). This ValueError is caught by the generic except Exception branch in apply_guardrail (line 296), which — when block_failures=False — silently returns the original inputs, logging only a generic error.

This means an API contract change (e.g., Noma starts returning "action": "REDACTED") would be indistinguishable from a network failure. Consider either: (a) logging the unexpected action value at warning/error level inside _resolve_action_from_response before raising, or (b) using a distinct exception type so apply_guardrail can differentiate contract violations from transport errors.

[krrishdholakia]

why change the name, instead of just rewriting the noma.py?

this adds additional code to maintain