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

linux_mcp_server/__init__.py

@@ -0,0 +1,4 @@
+import importlib.metadata
+
+
+__version__ = importlib.metadata.version(__spec__.parent)

linux_mcp_server/__main__.py

@@ -0,0 +1,30 @@
+"""Main entry point for the Linux MCP Server."""
+
+import logging
+import sys
+
+from linux_mcp_server import __version__
+from linux_mcp_server.logging_config import setup_logging
+from linux_mcp_server.server import main
+
+
+def cli():
+    """Console script entry point for the Linux MCP Server."""
+    setup_logging()
+
+    logger = logging.getLogger("linux-mcp-server")
+    logger.info(f"Starting Linux MCP Server {__version__}")
+
+    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,331 @@
+"""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 functools
+import inspect
+import logging
+import time
+import typing as t
+
+from contextlib import contextmanager
+from datetime import timedelta
+
+from linux_mcp_server.utils import StrEnum
+
+
+Function: t.TypeAlias = t.Callable[..., t.Any]
+
+# Sensitive field names that should be redacted in logs
+SENSITIVE_FIELDS = {
+    "password",
+    "passwd",
+    "pwd",
+    "secret",
+    "api_key",
+    "apikey",
+    "token",
+    "auth",
+    "authorization",
+    "private_key",
+    "privatekey",
+}
+
+
+class Event(StrEnum):
+    LOCAL_EXEC_ERROR = "LOCAL_EXEC_ERROR"
+    REMOTE_EXEC = "REMOTE_EXEC"
+    REMOTE_EXEC_ERROR = "REMOTE_EXEC_ERROR"
+    SSH_AUTH_FAILED = "SSH_AUTH_FAILED"
+    SSH_CONNECT = "SSH_CONNECT"
+    SSH_CONNECTING = "SSH_CONNECTING"
+    TOOL_CALL = "TOOL_CALL"
+    TOOL_COMPLETE = "TOOL_COMPLETE"
+
+
+class ExecutionMode(StrEnum):
+    REMOTE = "REMOTE"
+    LOCAL = "LOCAL"
+
+
+class Status(StrEnum):
+    success = "success"
+    error = "error"
+
+
+def sanitize_parameters(params: dict[str, t.Any]) -> dict[str, t.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"] = {}
+
+            if isinstance(self.extra, t.Iterable):
+                kwargs["extra"].update(self.extra)
+
+            return msg, kwargs
+
+    adapter = ContextAdapter(logger, extra_fields)
+    yield adapter
+
+
+def _log_event_start(
+    logger: logging.Logger,
+    tool_name: str,
+    params: dict[t.Any, t.Any],
+) -> int:
+    """
+    Emit a log event and return a performance counter timestamp.
+
+    The timestamp is in nanoseconds. It is meant to be used to calculate
+    total execution time.
+    """
+    execution_mode = ExecutionMode.REMOTE if params.get("host") else ExecutionMode.LOCAL
+    safe_params = sanitize_parameters(params)
+
+    extra = {
+        "tool": tool_name,
+        "execution_mode": execution_mode,
+    }
+    if "host" in params:
+        extra["host"] = params["host"]
+
+    if "username" in params:
+        extra["username"] = params["username"]
+
+    message = f"{Event.TOOL_CALL}: {tool_name}"
+
+    params_str = ", ".join(f"{k}={v}" for k, v in safe_params.items() if k not in ["host", "username"])
+    if params_str:
+        message += f" | {params_str}"
+
+    logger.info(message, extra=extra)
+
+    return time.perf_counter_ns()
+
+
+def _log_event_complete(
+    logger: logging.Logger,
+    tool_name: str,
+    start_time: int,
+    error: Exception | None = None,
+) -> None:
+    """
+    Log the completion of a tool call and calculate the total execution time.
+    """
+    stop_time = time.perf_counter_ns()
+    duration = timedelta(microseconds=(stop_time - start_time) / 1_000)
+    status = Status.error if error else Status.success
+    extra = {
+        "tool": tool_name,
+        "status": status,
+        "duration": f"{duration}s",
+    }
+
+    message = f"{Event.TOOL_COMPLETE}: {tool_name}"
+
+    if error:
+        extra["error"] = str(error)
+        message += f" | error: {error}"
+        logger.error(message, extra=extra)
+    else:
+        logger.info(message, extra=extra)
+
+
+def log_tool_call(func: t.Callable) -> Function:
+    """Decorator to log tool calls
+
+    Works with sync or async functions.
+    """
+    logger = logging.getLogger("linux-mcp-server")
+    tool_name = func.__name__
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        start_time = _log_event_start(logger, tool_name, kwargs)
+        error = None
+        result = None
+
+        try:
+            result = func(*args, **kwargs)
+        except Exception as exc:
+            error = exc
+            _log_event_complete(logger, tool_name, start_time, error)
+            raise
+
+        _log_event_complete(logger, tool_name, start_time, error)
+
+        return result
+
+    @functools.wraps(func)
+    async def awrapper(*args, **kwargs):
+        start_time = _log_event_start(logger, tool_name, kwargs)
+        error = None
+        result = None
+
+        try:
+            result = await func(*args, **kwargs)
+        except Exception as exc:
+            error = exc
+            _log_event_complete(logger, tool_name, start_time, error)
+            raise
+
+        _log_event_complete(logger, tool_name, start_time, error)
+
+        return result
+
+    if inspect.iscoroutinefunction(func):
+        return awrapper
+
+    return wrapper
+
+
+def log_ssh_connect(
+    host: str,
+    username: str,
+    status: str,
+    reused: bool = False,
+    key_path: str | None = None,
+    error: str | None = 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 == Status.success:
+        extra = {
+            "host": host,
+            "username": username,
+            "status": status,
+        }
+
+        # At INFO level, just log basic success
+        message = f"{Event.SSH_CONNECT}: {user_host}"
+
+        # At DEBUG level, add more details
+        if logger.isEnabledFor(logging.DEBUG):
+            if reused is not None:
+                extra["reused"] = str(reused)
+            if key_path:
+                extra["key"] = key_path
+
+        logger.info(message, extra=extra)
+
+    else:
+        # Connection failed
+        extra = {
+            "host": host,
+            "username": username,
+            "status": "failed",
+        }
+
+        if error:
+            extra["reason"] = error
+
+        message = f"{Event.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: float | None = 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 = {
+        "command": command,
+        "host": host,
+        "exit_code": exit_code,
+    }
+
+    message = f"{Event.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)

linux_mcp_server/connection/ssh.py

@@ -0,0 +1,338 @@
+"""SSH executor for remote command execution.
+
+This module provides functionality to execute commands on remote systems via SSH,
+with connection pooling and SSH key discovery. It seamlessly routes commands to
+either local or remote execution based on the provided parameters.
+"""
+
+import asyncio
+import getpass
+import logging
+import os
+import shlex
+import subprocess
+import time
+
+from pathlib import Path
+from typing import Optional
+
+import asyncssh
+
+from linux_mcp_server.audit import Event
+from linux_mcp_server.audit import log_ssh_command
+from linux_mcp_server.audit import log_ssh_connect
+from linux_mcp_server.audit import Status
+
+
+logger = logging.getLogger("linux-mcp-server")
+
+
+def discover_ssh_key() -> str | None:
+    """
+    Discover SSH private key for authentication.
+
+    Checks in order:
+    1. LINUX_MCP_SSH_KEY_PATH environment variable
+    2. Default locations: ~/.ssh/id_ed25519, ~/.ssh/id_rsa, ~/.ssh/id_ecdsa
+
+    Returns:
+        Path to SSH private key if found, None otherwise.
+    """
+    logger.debug("Discovering SSH key for authentication")
+
+    # Check environment variable first
+    env_key = os.getenv("LINUX_MCP_SSH_KEY_PATH")
+    if env_key:
+        logger.debug(f"Checking SSH key from environment: {env_key}")
+        key_path = Path(env_key)
+        if key_path.exists() and key_path.is_file():
+            logger.info(f"Using SSH key from environment: {env_key}")
+            return str(key_path)
+        else:
+            logger.warning(f"SSH key specified in LINUX_MCP_SSH_KEY_PATH not found: {env_key}")
+            return None
+
+    # Check default locations (prefer modern algorithms)
+    if os.getenv("LINUX_MCP_SEARCH_FOR_SSH_KEY", False):
+        home = Path.home()
+        default_keys = [
+            home / ".ssh" / "id_ed25519",
+            home / ".ssh" / "id_ecdsa",
+            home / ".ssh" / "id_rsa",
+        ]
+
+        logger.debug(f"Checking default SSH key locations: {[str(k) for k in default_keys]}")
+
+        for key_path in default_keys:
+            if key_path.exists() and key_path.is_file():
+                logger.info(f"Using SSH key: {key_path}")
+                return str(key_path)
+
+        logger.warning("No SSH private key found in default locations")
+
+    logger.debug("Not providing an SSH key")
+
+
+class SSHConnectionManager:
+    """
+    Manages SSH connections with connection pooling.
+
+    This class implements a singleton pattern to maintain a pool of SSH connections
+    across the lifetime of the application, improving performance by reusing
+    connections to the same hosts.
+    """
+
+    _instance: Optional["SSHConnectionManager"] = None
+    _connections: dict[str, asyncssh.SSHClientConnection]
+    _ssh_key: str | None
+
+    def __new__(cls):
+        """Implement singleton pattern."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._connections = {}
+            cls._instance._ssh_key = discover_ssh_key()
+        return cls._instance
+
+    async def get_connection(self, host: str, username: str) -> asyncssh.SSHClientConnection:
+        """
+        Get or create an SSH connection to a host.
+
+        Args:
+            host: Remote host address
+            username: SSH username
+
+        Returns:
+            SSH connection object
+
+        Raises:
+            ConnectionError: If connection fails
+        """
+        key = f"{username}@{host}"
+
+        # Return existing connection if available
+        if key in self._connections:
+            conn = self._connections[key]
+            if not conn.is_closed():
+                # DEBUG level: Log connection reuse and pool state
+                logger.debug(f"SSH_REUSE: {key} | pool_size={len(self._connections)}")
+                # Use audit log with connection reuse info
+                log_ssh_connect(host, username, status=Status.success, reused=True, key_path=self._ssh_key)
+                return conn
+            else:
+                # Connection was closed, remove it
+                logger.debug(f"SSH_POOL: remove_closed_connection | connection={key}")
+                del self._connections[key]
+
+        # Create new connection
+        # DEBUG level: Log connection attempt before it completes
+        logger.debug(f"{Event.SSH_CONNECTING}: {key} | key={self._ssh_key or 'none'}")
+
+        try:
+            connect_kwargs = {
+                "host": host,
+                "username": username,
+                "known_hosts": None,  # Don't verify host keys for now
+                "passphrase": os.getenv("LINUX_MCP_KEY_PASSPHRASE"),
+            }
+
+            if self._ssh_key:
+                connect_kwargs["client_keys"] = [self._ssh_key]
+
+            conn = await asyncssh.connect(**connect_kwargs)
+            self._connections[key] = conn
+
+            # Log successful connection using audit function
+            log_ssh_connect(host, username, status=Status.success, reused=False, key_path=self._ssh_key)
+
+            # DEBUG level: Log pool state
+            logger.debug(f"SSH_POOL: add_connection | connections={len(self._connections)}")
+
+            return conn
+
+        except asyncssh.PermissionDenied as e:
+            # Use audit log for authentication failure
+            error_msg = str(e)
+            log_ssh_connect(host, username, status="failed", error=f"Permission denied: {error_msg}")
+            raise ConnectionError(f"Authentication failed for {username}@{host}") from e
+        except asyncssh.Error as e:
+            # Use audit log for connection failure
+            error_msg = str(e)
+            log_ssh_connect(host, username, status="failed", error=error_msg)
+            raise ConnectionError(f"Failed to connect to {username}@{host}: {e}") from e
+
+    async def execute_remote(
+        self,
+        command: list[str],
+        host: str,
+        username: str,
+    ) -> tuple[int, str, str]:
+        """
+        Execute a command on a remote host via SSH.
+
+        Args:
+            command: Command and arguments to execute
+            host: Remote host address
+            username: SSH username
+
+        Returns:
+            Tuple of (return_code, stdout, stderr)
+
+        Raises:
+            ConnectionError: If SSH connection fails
+        """
+        conn = await self.get_connection(host, username)
+
+        # Build command string with proper shell escaping
+        # Use shlex.quote() to ensure special characters (like \n in printf format) are preserved
+        cmd_str = shlex.join(command)
+
+        # Start timing for command execution
+        start_time = time.time()
+
+        try:
+            result = await conn.run(cmd_str, check=False)
+
+            return_code = result.exit_status if result.exit_status is not None else 0
+
+            # Ensure stdout and stderr are strings (asyncssh can return bytes or str)
+            stdout_raw = result.stdout if result.stdout else ""
+            stderr_raw = result.stderr if result.stderr else ""
+            stdout = stdout_raw if isinstance(stdout_raw, str) else stdout_raw.decode("utf-8", errors="replace")
+            stderr = stderr_raw if isinstance(stderr_raw, str) else stderr_raw.decode("utf-8", errors="replace")
+
+            # Calculate duration
+            duration = time.time() - start_time
+
+            # Use audit log for command execution
+            log_ssh_command(cmd_str, host, exit_code=return_code, duration=duration)
+
+            return return_code, stdout, stderr
+
+        except asyncssh.Error as e:
+            duration = time.time() - start_time
+            logger.error(
+                f"Error executing command on {username}@{host}: {e}",
+                extra={
+                    "event": Event.REMOTE_EXEC_ERROR,
+                    "command": cmd_str,
+                    "host": host,
+                    "duration": f"{duration:.3f}s",
+                    "error": str(e),
+                },
+            )
+            raise ConnectionError(f"Failed to execute command on {username}@{host}: {e}") from e
+
+    async def close_all(self):
+        """Close all SSH connections."""
+        connection_count = len(self._connections)
+        logger.info(f"Closing {connection_count} SSH connections")
+
+        for key, conn in list(self._connections.items()):
+            try:
+                logger.debug(f"SSH_CLOSE: {key}")
+                conn.close()
+                await conn.wait_closed()
+            except Exception as e:
+                logger.warning(f"Error closing connection to {key}: {e}")
+
+        self._connections.clear()
+        logger.debug(f"SSH_POOL: cleared | closed_connections={connection_count}")
+
+
+# Global connection manager instance
+_connection_manager = SSHConnectionManager()
+
+
+async def execute_command(
+    command: list[str],
+    host: str | None = None,
+    username: str | None = None,
+    **kwargs,
+) -> tuple[int, str, str]:
+    """
+    Execute a command locally or remotely.
+
+    This is the main entry point for command execution. It routes the command
+    to either local subprocess execution or remote SSH execution based on
+    whether host/username parameters are provided.
+
+    Args:
+        command: Command and arguments to execute
+        host: Optional remote host address
+        username: Optional SSH username (required if host is provided)
+        **kwargs: Additional arguments (reserved for future use)
+
+    Returns:
+        Tuple of (return_code, stdout, stderr)
+
+    Raises:
+        ValueError: If host is provided without username
+        ConnectionError: If remote connection fails
+
+    Examples:
+        # Local execution
+        >>> returncode, stdout, stderr = await execute_command(["ls", "-la"])
+
+        # Remote execution
+        >>> returncode, stdout, stderr = await execute_command(
+        ...     ["ls", "-la"],
+        ...     host="server.example.com",
+        ...     username="admin"
+        ... )
+    """
+    cmd_str = " ".join(command)
+
+    # Route to remote execution if host is provided
+    if host:
+        if not username:
+            username = getpass.getuser()
+
+        logger.debug(f"Routing to remote execution: {username}@{host} | command={cmd_str}")
+        return await _connection_manager.execute_remote(command, host, username)
+
+    # Local execution
+    logger.debug(f"LOCAL_EXEC: {cmd_str}")
+    return await _execute_local(command)
+
+
+async def _execute_local(command: list[str]) -> tuple[int, str, str]:
+    """
+    Execute a command locally using subprocess.
+
+    Args:
+        command: Command and arguments to execute
+
+    Returns:
+        Tuple of (return_code, stdout, stderr)
+    """
+    cmd_str = " ".join(command)
+    start_time = time.time()
+
+    try:
+        proc = await asyncio.create_subprocess_exec(*command, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        stdout_bytes, stderr_bytes = await proc.communicate()
+
+        return_code = proc.returncode if proc.returncode is not None else 0
+        stdout = stdout_bytes.decode("utf-8", errors="replace")
+        stderr = stderr_bytes.decode("utf-8", errors="replace")
+
+        duration = time.time() - start_time
+
+        # DEBUG level: Log local command execution with timing
+        logger.debug(f"LOCAL_EXEC completed: {cmd_str} | exit_code={return_code} | duration={duration:.3f}s")
+
+        return return_code, stdout, stderr
+
+    except Exception as e:
+        duration = time.time() - start_time
+        logger.error(
+            f"Error executing local command: {cmd_str}",
+            extra={
+                "event": Event.LOCAL_EXEC_ERROR,
+                "command": cmd_str,
+                "duration": f"{duration:.3f}s",
+                "error": str(e),
+            },
+        )
+        return 1, "", str(e)