hushlog 0.3.0a1

Zero-config PII redaction for Python logging

HushLog

Zero-config PII redaction for Python logging.

Features

• Zero-config -- one call to hushlog.patch() and you're done
• Non-invasive -- wraps existing formatters, no logger rewrites needed
• Performant -- pre-compiled regex with heuristic early-exit checks
• Type-safe -- fully typed with PEP 561 py.typed marker
• Python 3.10+ -- supports Python 3.10 through 3.13

Installation

pip install hushlog

Or with uv:

uv add hushlog

Quick Start

import logging
import hushlog

# Configure logging FIRST, then patch
logging.basicConfig(level=logging.INFO)
hushlog.patch()

logger = logging.getLogger(__name__)

logger.info("User email: [e-mail]")
# Output: User email: [EMAIL REDACTED]

logger.info("Card: 4111-1111-1111-1111")
# Output: Card: [CREDIT_CARD REDACTED]

logger.info("SSN: 123-45-6789")
# Output: SSN: [SSN REDACTED]

How It Works

HushLog wraps your existing logging formatters with a RedactingFormatter that scans the final formatted string for PII patterns. It never replaces loggers or handlers -- your existing logger.info() calls remain unchanged. All regex patterns are pre-compiled at import time with lightweight heuristic pre-checks to minimize overhead on the hot logging path.

What Gets Redacted

Pattern	Example	Output	Notes
Email	[e-mail]	[EMAIL REDACTED]	RFC 5322 subset, @ heuristic pre-check
Credit Card	4111-1111-1111-1111	[CREDIT_CARD REDACTED]	Luhn validated, supports spaces/dashes
SSN	123-45-6789	[SSN REDACTED]	Dashed format only, invalid ranges excluded
Phone	[phone]	[PHONE REDACTED]	US NANP, multiple formats
JWT	eyJhbGci...	[JWT REDACTED]	3-5 segment base64url tokens
AWS Access Key	AKIAIOSFODNN7EXAMPLE	[AWS_ACCESS_KEY REDACTED]	AKIA/ASIA prefixed
AWS Secret Key	aws_secret_access_key=...	[AWS_SECRET_KEY REDACTED]	Context-dependent (requires label)
Stripe Key	sk_live_abc123...	[STRIPE_KEY REDACTED]	sk/pk/rk live/test keys
GitHub Token	ghp_xxxx...	[GITHUB_TOKEN REDACTED]	Classic + fine-grained (github_pat_)
GCP API Key	AIzaSyA...	[GCP_KEY REDACTED]	AIza-prefixed keys
Generic Secret	password=MyS3cret	[SECRET REDACTED]	Label-based (password, secret, api_key, etc.)
IPv4	192.168.1.1	[IPV4 REDACTED]	Octet-validated, rejects version strings
IPv6	2001:db8::8a2e:370:7334	[IPV6 REDACTED]	Full, compressed, and mixed forms

Configuration

Disable specific built-in patterns or add custom ones:

from hushlog import Config

hushlog.patch(Config(
    disable_patterns=frozenset({"phone"}),
    custom_patterns={"internal_id": r"ID-[A-Z]{3}-[0-9]{6}"},
))

Partial Masking

Show partial values instead of full redaction:

hushlog.patch(Config(mask_style="partial"))
# [e-mail] → j***@e***.com
# 4111111111111111 → ****-****-****-1111
# 078-05-1120      → ***-**-1120
# [phone]   → (***) ***-5678

Use a custom mask character:

hushlog.patch(Config(mask_style="partial", mask_character="#"))
# [e-mail] → j###@e###.com

Note: Partial masking reveals partial information (first/last characters). In small organizations, this may be identifying. Use mask_style="full" (default) for maximum privacy.

JSON / Structured Logging

HushLog supports JSON log output with automatic PII redaction in all string values, including nested structures.

RedactingJsonFormatter

Use RedactingJsonFormatter as a drop-in JSON formatter for any handler:

import logging
from hushlog import Config, RedactingJsonFormatter
from hushlog._registry import PatternRegistry  # internal API

registry = PatternRegistry.from_config(Config())
formatter = RedactingJsonFormatter(registry)

handler = logging.StreamHandler()
handler.setFormatter(formatter)
logging.getLogger().addHandler(handler)

logger = logging.getLogger(__name__)
logger.info("Contact [e-mail]", extra={"ssn": "078-05-1120"})
# Output: {"message": "Contact [EMAIL REDACTED]", "ssn": "[SSN REDACTED]", ...}

Works with or without python-json-logger installed. Install the optional dependency for enhanced JSON serialization:

pip install hushlog[json]

redact_dict()

For manual redaction of dict/list/string structures:

import hushlog

data = {"user": {"email": "[e-mail]", "name": "Alice", "age": 30}}
clean = hushlog.redact_dict(data)
# {"user": {"email": "[EMAIL REDACTED]", "name": "Alice", "age": 30}}

Note: redact_dict() creates a new PatternRegistry on every call. For repeated use, create a registry once via PatternRegistry.from_config() and call registry.redact_dict() directly.

Teardown

Call unpatch() to remove HushLog's formatter wrappers and restore the original formatters. This is useful for testing or runtime toggling:

hushlog.unpatch()

Calling unpatch() without a prior patch() is safe (no-op). Calling patch() multiple times is also safe (idempotent).

Limitations

• Only handlers present on the root logger at patch() time are wrapped. Handlers added later will not be redacted.
• Named loggers with propagate=False and their own handlers bypass root-level redaction.
• structlog/loguru integrations planned for v0.3.0.
• Phone detection is US NANP only.

Planned

Structlog/loguru integrations, pattern validation, and more. See the roadmap for details.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT -- see LICENSE for details.