Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions python/fi_instrumentation/instrumentation/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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

Expand Down
111 changes: 106 additions & 5 deletions python/fi_instrumentation/instrumentation/pii_redaction.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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(
Expand All @@ -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, "<EMAIL_ADDRESS>"),
(_SSN_RE, "<SSN>"),
(_CREDIT_CARD_RE, "<CREDIT_CARD>"),
]
_PII_PATTERNS_AFTER_CARD: list[tuple[re.Pattern[str], str]] = [
(_API_KEY_RE, "<API_KEY>"),
(_IP_RE, "<IP_ADDRESS>"),
(_PHONE_RE, "<PHONE_NUMBER>"),
]


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 <CREDIT_CARD>."""
return _CREDIT_CARD_CANDIDATE_RE.sub(
lambda m: "<CREDIT_CARD>" 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

Expand Down
67 changes: 67 additions & 0 deletions python/tests/test_config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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 <CREDIT_CARD>."""
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 "<CREDIT_CARD>" 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 "<CREDIT_CARD>" 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 "<CREDIT_CARD>" 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 "<EMAIL_ADDRESS>" 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 "<EMAIL_ADDRESS>" 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."""

Expand Down
Loading