thoth.utils.logger¶

Secure Logging Utilities - Standardized logging with automatic sensitive data redaction.

This module provides a secure logging framework for HorizonSec tools that automatically detects and redacts sensitive information from log messages to prevent data leaks.

The module includes: - SecureLogger: A logger class that extends Python’s standard logging.Logger - SensitiveDataFormatter: A formatter that redacts sensitive patterns from log messages - setup_logger: A convenience function to create pre-configured secure loggers

Key Features: - Automatic detection of sensitive patterns (passwords, API keys, tokens, etc.) - Case-insensitive pattern matching with word boundary detection - Graceful error handling for malformed log messages - Support for both detailed and simple log formats - Prevention of duplicate handlers when creating multiple loggers with the same name

Security Considerations: - All sensitive data is replaced with “[REDACTED]” before being written to logs - Redaction happens at the formatter level, ensuring no sensitive data reaches log handlers - Word boundary matching prevents false positives on partial keyword matches - Multiple sensitive values in a single message are all properly redacted

Example

>>> from horizon_core import setup_logger
>>> import logging
>>>
>>> logger = setup_logger("myapp", level=logging.INFO)
>>> logger.info("User password is secret123")  # Logs: "User password is [REDACTED]"
>>> logger.info("API key: abc123def")          # Logs: "API key: [REDACTED]"

Functions

`getLogger`([name])	Return a logger with the specified name, creating it if necessary.
`setup_logger`(name[, level, simple])	Creates and configures a secure logger with automatic sensitive data redaction.

Classes

`Any`(args, *kwargs)	Special type indicating an unconstrained type.
`Formatter`([fmt, datefmt, style, validate, ...])	Formatter instances are used to convert a LogRecord to text.
`LogRecord`(name, level, pathname, lineno, ...)	A LogRecord instance represents an event being logged.
`Logger`(name[, level])	Instances of the Logger class represent a single logging channel.
`SecureLogger`(name[, level])	A security-enhanced logger that provides safe handling of log messages.
`SensitiveDataFormatter`([fmt, datefmt, ...])	Custom formatter that automatically redacts sensitive information from log messages.
`StreamHandler`([stream])	A handler class which writes logging records, appropriately formatted, to a stream.

class thoth.utils.logger.SensitiveDataFormatter(fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)[source]¶

Bases: Formatter

Custom formatter that automatically redacts sensitive information from log messages.

This formatter extends the standard logging.Formatter to provide automatic detection and redaction of sensitive data patterns before log messages are written to any handler.

The formatter uses regex patterns with word boundaries to ensure accurate detection while avoiding false positives. It supports case-insensitive matching and handles multiple common patterns for sensitive data.

SENSITIVE_KEYWORDS¶

List of keywords that are considered sensitive. These keywords trigger redaction when found in specific patterns.

Type:: list

Supported Patterns:

“keyword is value” format: “password is secret123” → “password is [REDACTED]”
“keyword: value” format: “API key: abc123” → “API key: [REDACTED]”
“keyword=value” format: “token=xyz789” → “token=[REDACTED]”

Example

>>> formatter = SensitiveDataFormatter("%(levelname)s: %(message)s")
>>> record = logging.LogRecord("test", logging.INFO, "", 0, "password is secret", (), None)
>>> formatted = formatter.format(record)
>>> print(formatted)  # "INFO: password is [REDACTED]"

SENSITIVE_KEYWORDS: ClassVar[list[str]] = ['password', 'passwd', 'pwd', 'secret', 'token', 'apikey', 'api_key', 'auth', 'authorization', 'credential', 'key', 'private', 'session', 'cookie', 'jwt', 'bearer', 'oauth']¶

format(record: LogRecord) → str[source]¶

Format the log record and redact any sensitive information.

This method first formats the log record using the parent formatter, then applies regex patterns to detect and redact sensitive data.

Parameters:: record (logging.LogRecord) – The log record to format and redact.
Returns:: The formatted log message with sensitive data redacted.
Return type:: str

Note

Redaction is performed using regex substitution with case-insensitive matching. Multiple sensitive values in the same message will all be redacted.

thoth.utils.logger.setup_logger(name: str, level: int = 20, simple: bool = False) → Logger[source]¶

Creates and configures a secure logger with automatic sensitive data redaction.

This function is the main entry point for creating secure loggers in the application. It handles logger reuse, prevents duplicate handlers, and configures appropriate formatters based on the security requirements.

Parameters:

name (str) – Name of the logger. Should be unique within the application. Common practice is to use __name__ from the calling module.
level (int) – Logging level threshold. Only messages at or above this level will be processed. Defaults to logging.INFO. Common values: logging.DEBUG, logging.INFO, logging.WARNING, logging.ERROR, logging.CRITICAL
simple (bool) – If True, uses a simple format with just level and message. If False (default), uses detailed format with timestamp, logger name, level, and message. Simple format does NOT include sensitive data redaction.

Returns:

A configured SecureLogger instance with automatic: sensitive data redaction (unless simple=True).

Return type:

logging.Logger

Note

If a logger with the same name already exists and is a SecureLogger, it will be returned without modification
When simple=True, sensitive data redaction is NOT applied for performance
The logger uses StreamHandler to output to stderr by default

Example

>>> logger = setup_logger("myapp", level=logging.DEBUG)
>>> logger.info("Database password is secret123")  # Redacted output
>>>
>>> simple_logger = setup_logger("console", simple=True)
>>> simple_logger.info("Quick message")  # No redaction, faster output

class thoth.utils.logger.SecureLogger(name: str, level: int = 0)[source]¶

Bases: Logger

A security-enhanced logger that provides safe handling of log messages.

SecureLogger extends Python’s standard Logger class to provide additional safety measures for log message processing. While the actual sensitive data redaction is handled by SensitiveDataFormatter, this logger provides robust error handling to prevent logging failures from crashing applications.

Key Features:

Graceful handling of malformed log messages
Safe string formatting with automatic fallbacks
Prevention of exceptions during log message processing
Compatibility with all standard logging methods

The logger handles various edge cases:

Mismatched format strings and arguments
Non-string message objects
None values and other unexpected types
Encoding issues and special characters

SENSITIVE_KEYWORDS¶

Legacy list of sensitive keywords. Note: This is kept for backward compatibility but actual redaction is handled by the formatter.

Type:: list

Example

>>> logger = SecureLogger("myapp")
>>> logger.info("Normal message")  # Works normally
>>> logger.info("Message with %s", "argument")  # Safe formatting
>>> logger.info(None)  # Gracefully handles None
>>> logger.info("Missing arg: %s")  # Won't crash on missing args

SENSITIVE_KEYWORDS: ClassVar[list[str]] = ['password', 'passwd', 'pwd', 'secret', 'token', 'apikey', 'api_key', 'auth', 'authorization', 'credential', 'key', 'private', 'session', 'cookie', 'jwt', 'bearer', 'oauth']¶

__init__(name: str, level: int = 0) → None[source]¶

Initialize the SecureLogger with the specified name and level.

Parameters:

name (str) – Name of the logger, typically the module name.
level (int) – Minimum logging level. Defaults to NOTSET (inherits from parent).

debug(msg: Any, *args: Any, **kwargs: Any) → None[source]¶

Log a debug message with safe formatting and error handling.

Parameters:

msg – The message to log. Can be a string, format string, or any object.
*args – Arguments for string formatting if msg is a format string.
**kwargs – Additional keyword arguments passed to the parent logger.

Note