From 9e6ae458e1117fbaebe45158f9d6b366f0318843 Mon Sep 17 00:00:00 2001 From: Vivek Kalyanarangan <12863647+vivekkalyanarangan30@users.noreply.github.com> Date: Tue, 20 Oct 2026 09:00:45 +0530 Subject: [PATCH 1/9] feat(guardrails): checksum validators for content filter patterns Prebuilt content filter patterns can now declare a "validator" that a regex match must pass before it counts. The card patterns use Luhn and the IBAN patterns use ISO 13616 mod-97, so look-alike digit runs such as order ids or random 16 digit numbers stop being redacted as card numbers --- .../litellm_content_filter/content_filter.py | 18 ++++++++-- .../litellm_content_filter/patterns.json | 7 ++++ .../litellm_content_filter/validators.py | 34 ++++++++++++++++++ .../content_filter/test_content_filter.py | 35 ++++++++++++++++++- .../litellm_content_filter/test_validators.py | 34 ++++++++++++++++++ 5 files changed, 125 insertions(+), 3 deletions(-) create mode 100644 litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py create mode 100644 tests/unit/proxy/guardrails/guardrail_hooks/litellm_content_filter/test_validators.py diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py index 40e44151e65..eb742902a28 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py @@ -12,7 +12,7 @@ import json import os import re import time -from collections.abc import AsyncGenerator, Coroutine, Mapping, Sequence +from collections.abc import AsyncGenerator, Callable, Coroutine, Mapping, Sequence from dataclasses import dataclass, replace from datetime import datetime from re import Pattern @@ -21,6 +21,7 @@ from typing import TYPE_CHECKING, Any, Final, Literal, Optional, TypedDict, cast import yaml from fastapi import HTTPException from pydantic import TypeAdapter +from typing_extensions import ReadOnly from litellm import Router from litellm._logging import verbose_proxy_logger @@ -75,6 +76,7 @@ from .competitor_intent import ( BaseCompetitorIntentChecker, ) from .patterns import PATTERN_EXTRA_CONFIG, get_compiled_pattern +from .validators import PATTERN_VALIDATORS MAX_KEYWORD_VALUE_GAP_WORDS: Final = 1 _DECODED_ARGUMENTS: Final = TypeAdapter(object) @@ -124,11 +126,13 @@ class CompiledPatternEntry(TypedDict): action: ContentFilterAction keyword_regex: Pattern[str] | None allow_word_numbers: bool + validator: ReadOnly[Callable[[str], bool] | None] class _PatternExtraLookup(TypedDict): keyword_pattern: str | None allow_word_numbers: bool + validator: ReadOnly[Callable[[str], bool] | None] class _CategoryConfigView(TypedDict): @@ -749,7 +753,11 @@ class ContentFilterGuardrail(CustomGuardrail): pattern_config: ContentFilterPattern configuration """ try: - extra_config: _PatternExtraLookup = {"keyword_pattern": None, "allow_word_numbers": False} + extra_config: _PatternExtraLookup = { + "keyword_pattern": None, + "allow_word_numbers": False, + "validator": None, + } if pattern_config.pattern_type == "prebuilt": if not pattern_config.pattern_name: raise ValueError("pattern_name is required for prebuilt patterns") @@ -774,6 +782,7 @@ class ContentFilterGuardrail(CustomGuardrail): "action": pattern_config.action, "keyword_regex": keyword_regex, "allow_word_numbers": extra_config["allow_word_numbers"], + "validator": extra_config["validator"], } ) verbose_proxy_logger.debug("Added pattern: %s with action %s", pattern_name, pattern_config.action) @@ -784,9 +793,11 @@ class ContentFilterGuardrail(CustomGuardrail): @staticmethod def _lookup_pattern_extra(pattern_name: str) -> _PatternExtraLookup: extra: Final = PATTERN_EXTRA_CONFIG.get(pattern_name) + validator_name: Final = extra.get("validator") if extra is not None else None return { "keyword_pattern": extra.get("keyword_pattern") if extra is not None else None, "allow_word_numbers": bool(extra.get("allow_word_numbers")) if extra is not None else False, + "validator": PATTERN_VALIDATORS[validator_name] if validator_name is not None else None, } def _load_blocked_words_file(self, file_path: str) -> None: @@ -834,6 +845,7 @@ class ContentFilterGuardrail(CustomGuardrail): regex: Final[Pattern[str]] = pattern_entry["regex"] keyword_regex: Final[Pattern[str] | None] = pattern_entry.get("keyword_regex") allow_word_numbers: Final[bool] = pattern_entry.get("allow_word_numbers", False) + validator: Final = pattern_entry.get("validator") keyword_matches: Final = list(keyword_regex.finditer(text)) if keyword_regex is not None else None if keyword_matches is not None and not keyword_matches: @@ -842,6 +854,8 @@ class ContentFilterGuardrail(CustomGuardrail): match_spans: Final[list[tuple[int, int]]] = [] for match in regex.finditer(text): + if validator is not None and not validator(match.group()): + continue if keyword_matches is not None and not self._match_near_keyword( match.start(), match.end(), keyword_matches, text ): diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/patterns.json b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/patterns.json index db6dd36726c..44fe4775120 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/patterns.json +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/patterns.json @@ -32,6 +32,7 @@ "name": "visa", "display_name": "Credit Card (Visa)", "pattern": "\\b4\\d{3}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b", + "validator": "luhn", "category": "Payment Card Patterns", "description": "Detects Visa credit card numbers" }, @@ -39,6 +40,7 @@ "name": "mastercard", "display_name": "Credit Card (Mastercard)", "pattern": "\\b5[1-5]\\d{2}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b", + "validator": "luhn", "category": "Payment Card Patterns", "description": "Detects Mastercard credit card numbers" }, @@ -46,6 +48,7 @@ "name": "amex", "display_name": "Credit Card (American Express)", "pattern": "\\b3[47]\\d{2}[\\s\\-]?\\d{6}[\\s\\-]?\\d{5}\\b", + "validator": "luhn", "category": "Payment Card Patterns", "description": "Detects American Express credit card numbers" }, @@ -53,6 +56,7 @@ "name": "discover", "display_name": "Credit Card (Discover)", "pattern": "\\b6(?:011|5\\d{2})[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b", + "validator": "luhn", "category": "Payment Card Patterns", "description": "Detects Discover credit card numbers" }, @@ -60,6 +64,7 @@ "name": "credit_card", "display_name": "Credit Card (Any)", "pattern": "(?:\\b4\\d{3}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b|\\b5[1-5]\\d{2}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b|\\b3[47]\\d{2}[\\s\\-]?\\d{6}[\\s\\-]?\\d{5}\\b|\\b6(?:011|5\\d{2})[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b)", + "validator": "luhn", "category": "Payment Card Patterns", "description": "Detects any major credit card number" }, @@ -395,6 +400,7 @@ "name": "iban", "display_name": "IBAN (International Bank Account Number)", "pattern": "\\b[A-Z]{2}\\d{2}[A-Z0-9]{11,30}\\b", + "validator": "iban_mod97", "category": "Payment Card Patterns", "description": "Detects IBANs (2 letter country code + 2 check digits + 4 char bank code + 7 digit base + optional 0-16 alphanumeric)" }, @@ -409,6 +415,7 @@ "name": "eu_iban_enhanced", "display_name": "IBAN (Enhanced EU Format)", "pattern": "\\b[A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{7}[A-Z0-9]{0,16}\\b", + "validator": "iban_mod97", "category": "EU PII Patterns", "description": "Enhanced IBAN detection with more specific format validation (2 letter country + 2 check digits + 4 char bank code + 7 digit account base + optional 0-16 alphanumeric)" }, diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py new file mode 100644 index 00000000000..4021c873356 --- /dev/null +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py @@ -0,0 +1,34 @@ +import re +from collections.abc import Callable, Mapping +from types import MappingProxyType +from typing import Final + +_SEPARATORS: Final = re.compile(r"[\s\-]") +_IBAN_CHARACTERS: Final = re.compile(r"[0-9A-Z]{5,34}") + + +def _luhn_term(position: int, digit: int) -> int: + if position % 2 == 0: + return digit + doubled: Final = digit * 2 + return doubled - 9 if doubled > 9 else doubled + + +def passes_luhn(value: str) -> bool: + digits: Final = _SEPARATORS.sub("", value) + if not digits.isdecimal(): + return False + return sum(_luhn_term(position, int(digit)) for position, digit in enumerate(reversed(digits))) % 10 == 0 + + +def passes_iban_mod97(value: str) -> bool: + iban: Final = _SEPARATORS.sub("", value).upper() + if _IBAN_CHARACTERS.fullmatch(iban) is None: + return False + rearranged: Final = iban[4:] + iban[:4] + return int("".join(str(int(character, 36)) for character in rearranged)) % 97 == 1 + + +PATTERN_VALIDATORS: Final[Mapping[str, Callable[[str], bool]]] = MappingProxyType( + {"luhn": passes_luhn, "iban_mod97": passes_iban_mod97} +) diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py index f7fb7e1fed0..55aecc4dc1f 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py @@ -367,10 +367,43 @@ class TestContentFilterGuardrail: ) # Test Visa card - result = guardrail._check_patterns("My card is 4532-1234-5678-9010") + result = guardrail._check_patterns("My card is 4532-0151-1283-0366") assert result is not None assert result[1] == "visa" + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("pattern_name", "checksum_valid", "checksum_invalid"), + [ + ("credit_card", "4532 0151 1283 0366", "4532 0151 1283 0367"), + ("visa", "4532-0151-1283-0366", "4532-1234-5678-9010"), + ("mastercard", "5555555555554444", "5555555555554445"), + ("amex", "3782 822463 10005", "3782 822463 10006"), + ("discover", "6011111111111117", "6011111111111118"), + ("iban", "GB82WEST12345698765432", "GB83WEST12345698765432"), + ("eu_iban_enhanced", "DE89370400440532013000", "DE88370400440532013000"), + ], + ) + async def test_checksum_pattern_masks_only_values_that_pass_the_checksum( + self, pattern_name: str, checksum_valid: str, checksum_invalid: str + ): + guardrail: Final = ContentFilterGuardrail( + guardrail_name="test-checksum", + patterns=[ + ContentFilterPattern(pattern_type="prebuilt", pattern_name=pattern_name, action=ContentFilterAction.MASK) + ], + ) + + guardrailed_inputs: Final = await guardrail.apply_guardrail( + inputs={"texts": [f"real {checksum_valid} and look-alike {checksum_invalid}"]}, + request_data={}, + input_type="request", + ) + + assert guardrailed_inputs.get("texts") == [ + f"real [{pattern_name.upper()}_REDACTED] and look-alike {checksum_invalid}" + ] + def test_api_key_patterns(self): """ Test API key pattern detection diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/litellm_content_filter/test_validators.py b/tests/unit/proxy/guardrails/guardrail_hooks/litellm_content_filter/test_validators.py new file mode 100644 index 00000000000..1cf963fae85 --- /dev/null +++ b/tests/unit/proxy/guardrails/guardrail_hooks/litellm_content_filter/test_validators.py @@ -0,0 +1,34 @@ +import pytest + +from litellm.proxy.guardrails.guardrail_hooks.litellm_content_filter.validators import ( + passes_iban_mod97, + passes_luhn, +) + + +@pytest.mark.parametrize( + ("value", "expected"), + [ + ("4111 1111 1111 1111", True), + ("4111-1111-1111-1112", False), + ("٤" + "١" * 15, True), + ("4111 1111 1111 111x", False), + ("", False), + ], +) +def test_passes_luhn(value: str, expected: bool): + assert passes_luhn(value) is expected + + +@pytest.mark.parametrize( + ("value", "expected"), + [ + ("GB82 WEST 1234 5698 7654 32", True), + ("gb82west12345698765432", True), + ("GB82WEST12345698765433", False), + ("GB82", False), + ("GB82WEST1234569876543é", False), + ], +) +def test_passes_iban_mod97(value: str, expected: bool): + assert passes_iban_mod97(value) is expected From ad093f0585e6b1e91a9d787e602986562e1717e1 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 05:17:58 -0700 Subject: [PATCH 2/9] fix(guardrails): mask a checksum-valid card that overlaps a rejected look-alike --- .../litellm_content_filter/content_filter.py | 26 +++++++++++++------ .../content_filter/test_content_filter.py | 24 +++++++++++++++++ 2 files changed, 42 insertions(+), 8 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py index 305c2061d09..3b08ac6dc88 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py @@ -12,7 +12,7 @@ import json import os import re import time -from collections.abc import AsyncGenerator, Callable, Coroutine, Mapping, Sequence +from collections.abc import AsyncGenerator, Callable, Coroutine, Iterator, Mapping, Sequence from dataclasses import dataclass, replace from datetime import datetime from re import Pattern @@ -852,15 +852,16 @@ class ContentFilterGuardrail(CustomGuardrail): return [] match_spans: Final[list[tuple[int, int]]] = [] + candidate_spans: Final = ( + self._checksum_valid_spans(regex, text, validator) + if validator is not None + else ((match.start(), match.end()) for match in regex.finditer(text)) + ) - for match in regex.finditer(text): - if validator is not None and not validator(match.group()): + for start, end in candidate_spans: + if keyword_matches is not None and not self._match_near_keyword(start, end, keyword_matches, text): continue - if keyword_matches is not None and not self._match_near_keyword( - match.start(), match.end(), keyword_matches, text - ): - continue - match_spans.append((match.start(), match.end())) + match_spans.append((start, end)) if allow_word_numbers: for word_match in WORD_NUMBER_SEQUENCE_PATTERN.finditer(text): @@ -877,6 +878,15 @@ class ContentFilterGuardrail(CustomGuardrail): return self._merge_spans(match_spans) + @staticmethod + def _checksum_valid_spans( + regex: Pattern[str], text: str, validator: Callable[[str], bool] + ) -> Iterator[tuple[int, int]]: + overlapping_regex: Final = re.compile(f"(?=({regex.pattern}))", regex.flags) + return ( + (match.start(1), match.end(1)) for match in overlapping_regex.finditer(text) if validator(match.group(1)) + ) + def _match_near_keyword( self, value_start: int, diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py index 55aecc4dc1f..3d69b37c855 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py @@ -404,6 +404,30 @@ class TestContentFilterGuardrail: f"real [{pattern_name.upper()}_REDACTED] and look-alike {checksum_invalid}" ] + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("text", "expected"), + [ + ("PIN 4821 4532 0151 1283 0366 thanks", "PIN 4821 [CREDIT_CARD_REDACTED] thanks"), + ("order 4111 4532 0151 1283 0366", "order [CREDIT_CARD_REDACTED]"), + ], + ) + async def test_checksum_pattern_masks_a_valid_card_overlapping_another_candidate(self, text: str, expected: str): + guardrail: Final = ContentFilterGuardrail( + guardrail_name="test-checksum-overlap", + patterns=[ + ContentFilterPattern(pattern_type="prebuilt", pattern_name="credit_card", action=ContentFilterAction.MASK) + ], + ) + + guardrailed_inputs: Final = await guardrail.apply_guardrail( + inputs={"texts": [text]}, + request_data={}, + input_type="request", + ) + + assert guardrailed_inputs.get("texts") == [expected] + def test_api_key_patterns(self): """ Test API key pattern detection From 54c8c50a77d9ad6a2fb73c6e7b7990b2a302a632 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 06:15:23 -0700 Subject: [PATCH 3/9] fix(guardrails): mask a whole candidate run around a valid card, fold IBAN look-alike characters, speed up Luhn --- .../litellm_content_filter/content_filter.py | 22 ++++++++++----- .../litellm_content_filter/patterns.json | 14 +++++----- .../litellm_content_filter/validators.py | 21 +++++++++----- .../content_filter/test_content_filter.py | 28 +++++++++++++++++-- .../litellm_content_filter/test_validators.py | 17 +++++++++++ 5 files changed, 79 insertions(+), 23 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py index 3b08ac6dc88..4132f4960c8 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py @@ -12,7 +12,8 @@ import json import os import re import time -from collections.abc import AsyncGenerator, Callable, Coroutine, Iterator, Mapping, Sequence +from bisect import bisect_left +from collections.abc import AsyncGenerator, Callable, Coroutine, Mapping, Sequence from dataclasses import dataclass, replace from datetime import datetime from re import Pattern @@ -878,14 +879,21 @@ class ContentFilterGuardrail(CustomGuardrail): return self._merge_spans(match_spans) - @staticmethod def _checksum_valid_spans( - regex: Pattern[str], text: str, validator: Callable[[str], bool] - ) -> Iterator[tuple[int, int]]: + self, regex: Pattern[str], text: str, validator: Callable[[str], bool] + ) -> tuple[tuple[int, int], ...]: overlapping_regex: Final = re.compile(f"(?=({regex.pattern}))", regex.flags) - return ( - (match.start(1), match.end(1)) for match in overlapping_regex.finditer(text) if validator(match.group(1)) - ) + candidates: Final = tuple(overlapping_regex.finditer(text)) + valid_starts: Final = tuple(candidate.start(1) for candidate in candidates if validator(candidate.group(1))) + if not valid_starts: + return () + candidate_runs: Final = self._merge_spans([candidate.span(1) for candidate in candidates]) + return tuple(run for run in candidate_runs if self._run_contains_start(run, valid_starts)) + + @staticmethod + def _run_contains_start(run: tuple[int, int], sorted_starts: Sequence[int]) -> bool: + index: Final = bisect_left(sorted_starts, run[0]) + return index < len(sorted_starts) and sorted_starts[index] < run[1] def _match_near_keyword( self, diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/patterns.json b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/patterns.json index 44fe4775120..50b6d86ae7e 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/patterns.json +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/patterns.json @@ -34,7 +34,7 @@ "pattern": "\\b4\\d{3}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b", "validator": "luhn", "category": "Payment Card Patterns", - "description": "Detects Visa credit card numbers" + "description": "Detects Visa credit card numbers that pass the Luhn checksum" }, { "name": "mastercard", @@ -42,7 +42,7 @@ "pattern": "\\b5[1-5]\\d{2}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b", "validator": "luhn", "category": "Payment Card Patterns", - "description": "Detects Mastercard credit card numbers" + "description": "Detects Mastercard credit card numbers that pass the Luhn checksum" }, { "name": "amex", @@ -50,7 +50,7 @@ "pattern": "\\b3[47]\\d{2}[\\s\\-]?\\d{6}[\\s\\-]?\\d{5}\\b", "validator": "luhn", "category": "Payment Card Patterns", - "description": "Detects American Express credit card numbers" + "description": "Detects American Express credit card numbers that pass the Luhn checksum" }, { "name": "discover", @@ -58,7 +58,7 @@ "pattern": "\\b6(?:011|5\\d{2})[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b", "validator": "luhn", "category": "Payment Card Patterns", - "description": "Detects Discover credit card numbers" + "description": "Detects Discover credit card numbers that pass the Luhn checksum" }, { "name": "credit_card", @@ -66,7 +66,7 @@ "pattern": "(?:\\b4\\d{3}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b|\\b5[1-5]\\d{2}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b|\\b3[47]\\d{2}[\\s\\-]?\\d{6}[\\s\\-]?\\d{5}\\b|\\b6(?:011|5\\d{2})[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b)", "validator": "luhn", "category": "Payment Card Patterns", - "description": "Detects any major credit card number" + "description": "Detects any major credit card number that passes the Luhn checksum" }, { "name": "aws_access_key", @@ -402,7 +402,7 @@ "pattern": "\\b[A-Z]{2}\\d{2}[A-Z0-9]{11,30}\\b", "validator": "iban_mod97", "category": "Payment Card Patterns", - "description": "Detects IBANs (2 letter country code + 2 check digits + 4 char bank code + 7 digit base + optional 0-16 alphanumeric)" + "description": "Detects IBANs (2 letter country code + 2 check digits + 4 char bank code + 7 digit base + optional 0-16 alphanumeric) that pass the mod-97 check" }, { "name": "fr_nir", @@ -417,7 +417,7 @@ "pattern": "\\b[A-Z]{2}[0-9]{2}[A-Z0-9]{4}[0-9]{7}[A-Z0-9]{0,16}\\b", "validator": "iban_mod97", "category": "EU PII Patterns", - "description": "Enhanced IBAN detection with more specific format validation (2 letter country + 2 check digits + 4 char bank code + 7 digit account base + optional 0-16 alphanumeric)" + "description": "Enhanced IBAN detection with more specific format validation (2 letter country + 2 check digits + 4 char bank code + 7 digit account base + optional 0-16 alphanumeric) that pass the mod-97 check" }, { "name": "fr_phone", diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py index 4021c873356..125e426815c 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py @@ -5,24 +5,31 @@ from typing import Final _SEPARATORS: Final = re.compile(r"[\s\-]") _IBAN_CHARACTERS: Final = re.compile(r"[0-9A-Z]{5,34}") +_IGNORECASE_ASCII_LETTER_ALIASES: Final = str.maketrans({"\u0130": "I", "\u212a": "K"}) +_DIGIT_VALUES: Final = bytes.maketrans(b"0123456789", bytes(range(10))) +_DOUBLED_DIGIT_SUMS: Final = bytes.maketrans(b"0123456789", bytes((0, 2, 4, 6, 8, 1, 3, 5, 7, 9))) -def _luhn_term(position: int, digit: int) -> int: - if position % 2 == 0: - return digit - doubled: Final = digit * 2 - return doubled - 9 if doubled > 9 else doubled +def _to_ascii(value: str) -> str: + if value.isascii(): + return value + folded: Final = value.translate(_IGNORECASE_ASCII_LETTER_ALIASES) + return "".join(str(int(character)) if character.isdecimal() else character for character in folded) def passes_luhn(value: str) -> bool: digits: Final = _SEPARATORS.sub("", value) if not digits.isdecimal(): return False - return sum(_luhn_term(position, int(digit)) for position, digit in enumerate(reversed(digits))) % 10 == 0 + reversed_digits: Final = _to_ascii(digits)[::-1].encode() + checksum: Final = sum(reversed_digits[::2].translate(_DIGIT_VALUES)) + sum( + reversed_digits[1::2].translate(_DOUBLED_DIGIT_SUMS) + ) + return checksum % 10 == 0 def passes_iban_mod97(value: str) -> bool: - iban: Final = _SEPARATORS.sub("", value).upper() + iban: Final = _to_ascii(_SEPARATORS.sub("", value)).upper() if _IBAN_CHARACTERS.fullmatch(iban) is None: return False rearranged: Final = iban[4:] + iban[:4] diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py index 3d69b37c855..29294070b80 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py @@ -408,11 +408,12 @@ class TestContentFilterGuardrail: @pytest.mark.parametrize( ("text", "expected"), [ - ("PIN 4821 4532 0151 1283 0366 thanks", "PIN 4821 [CREDIT_CARD_REDACTED] thanks"), + ("PIN 4821 4532 0151 1283 0366 thanks", "PIN [CREDIT_CARD_REDACTED] thanks"), ("order 4111 4532 0151 1283 0366", "order [CREDIT_CARD_REDACTED]"), + ("order 4532 1234 5678 9010 paid by 4532 0151 1283 0366", "order 4532 1234 5678 9010 paid by [CREDIT_CARD_REDACTED]"), ], ) - async def test_checksum_pattern_masks_a_valid_card_overlapping_another_candidate(self, text: str, expected: str): + async def test_checksum_pattern_masks_each_run_of_candidates_that_holds_a_valid_card(self, text: str, expected: str): guardrail: Final = ContentFilterGuardrail( guardrail_name="test-checksum-overlap", patterns=[ @@ -428,6 +429,29 @@ class TestContentFilterGuardrail: assert guardrailed_inputs.get("texts") == [expected] + @pytest.mark.asyncio + @pytest.mark.parametrize( + "iban", + [ + "GB66\u212aEST12345698765432", + "GB73W\u0130ST12345698765432", + "GB\u0668\u0662WEST12345698765432", + ], + ) + async def test_checksum_pattern_masks_a_valid_iban_with_characters_the_regex_case_folds(self, iban: str): + guardrail: Final = ContentFilterGuardrail( + guardrail_name="test-checksum-folding", + patterns=[ContentFilterPattern(pattern_type="prebuilt", pattern_name="iban", action=ContentFilterAction.MASK)], + ) + + guardrailed_inputs: Final = await guardrail.apply_guardrail( + inputs={"texts": [f"send it to {iban}"]}, + request_data={}, + input_type="request", + ) + + assert guardrailed_inputs.get("texts") == ["send it to [IBAN_REDACTED]"] + def test_api_key_patterns(self): """ Test API key pattern detection diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/litellm_content_filter/test_validators.py b/tests/unit/proxy/guardrails/guardrail_hooks/litellm_content_filter/test_validators.py index 1cf963fae85..0214777cd22 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/litellm_content_filter/test_validators.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/litellm_content_filter/test_validators.py @@ -1,3 +1,6 @@ +from itertools import product +from typing import Final + import pytest from litellm.proxy.guardrails.guardrail_hooks.litellm_content_filter.validators import ( @@ -20,6 +23,20 @@ def test_passes_luhn(value: str, expected: bool): assert passes_luhn(value) is expected +@pytest.mark.parametrize( + "valid_number", + ["4111111111111111", "4012888888881881", "5555555555554444", "378282246310005", "6011000990139424"], +) +def test_passes_luhn_rejects_every_single_digit_change(valid_number: str): + single_digit_changes: Final = tuple( + valid_number[:position] + replacement + valid_number[position + 1 :] + for position, replacement in product(range(len(valid_number)), "0123456789") + ) + + assert passes_luhn(valid_number) + assert not any(passes_luhn(changed) for changed in single_digit_changes if changed != valid_number) + + @pytest.mark.parametrize( ("value", "expected"), [ From 3132e4bbc4de8b94c506d017121d4c79948131af Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 10:11:21 -0700 Subject: [PATCH 4/9] fix(guardrails): mask only the candidates overlapping a valid card so streamed replies keep their text Masking a whole run of overlapping candidates let a late valid card grow the masked span past the stream holdback, so text already sent shifted and the rest of the reply was lost. A valid window now masks only the candidates that overlap it, and text with no candidate skips the overlapping scan. --- .../litellm_content_filter/content_filter.py | 25 +++++++---- .../content_filter/test_content_filter.py | 44 ++++++++++++++++++- 2 files changed, 59 insertions(+), 10 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py index 4132f4960c8..7178494075d 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py @@ -882,18 +882,25 @@ class ContentFilterGuardrail(CustomGuardrail): def _checksum_valid_spans( self, regex: Pattern[str], text: str, validator: Callable[[str], bool] ) -> tuple[tuple[int, int], ...]: - overlapping_regex: Final = re.compile(f"(?=({regex.pattern}))", regex.flags) - candidates: Final = tuple(overlapping_regex.finditer(text)) - valid_starts: Final = tuple(candidate.start(1) for candidate in candidates if validator(candidate.group(1))) - if not valid_starts: + if regex.search(text) is None: return () - candidate_runs: Final = self._merge_spans([candidate.span(1) for candidate in candidates]) - return tuple(run for run in candidate_runs if self._run_contains_start(run, valid_starts)) + overlapping_regex: Final = re.compile(f"(?=({regex.pattern}))", regex.flags) + candidate_spans: Final = tuple(candidate.span(1) for candidate in overlapping_regex.finditer(text)) + valid_spans: Final = tuple(span for span in candidate_spans if validator(text[span[0] : span[1]])) + if not valid_spans: + return () + valid_starts: Final = tuple(start for start, _ in valid_spans) + furthest_valid_ends: Final = tuple(itertools.accumulate((end for _, end in valid_spans), max)) + return tuple( + span for span in candidate_spans if self._overlaps_a_valid_span(span, valid_starts, furthest_valid_ends) + ) @staticmethod - def _run_contains_start(run: tuple[int, int], sorted_starts: Sequence[int]) -> bool: - index: Final = bisect_left(sorted_starts, run[0]) - return index < len(sorted_starts) and sorted_starts[index] < run[1] + def _overlaps_a_valid_span( + span: tuple[int, int], sorted_valid_starts: Sequence[int], furthest_valid_ends: Sequence[int] + ) -> bool: + index: Final = bisect_left(sorted_valid_starts, span[1]) + return index > 0 and furthest_valid_ends[index - 1] > span[0] def _match_near_keyword( self, diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py index 29294070b80..6f69bb25185 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py @@ -410,10 +410,11 @@ class TestContentFilterGuardrail: [ ("PIN 4821 4532 0151 1283 0366 thanks", "PIN [CREDIT_CARD_REDACTED] thanks"), ("order 4111 4532 0151 1283 0366", "order [CREDIT_CARD_REDACTED]"), + ("codes 4532 4532 4532 4532 4532 0151 1283 0366 thanks", "codes 4532 [CREDIT_CARD_REDACTED] thanks"), ("order 4532 1234 5678 9010 paid by 4532 0151 1283 0366", "order 4532 1234 5678 9010 paid by [CREDIT_CARD_REDACTED]"), ], ) - async def test_checksum_pattern_masks_each_run_of_candidates_that_holds_a_valid_card(self, text: str, expected: str): + async def test_checksum_pattern_masks_a_valid_card_with_the_candidates_overlapping_it(self, text: str, expected: str): guardrail: Final = ContentFilterGuardrail( guardrail_name="test-checksum-overlap", patterns=[ @@ -429,6 +430,47 @@ class TestContentFilterGuardrail: assert guardrailed_inputs.get("texts") == [expected] + @pytest.mark.asyncio + async def test_checksum_pattern_streams_the_same_text_as_a_whole_response(self): + from litellm.types.utils import Delta, ModelResponseStream, StreamingChoices + + guardrail: Final = ContentFilterGuardrail( + guardrail_name="test-checksum-streaming", + patterns=[ + ContentFilterPattern(pattern_type="prebuilt", pattern_name="credit_card", action=ContentFilterAction.MASK) + ], + ) + chunks: Final = ("4532 " * 20, "4532 0151 1283 0366 thanks") + + async def mock_stream(): + for index, content in enumerate(chunks): + yield ModelResponseStream( + id=f"chunk{index}", + choices=[ + StreamingChoices( + delta=Delta(content=content), + index=0, + finish_reason="stop" if index == len(chunks) - 1 else None, + ) + ], + model="gpt-4", + ) + + streamed: Final = "".join( + [ + chunk.choices[0].delta.content or "" + async for chunk in guardrail.async_post_call_streaming_iterator_hook( + user_api_key_dict=MagicMock(), response=mock_stream(), request_data={} + ) + ] + ) + whole_response: Final = await guardrail.apply_guardrail( + inputs={"texts": ["".join(chunks)]}, request_data={}, input_type="response" + ) + + assert "0366" not in streamed + assert [streamed] == whole_response.get("texts") + @pytest.mark.asyncio @pytest.mark.parametrize( "iban", From 56c00af0c4733fd82c49d6567a79885c11a4a5d7 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 12:09:39 -0700 Subject: [PATCH 5/9] fix(guardrails): check an IBAN's registry length before its suffix and memoize checksums per stream --- litellm/constants.py | 1 + .../litellm_content_filter/content_filter.py | 40 ++++-- .../litellm_content_filter/validators.py | 121 +++++++++++++++++- .../content_filter/test_content_filter.py | 28 +++- .../litellm_content_filter/test_validators.py | 2 + 5 files changed, 180 insertions(+), 12 deletions(-) diff --git a/litellm/constants.py b/litellm/constants.py index 0d6dfb5c0d4..420ce599737 100644 --- a/litellm/constants.py +++ b/litellm/constants.py @@ -495,6 +495,7 @@ GUARDRAIL_SCANNED_MESSAGES_CACHE_TTL_SECONDS: Final = get_env_int( BEDROCK_APPLY_GUARDRAIL_CHUNK_BUDGET_CHARS: Final = 25_000 CONTENT_FILTER_STREAMING_HOLDBACK_CHARS: Final = 50 CONTENT_FILTER_STREAMING_SCAN_CONTEXT_CHARS: Final = 512 +CONTENT_FILTER_STREAMING_CHECKSUM_CACHE_SIZE: Final = 1024 DEFAULT_PRESIDIO_ANALYZE_CHUNK_SIZE_BYTES: Final = 500_000 PRESIDIO_ANALYZE_CHUNK_OVERLAP_CHARS: Final = 4096 PRESIDIO_ANALYZE_CHUNK_CONCURRENCY: Final = 8 diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py index 7178494075d..bd3b78c959e 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py @@ -7,6 +7,7 @@ to detect and block/mask sensitive content. import asyncio import contextvars +import functools import itertools import json import os @@ -27,6 +28,7 @@ from typing_extensions import ReadOnly from litellm import Router from litellm._logging import verbose_proxy_logger from litellm.constants import ( + CONTENT_FILTER_STREAMING_CHECKSUM_CACHE_SIZE, CONTENT_FILTER_STREAMING_HOLDBACK_CHARS, CONTENT_FILTER_STREAMING_SCAN_CONTEXT_CHARS, DEFAULT_MAX_RECURSE_DEPTH, @@ -77,7 +79,7 @@ from .competitor_intent import ( BaseCompetitorIntentChecker, ) from .patterns import PATTERN_EXTRA_CONFIG, get_compiled_pattern -from .validators import PATTERN_VALIDATORS +from .validators import PATTERN_VALIDATORS, CandidateCheck, run_validator MAX_KEYWORD_VALUE_GAP_WORDS: Final = 1 _DECODED_ARGUMENTS: Final = TypeAdapter(object) @@ -840,7 +842,12 @@ class ContentFilterGuardrail(CustomGuardrail): except Exception as e: raise Exception(f"Error loading blocked words file {file_path}: {e}") - def _find_pattern_spans(self, text: str, pattern_entry: CompiledPatternEntry) -> list[tuple[int, int]]: + def _find_pattern_spans( + self, + text: str, + pattern_entry: CompiledPatternEntry, + check_candidate: CandidateCheck = run_validator, + ) -> list[tuple[int, int]]: """Return all match spans for a pattern, applying contextual rules if required.""" regex: Final[Pattern[str]] = pattern_entry["regex"] @@ -854,7 +861,7 @@ class ContentFilterGuardrail(CustomGuardrail): match_spans: Final[list[tuple[int, int]]] = [] candidate_spans: Final = ( - self._checksum_valid_spans(regex, text, validator) + self._checksum_valid_spans(regex, text, validator, check_candidate) if validator is not None else ((match.start(), match.end()) for match in regex.finditer(text)) ) @@ -880,13 +887,19 @@ class ContentFilterGuardrail(CustomGuardrail): return self._merge_spans(match_spans) def _checksum_valid_spans( - self, regex: Pattern[str], text: str, validator: Callable[[str], bool] + self, + regex: Pattern[str], + text: str, + validator: Callable[[str], bool], + check_candidate: CandidateCheck, ) -> tuple[tuple[int, int], ...]: if regex.search(text) is None: return () overlapping_regex: Final = re.compile(f"(?=({regex.pattern}))", regex.flags) candidate_spans: Final = tuple(candidate.span(1) for candidate in overlapping_regex.finditer(text)) - valid_spans: Final = tuple(span for span in candidate_spans if validator(text[span[0] : span[1]])) + valid_spans: Final = tuple( + span for span in candidate_spans if check_candidate(validator, text[span[0] : span[1]]) + ) if not valid_spans: return () valid_starts: Final = tuple(start for start, _ in valid_spans) @@ -1431,7 +1444,12 @@ class ContentFilterGuardrail(CustomGuardrail): return text - def _filter_single_text(self, text: str, detections: list[ContentFilterDetection] | None = None) -> str: + def _filter_single_text( + self, + text: str, + detections: list[ContentFilterDetection] | None = None, + check_candidate: CandidateCheck = run_validator, + ) -> str: """ Apply all content filtering checks to a single text. @@ -1443,6 +1461,7 @@ class ContentFilterGuardrail(CustomGuardrail): Args: text: Text to filter detections: Optional list to append detection information + check_candidate: Runs a pattern's checksum validator on a candidate match Returns: Filtered text (with masking applied if action is MASK) @@ -1475,7 +1494,7 @@ class ContentFilterGuardrail(CustomGuardrail): # Check regex patterns - process ALL patterns, not just first match for pattern_entry in self.compiled_patterns: - spans = self._find_pattern_spans(text, pattern_entry) + spans = self._find_pattern_spans(text, pattern_entry, check_candidate) if spans: pattern_name = pattern_entry["pattern_name"] action = pattern_entry["action"] @@ -2130,6 +2149,9 @@ class ContentFilterGuardrail(CustomGuardrail): """ state_by_choice: Final[dict[int, _StreamedChoiceState]] = {} plan: Final = self._streamed_scan_plan() + check_candidate: Final = functools.lru_cache(maxsize=CONTENT_FILTER_STREAMING_CHECKSUM_CACHE_SIZE)( + run_validator + ) start_time: Final = datetime.now() scan_seconds: float = 0.0 # rebind-ok: accumulates per-chunk scan time across the stream @@ -2170,7 +2192,9 @@ class ContentFilterGuardrail(CustomGuardrail): scan_started = time.perf_counter() try: - masked_text = self._filter_single_text(text_to_scan, detections=choice_detections) + masked_text = self._filter_single_text( + text_to_scan, detections=choice_detections, check_candidate=check_candidate + ) if is_final and masked_text.endswith(" "): masked_text = masked_text[:-1] latest_detections = tuple(choice_detections) diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py index 125e426815c..7ab3e194371 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py @@ -1,11 +1,120 @@ import re from collections.abc import Callable, Mapping from types import MappingProxyType -from typing import Final +from typing import Final, TypeAlias _SEPARATORS: Final = re.compile(r"[\s\-]") _IBAN_CHARACTERS: Final = re.compile(r"[0-9A-Z]{5,34}") _IGNORECASE_ASCII_LETTER_ALIASES: Final = str.maketrans({"\u0130": "I", "\u212a": "K"}) +_ISO_13616_IBAN_LENGTHS: Final[Mapping[str, int]] = MappingProxyType( + { + "AD": 24, + "AE": 23, + "AL": 28, + "AT": 20, + "AX": 18, + "AZ": 28, + "BA": 20, + "BE": 16, + "BG": 22, + "BH": 22, + "BI": 27, + "BL": 27, + "BR": 29, + "BY": 28, + "CH": 21, + "CR": 22, + "CY": 28, + "CZ": 24, + "DE": 22, + "DJ": 27, + "DK": 18, + "DO": 28, + "EE": 20, + "EG": 29, + "ES": 24, + "FI": 18, + "FK": 18, + "FO": 18, + "FR": 27, + "GB": 22, + "GE": 22, + "GF": 27, + "GG": 22, + "GI": 23, + "GL": 18, + "GP": 27, + "GR": 27, + "GT": 28, + "HN": 28, + "HR": 21, + "HU": 28, + "IE": 22, + "IL": 23, + "IM": 22, + "IQ": 23, + "IS": 26, + "IT": 27, + "JE": 22, + "JO": 30, + "KW": 30, + "KZ": 20, + "LB": 28, + "LC": 32, + "LI": 21, + "LT": 20, + "LU": 20, + "LV": 21, + "LY": 25, + "MC": 27, + "MD": 24, + "ME": 22, + "MF": 27, + "MK": 19, + "MN": 20, + "MQ": 27, + "MR": 27, + "MT": 31, + "MU": 30, + "NC": 27, + "NI": 28, + "NL": 18, + "NO": 15, + "OM": 23, + "PF": 27, + "PK": 24, + "PL": 28, + "PM": 27, + "PS": 29, + "PT": 25, + "QA": 29, + "RE": 27, + "RO": 24, + "RS": 22, + "RU": 33, + "SA": 24, + "SC": 31, + "SD": 18, + "SE": 24, + "SI": 19, + "SK": 24, + "SM": 27, + "SO": 23, + "ST": 25, + "SV": 28, + "TF": 27, + "TL": 23, + "TN": 24, + "TR": 26, + "UA": 29, + "VA": 22, + "VG": 24, + "WF": 27, + "XK": 20, + "YE": 30, + "YT": 27, + } +) _DIGIT_VALUES: Final = bytes.maketrans(b"0123456789", bytes(range(10))) _DOUBLED_DIGIT_SUMS: Final = bytes.maketrans(b"0123456789", bytes((0, 2, 4, 6, 8, 1, 3, 5, 7, 9))) @@ -29,13 +138,21 @@ def passes_luhn(value: str) -> bool: def passes_iban_mod97(value: str) -> bool: - iban: Final = _to_ascii(_SEPARATORS.sub("", value)).upper() + compact: Final = _to_ascii(_SEPARATORS.sub("", value)).upper() + iban: Final = compact[: _ISO_13616_IBAN_LENGTHS.get(compact[:2], len(compact))] if _IBAN_CHARACTERS.fullmatch(iban) is None: return False rearranged: Final = iban[4:] + iban[:4] return int("".join(str(int(character, 36)) for character in rearranged)) % 97 == 1 +CandidateCheck: TypeAlias = Callable[[Callable[[str], bool], str], bool] + + +def run_validator(validator: Callable[[str], bool], candidate: str) -> bool: + return validator(candidate) + + PATTERN_VALIDATORS: Final[Mapping[str, Callable[[str], bool]]] = MappingProxyType( {"luhn": passes_luhn, "iban_mod97": passes_iban_mod97} ) diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py index 6f69bb25185..00ea00eb363 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py @@ -20,6 +20,10 @@ from litellm.constants import ( from litellm.proxy.guardrails.guardrail_hooks.litellm_content_filter.content_filter import ( ContentFilterGuardrail, ) +from litellm.proxy.guardrails.guardrail_hooks.litellm_content_filter.validators import ( + CandidateCheck, + run_validator, +) from litellm.types.guardrails import ( BlockedWord, ContentFilterAction, @@ -494,6 +498,24 @@ class TestContentFilterGuardrail: assert guardrailed_inputs.get("texts") == ["send it to [IBAN_REDACTED]"] + @pytest.mark.asyncio + @pytest.mark.parametrize("pattern_name", ["iban", "eu_iban_enhanced"]) + async def test_checksum_pattern_masks_a_valid_iban_with_characters_attached_to_its_end(self, pattern_name: str): + guardrail: Final = ContentFilterGuardrail( + guardrail_name="test-checksum-attached", + patterns=[ + ContentFilterPattern(pattern_type="prebuilt", pattern_name=pattern_name, action=ContentFilterAction.MASK) + ], + ) + + guardrailed_inputs: Final = await guardrail.apply_guardrail( + inputs={"texts": ["pay DE89370400440532013000EUR or DE88370400440532013000EUR"]}, + request_data={}, + input_type="request", + ) + + assert guardrailed_inputs.get("texts") == [f"pay [{pattern_name.upper()}_REDACTED] or DE88370400440532013000EUR"] + def test_api_key_patterns(self): """ Test API key pattern detection @@ -1080,9 +1102,10 @@ class TestContentFilterGuardrail: self, text: str, detections: list[ContentFilterDetection] | None = None, + check_candidate: CandidateCheck = run_validator, ) -> str: scanned_lengths.append(len(text)) - return super()._filter_single_text(text, detections=detections) + return super()._filter_single_text(text, detections=detections, check_candidate=check_candidate) guardrail: Final = RecordingGuardrail( guardrail_name="test-streaming-bounded-scan", @@ -1122,9 +1145,10 @@ class TestContentFilterGuardrail: self, text: str, detections: list[ContentFilterDetection] | None = None, + check_candidate: CandidateCheck = run_validator, ) -> str: scanned_lengths.append(len(text)) - return super()._filter_single_text(text, detections=detections) + return super()._filter_single_text(text, detections=detections, check_candidate=check_candidate) guardrail: Final = RecordingGuardrail( guardrail_name="test-streaming-refused-cut-backoff", diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/litellm_content_filter/test_validators.py b/tests/unit/proxy/guardrails/guardrail_hooks/litellm_content_filter/test_validators.py index 0214777cd22..d2d6da2d722 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/litellm_content_filter/test_validators.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/litellm_content_filter/test_validators.py @@ -45,6 +45,8 @@ def test_passes_luhn_rejects_every_single_digit_change(valid_number: str): ("GB82WEST12345698765433", False), ("GB82", False), ("GB82WEST1234569876543é", False), + ("DE89370400440532013000EUR", True), + ("DE88370400440532013000EUR", False), ], ) def test_passes_iban_mod97(value: str, expected: bool): From 16743848cf7e0fd6856f5735ecd77bda3ec7a972 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 13:49:50 -0700 Subject: [PATCH 6/9] fix(guardrails): mask only the base matches that overlap a valid card and cache the lookahead regex --- .../litellm_content_filter/content_filter.py | 16 +++++++++++----- .../content_filter/test_content_filter.py | 6 ++++-- 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py index bd3b78c959e..eeea224077d 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py @@ -109,6 +109,12 @@ WORD_NUMBER_SEQUENCE_PATTERN: Final = re.compile( ) WORD_NUMBER_TOKEN_FINDER: Final = re.compile(rf"(?:{WORD_NUMBER_TOKEN_REGEX})", re.IGNORECASE) + +@functools.cache +def _overlapping_matches_regex(regex: Pattern[str]) -> Pattern[str]: + return re.compile(f"(?=({regex.pattern}))", regex.flags) + + _logging_only_scan_guardrail: Final[contextvars.ContextVar["ContentFilterGuardrail | None"]] = contextvars.ContextVar( "litellm_content_filter_logging_only_scan", default=None ) @@ -893,10 +899,10 @@ class ContentFilterGuardrail(CustomGuardrail): validator: Callable[[str], bool], check_candidate: CandidateCheck, ) -> tuple[tuple[int, int], ...]: - if regex.search(text) is None: + leftmost_spans: Final = tuple(match.span() for match in regex.finditer(text)) + if not leftmost_spans: return () - overlapping_regex: Final = re.compile(f"(?=({regex.pattern}))", regex.flags) - candidate_spans: Final = tuple(candidate.span(1) for candidate in overlapping_regex.finditer(text)) + candidate_spans: Final = (candidate.span(1) for candidate in _overlapping_matches_regex(regex).finditer(text)) valid_spans: Final = tuple( span for span in candidate_spans if check_candidate(validator, text[span[0] : span[1]]) ) @@ -904,8 +910,8 @@ class ContentFilterGuardrail(CustomGuardrail): return () valid_starts: Final = tuple(start for start, _ in valid_spans) furthest_valid_ends: Final = tuple(itertools.accumulate((end for _, end in valid_spans), max)) - return tuple( - span for span in candidate_spans if self._overlaps_a_valid_span(span, valid_starts, furthest_valid_ends) + return valid_spans + tuple( + span for span in leftmost_spans if self._overlaps_a_valid_span(span, valid_starts, furthest_valid_ends) ) @staticmethod diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py index 00ea00eb363..8ee0e3790ce 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py @@ -414,11 +414,13 @@ class TestContentFilterGuardrail: [ ("PIN 4821 4532 0151 1283 0366 thanks", "PIN [CREDIT_CARD_REDACTED] thanks"), ("order 4111 4532 0151 1283 0366", "order [CREDIT_CARD_REDACTED]"), - ("codes 4532 4532 4532 4532 4532 0151 1283 0366 thanks", "codes 4532 [CREDIT_CARD_REDACTED] thanks"), + ("codes 4532 4532 4532 4532 4532 0151 1283 0366 thanks", "codes 4532 4532 4532 4532 [CREDIT_CARD_REDACTED] thanks"), ("order 4532 1234 5678 9010 paid by 4532 0151 1283 0366", "order 4532 1234 5678 9010 paid by [CREDIT_CARD_REDACTED]"), + ("card 4532 4151 4283 4000 4777 4888 4999 ok", "card [CREDIT_CARD_REDACTED] 4777 4888 4999 ok"), + ("card 4532 4111 1111 1116 2025 ok", "card [CREDIT_CARD_REDACTED] 2025 ok"), ], ) - async def test_checksum_pattern_masks_a_valid_card_with_the_candidates_overlapping_it(self, text: str, expected: str): + async def test_checksum_pattern_masks_a_valid_card_with_the_base_matches_overlapping_it(self, text: str, expected: str): guardrail: Final = ContentFilterGuardrail( guardrail_name="test-checksum-overlap", patterns=[ From d28c8a629a009b1cbab8f638a707a4c86a983241 Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 16:09:43 -0700 Subject: [PATCH 7/9] fix(guardrails): mask other card brands' valid numbers that a card mask touches, and speed up mod-97 --- .../litellm_content_filter/content_filter.py | 56 +++++++++++++++---- .../litellm_content_filter/validators.py | 6 +- .../content_filter/test_content_filter.py | 27 +++++++++ 3 files changed, 77 insertions(+), 12 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py index eeea224077d..f6c8f2a65e4 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py @@ -853,7 +853,7 @@ class ContentFilterGuardrail(CustomGuardrail): text: str, pattern_entry: CompiledPatternEntry, check_candidate: CandidateCheck = run_validator, - ) -> list[tuple[int, int]]: + ) -> Sequence[tuple[int, int]]: """Return all match spans for a pattern, applying contextual rules if required.""" regex: Final[Pattern[str]] = pattern_entry["regex"] @@ -890,7 +890,42 @@ class ContentFilterGuardrail(CustomGuardrail): continue match_spans.append((word_match.start(), word_match.end())) - return self._merge_spans(match_spans) + merged_spans: Final = self._merge_spans(match_spans) + if validator is None or not merged_spans: + return merged_spans + return self._with_overlapping_checksum_matches(text, pattern_entry, merged_spans, check_candidate) + + def _with_overlapping_checksum_matches( + self, + text: str, + pattern_entry: CompiledPatternEntry, + spans: Sequence[tuple[int, int]], + check_candidate: CandidateCheck, + ) -> Sequence[tuple[int, int]]: + other_checksum_spans: Final = tuple( + itertools.chain.from_iterable( + self._entry_checksum_valid_spans(entry, text, check_candidate) + for entry in self.compiled_patterns + if entry is not pattern_entry + ) + ) + if not other_checksum_spans: + return spans + span_starts: Final = tuple(start for start, _ in spans) + span_ends: Final = tuple(end for _, end in spans) + return tuple( + component + for component in self._merge_spans([*spans, *other_checksum_spans]) + if self._overlaps_any_span(component, span_starts, span_ends) + ) + + def _entry_checksum_valid_spans( + self, entry: CompiledPatternEntry, text: str, check_candidate: CandidateCheck + ) -> tuple[tuple[int, int], ...]: + validator: Final = entry.get("validator") + if validator is None: + return () + return self._checksum_valid_spans(entry["regex"], text, validator, check_candidate) def _checksum_valid_spans( self, @@ -911,15 +946,13 @@ class ContentFilterGuardrail(CustomGuardrail): valid_starts: Final = tuple(start for start, _ in valid_spans) furthest_valid_ends: Final = tuple(itertools.accumulate((end for _, end in valid_spans), max)) return valid_spans + tuple( - span for span in leftmost_spans if self._overlaps_a_valid_span(span, valid_starts, furthest_valid_ends) + span for span in leftmost_spans if self._overlaps_any_span(span, valid_starts, furthest_valid_ends) ) @staticmethod - def _overlaps_a_valid_span( - span: tuple[int, int], sorted_valid_starts: Sequence[int], furthest_valid_ends: Sequence[int] - ) -> bool: - index: Final = bisect_left(sorted_valid_starts, span[1]) - return index > 0 and furthest_valid_ends[index - 1] > span[0] + def _overlaps_any_span(span: tuple[int, int], sorted_starts: Sequence[int], furthest_ends: Sequence[int]) -> bool: + index: Final = bisect_left(sorted_starts, span[1]) + return index > 0 and furthest_ends[index - 1] > span[0] def _match_near_keyword( self, @@ -973,7 +1006,7 @@ class ContentFilterGuardrail(CustomGuardrail): merged.append((start, end)) return merged - def _mask_spans(self, text: str, spans: list[tuple[int, int]], redaction: str) -> str: + def _mask_spans(self, text: str, spans: Sequence[tuple[int, int]], redaction: str) -> str: """Apply masking for the provided spans using the given redaction tag.""" if not spans: @@ -1379,7 +1412,7 @@ class ContentFilterGuardrail(CustomGuardrail): pattern_name: str, action: ContentFilterAction, text: str, - spans: list[tuple[int, int]], + spans: Sequence[tuple[int, int]], detections: list[ContentFilterDetection] | None, ) -> str: """Handle regex pattern match detection and action.""" @@ -1499,8 +1532,9 @@ class ContentFilterGuardrail(CustomGuardrail): text = self._handle_category_keyword_match(keyword, category_name, severity, action, text, detections) # Check regex patterns - process ALL patterns, not just first match + memoized_check: Final = functools.cache(check_candidate) for pattern_entry in self.compiled_patterns: - spans = self._find_pattern_spans(text, pattern_entry, check_candidate) + spans = self._find_pattern_spans(text, pattern_entry, memoized_check) if spans: pattern_name = pattern_entry["pattern_name"] action = pattern_entry["action"] diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py index 7ab3e194371..2af21d377f8 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/validators.py @@ -1,4 +1,5 @@ import re +import string from collections.abc import Callable, Mapping from types import MappingProxyType from typing import Final, TypeAlias @@ -115,6 +116,9 @@ _ISO_13616_IBAN_LENGTHS: Final[Mapping[str, int]] = MappingProxyType( "YT": 27, } ) +_IBAN_LETTER_VALUES: Final = str.maketrans( + {letter: str(value) for value, letter in enumerate(string.ascii_uppercase, 10)} +) _DIGIT_VALUES: Final = bytes.maketrans(b"0123456789", bytes(range(10))) _DOUBLED_DIGIT_SUMS: Final = bytes.maketrans(b"0123456789", bytes((0, 2, 4, 6, 8, 1, 3, 5, 7, 9))) @@ -143,7 +147,7 @@ def passes_iban_mod97(value: str) -> bool: if _IBAN_CHARACTERS.fullmatch(iban) is None: return False rearranged: Final = iban[4:] + iban[:4] - return int("".join(str(int(character, 36)) for character in rearranged)) % 97 == 1 + return int(rearranged.translate(_IBAN_LETTER_VALUES)) % 97 == 1 CandidateCheck: TypeAlias = Callable[[Callable[[str], bool], str], bool] diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py index 8ee0e3790ce..05f6b6d637f 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py @@ -436,6 +436,33 @@ class TestContentFilterGuardrail: assert guardrailed_inputs.get("texts") == [expected] + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("text", "expected"), + [ + ("ids 4853 4091 4909 4475 5508 5016 6232 6258 end", "ids [VISA_REDACTED] end"), + ("ids 4336 4262 4755 4637 3753 786027 13221 end", "ids [VISA_REDACTED] end"), + ("4000 4000 0000 0000\n5555 5555 5555 4444", "[VISA_REDACTED]"), + ("cards 4532 0151 1283 0366 5555 5555 5555 4444 ok", "cards [VISA_REDACTED] [MASTERCARD_REDACTED] ok"), + ], + ) + async def test_checksum_pattern_masks_the_valid_cards_of_later_patterns_it_overlaps(self, text: str, expected: str): + guardrail: Final = ContentFilterGuardrail( + guardrail_name="test-checksum-cross-pattern", + patterns=[ + ContentFilterPattern(pattern_type="prebuilt", pattern_name=pattern_name, action=ContentFilterAction.MASK) + for pattern_name in ("visa", "mastercard", "amex", "discover", "credit_card", "iban") + ], + ) + + guardrailed_inputs: Final = await guardrail.apply_guardrail( + inputs={"texts": [text]}, + request_data={}, + input_type="request", + ) + + assert guardrailed_inputs.get("texts") == [expected] + @pytest.mark.asyncio async def test_checksum_pattern_streams_the_same_text_as_a_whole_response(self): from litellm.types.utils import Delta, ModelResponseStream, StreamingChoices From bdec96442b2adc4c98b8037d6d5279be560e279e Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 19:40:07 -0700 Subject: [PATCH 8/9] fix(guardrails): keep base masking where a checksum mask meets a later pattern's match A MASK checksum pattern now merges only with later patterns' matches, skips that step for BLOCK patterns, and falls back to its own matches where a merged region would cut a later masking match or cover a later blocking match. A later BLOCK pattern keeps seeing its card, and two overlapping brands keep their own tags. --- .../litellm_content_filter/content_filter.py | 97 +++++++++++++++---- .../content_filter/test_content_filter.py | 54 ++++++++++- 2 files changed, 129 insertions(+), 22 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py index f6c8f2a65e4..d2c3ad4c322 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py @@ -13,8 +13,8 @@ import json import os import re import time -from bisect import bisect_left -from collections.abc import AsyncGenerator, Callable, Coroutine, Mapping, Sequence +from bisect import bisect_left, bisect_right +from collections.abc import AsyncGenerator, Callable, Coroutine, Iterable, Iterator, Mapping, Sequence from dataclasses import dataclass, replace from datetime import datetime from re import Pattern @@ -161,6 +161,12 @@ class _StreamedChoiceState: next_trim_len: int = 0 +@dataclass(frozen=True, slots=True) +class _SpanIndex: + spans: tuple[tuple[int, int], ...] + furthest_ends: tuple[int, ...] + + @dataclass(frozen=True, slots=True) class _StreamedScanPlan: context_chars: int @@ -902,31 +908,86 @@ class ContentFilterGuardrail(CustomGuardrail): spans: Sequence[tuple[int, int]], check_candidate: CandidateCheck, ) -> Sequence[tuple[int, int]]: - other_checksum_spans: Final = tuple( + if pattern_entry["action"] == ContentFilterAction.BLOCK: + return spans + position: Final = next(index for index, entry in enumerate(self.compiled_patterns) if entry is pattern_entry) + later_entries: Final = self.compiled_patterns[position + 1 :] + masking: Final = self._span_index( + text, (entry for entry in later_entries if entry["action"] != ContentFilterAction.BLOCK), check_candidate + ) + blocking: Final = self._span_index( + text, (entry for entry in later_entries if entry["action"] == ContentFilterAction.BLOCK), check_candidate + ) + if not masking.spans and not blocking.spans: + return spans + leftmost_spans: Final = tuple(match.span() for match in pattern_entry["regex"].finditer(text)) + union_regions: Final = tuple(self._merge_spans([*spans, *masking.spans])) + resolved: Final = self._merge_spans( + [ + *itertools.chain.from_iterable( + self._resolve_component(component, leftmost_spans, masking, union_regions) for component in spans + ) + ] + ) + return tuple( itertools.chain.from_iterable( - self._entry_checksum_valid_spans(entry, text, check_candidate) - for entry in self.compiled_patterns - if entry is not pattern_entry + self._spans_overlapping(leftmost_spans, region) + if any(self._spans_reaching(region, blocking)) + else (region,) + for region in resolved ) ) - if not other_checksum_spans: - return spans - span_starts: Final = tuple(start for start, _ in spans) - span_ends: Final = tuple(end for _, end in spans) - return tuple( - component - for component in self._merge_spans([*spans, *other_checksum_spans]) - if self._overlaps_any_span(component, span_starts, span_ends) - ) - def _entry_checksum_valid_spans( + def _resolve_component( + self, + component: tuple[int, int], + leftmost_spans: Sequence[tuple[int, int]], + masking: _SpanIndex, + union_regions: Sequence[tuple[int, int]], + ) -> Sequence[tuple[int, int]]: + sticking_out: Final = tuple( + span + for span in self._spans_reaching(component, masking) + if span[0] < component[0] or span[1] > component[1] + ) + if not sticking_out: + return (component,) + leftmost_in_component: Final = self._spans_overlapping(leftmost_spans, component) + if not any(self._spans_overlapping(leftmost_in_component, span) for span in sticking_out): + return leftmost_in_component + return (union_regions[bisect_right(union_regions, component[0], key=lambda region: region[0]) - 1],) + + def _span_index( + self, text: str, entries: Iterable[CompiledPatternEntry], check_candidate: CandidateCheck + ) -> _SpanIndex: + spans: Final = tuple( + sorted(itertools.chain.from_iterable(self._entry_spans(entry, text, check_candidate) for entry in entries)) + ) + return _SpanIndex(spans=spans, furthest_ends=tuple(itertools.accumulate((end for _, end in spans), max))) + + def _entry_spans( self, entry: CompiledPatternEntry, text: str, check_candidate: CandidateCheck - ) -> tuple[tuple[int, int], ...]: + ) -> Sequence[tuple[int, int]]: validator: Final = entry.get("validator") if validator is None: - return () + return self._find_pattern_spans(text, entry, check_candidate) return self._checksum_valid_spans(entry["regex"], text, validator, check_candidate) + @staticmethod + def _spans_reaching(component: tuple[int, int], index: _SpanIndex) -> Iterator[tuple[int, int]]: + later_position: Final = bisect_left(index.spans, (component[1],)) + positions_reaching_start: Final = itertools.takewhile( + lambda position: index.furthest_ends[position] > component[0], range(later_position - 1, -1, -1) + ) + return ( + index.spans[position] for position in positions_reaching_start if index.spans[position][1] > component[0] + ) + + @staticmethod + def _spans_overlapping(spans: Sequence[tuple[int, int]], component: tuple[int, int]) -> Sequence[tuple[int, int]]: + first: Final = bisect_right(spans, component[0], key=lambda span: span[1]) + return spans[first : bisect_left(spans, component[1], lo=first, key=lambda span: span[0])] + def _checksum_valid_spans( self, regex: Pattern[str], diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py index 05f6b6d637f..531dd5d3715 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py @@ -440,13 +440,15 @@ class TestContentFilterGuardrail: @pytest.mark.parametrize( ("text", "expected"), [ - ("ids 4853 4091 4909 4475 5508 5016 6232 6258 end", "ids [VISA_REDACTED] end"), - ("ids 4336 4262 4755 4637 3753 786027 13221 end", "ids [VISA_REDACTED] end"), - ("4000 4000 0000 0000\n5555 5555 5555 4444", "[VISA_REDACTED]"), + ("ids 4853 4091 4909 4475 5508 5016 6232 6258 end", "ids [VISA_REDACTED] [MASTERCARD_REDACTED] end"), + ("ids 4336 4262 4755 4637 3753 786027 13221 end", "ids [VISA_REDACTED] [AMEX_REDACTED] end"), + ("4000 4000 0000 0000\n5555 5555 5555 4444", "[VISA_REDACTED]\n[MASTERCARD_REDACTED]"), + ("cards 4378 4937 4618 4485 5555 5555 5555 4444 ok", "cards [VISA_REDACTED] [MASTERCARD_REDACTED] ok"), + ("pay 5472 3038 5280 1841 1485 4534 3853 6336 1330 ok", "pay [VISA_REDACTED] ok"), ("cards 4532 0151 1283 0366 5555 5555 5555 4444 ok", "cards [VISA_REDACTED] [MASTERCARD_REDACTED] ok"), ], ) - async def test_checksum_pattern_masks_the_valid_cards_of_later_patterns_it_overlaps(self, text: str, expected: str): + async def test_checksum_patterns_mask_each_valid_card_where_two_brands_overlap(self, text: str, expected: str): guardrail: Final = ContentFilterGuardrail( guardrail_name="test-checksum-cross-pattern", patterns=[ @@ -463,6 +465,50 @@ class TestContentFilterGuardrail: assert guardrailed_inputs.get("texts") == [expected] + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("masking_pattern", "blocking_pattern", "text"), + [ + ("visa", "mastercard", "4004 5555 5555 5557 5555 5555 5555 4444"), + ("visa", "mastercard", "4000 4000 0000 0000 5555 5555 5555 4444"), + ("visa", "mastercard", "ids 4853 4091 4909 4475 5508 5016 6232 6258 end"), + ("discover", "credit_card", "4629 4611-6260-8050-5592-2700 65405563 93269332"), + ], + ) + async def test_checksum_mask_leaves_a_later_blocking_pattern_its_valid_card( + self, masking_pattern: str, blocking_pattern: str, text: str + ): + guardrail: Final = ContentFilterGuardrail( + guardrail_name="test-checksum-mask-then-block", + patterns=[ + ContentFilterPattern( + pattern_type="prebuilt", pattern_name=masking_pattern, action=ContentFilterAction.MASK + ), + ContentFilterPattern( + pattern_type="prebuilt", pattern_name=blocking_pattern, action=ContentFilterAction.BLOCK + ), + ], + ) + with pytest.raises(HTTPException) as exc_info: + await guardrail.apply_guardrail(inputs={"texts": [text]}, request_data={}, input_type="request") + assert exc_info.value.detail["pattern"] == blocking_pattern + + @pytest.mark.asyncio + async def test_checksum_mask_before_a_blocking_pattern_still_masks_the_card_both_match(self): + guardrail: Final = ContentFilterGuardrail( + guardrail_name="test-checksum-mask-before-block", + patterns=[ + ContentFilterPattern( + pattern_type="prebuilt", pattern_name="credit_card", action=ContentFilterAction.MASK + ), + ContentFilterPattern(pattern_type="prebuilt", pattern_name="visa", action=ContentFilterAction.BLOCK), + ], + ) + guardrailed_inputs: Final = await guardrail.apply_guardrail( + inputs={"texts": ["card 4111 1111 1111 1111 ok"]}, request_data={}, input_type="request" + ) + assert guardrailed_inputs.get("texts") == ["card [CREDIT_CARD_REDACTED] ok"] + @pytest.mark.asyncio async def test_checksum_pattern_streams_the_same_text_as_a_whole_response(self): from litellm.types.utils import Delta, ModelResponseStream, StreamingChoices From c4ea04e4b8b7b37d8edebc1be6c78632a2a1083a Mon Sep 17 00:00:00 2001 From: mateo-berri <277851410+mateo-berri@users.noreply.github.com> Date: Wed, 28 Oct 2026 20:36:23 -0700 Subject: [PATCH 9/9] fix(guardrails): keep a later rule's keyword when a checksum mask meets its match --- .../litellm_content_filter/content_filter.py | 47 ++++++++++----- .../content_filter/test_content_filter.py | 57 +++++++++++++++++++ 2 files changed, 89 insertions(+), 15 deletions(-) diff --git a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py index d2c3ad4c322..120650c69e5 100644 --- a/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py +++ b/litellm/proxy/guardrails/guardrail_hooks/litellm_content_filter/content_filter.py @@ -912,20 +912,27 @@ class ContentFilterGuardrail(CustomGuardrail): return spans position: Final = next(index for index, entry in enumerate(self.compiled_patterns) if entry is pattern_entry) later_entries: Final = self.compiled_patterns[position + 1 :] - masking: Final = self._span_index( - text, (entry for entry in later_entries if entry["action"] != ContentFilterAction.BLOCK), check_candidate + later_masking_entries: Final = tuple( + entry for entry in later_entries if entry["action"] != ContentFilterAction.BLOCK + ) + checksum_masking: Final = self._span_index( + text, (entry for entry in later_masking_entries if entry.get("validator") is not None), check_candidate + ) + other_masking: Final = self._span_index( + text, (entry for entry in later_masking_entries if entry.get("validator") is None), check_candidate ) blocking: Final = self._span_index( text, (entry for entry in later_entries if entry["action"] == ContentFilterAction.BLOCK), check_candidate ) - if not masking.spans and not blocking.spans: + if not checksum_masking.spans and not other_masking.spans and not blocking.spans: return spans leftmost_spans: Final = tuple(match.span() for match in pattern_entry["regex"].finditer(text)) - union_regions: Final = tuple(self._merge_spans([*spans, *masking.spans])) + union_regions: Final = tuple(self._merge_spans([*spans, *checksum_masking.spans])) resolved: Final = self._merge_spans( [ *itertools.chain.from_iterable( - self._resolve_component(component, leftmost_spans, masking, union_regions) for component in spans + self._resolve_component(component, leftmost_spans, checksum_masking, other_masking, union_regions) + for component in spans ) ] ) @@ -942,20 +949,30 @@ class ContentFilterGuardrail(CustomGuardrail): self, component: tuple[int, int], leftmost_spans: Sequence[tuple[int, int]], - masking: _SpanIndex, + checksum_masking: _SpanIndex, + other_masking: _SpanIndex, union_regions: Sequence[tuple[int, int]], ) -> Sequence[tuple[int, int]]: - sticking_out: Final = tuple( - span - for span in self._spans_reaching(component, masking) - if span[0] < component[0] or span[1] > component[1] - ) - if not sticking_out: - return (component,) leftmost_in_component: Final = self._spans_overlapping(leftmost_spans, component) - if not any(self._spans_overlapping(leftmost_in_component, span) for span in sticking_out): + sticking_out: Final = tuple(self._spans_sticking_out(component, checksum_masking)) + if sticking_out and not any(self._spans_overlapping(leftmost_in_component, span) for span in sticking_out): return leftmost_in_component - return (union_regions[bisect_right(union_regions, component[0], key=lambda region: region[0]) - 1],) + region: Final = ( + union_regions[bisect_right(union_regions, component[0], key=lambda region: region[0]) - 1] + if sticking_out + else component + ) + leftmost_in_region: Final = self._spans_overlapping(leftmost_spans, region) + if any( + not self._spans_overlapping(leftmost_in_region, span) + for span in self._spans_sticking_out(region, other_masking) + ): + return leftmost_in_component + return (region,) + + @classmethod + def _spans_sticking_out(cls, region: tuple[int, int], index: _SpanIndex) -> Iterator[tuple[int, int]]: + return (span for span in cls._spans_reaching(region, index) if span[0] < region[0] or span[1] > region[1]) def _span_index( self, text: str, entries: Iterable[CompiledPatternEntry], check_candidate: CandidateCheck diff --git a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py index 531dd5d3715..7d09087bc4f 100644 --- a/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py +++ b/tests/unit/proxy/guardrails/guardrail_hooks/content_filter/test_content_filter.py @@ -509,6 +509,63 @@ class TestContentFilterGuardrail: ) assert guardrailed_inputs.get("texts") == ["card [CREDIT_CARD_REDACTED] ok"] + @pytest.mark.asyncio + @pytest.mark.parametrize( + ("checksum_patterns", "regex", "later_patterns", "text", "expected"), + [ + ( + ("credit_card",), + "1111 BSN", + ("nl_bsn_contextual",), + "4111 1111 1111 1111 BSN 123456789", + "[CREDIT_CARD_REDACTED] BSN [NL_BSN_CONTEXTUAL_REDACTED]", + ), + ( + ("visa", "mastercard"), + "4444 BSN", + ("nl_bsn_contextual",), + "4532 0151 1283 0366 5555 5555 5555 4444 BSN 123456789", + "[VISA_REDACTED] [MASTERCARD_REDACTED] BSN [NL_BSN_CONTEXTUAL_REDACTED]", + ), + ( + ("visa", "mastercard", "amex", "discover", "credit_card", "iban"), + "1330 BSN", + ("nl_bsn_contextual",), + "pay 5472 3038 5280 1841 1485 4534 3853 6336 1330 BSN 123456789", + "pay [VISA_REDACTED] BSN [NL_BSN_CONTEXTUAL_REDACTED]", + ), + (("credit_card",), "PIN 4821", (), "PIN 4821 4532 0151 1283 0366 ok", "PIN [CREDIT_CARD_REDACTED] ok"), + ], + ) + async def test_checksum_mask_keeps_the_words_a_later_regex_match_shares_with_the_card( + self, + checksum_patterns: tuple[str, ...], + regex: str, + later_patterns: tuple[str, ...], + text: str, + expected: str, + ): + guardrail: Final = ContentFilterGuardrail( + guardrail_name="test-checksum-mask-then-regex", + patterns=[ + *( + ContentFilterPattern(pattern_type="prebuilt", pattern_name=name, action=ContentFilterAction.MASK) + for name in checksum_patterns + ), + ContentFilterPattern( + pattern_type="regex", pattern=regex, name="account_note", action=ContentFilterAction.MASK + ), + *( + ContentFilterPattern(pattern_type="prebuilt", pattern_name=name, action=ContentFilterAction.MASK) + for name in later_patterns + ), + ], + ) + guardrailed_inputs: Final = await guardrail.apply_guardrail( + inputs={"texts": [text]}, request_data={}, input_type="request" + ) + assert guardrailed_inputs.get("texts") == [expected] + @pytest.mark.asyncio async def test_checksum_pattern_streams_the_same_text_as_a_whole_response(self): from litellm.types.utils import Delta, ModelResponseStream, StreamingChoices