safe-logs 0.1.0__tar.gz

safe_logs-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: safe-logs
+Version: 0.1.0
+Summary: 
+Author: alien1403
+Author-email: hanghicelrazvanmihai@gmail.com
+Requires-Python: >=3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Description-Content-Type: text/markdown
+
+# 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:
+
+```bash
+pip install safe-logs
+```
+
+Or using poetry:
+
+```bash
+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.
+
+```python
+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 test@example.com 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`.
+
+```python
+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.
+
+```python
+from safe_logs import LogScrubber
+
+scrubber = LogScrubber()
+
+data = {
+    "user_id": 123,
+    "email": "user@domain.com",
+    "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.
+
+```python
+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:
+
+```python
+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"))
+```
+
+

safe_logs-0.1.0/README.md

@@ -0,0 +1,108 @@
+# 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:
+
+```bash
+pip install safe-logs
+```
+
+Or using poetry:
+
+```bash
+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.
+
+```python
+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 test@example.com 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`.
+
+```python
+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.
+
+```python
+from safe_logs import LogScrubber
+
+scrubber = LogScrubber()
+
+data = {
+    "user_id": 123,
+    "email": "user@domain.com",
+    "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.
+
+```python
+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:
+
+```python
+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"))
+```
+

safe_logs-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "safe-logs"
+version = "0.1.0"
+description = ""
+authors = [
+    {name = "alien1403",email = "hanghicelrazvanmihai@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+]
+
+[tool.poetry]
+packages = [{include = "safe_logs", from = "src"}]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+dev = [
+    "pytest (>=9.0.3,<10.0.0)"
+]

safe_logs-0.1.0/src/safe_logs/__init__.py

@@ -0,0 +1,153 @@
+"""
+safe_logs: A lightweight Python library to scrub sensitive information (PII, secrets) from logs.
+"""
+import re
+import logging
+from typing import Dict, Optional, Any, Callable, Union, Set, List
+
+def keep_last_n_chars(n: int, mask_char: str = '*') -> Callable[[re.Match], str]:
+    """
+    Returns a callable mask that replaces all but the last `n` characters of the matched string.
+    Useful for partial obfuscation of credit cards or API keys.
+    """
+    def _masker(match: re.Match) -> str:
+        # If there's a capture group (like for api_key), we mask the group
+        text = match.group(1) if match.groups() else match.group(0)
+        
+        if len(text) <= n:
+            masked = mask_char * len(text)
+        else:
+            masked = mask_char * (len(text) - n) + text[-n:]
+            
+        if match.groups():
+            return match.group(0).replace(match.group(1), masked)
+        return masked
+        
+    return _masker
+
+class LogScrubber:
+    """
+    A utility class that scrubs sensitive information from strings, lists, and dictionaries.
+    """
+    DEFAULT_PATTERNS: Dict[str, re.Pattern] = {
+        "email": re.compile(r'[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}'),
+        "phone": re.compile(r'(?<!\d)(?:\+?\d{1,3}[-. ]?)?\(?\d{3}\)?[-. ]?\d{3}[-. ]?\d{4}(?!\d)'),
+        "credit_card": re.compile(r'\b(?:\d{4}[- ]?){3}\d{4}\b'),
+        "api_key": re.compile(r'(?i)(?:api[_-]?key|secret|password|token)\s*[:=]\s*["\']([^"\']+)["\']'),
+    }
+
+    def __init__(self, mask_templates: Optional[Dict[str, Union[str, Callable[[re.Match], str]]]] = None,
+                 sensitive_keys: Optional[Set[str]] = None):
+        """
+        Initializes the LogScrubber.
+        
+        Args:
+            mask_templates: A dictionary mapping pattern keys to their replacement strings or callable functions.
+            sensitive_keys: A set of string keys. If scrubbing a dictionary, values for these keys will be entirely masked.
+        """
+        self.patterns = self.DEFAULT_PATTERNS.copy()
+        self.masks: Dict[str, Union[str, Callable[[re.Match], str]]] = {
+            "email": "[MASKED_EMAIL]",
+            "phone": "[MASKED_PHONE]",
+            "credit_card": "[MASKED_CARD]",
+            "api_key": "[MASKED_SECRET]"
+        }
+        if mask_templates:
+            self.masks.update(mask_templates)
+        self.sensitive_keys: Set[str] = sensitive_keys or {"password", "secret", "token", "api_key", "access_token"}
+
+    def add_pattern(self, name: str, pattern: Union[str, re.Pattern], mask: Union[str, Callable[[re.Match], str]]):
+        """
+        Registers a new regular expression pattern and its corresponding mask.
+        
+        Args:
+            name: The key/name for this pattern.
+            pattern: The regex pattern (string or compiled re.Pattern).
+            mask: The replacement string or a callable taking an re.Match and returning a string.
+        """
+        if isinstance(pattern, str):
+            pattern = re.compile(pattern)
+        self.patterns[name] = pattern
+        self.masks[name] = mask
+
+    def _apply_mask(self, match: re.Match, mask: Union[str, Callable[[re.Match], str]]) -> str:
+        if callable(mask):
+            return mask(match)
+        if match.groups():
+            return match.group(0).replace(match.group(1), str(mask))
+        return str(mask)
+
+    def scrub(self, data: Any) -> Any:
+        """
+        Recursively scrubs sensitive information from strings, dictionaries, or lists.
+        
+        Args:
+            data (Any): The input data to scrub.
+            
+        Returns:
+            Any: The scrubbed data.
+        """
+        if isinstance(data, str):
+            return self._scrub_string(data)
+        elif isinstance(data, dict):
+            return {k: ("[MASKED]" if str(k).lower() in self.sensitive_keys else self.scrub(v)) for k, v in data.items()}
+        elif isinstance(data, list):
+            return [self.scrub(item) for item in data]
+        return data
+
+    def _scrub_string(self, text: str) -> str:
+        for name, pattern in self.patterns.items():
+            mask = self.masks.get(name, "[MASKED]")
+            text = pattern.sub(lambda m: self._apply_mask(m, mask), text)
+        return text
+
+class ScrubbingFormatter(logging.Formatter):
+    """
+    A custom logging.Formatter that automatically scrubs sensitive information 
+    from log messages before they are emitted.
+    """
+    def __init__(self, fmt: Optional[str] = None, datefmt: Optional[str] = None, 
+                 style: str = '%', mask_templates: Optional[Dict[str, Union[str, Callable]]] = None,
+                 sensitive_keys: Optional[Set[str]] = None):
+        """
+        Initializes the ScrubbingFormatter.
+        
+        Args:
+            fmt: The format string for the log message.
+            datefmt: The format string for the date/time.
+            style: The format style ('%', '{', or '$').
+            mask_templates: Custom mask templates for the scrubber.
+            sensitive_keys: A set of dictionary keys that should be scrubbed when logging dicts/JSON.
+        """
+        super().__init__(fmt, datefmt, style)
+        self.scrubber = LogScrubber(mask_templates, sensitive_keys)
+
+    def format(self, record: logging.LogRecord) -> str:
+        """
+        Formats the given log record and scrubs any sensitive information from the resulting string.
+        """
+        original_msg = super().format(record)
+        return self.scrubber.scrub(original_msg)
+
+def get_safe_logger(name: str, level: int = logging.INFO, **kwargs) -> logging.Logger:
+    """
+    A convenience function to quickly instantiate a logger with the ScrubbingFormatter attached.
+    
+    Args:
+        name: The name of the logger.
+        level: The logging level. Defaults to logging.INFO.
+        **kwargs: Additional arguments to pass to ScrubbingFormatter (like mask_templates or sensitive_keys).
+        
+    Returns:
+        logging.Logger: A configured logger instance ready to safely log messages.
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(level)
+    
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        formatter = ScrubbingFormatter(fmt='%(asctime)s - %(name)s - %(levelname)s - %(message)s', **kwargs)
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+        
+    return logger