crackerjack 0.32.0__py3-none-any.whl → 0.33.1__py3-none-any.whl

crackerjack/services/secure_status_formatter.py

@@ -1,11 +1,3 @@
-"""
-Secure status formatter to prevent information disclosure vulnerabilities.
-
-This module provides secure sanitization of status responses to prevent
-leaking sensitive system information such as absolute paths, internal URLs,
-configuration details, and other sensitive data.
-"""
-
 import tempfile
 import typing as t
 from enum import Enum
@@ -15,51 +7,37 @@ from .security_logger import get_security_logger
 
 
 class StatusVerbosity(str, Enum):
-    """Status output verbosity levels for security-aware responses."""
-
-    MINIMAL = "minimal"  # Only essential operational status
-    STANDARD = "standard"  # Standard operational information (default)
-    DETAILED = "detailed"  # More detailed information for debugging
-    FULL = "full"  # Complete information (for internal use only)
+    MINIMAL = "minimal"
+    STANDARD = "standard"
+    DETAILED = "detailed"
+    FULL = "full"
 
 
 class SecureStatusFormatter:
-    """
-    Secure status formatter with configurable verbosity levels.
-
-    Sanitizes sensitive information while preserving necessary operational data.
-    """
-
-    # Patterns for sensitive information that should be masked or removed
     SENSITIVE_PATTERNS = {
-        # Absolute system paths (replace with relative paths)
         "absolute_paths": [
-            r"(/[^/\s]*){2,}",  # Paths like /Users/username/...
-            rf"{tempfile.gettempdir()}/[^\s]*",  # Temp directory paths - using tempfile.gettempdir() (B108)
-            r"/var/[^\s]*",  # Var directory paths
-            r"/home/[^\s]*",  # Home directory paths
+            r"(/[^/\s]*){2, }",
+            rf"{tempfile.gettempdir()}/[^\s]*",
+            r"/var/[^\s]*",
+            r"/home/[^\s]*",
         ],
-        # URLs with localhost/internal IPs
         "internal_urls": [
-            r"https?://localhost:\d+",
-            r"https?://127\.0\.0\.1:\d+",
-            r"https?://0\.0\.0\.0:\d+",
-            r"ws://localhost:\d+",
-            r"ws://127\.0\.0\.1:\d+",
+            r"https?: //localhost: \d+",
+            r"https?: //127\.0\.0\.1: \d+",
+            r"https?: //0\.0\.0\.0: \d+",
+            r"ws: //localhost: \d+",
+            r"ws: //127\.0\.0\.1: \d+",
         ],
-        # Tokens and API keys
         "secrets": [
-            r"[A-Za-z0-9]{20,}",  # Long alphanumeric strings (potential tokens)
-            r"[A-Za-z0-9+/]{32,}={0,2}",  # Base64-like strings
+            r"[A-Za-z0-9]{20, }",
+            r"[A-Za-z0-9+/]{32, }={0, 2}",
         ],
-        # Process IDs and system identifiers
         "system_ids": [
-            r"pid:\d+",
-            r"process_id:\s*\d+",
+            r"pid: \d+",
+            r"process_id: \s*\d+",
         ],
     }
 
-    # Sensitive keys that should be masked or removed
     SENSITIVE_KEYS = {
         "remove_minimal": {
             "progress_dir",
@@ -83,12 +61,6 @@ class SecureStatusFormatter:
     }
 
     def __init__(self, project_root: Path | None = None):
-        """
-        Initialize secure status formatter.
-
-        Args:
-            project_root: Project root path for relative path conversion
-        """
         self.project_root = project_root or Path.cwd()
         self.security_logger = get_security_logger()
 
@@ -98,17 +70,6 @@ class SecureStatusFormatter:
         verbosity: StatusVerbosity = StatusVerbosity.STANDARD,
         user_context: str | None = None,
     ) -> dict[str, t.Any]:
-        """
-        Format status data with security sanitization.
-
-        Args:
-            status_data: Raw status data to sanitize
-            verbosity: Output verbosity level
-            user_context: Optional user context for logging
-
-        Returns:
-            Sanitized status data appropriate for the verbosity level
-        """
         self._log_status_access(status_data, verbosity, user_context)
         sanitized = self._prepare_data_for_sanitization(status_data)
         sanitized = self._apply_all_sanitization_steps(sanitized, verbosity)
@@ -120,31 +81,27 @@ class SecureStatusFormatter:
         verbosity: StatusVerbosity,
         user_context: str | None,
     ) -> None:
-        """Log status access attempt for security monitoring."""
         self.security_logger.log_status_access_attempt(
             endpoint="status_data",
             verbosity_level=verbosity.value,
             user_context=user_context,
-            data_keys=list(status_data.keys()),
+            data_keys=list[t.Any](status_data.keys()),
         )
 
     def _prepare_data_for_sanitization(
         self, status_data: dict[str, t.Any]
     ) -> dict[str, t.Any]:
-        """Create a deep copy of status data to avoid modifying original."""
-        return self._deep_copy_dict(status_data)
+        return self._deep_copy_dict(status_data)  # type: ignore[no-any-return]
 
     def _apply_all_sanitization_steps(
         self, data: dict[str, t.Any], verbosity: StatusVerbosity
     ) -> dict[str, t.Any]:
-        """Apply all sanitization steps in proper order."""
         data = self._apply_verbosity_filter(data, verbosity)
         return self._sanitize_sensitive_data(data, verbosity)
 
     def _add_security_metadata(
         self, data: dict[str, t.Any], verbosity: StatusVerbosity
     ) -> dict[str, t.Any]:
-        """Add security metadata to sanitized response."""
         data["_security"] = {
             "sanitized": True,
             "verbosity": verbosity.value,
@@ -155,22 +112,17 @@ class SecureStatusFormatter:
     def _apply_verbosity_filter(
         self, data: dict[str, t.Any], verbosity: StatusVerbosity
     ) -> dict[str, t.Any]:
-        """Apply verbosity-based key filtering."""
-
-        # Keys to remove based on verbosity level
         if verbosity == StatusVerbosity.MINIMAL:
             remove_keys = self.SENSITIVE_KEYS["remove_minimal"]
         elif verbosity == StatusVerbosity.STANDARD:
             remove_keys = self.SENSITIVE_KEYS["remove_standard"]
         else:
-            remove_keys = set()  # Keep all keys for DETAILED/FULL
+            remove_keys = set()
 
-        # Remove sensitive keys
-        for key in list(data.keys()):
+        for key in list[t.Any](data.keys()):
             if key in remove_keys:
                 del data[key]
 
-        # Recursively apply to nested dictionaries
         for key, value in data.items():
             if isinstance(value, dict):
                 data[key] = self._apply_verbosity_filter(value, verbosity)
@@ -180,20 +132,14 @@ class SecureStatusFormatter:
     def _sanitize_sensitive_data(
         self, data: dict[str, t.Any], verbosity: StatusVerbosity
     ) -> dict[str, t.Any]:
-        """Sanitize sensitive data based on patterns and keys."""
-
-        return self._sanitize_recursive(data, verbosity)
+        return self._sanitize_recursive(data, verbosity)  # type: ignore[no-any-return]
 
     def _sanitize_recursive(self, obj: t.Any, verbosity: StatusVerbosity) -> t.Any:
-        """Recursively sanitize data structures."""
-
         if isinstance(obj, dict):
             sanitized = {}
             for key, value in obj.items():
-                # Sanitize the key
                 sanitized_key = self._sanitize_string(key, verbosity)
 
-                # Sanitize the value
                 if (
                     key in self.SENSITIVE_KEYS["mask"]
                     and verbosity != StatusVerbosity.FULL
@@ -215,16 +161,14 @@ class SecureStatusFormatter:
         return obj
 
     def _sanitize_string(self, text: str, verbosity: StatusVerbosity) -> str:
-        """Sanitize string content based on verbosity level."""
         if verbosity == StatusVerbosity.FULL:
-            return text  # No sanitization for full verbosity
+            return text
 
         return self._apply_string_sanitization_pipeline(text, verbosity)
 
     def _apply_string_sanitization_pipeline(
         self, text: str, verbosity: StatusVerbosity
     ) -> str:
-        """Apply string sanitization steps in correct order."""
         sanitized = self._sanitize_internal_urls(text)
         sanitized = self._sanitize_paths(sanitized)
         return self._apply_secret_masking_if_needed(sanitized, verbosity)
@@ -232,16 +176,13 @@ class SecureStatusFormatter:
     def _apply_secret_masking_if_needed(
         self, text: str, verbosity: StatusVerbosity
     ) -> str:
-        """Apply secret masking for minimal verbosity only."""
         if verbosity == StatusVerbosity.MINIMAL:
             return self._mask_potential_secrets(text)
         return text
 
     def _sanitize_paths(self, text: str) -> str:
-        """Convert absolute paths to relative paths where possible."""
         from .regex_patterns import SAFE_PATTERNS
 
-        # Use validated patterns for path detection
         unix_path_pattern = SAFE_PATTERNS.get("detect_absolute_unix_paths")
 
         if not unix_path_pattern:
@@ -250,10 +191,9 @@ class SecureStatusFormatter:
         return text
 
     def _sanitize_paths_fallback(self, text: str) -> str:
-        """Fallback path sanitization when patterns don't exist."""
         path_patterns = [
-            r"/[a-zA-Z0-9_\-\.\/]+",  # Unix-style absolute paths
-            r"[A-Z]:[\\\/][a-zA-Z0-9_\-\.\\\/]+",  # Windows-style absolute paths
+            r"/[a-zA-Z0-9_\-\.\/]+",
+            r"[A-Z]: [\\\/][a-zA-Z0-9_\-\.\\\/]+",
         ]
 
         for pattern_str in path_patterns:
@@ -262,7 +202,6 @@ class SecureStatusFormatter:
         return text
 
     def _process_path_pattern(self, text: str, pattern_str: str) -> str:
-        """Process a single path pattern safely."""
         from contextlib import suppress
 
         from .regex_patterns import CompiledPatternCache
@@ -272,19 +211,17 @@ class SecureStatusFormatter:
             matches = compiled.findall(text)
 
             for match in matches:
-                if len(match) > 3:  # Only process paths longer than 3 chars
+                if len(match) > 3:
                     text = self._replace_path_match(text, match)
 
         return text
 
     def _replace_path_match(self, text: str, match: str) -> str:
-        """Replace a single path match with relative or redacted version."""
         try:
             abs_path = Path(match)
             if abs_path.is_absolute():
                 return self._convert_to_relative_or_redact(text, match, abs_path)
         except (ValueError, OSError):
-            # If path operations fail, mask it
             text = text.replace(match, "[REDACTED_PATH]")
 
         return text
@@ -292,22 +229,18 @@ class SecureStatusFormatter:
     def _convert_to_relative_or_redact(
         self, text: str, match: str, abs_path: Path
     ) -> str:
-        """Convert absolute path to relative or redact if outside project."""
         try:
             rel_path = abs_path.relative_to(self.project_root)
             return text.replace(match, f"./{rel_path}")
         except (ValueError, OSError):
-            # If not within project, mask it
             return text.replace(match, "[REDACTED_PATH]")
 
     def _sanitize_internal_urls(self, text: str) -> str:
-        """Replace internal URLs with generic placeholders."""
         from .regex_patterns import sanitize_internal_urls
 
         return sanitize_internal_urls(text)
 
     def _mask_potential_secrets(self, text: str) -> str:
-        """Mask strings that might be secrets."""
         if self._should_skip_secret_masking(text):
             return text
 
@@ -318,11 +251,9 @@ class SecureStatusFormatter:
         return self._apply_fallback_secret_patterns(text)
 
     def _should_skip_secret_masking(self, text: str) -> bool:
-        """Check if secret masking should be skipped for already sanitized content."""
         return "[INTERNAL_URL]" in text or "[REDACTED_PATH]" in text
 
     def _get_validated_secret_patterns(self) -> list[t.Any]:
-        """Get validated patterns from the safe patterns registry."""
         from .regex_patterns import SAFE_PATTERNS
 
         patterns = []
@@ -337,16 +268,14 @@ class SecureStatusFormatter:
         return patterns
 
     def _apply_validated_secret_patterns(self, text: str, patterns: list[t.Any]) -> str:
-        """Apply validated patterns for secret detection."""
         for pattern in patterns:
             try:
                 text = self._mask_pattern_matches(text, pattern.findall(text))
             except Exception:
-                continue  # Skip failed pattern matching
+                continue
         return text
 
     def _apply_fallback_secret_patterns(self, text: str) -> str:
-        """Apply fallback patterns when validated patterns don't exist."""
         for pattern_str in self.SENSITIVE_PATTERNS["secrets"]:
             try:
                 from .regex_patterns import CompiledPatternCache
@@ -354,11 +283,10 @@ class SecureStatusFormatter:
                 compiled = CompiledPatternCache.get_compiled_pattern(pattern_str)
                 text = self._mask_pattern_matches(text, compiled.findall(text))
             except Exception:
-                continue  # Skip failed pattern compilation
+                continue
         return text
 
     def _mask_pattern_matches(self, text: str, matches: list[str]) -> str:
-        """Mask matches from pattern matching."""
         for match in matches:
             if self._should_mask_match(match):
                 masked = self._create_masked_string(match)
@@ -366,19 +294,15 @@ class SecureStatusFormatter:
         return text
 
     def _should_mask_match(self, match: str) -> bool:
-        """Determine if a match should be masked."""
         if len(match) <= 16:
             return False
-        # Don't mask if it looks like a URL or path component
-        return not any(x in match for x in ("://", "/", "\\", "."))
+
+        return not any(x in match for x in (": //", "/", "\\", "."))
 
     def _create_masked_string(self, text: str) -> str:
-        """Create a masked version of the text."""
         return text[:4] + "*" * (len(text) - 8) + text[-4:]
 
     def _mask_sensitive_value(self, value: str) -> str:
-        """Mask a known sensitive value."""
-
         if len(value) <= 4:
             return "***"
         elif len(value) <= 8:
@@ -386,8 +310,6 @@ class SecureStatusFormatter:
         return value[:2] + "*" * (len(value) - 4) + value[-2:]
 
     def _deep_copy_dict(self, obj: t.Any) -> t.Any:
-        """Deep copy a dictionary-like object safely."""
-
         if isinstance(obj, dict):
             return {key: self._deep_copy_dict(value) for key, value in obj.items()}
         elif isinstance(obj, list):
@@ -395,7 +317,6 @@ class SecureStatusFormatter:
         return obj
 
     def _get_timestamp(self) -> float:
-        """Get current timestamp."""
         import time
 
         return time.time()
@@ -406,17 +327,6 @@ class SecureStatusFormatter:
         verbosity: StatusVerbosity = StatusVerbosity.STANDARD,
         include_details: bool = False,
     ) -> dict[str, t.Any]:
-        """
-        Format error responses without leaking system details.
-
-        Args:
-            error_message: Original error message
-            verbosity: Output verbosity level
-            include_details: Whether to include error details
-
-        Returns:
-            Sanitized error response
-        """
         error_type = self._classify_error(error_message)
 
         if verbosity == StatusVerbosity.MINIMAL:
@@ -427,7 +337,6 @@ class SecureStatusFormatter:
         )
 
     def _create_minimal_error_response(self, error_type: str) -> dict[str, t.Any]:
-        """Create minimal error response for production use."""
         generic_messages = {
             "connection": "Service temporarily unavailable. Please try again later.",
             "validation": "Invalid request parameters.",
@@ -449,7 +358,6 @@ class SecureStatusFormatter:
         verbosity: StatusVerbosity,
         include_details: bool,
     ) -> dict[str, t.Any]:
-        """Create detailed error response with sanitized message."""
         sanitized_message = self._sanitize_string(error_message, verbosity)
 
         response: dict[str, t.Any] = {
@@ -470,15 +378,12 @@ class SecureStatusFormatter:
     def _should_include_error_details(
         self, include_details: bool, verbosity: StatusVerbosity
     ) -> bool:
-        """Determine if error details should be included."""
         return include_details and verbosity in (
             StatusVerbosity.DETAILED,
             StatusVerbosity.FULL,
         )
 
     def _classify_error(self, error_message: str) -> str:
-        """Classify error message type for appropriate handling."""
-
         error_patterns = {
             "connection": ["connection", "timeout", "refused", "unavailable"],
             "validation": ["invalid", "validation", "format", "parameter"],
@@ -495,15 +400,12 @@ class SecureStatusFormatter:
         return "internal"
 
 
-# Singleton instance for global use
 _secure_formatter: SecureStatusFormatter | None = None
 
 
 def get_secure_status_formatter(
     project_root: Path | None = None,
 ) -> SecureStatusFormatter:
-    """Get the global secure status formatter instance."""
-
     global _secure_formatter
     if _secure_formatter is None:
         _secure_formatter = SecureStatusFormatter(project_root)
@@ -516,19 +418,6 @@ def format_secure_status(
     project_root: Path | None = None,
     user_context: str | None = None,
 ) -> dict[str, t.Any]:
-    """
-    Convenience function for secure status formatting.
-
-    Args:
-        status_data: Raw status data to sanitize
-        verbosity: Output verbosity level
-        project_root: Project root for relative path conversion
-        user_context: Optional user context for logging
-
-    Returns:
-        Sanitized status data
-    """
-
     return get_secure_status_formatter(project_root).format_status(
         status_data, verbosity, user_context
     )