Logging and Monitoring API¶

class SSHLogger:
    """Enhanced logger for SpindleX with security and performance features."""

    def __init__(self, name: str, logger: Optional[logging.Logger] = None):
        """
        Initialize SSH logger.

        Args:
            name: Logger name
            logger: Existing logger instance (if None, creates new one)
        """
        self.name = name
        self.logger = logger or logging.getLogger(name)

        from .sanitizer import SanitizingFilter

        has_filter = any(isinstance(f, SanitizingFilter) for f in self.logger.filters)
        if not has_filter:
            self.logger.addFilter(SanitizingFilter())

        self._security_logger: Optional[logging.Logger] = None
        self._performance_logger: Optional[logging.Logger] = None

    def debug(self, msg: str, *args: Any, **kwargs: Any) -> None:
        """Log debug message."""
        self.logger.debug(msg, *args, **kwargs)

    def info(self, msg: str, *args: Any, **kwargs: Any) -> None:
        """Log info message."""
        self.logger.info(msg, *args, **kwargs)

    def warning(self, msg: str, *args: Any, **kwargs: Any) -> None:
        """Log warning message."""
        self.logger.warning(msg, *args, **kwargs)

    def error(self, msg: str, *args: Any, **kwargs: Any) -> None:
        """Log error message."""
        self.logger.error(msg, *args, **kwargs)

    def critical(self, msg: str, *args: Any, **kwargs: Any) -> None:
        """Log critical message."""
        self.logger.critical(msg, *args, **kwargs)

    def exception(self, msg: str, *args: Any, **kwargs: Any) -> None:
        """Log exception with traceback."""
        self.logger.exception(msg, *args, **kwargs)

    def security_event(
        self,
        event_type: str,
        message: str,
        client_ip: str = "unknown",
        username: str = "unknown",
        **kwargs: Any,
    ) -> None:
        """
        Log security-related event.

        Args:
            event_type: Type of security event (auth_success, auth_failure, etc.)
            message: Event description
            client_ip: Client IP address
            username: Username involved in event
            **kwargs: Additional event data
        """
        if not self._security_logger:
            self._security_logger = logging.getLogger(f"{self.name}.security")

        extra = {
            "event_type": event_type,
            "client_ip": client_ip,
            "username": username,
            **kwargs,
        }

        self._security_logger.info(message, extra=extra)

    def performance_metric(
        self, operation: str, duration: float, **kwargs: Any
    ) -> None:
        """
        Log performance metric.

        Args:
            operation: Operation name
            duration: Operation duration in seconds
            **kwargs: Additional metric data
        """
        if not self._performance_logger:
            self._performance_logger = logging.getLogger(f"{self.name}.performance")

        extra = {"operation": operation, "duration_seconds": duration, **kwargs}

        message = f"Operation '{operation}' completed in {duration:.4f}s"
        self._performance_logger.info(message, extra=extra)

    def protocol_debug(
        self, direction: str, message_type: str, data: dict[str, Any], **kwargs: Any
    ) -> None:
        """
        Log protocol-level debugging information.

        Args:
            direction: 'sent' or 'received'
            message_type: SSH message type
            data: Message data
            **kwargs: Additional debug data
        """
        extra = {
            "direction": direction,
            "message_type": message_type,
            "data": data,
            **kwargs,
        }

        message = f"SSH {direction} {message_type}"
        self.logger.debug(message, extra=extra)

class LogSanitizer:
    """Sanitizes log messages to prevent sensitive information leakage."""

    # Patterns for sensitive data that should be redacted
    SENSITIVE_PATTERNS: dict[str, Pattern[str]] = {
        # Passwords and secrets (Captured prefix and value) - handles multiple separators
        "password": re.compile(r'(?i)(\bpassword(?:[\s:=]|is\b)+)([^\s,"}]+)'),
        "secret": re.compile(r'(?i)(\bsecret(?:[\s:=]|is\b)+)([^\s,"}]+)'),
        "token": re.compile(r'(?i)(\btoken(?:[\s:=]|is\b)+)([^\s,"}]+)'),
        "key": re.compile(
            r'(?i)(\b(?:api_key|private_key|host_key|secret_key|auth_key|access_key|encryption_key)(?:[\s:=]|is\b)+)([^\s,"}]+)'
        ),
        "passphrase": re.compile(r'(?i)(\bpassphrase(?:[\s:=]|is\b)+)([^\s,"}]+)'),
        # SSH key material (base64 encoded)
        "ssh_key": re.compile(r"AAAA[A-Za-z0-9+/]{20,}={0,2}"),
        # Private key headers/footers
        "private_key": re.compile(
            r"-----BEGIN [A-Z ]+PRIVATE KEY-----.*?-----END [A-Z ]+PRIVATE KEY-----",
            re.DOTALL,
        ),
        # IP addresses (partial redaction)
        "ip": re.compile(r"(\d{1,3}\.\d{1,3}\.\d{1,3}\.)\d{1,3}"),
        # Hostnames (partial redaction for internal hosts)
        "hostname": re.compile(r"([a-zA-Z0-9-]+\.)(internal|local|corp|lan)"),
    }

    # Replacement patterns
    REPLACEMENTS = {
        "password": "[PASSWORD_REDACTED]",  # nosec
        "secret": "[SECRET_REDACTED]",  # nosec
        "token": "[TOKEN_REDACTED]",  # nosec
        "key": "[KEY_REDACTED]",  # nosec
        "passphrase": "[PASSPHRASE_REDACTED]",  # nosec
        "ssh_key": "[SSH_KEY_REDACTED]",  # nosec
        "private_key": "[PRIVATE_KEY_REDACTED]",  # nosec
        "ip_partial": r"\1***",
        "hostname_partial": r"\1[REDACTED]",
    }

    @classmethod
    def sanitize_message(cls, message: str) -> str:
        """
        Sanitize a log message by redacting sensitive information.

        Args:
            message: The log message to sanitize

        Returns:
            Sanitized message with sensitive data redacted
        """
        sanitized = message

        # Apply password/secret patterns using groups
        for pattern_type in ["password", "secret", "token", "key", "passphrase"]:
            pattern = cls.SENSITIVE_PATTERNS[pattern_type]

            def replace_with_group(match: re.Match[str], pt: str = pattern_type) -> str:
                return match.group(1) + cls.REPLACEMENTS[pt]

            sanitized = pattern.sub(replace_with_group, sanitized)

        # SSH key material
        sanitized = cls.SENSITIVE_PATTERNS["ssh_key"].sub(
            cls.REPLACEMENTS["ssh_key"], sanitized
        )

        # Private key blocks
        sanitized = cls.SENSITIVE_PATTERNS["private_key"].sub(
            cls.REPLACEMENTS["private_key"], sanitized
        )

        # IP addresses (keep first 3 octets)
        sanitized = cls.SENSITIVE_PATTERNS["ip"].sub(
            cls.REPLACEMENTS["ip_partial"], sanitized
        )

        # Internal hostnames
        sanitized = cls.SENSITIVE_PATTERNS["hostname"].sub(
            cls.REPLACEMENTS["hostname_partial"], sanitized
        )

        return sanitized

    @classmethod
    def sanitize_dict(cls, data: dict[str, Any]) -> dict[str, Any]:
        """
        Sanitize a dictionary by redacting sensitive keys and values.

        Args:
            data: Dictionary to sanitize

        Returns:
            Sanitized dictionary
        """
        sanitized: dict[str, Any] = {}
        sensitive_keys = {
            "password",
            "secret",
            "token",
            "key",
            "private_key",
            "passphrase",
        }

        for key, value in data.items():
            if key.lower() in sensitive_keys:
                sanitized[key] = "[REDACTED]"
            elif isinstance(value, str):
                sanitized[key] = cls.sanitize_message(value)
            elif isinstance(value, dict):
                sanitized[key] = cls.sanitize_dict(value)
            elif isinstance(value, (list, tuple)):
                sanitized_list: list[Any] = []
                for item in value:
                    if isinstance(item, str):
                        sanitized_list.append(cls.sanitize_message(item))
                    elif isinstance(item, dict):
                        sanitized_list.append(cls.sanitize_dict(item))
                    else:
                        sanitized_list.append(item)
                sanitized[key] = sanitized_list
            else:
                sanitized[key] = value

        return sanitized

class SanitizingFilter(logging.Filter):
    """Logging filter that redacts sensitive information from all log records."""

    def filter(self, record: logging.LogRecord) -> bool:
        record.msg = LogSanitizer.sanitize_message(str(record.msg))
        if record.args:
            if isinstance(record.args, dict):
                record.args = LogSanitizer.sanitize_dict(record.args)
            else:
                record.args = tuple(
                    LogSanitizer.sanitize_message(str(a)) if isinstance(a, str) else a
                    for a in record.args
                )
        return True

class DebugFormatter(SSHFormatter):
    """Detailed formatter for debugging with protocol information."""

    def __init__(self, sanitize: bool = False):
        """Initialize debug formatter with detailed format."""
        fmt = (
            "[%(asctime)s.%(msecs)03d] %(name)s.%(levelname)s "
            "[%(filename)s:%(lineno)d] %(funcName)s(): %(message)s"
        )
        datefmt = "%Y-%m-%d %H:%M:%S"
        super().__init__(fmt, datefmt, sanitize=sanitize)

class JSONFormatter(logging.Formatter):
    """JSON log formatter for structured logging."""

    def __init__(self, sanitize: bool = True, include_extra: bool = True):
        """
        Initialize JSON formatter.

        Args:
            sanitize: Whether to sanitize sensitive information
            include_extra: Whether to include extra fields from LogRecord
        """
        super().__init__()
        self.sanitize = sanitize
        self.include_extra = include_extra

    def format(self, record: logging.LogRecord) -> str:
        """Format log record as JSON."""
        log_data = {
            "timestamp": time.time(),
            "level": record.levelname,
            "logger": record.name,
            "message": (
                str(record.msg) % record.args if record.args else str(record.msg)
            ),
            "module": record.module,
            "function": record.funcName,
            "line": record.lineno,
        }

        # Add exception info if present
        if record.exc_info:
            log_data["exception"] = self.formatException(record.exc_info)

        # Add extra fields
        if self.include_extra:
            extra_fields = {}
            for key, value in record.__dict__.items():
                if key not in {
                    "name",
                    "msg",
                    "args",
                    "levelname",
                    "levelno",
                    "pathname",
                    "filename",
                    "module",
                    "exc_info",
                    "exc_text",
                    "stack_info",
                    "lineno",
                    "funcName",
                    "created",
                    "msecs",
                    "relativeCreated",
                    "thread",
                    "threadName",
                    "processName",
                    "process",
                    "getMessage",
                }:
                    extra_fields[key] = value

            if extra_fields:
                log_data["extra"] = extra_fields

        # Sanitize if requested
        if self.sanitize:
            log_data = LogSanitizer.sanitize_dict(log_data)

        return json.dumps(log_data, default=str, separators=(",", ":"))

class SSHFormatter(logging.Formatter):
    """Standard SpindleX log formatter with security sanitization."""

    def __init__(
        self,
        fmt: Optional[str] = None,
        datefmt: Optional[str] = None,
        sanitize: bool = True,
    ):
        """
        Initialize SSH formatter.

        Args:
            fmt: Log format string
            datefmt: Date format string
            sanitize: Whether to sanitize sensitive information
        """
        if fmt is None:
            fmt = "[%(asctime)s] %(name)s.%(levelname)s: %(message)s"
        if datefmt is None:
            datefmt = "%Y-%m-%d %H:%M:%S"

        super().__init__(fmt, datefmt)
        self.sanitize = sanitize

    def format(self, record: logging.LogRecord) -> str:
        """Format log record. Sanitization is handled by SanitizingFilter."""
        return super().format(record)