Skip to content

Configuration

Sensitive field configuration for automatic log masking. This module manages the registry of field names that are automatically masked in log output.

Quick Reference

Python
from pylogshield import (
    add_sensitive_fields,
    remove_sensitive_fields,
    get_sensitive_fields,
)
from pylogshield.config import get_sensitive_pattern

# Add custom sensitive fields
add_sensitive_fields(["ssn", "credit_card", "bank_account"])

# Remove fields from the registry
remove_sensitive_fields(["auth"])

# Get all registered fields
fields = get_sensitive_fields()
print(fields)  # frozenset({'password', 'token', 'api_key', ...})

# Get the compiled regex pattern for matching
pattern = get_sensitive_pattern()

Default Sensitive Fields

The following fields are masked by default:

Field Description
password, passwd, pwd Password fields
token, access_token, refresh_token Authentication tokens
secret, secret_key, client_secret Secret values
api_key, apikey API keys
authorization, auth, bearer Authorization headers
private_key, encryption_key Cryptographic keys
session_token, session_id, sessionid Session identifiers
credit_card, creditcard, card_number Payment card data
ssn, social_security Social security numbers
cvv, pin Card verification values
jwt, cookie JWT tokens and cookies

Examples

Adding Custom Fields

Python
from pylogshield import add_sensitive_fields, get_logger

# Add custom fields before creating loggers
add_sensitive_fields(["employee_id", "salary", "dob"])

logger = get_logger("hr_app")

# These fields will now be masked
logger.info({
    "employee_id": "EMP123",
    "name": "John Doe",
    "salary": 75000
}, mask=True)
# Output: {"employee_id": "***", "name": "John Doe", "salary": "***"}

Checking Registered Fields

Python
from pylogshield import get_sensitive_fields

fields = get_sensitive_fields()
print(f"Total sensitive fields: {len(fields)}")
print(f"Password protected: {'password' in fields}")

Removing Fields

Python
from pylogshield import remove_sensitive_fields

# If you need to log auth tokens for debugging
remove_sensitive_fields(["auth"])

# Note: This affects all loggers globally

Thread Safety

All functions in this module are thread-safe. The pattern cache is automatically invalidated when fields are added or removed:

Python
from pylogshield import add_sensitive_fields, get_sensitive_pattern

# Thread-safe operations
pattern1 = get_sensitive_pattern()  # Cached
add_sensitive_fields(["new_field"])  # Invalidates cache
pattern2 = get_sensitive_pattern()  # New pattern compiled

API Reference

config

Sensitive field configuration for log masking.

This module manages the registry of field names that should be automatically masked in log output to prevent sensitive data leakage.

The module provides thread-safe functions to add, remove, and query sensitive field names, as well as a compiled regex pattern for efficient matching.

FUNCTION DESCRIPTION
add_sensitive_fields

Add new field names to the sensitive registry.
remove_sensitive_fields

Remove field names from the sensitive registry.
get_sensitive_fields

Return a frozen copy of the current sensitive fields.
get_sensitive_pattern

Return a compiled regex that matches 'key: value' for any sensitive field.
invalidate_sensitive_pattern_cache

Invalidate the cached regex so it's rebuilt on next request.
ATTRIBUTE DESCRIPTION
SENSITIVE_FIELDS

TYPE: Set[str]

SENSITIVE_FIELDS: Set[str] = {'password', 'passwd', 'pwd', 'token', 'access_token', 'refresh_token', 'secret', 'api_key', 'apikey', 'authorization', 'auth', 'bearer', 'client_secret', 'private_key', 'secret_key', 'session_token', 'credit_card', 'creditcard', 'card_number', 'ssn', 'social_security', 'cvv', 'pin', 'encryption_key', 'jwt', 'cookie', 'session_id', 'sessionid'} module-attribute

add_sensitive_fields(fields: Iterable[str]) -> None

Add new field names to the sensitive registry.

PARAMETER DESCRIPTION

fields

Iterable of field names to add. Fields are normalized to lowercase for case-insensitive matching.

TYPE: Iterable[str]

Examples:

Python Console Session
>>> add_sensitive_fields(["ssn", "credit_card"])
>>> add_sensitive_fields(["SSN"])  # Normalized to "ssn"
Source code in src/pylogshield/config.py
Python
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def add_sensitive_fields(fields: Iterable[str]) -> None:
    """Add new field names to the sensitive registry.

    Parameters
    ----------
    fields : Iterable[str]
        Iterable of field names to add. Fields are normalized to lowercase
        for case-insensitive matching.

    Examples
    --------
    >>> add_sensitive_fields(["ssn", "credit_card"])
    >>> add_sensitive_fields(["SSN"])  # Normalized to "ssn"
    """
    with SENSITIVE_LOCK:
        for f in fields:
            if f and f.strip():
                SENSITIVE_FIELDS.add(f.strip().lower())
        invalidate_sensitive_pattern_cache()

remove_sensitive_fields(fields: Iterable[str]) -> None

Remove field names from the sensitive registry.

PARAMETER DESCRIPTION

fields

Iterable of field names to remove.

TYPE: Iterable[str]

Examples:

Python Console Session
>>> remove_sensitive_fields(["password"])
Source code in src/pylogshield/config.py
Python
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def remove_sensitive_fields(fields: Iterable[str]) -> None:
    """Remove field names from the sensitive registry.

    Parameters
    ----------
    fields : Iterable[str]
        Iterable of field names to remove.

    Examples
    --------
    >>> remove_sensitive_fields(["password"])
    """
    with SENSITIVE_LOCK:
        for f in fields:
            SENSITIVE_FIELDS.discard(f.strip().lower())
        invalidate_sensitive_pattern_cache()

get_sensitive_fields() -> FrozenSet[str]

Return a frozen copy of the current sensitive fields.

RETURNS DESCRIPTION
frozenset of str

Immutable set of currently registered sensitive field names.

Examples:

Python Console Session
>>> fields = get_sensitive_fields()
>>> "password" in fields
True
Source code in src/pylogshield/config.py
Python
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
def get_sensitive_fields() -> FrozenSet[str]:
    """Return a frozen copy of the current sensitive fields.

    Returns
    -------
    frozenset of str
        Immutable set of currently registered sensitive field names.

    Examples
    --------
    >>> fields = get_sensitive_fields()
    >>> "password" in fields
    True
    """
    with SENSITIVE_LOCK:
        return frozenset(SENSITIVE_FIELDS)

get_sensitive_pattern() -> re.Pattern[str]

Return a compiled regex that matches 'key: value' for any sensitive field.

The pattern is rebuilt lazily and cached until invalidated by adding or removing sensitive fields.

RETURNS DESCRIPTION
Pattern[str]

A compiled regex pattern for matching sensitive field patterns.
Notes

The pattern matches formats like: - password: value - token=value - api_key: "value"

Source code in src/pylogshield/config.py
Python
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def get_sensitive_pattern() -> re.Pattern[str]:
    """Return a compiled regex that matches 'key: value' for any sensitive field.

    The pattern is rebuilt lazily and cached until invalidated by adding or
    removing sensitive fields.

    Returns
    -------
    re.Pattern[str]
        A compiled regex pattern for matching sensitive field patterns.

    Notes
    -----
    The pattern matches formats like:
    - ``password: value``
    - ``token=value``
    - ``api_key: "value"``
    """
    global __pattern_cache
    with SENSITIVE_LOCK:
        if __pattern_cache is None:
            fields = sorted(SENSITIVE_FIELDS)
            if fields:
                joined = "|".join(map(re.escape, fields))
                __pattern_cache = re.compile(
                    rf"(?i)\b({joined})\b(\s*[:=]\s*)['\"]?([^'\"\s]*)['\"]?"
                )
            else:
                # Compile a never-matching pattern to avoid special-casing.
                __pattern_cache = re.compile(r"(?!x)x")  # never matches
        return __pattern_cache

invalidate_sensitive_pattern_cache() -> None

Invalidate the cached regex so it's rebuilt on next request.

This function is called automatically when sensitive fields are added or removed. Users typically don't need to call this directly.

Source code in src/pylogshield/config.py
Python
89
90
91
92
93
94
95
96
97
def invalidate_sensitive_pattern_cache() -> None:
    """Invalidate the cached regex so it's rebuilt on next request.

    This function is called automatically when sensitive fields are added
    or removed. Users typically don't need to call this directly.
    """
    global __pattern_cache
    with SENSITIVE_LOCK:
        __pattern_cache = None