diff --git a/python/fi_instrumentation/instrumentation/config.py b/python/fi_instrumentation/instrumentation/config.py index 2e37f5279..0fcbb532a 100644 --- a/python/fi_instrumentation/instrumentation/config.py +++ b/python/fi_instrumentation/instrumentation/config.py @@ -22,7 +22,7 @@ from ._chat_input import ChatInput, mask_chat_input from ._errors import is_error_detail_key from .logging import logger -from .pii_redaction import redact_pii_in_value +from .pii_redaction import key_carries_free_text, redact_pii_in_value class suppress_tracing: @@ -467,7 +467,14 @@ def mask( ): return None resolved = value() if callable(value) else value - if self.pii_redaction and resolved is not None: + if ( + self.pii_redaction + and resolved is not None + # Only free-text attributes get scanned — identifiers like + # session.id/user.id/metadata are structured values where a + # regex hit corrupts correlation, not a secret (#195). + and key_carries_free_text(key) + ): resolved = redact_pii_in_value(resolved) return resolved diff --git a/python/fi_instrumentation/instrumentation/pii_redaction.py b/python/fi_instrumentation/instrumentation/pii_redaction.py index 6d8c782e5..b250fc652 100644 --- a/python/fi_instrumentation/instrumentation/pii_redaction.py +++ b/python/fi_instrumentation/instrumentation/pii_redaction.py @@ -8,6 +8,15 @@ import re from typing import Any +from fi_instrumentation.fi_types import ( + DocumentAttributes, + MessageAttributes, + MessageContentAttributes, + RerankerAttributes, + SpanAttributes, + ToolCallAttributes, +) + # --------------------------------------------------------------------------- # Quick-check: a single regex that matches if the string *might* contain PII. # If it doesn't match, we skip all 6 pattern scans entirely. @@ -32,12 +41,19 @@ r"\b\d{3}[\-\.\s]\d{2}[\-\.\s]\d{4}\b" ) -_CREDIT_CARD_RE = re.compile( +# Credit cards are handled separately from the simple sub() loop: a bare +# 13-19 digit run is only a *candidate* — it must also look grouped like a +# card and pass Luhn before it is redacted. UUIDs, timestamps, request ids +# and other incidental digit runs are not card-shaped (#195). +_CREDIT_CARD_CANDIDATE_RE = re.compile( r"\b(?:\d[ \-]*?){13,19}\b" ) +# Leading \b is load-bearing: without it the pattern matches the last +# 10-11 digits inside a longer run (timestamps, request ids), mangling +# numeric content the card check already cleared (#195). _PHONE_RE = re.compile( - r"(?:\+?1[\s\-\.]?)?\(?\d{3}\)?[\s\-\.]?\d{3}[\s\-\.]?\d{4}\b" + r"\b(?:\+?1[\s\-\.]?)?\(?\d{3}\)?[\s\-\.]?\d{3}[\s\-\.]?\d{4}\b" ) _IP_RE = re.compile( @@ -49,21 +65,106 @@ ) # Ordered: most specific → least specific to avoid partial overlaps. -_PII_PATTERNS: list[tuple[re.Pattern[str], str]] = [ +# The card check must run between SSN and API-key/phone: the phone pattern +# would otherwise claim the leading digits of a card-shaped run first. +_PII_PATTERNS_BEFORE_CARD: list[tuple[re.Pattern[str], str]] = [ (_EMAIL_RE, ""), (_SSN_RE, ""), - (_CREDIT_CARD_RE, ""), +] +_PII_PATTERNS_AFTER_CARD: list[tuple[re.Pattern[str], str]] = [ (_API_KEY_RE, ""), (_IP_RE, ""), (_PHONE_RE, ""), ] +def _luhn_ok(digits: str) -> bool: + """Standard Luhn checksum over a string of ASCII digits.""" + total = 0 + for i, ch in enumerate(reversed(digits)): + d = ord(ch) - 48 + if i % 2 == 1: + d *= 2 + if d > 9: + d -= 9 + total += d + return total % 10 == 0 + + +def _is_card_like(candidate: str) -> bool: + """Whether a digit-run candidate is shaped like a real card number. + + A match must carry 13-19 digits and either be contiguous or use + card-style grouping — groups of 4-6 digits separated by single + spaces or dashes (Visa 4-4-4-4, Amex 4-6-5, Diners 4-6-4). The digit + string must then pass the Luhn checksum every issuer applies. + """ + digits = "".join(c for c in candidate if c.isdigit()) + if not 13 <= len(digits) <= 19: + return False + if " " in candidate or "-" in candidate: + groups = candidate.strip().replace("-", " ").split() + if any(not g.isdigit() or not 4 <= len(g) <= 6 for g in groups): + return False + return _luhn_ok(digits) + + +def _redact_credit_cards(text: str) -> str: + """Replace only Luhn-valid, card-grouped candidates with .""" + return _CREDIT_CARD_CANDIDATE_RE.sub( + lambda m: "" if _is_card_like(m.group(0)) else m.group(0), + text, + ) + + +# --------------------------------------------------------------------------- +# Key scoping — PII redaction applies only to attribute keys that carry +# user/model free text. Structured identifiers (session.id, user.id, +# metadata) and typed scalars are never scanned: a regex hit there +# corrupts correlation identifiers, not secrets (#195). +# --------------------------------------------------------------------------- +_PII_SCANNABLE_KEYS = frozenset( + { + SpanAttributes.INPUT_VALUE, + SpanAttributes.OUTPUT_VALUE, + SpanAttributes.GEN_AI_TOOL_CALL_ARGUMENTS, + SpanAttributes.GEN_AI_TOOL_CALL_RESULT, + SpanAttributes.GEN_AI_RETRIEVAL_QUERY, + SpanAttributes.GEN_AI_RERANKER_QUERY, + RerankerAttributes.RERANKER_QUERY, + } +) + +# Nested free-text carriers keyed by their leaf attribute name — e.g. +# ``gen_ai.input.messages.0.message.content`` ends with ``.message.content``. +_PII_SCANNABLE_SUFFIXES = tuple( + "." + leaf + for leaf in ( + MessageAttributes.MESSAGE_CONTENT, + MessageContentAttributes.MESSAGE_CONTENT_TEXT, + DocumentAttributes.DOCUMENT_CONTENT, + ToolCallAttributes.TOOL_CALL_FUNCTION_ARGUMENTS_JSON, + ) +) + + +def key_carries_free_text(key: str) -> bool: + """Whether *key* is an attribute that can hold free text and should be + PII-scanned. Exact match for top-level content keys; suffix match for + indexed carriers (``…0.message.content``, ``…0.document.content``).""" + if key in _PII_SCANNABLE_KEYS: + return True + return any(key.endswith(suffix) for suffix in _PII_SCANNABLE_SUFFIXES) + + def redact_pii_in_string(text: str) -> str: """Scan *text* for PII patterns and replace each match with its entity token.""" if not text or not _QUICK_CHECK.search(text): return text - for pattern, replacement in _PII_PATTERNS: + for pattern, replacement in _PII_PATTERNS_BEFORE_CARD: + text = pattern.sub(replacement, text) + text = _redact_credit_cards(text) + for pattern, replacement in _PII_PATTERNS_AFTER_CARD: text = pattern.sub(replacement, text) return text diff --git a/python/tests/test_config.py b/python/tests/test_config.py index 1db35fe16..d8e45cd50 100644 --- a/python/tests/test_config.py +++ b/python/tests/test_config.py @@ -6,6 +6,7 @@ from opentelemetry.context import get_current, get_value from opentelemetry.context import _SUPPRESS_INSTRUMENTATION_KEY +from fi_instrumentation.fi_types import SpanAttributes from fi_instrumentation.instrumentation.config import ( TraceConfig, suppress_tracing, @@ -148,6 +149,72 @@ def test_trace_config_mask_with_redaction(self, clean_env): assert result == "__REDACTED__" +class TestPiiRedactionScope: + """PII redaction applies only to free-text attribute keys, and the + credit-card check requires card shape + Luhn — identifier attributes + and incidental digit runs must pass through untouched (#195).""" + + def test_session_id_uuid_not_corrupted(self, clean_env): + """The exact UUID from #195 — a 13+ digit run inside it used to + be replaced with .""" + config = TraceConfig(pii_redaction=True) + sid = "73630065-0794-4450-a1f9-8cc987a02b09" + assert config.mask(SpanAttributes.SESSION_ID, sid) == sid + + def test_user_id_digit_run_not_corrupted(self, clean_env): + config = TraceConfig(pii_redaction=True) + uid = "1234567890123" + assert config.mask(SpanAttributes.USER_ID, uid) == uid + + def test_metadata_numeric_ids_not_corrupted(self, clean_env): + config = TraceConfig(pii_redaction=True) + md = '{"request_id": "20240115103045123", "cost_usd": 3.14159}' + assert config.mask(SpanAttributes.METADATA, md) == md + + def test_free_text_card_still_redacted(self, clean_env): + """A Luhn-valid, 4-4-4-4 grouped card inside input.value is + real PII and must still be masked.""" + config = TraceConfig(pii_redaction=True) + out = config.mask(SpanAttributes.INPUT_VALUE, "my card is 4111 1111 1111 1111") + assert "" in out + assert "4111" not in out + + def test_free_text_contiguous_card_redacted(self, clean_env): + config = TraceConfig(pii_redaction=True) + out = config.mask(SpanAttributes.OUTPUT_VALUE, "charged 4111111111111111 today") + assert "" in out + + def test_non_luhn_digit_run_not_redacted(self, clean_env): + """A 17-digit request id inside a free-text attribute fails Luhn + and must survive — free-text scoping alone doesn't fix over- + redaction, the card check has to be real.""" + config = TraceConfig(pii_redaction=True) + out = config.mask(SpanAttributes.INPUT_VALUE, "request 20240115103045123 failed") + assert "" not in out + assert "20240115103045123" in out + + def test_free_text_email_still_redacted(self, clean_env): + config = TraceConfig(pii_redaction=True) + out = config.mask(SpanAttributes.INPUT_VALUE, "reach me at jane@example.com") + assert "" in out + assert "jane@example.com" not in out + + def test_message_content_key_scanned(self, clean_env): + """Nested message content keys carry free text and stay in scope.""" + config = TraceConfig(pii_redaction=True) + key = "gen_ai.input.messages.0.message.content" + out = config.mask(key, "email jane@example.com") + assert "" in out + + def test_identifier_key_with_pii_text_not_scanned(self, clean_env): + """Document the deliberate tradeoff: a non-free-text key is never + scanned, even when its value looks like PII — correctness of + correlation ids outranks coverage of stray keys.""" + config = TraceConfig(pii_redaction=True) + val = "session tag jane@example.com" + assert config.mask("session.id", val) == val + + class TestSuppressTracing: """Test suppress_tracing context manager."""