linux-mcp-server 0.1.0.dev0__py3-none-any.whl

linux_mcp_server/__init__.py

@@ -0,0 +1,4 @@
+"""Linux MCP Server - Read-only diagnostics and troubleshooting for RHEL systems."""
+
+__version__ = "0.1.0"
+

linux_mcp_server/__main__.py

@@ -0,0 +1,30 @@
+"""Main entry point for the Linux MCP Server."""
+
+import logging
+import sys
+from .logging_config import setup_logging
+from .server import main
+
+
+def cli():
+    """Console script entry point for the Linux MCP Server."""
+    # Initialize logging first, before any other operations
+    setup_logging()
+    
+    logger = logging.getLogger(__name__)
+    logger.info("Starting Linux MCP Server")
+    
+    try:
+        # FastMCP.run() creates its own event loop, don't use asyncio.run()
+        main()
+    except KeyboardInterrupt:
+        logger.info("Linux MCP Server stopped by user")
+        sys.exit(0)
+    except Exception as e:
+        logger.critical(f"Fatal error in Linux MCP Server: {e}", exc_info=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    cli()
+

linux_mcp_server/audit.py

@@ -0,0 +1,285 @@
+"""Audit logging utilities for Linux MCP Server.
+
+This module provides helper functions for consistent audit logging across
+the entire MCP server. All functions add structured context to log records
+that can be output in both human-readable and JSON formats.
+"""
+
+import logging
+from typing import Any, Dict, Optional
+from contextlib import contextmanager
+
+
+# Sensitive field names that should be redacted in logs
+SENSITIVE_FIELDS = {
+    'password', 'passwd', 'pwd',
+    'secret', 'api_key', 'apikey',
+    'token', 'auth', 'authorization',
+    'private_key', 'privatekey'
+}
+
+
+def sanitize_parameters(params: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Sanitize parameters by redacting sensitive fields.
+    
+    Args:
+        params: Dictionary of parameters to sanitize
+        
+    Returns:
+        Dictionary with sensitive fields redacted
+    """
+    if not params:
+        return params
+    
+    sanitized = {}
+    for key, value in params.items():
+        # Check if key is sensitive
+        key_lower = key.lower().replace('_', '').replace('-', '')
+        is_sensitive = any(sensitive in key_lower for sensitive in 
+                          [s.replace('_', '') for s in SENSITIVE_FIELDS])
+        
+        if is_sensitive:
+            sanitized[key] = "***REDACTED***"
+        elif isinstance(value, dict):
+            # Recursively sanitize nested dicts
+            sanitized[key] = sanitize_parameters(value)
+        else:
+            sanitized[key] = value
+    
+    return sanitized
+
+
+@contextmanager
+def AuditContext(**extra_fields):
+    """
+    Context manager for adding extra fields to all log records.
+    
+    Usage:
+        with AuditContext(tool="list_services", host="server1.com") as logger:
+            logger.info("Starting operation")
+    
+    Args:
+        **extra_fields: Additional fields to add to log records
+        
+    Yields:
+        Logger with extra fields
+    """
+    logger = logging.getLogger()
+    
+    # Create adapter with extra fields
+    class ContextAdapter(logging.LoggerAdapter):
+        def process(self, msg, kwargs):
+            # Add extra fields to the record
+            if 'extra' not in kwargs:
+                kwargs['extra'] = {}
+            kwargs['extra'].update(self.extra)
+            return msg, kwargs
+    
+    adapter = ContextAdapter(logger, extra_fields)
+    yield adapter
+
+
+def log_tool_call(tool_name: str, parameters: Dict[str, Any]):
+    """
+    Log a tool invocation.
+    
+    Args:
+        tool_name: Name of the tool being called
+        parameters: Tool parameters (will be sanitized)
+    """
+    logger = logging.getLogger(__name__)
+    
+    # Determine if local or remote execution
+    execution_mode = "remote" if parameters.get("host") else "local"
+    
+    # Sanitize parameters
+    safe_params = sanitize_parameters(parameters)
+    
+    # Build log record with extra fields
+    extra = {
+        'event': 'TOOL_CALL',
+        'tool': tool_name,
+        'execution_mode': execution_mode,
+    }
+    
+    # Add host and username if present
+    if 'host' in parameters:
+        extra['host'] = parameters['host']
+    if 'username' in parameters:
+        extra['username'] = parameters['username']
+    
+    # Add sanitized parameters as string
+    params_str = ', '.join(f'{k}={v}' for k, v in safe_params.items() 
+                           if k not in ['host', 'username'])
+    
+    message = f"TOOL_CALL: {tool_name}"
+    if params_str:
+        message += f" | {params_str}"
+    
+    logger.info(message, extra=extra)
+
+
+def log_tool_complete(tool_name: str, status: str, duration: float, error: Optional[str] = None):
+    """
+    Log tool completion.
+    
+    Args:
+        tool_name: Name of the tool
+        status: Completion status ("success" or "error")
+        duration: Execution time in seconds
+        error: Optional error message
+    """
+    logger = logging.getLogger(__name__)
+    
+    extra = {
+        'event': 'TOOL_COMPLETE',
+        'tool': tool_name,
+        'status': status,
+        'duration': f"{duration:.3f}s",
+    }
+    
+    message = f"TOOL_COMPLETE: {tool_name}"
+    
+    if status == "error":
+        if error:
+            extra['error'] = error
+            message += f" | error: {error}"
+        logger.error(message, extra=extra)
+    else:
+        logger.info(message, extra=extra)
+
+
+def log_ssh_connect(
+    host: str,
+    username: str,
+    status: str,
+    reused: bool = False,
+    key_path: Optional[str] = None,
+    error: Optional[str] = None
+):
+    """
+    Log SSH connection event.
+    
+    Verbosity is tiered based on log level:
+    - INFO: Basic connection success/failure
+    - DEBUG: Detailed information including key path, reuse status
+    
+    Args:
+        host: Remote host
+        username: SSH username
+        status: Connection status ("success" or "failed")
+        reused: Whether connection was reused (shown at DEBUG level)
+        key_path: Path to SSH key used (shown at DEBUG level)
+        error: Optional error message
+    """
+    logger = logging.getLogger(__name__)
+    
+    user_host = f"{username}@{host}"
+    
+    if status == "success":
+        extra = {
+            'event': 'SSH_CONNECT',
+            'host': host,
+            'username': username,
+            'status': status,
+        }
+        
+        # At INFO level, just log basic success
+        message = f"SSH_CONNECT: {user_host}"
+        
+        # At DEBUG level, add more details
+        if logger.isEnabledFor(logging.DEBUG):
+            if reused is not None:
+                extra['reused'] = reused
+            if key_path:
+                extra['key'] = key_path
+        
+        logger.info(message, extra=extra)
+        
+    else:
+        # Connection failed
+        extra = {
+            'event': 'SSH_CONNECT_FAILED',
+            'host': host,
+            'username': username,
+            'status': 'failed',
+        }
+        
+        if error:
+            extra['reason'] = error
+        
+        message = f"SSH_AUTH_FAILED: {user_host}"
+        if error:
+            message += f" | reason: {error}"
+        
+        logger.warning(message, extra=extra)
+
+
+def log_ssh_command(
+    command: str,
+    host: str,
+    exit_code: int,
+    duration: Optional[float] = None
+):
+    """
+    Log SSH command execution.
+    
+    Verbosity is tiered based on log level:
+    - INFO: Command and exit code
+    - DEBUG: Also includes execution duration
+    
+    Args:
+        command: Command that was executed
+        host: Remote host
+        exit_code: Command exit code
+        duration: Optional execution duration in seconds (shown at DEBUG level)
+    """
+    logger = logging.getLogger(__name__)
+    
+    extra = {
+        'event': 'REMOTE_EXEC',
+        'command': command,
+        'host': host,
+        'exit_code': exit_code,
+    }
+    
+    message = f"REMOTE_EXEC: {command} | host={host} | exit_code={exit_code}"
+    
+    # At DEBUG level, include duration
+    if duration is not None and logger.isEnabledFor(logging.DEBUG):
+        extra['duration'] = f"{duration:.3f}s"
+        message += f" | duration={duration:.3f}s"
+    
+    logger.info(message, extra=extra)
+
+
+def log_operation(
+    operation: str,
+    message: str,
+    level: int = logging.INFO,
+    **context
+):
+    """
+    Log a general operation with context.
+    
+    This is a generic logging function for operations that don't fit
+    other specific logging functions.
+    
+    Args:
+        operation: Name of the operation
+        message: Log message
+        level: Log level (default: INFO)
+        **context: Additional context fields
+    """
+    logger = logging.getLogger(__name__)
+    
+    extra = {
+        'operation': operation,
+        **context
+    }
+    
+    full_message = f"{operation}: {message}"
+    
+    logger.log(level, full_message, extra=extra)
+

linux_mcp_server/logging_config.py

@@ -0,0 +1,144 @@
+"""Centralized logging configuration for Linux MCP Server.
+
+Simplified logging setup with standard Python logging infrastructure.
+Supports structured logging with extra fields for audit and diagnostic purposes.
+"""
+
+import json
+import logging
+import logging.handlers
+import os
+from pathlib import Path
+
+
+def get_log_directory() -> Path:
+    """Get the log directory path, creating it if necessary."""
+    env_log_dir = os.getenv("LINUX_MCP_LOG_DIR")
+    log_dir = Path(env_log_dir) if env_log_dir else Path.home() / ".local" / "share" / "linux-mcp-server" / "logs"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir
+
+
+def get_log_level() -> int:
+    """Get the log level from environment variable (defaults to INFO)."""
+    level_name = os.getenv("LINUX_MCP_LOG_LEVEL", "INFO").upper()
+    return getattr(logging, level_name, logging.INFO)
+
+
+def get_retention_days() -> int:
+    """Get the log retention days from environment variable (defaults to 10)."""
+    try:
+        return int(os.getenv("LINUX_MCP_LOG_RETENTION_DAYS", "10"))
+    except ValueError:
+        return 10
+
+
+class StructuredFormatter(logging.Formatter):
+    """
+    Structured log formatter supporting extra fields.
+    
+    Format: TIMESTAMP | LEVEL | MODULE | MESSAGE | key=value ...
+    Extra fields added to LogRecord are appended as key=value pairs.
+    """
+    
+    STANDARD_FIELDS = {
+        'name', 'msg', 'args', 'created', 'filename', 'funcName', 'levelname',
+        'levelno', 'lineno', 'module', 'msecs', 'message', 'pathname', 'process',
+        'processName', 'relativeCreated', 'thread', 'threadName', 'exc_info',
+        'exc_text', 'stack_info', 'asctime', 'taskName'
+    }
+    
+    def format(self, record: logging.LogRecord) -> str:
+        """Format a log record with extra fields."""
+        # Base message
+        base_msg = super().format(record)
+        
+        # Append extra fields as key=value pairs
+        extra_fields = [f"{k}={v}" for k, v in record.__dict__.items() 
+                       if k not in self.STANDARD_FIELDS]
+        
+        return f"{base_msg} | {' | '.join(extra_fields)}" if extra_fields else base_msg
+
+
+class JSONFormatter(logging.Formatter):
+    """JSON log formatter for machine-readable logs."""
+    
+    EXCLUDE_FIELDS = {
+        'args', 'exc_text', 'exc_info', 'stack_info', 'filename', 'funcName',
+        'lineno', 'module', 'msecs', 'pathname', 'process', 'processName',
+        'relativeCreated', 'thread', 'threadName', 'taskName'
+    }
+    
+    def format(self, record: logging.LogRecord) -> str:
+        """Format a log record as JSON."""
+        log_data = {
+            'timestamp': self.formatTime(record, self.datefmt),
+            'level': record.levelname,
+            'logger': record.name,
+            'message': record.getMessage(),
+        }
+        
+        # Add exception info if present
+        if record.exc_info:
+            log_data['exception'] = self.formatException(record.exc_info)
+        
+        # Add extra fields
+        for key, value in record.__dict__.items():
+            if (key not in self.EXCLUDE_FIELDS and key not in log_data 
+                and key not in {'name', 'msg', 'levelname', 'levelno', 'created'}):
+                log_data[key] = value
+        
+        return json.dumps(log_data)
+
+
+def setup_logging():
+    """Set up logging with structured formatters and rotation."""
+    log_dir = get_log_directory()
+    log_level = get_log_level()
+    retention_days = get_retention_days()
+    
+    # Configure root logger
+    root_logger = logging.getLogger()
+    root_logger.setLevel(log_level)
+    root_logger.handlers.clear()  # Remove existing handlers
+    
+    # Human-readable text log
+    text_handler = logging.handlers.TimedRotatingFileHandler(
+        filename=log_dir / "server.log",
+        when='midnight',
+        interval=1,
+        backupCount=retention_days,
+        encoding='utf-8',
+    )
+    text_handler.setLevel(log_level)
+    text_handler.setFormatter(StructuredFormatter(
+        '%(asctime)s | %(levelname)s | %(name)s | %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    ))
+    text_handler.suffix = "%Y-%m-%d"
+    root_logger.addHandler(text_handler)
+    
+    # JSON log
+    json_handler = logging.handlers.TimedRotatingFileHandler(
+        filename=log_dir / "server.json",
+        when='midnight',
+        interval=1,
+        backupCount=retention_days,
+        encoding='utf-8',
+    )
+    json_handler.setLevel(log_level)
+    json_handler.setFormatter(JSONFormatter(datefmt='%Y-%m-%dT%H:%M:%S'))
+    json_handler.suffix = "%Y-%m-%d"
+    root_logger.addHandler(json_handler)
+    
+    # Console handler for development
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(log_level)
+    console_handler.setFormatter(StructuredFormatter(
+        '%(asctime)s | %(levelname)s | %(name)s | %(message)s',
+        datefmt='%Y-%m-%d %H:%M:%S'
+    ))
+    root_logger.addHandler(console_handler)
+    
+    logging.getLogger(__name__).info(f"Logging initialized: {log_dir}")
+