safe-logs 0.1.0

No project description provided

safe-logs

A lightweight, zero-dependency Python library that automatically scrubs sensitive information (PII, secrets, API keys) from your logs.

Why use safe-logs?

Keeping sensitive information out of your logs is critical for security and compliance. Log files are often aggregated and stored in centralized systems where multiple developers or third-party services might have access to them. Leaking emails, phone numbers, credit cards, or API tokens can lead to severe security breaches. safe-logs acts as a safety net, ensuring these secrets are masked before they ever hit the output stream.

Installation

You can install safe-logs via pip:

pip install safe-logs

Or using poetry:

poetry add safe-logs

Usage

1. The Quickest Way (Convenience Function)

The easiest way to start logging safely is to use the get_safe_logger function. This returns a standard Python logging.Logger with our scrubbing formatter already attached.

from safe_logs import get_safe_logger

logger = get_safe_logger("my_app")

# Outputs: 2026-06-12 12:00:00,000 - my_app - INFO - User [MASKED_EMAIL] has signed in.
logger.info("User [e-mail] has signed in.")

2. Using with an Existing Logger (ScrubbingFormatter)

If you already have a complex logging setup, you can simply swap out your standard formatter for the ScrubbingFormatter.

import logging
from safe_logs import ScrubbingFormatter

logger = logging.getLogger("custom_app")
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler()
formatter = ScrubbingFormatter(fmt='%(levelname)s: %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)

logger.debug("API request with token='super-secret-token'")
# Outputs: DEBUG: API request with token='[MASKED_SECRET]'

3. Direct String & Structured Data Scrubbing (LogScrubber)

If you just need to scrub data independent of the logging module, you can use the LogScrubber class directly. It recursively scrubs strings, lists, and dictionaries.

from safe_logs import LogScrubber

scrubber = LogScrubber()

data = {
    "user_id": 123,
    "email": "[e-mail]",
    "password": "my_super_secret_password"
}

clean_data = scrubber.scrub(data)
print(clean_data)
# Outputs: {'user_id': 123, 'email': '[MASKED_EMAIL]', 'password': '[MASKED]'}

Note: Any dictionary key matching "password", "secret", "token", etc., is automatically scrubbed entirely, regardless of its value's format.

Advanced Features

Partial Masking (Obfuscation)

Sometimes for debugging, you want to see the last 4 digits of a credit card or API key instead of replacing the entire string.

from safe_logs import LogScrubber, keep_last_n_chars

scrubber = LogScrubber(mask_templates={
    "credit_card": keep_last_n_chars(4, '*'),
    "api_key": keep_last_n_chars(4, '*')
})

# Outputs: "Card: ****************3456"
print(scrubber.scrub("Card: 1234-5678-9012-3456"))

Adding Custom Patterns

You can easily add your own regex patterns to the scrubber:

scrubber = LogScrubber()

# Add a Social Security Number pattern
scrubber.add_pattern("ssn", r"\b\d{3}-\d{2}-\d{4}\b", "[MASKED_SSN]")

# Outputs: "SSN: [MASKED_SSN]"
print(scrubber.scrub("SSN: 123-45-6789"))