server-management-lib 0.2.0__py3-none-any.whl

server_management_lib/__init__.py

@@ -0,0 +1,124 @@
+"""
+Server Management Library
+
+Shared components for server management MCPs:
+
+- Configuration loading (YAML + environment + XDG paths)
+- Security validation (commands, queries, paths)
+- SSH connection management (host key verification by default)
+- InfluxDB and Prometheus HTTP clients
+"""
+
+from .audit import AuditLogger, create_audit_logger
+from .base import (
+    ExecutorBase,
+    ExecutorError,
+    RemoteDirEntry,
+    RemoteFileError,
+    RemotePathError,
+)
+from .config import (
+    DEFAULT_CONFIG,
+    ConfigError,
+    ConfigNotFoundError,
+    config_schema,
+    load_config,
+    redact_config_values,
+    resolve_config_path,
+)
+from .executor import Executor, create_executor
+from .http_clients import InfluxDBClient, PrometheusClient, parse_duration
+from .local_executor import LocalExecutor
+from .operations import Operation
+from .output import DEFAULT_MAX_OUTPUT_BYTES, sanitize_output, strip_ansi
+from .rate_limit import (
+    RateLimitConfig,
+    RateLimiter,
+    create_rate_limiter,
+)
+from .redaction import REDACTED_VALUE, redact_env_content, redact_secrets
+from .responses import (
+    ToolOutput,
+    ToolResponse,
+    build_response,
+    make_structured_tool,
+)
+from .security import (
+    SNAPRAID_STATUS_SUDO_ARGV,
+    FileAccess,
+    SecurityValidator,
+    ServiceFilePath,
+)
+from .ssh_manager import SSHConfigurationError, SSHManager
+from .transport import (
+    BearerTokenMiddleware,
+    is_loopback_host,
+    run_streamable_http,
+    validate_http_binding,
+)
+from .tunnel import (
+    ActiveTunnel,
+    SSHTunnel,
+    SSHTunnelError,
+    TunnelConfig,
+    TunnelEndpoint,
+    close_metric_tunnels,
+    open_metric_tunnels,
+)
+
+__all__ = [
+    "DEFAULT_CONFIG",
+    "DEFAULT_MAX_OUTPUT_BYTES",
+    "REDACTED_VALUE",
+    "SNAPRAID_STATUS_SUDO_ARGV",
+    "ActiveTunnel",
+    "AuditLogger",
+    "BearerTokenMiddleware",
+    "ConfigError",
+    "ConfigNotFoundError",
+    "Executor",
+    "ExecutorBase",
+    "ExecutorError",
+    "FileAccess",
+    "InfluxDBClient",
+    "LocalExecutor",
+    "Operation",
+    "PrometheusClient",
+    "RateLimitConfig",
+    "RateLimiter",
+    "RemoteDirEntry",
+    "RemoteFileError",
+    "RemotePathError",
+    "SSHConfigurationError",
+    "SSHManager",
+    "SSHTunnel",
+    "SSHTunnelError",
+    "SecurityValidator",
+    "ServiceFilePath",
+    "ToolOutput",
+    "ToolResponse",
+    "TunnelConfig",
+    "TunnelEndpoint",
+    "__version__",
+    "build_response",
+    "close_metric_tunnels",
+    "config_schema",
+    "create_audit_logger",
+    "create_executor",
+    "create_rate_limiter",
+    "is_loopback_host",
+    "load_config",
+    "make_structured_tool",
+    "open_metric_tunnels",
+    "parse_duration",
+    "redact_config_values",
+    "redact_env_content",
+    "redact_secrets",
+    "resolve_config_path",
+    "run_streamable_http",
+    "sanitize_output",
+    "strip_ansi",
+    "validate_http_binding",
+]
+
+__version__ = "0.2.0"

server_management_lib/audit.py

@@ -0,0 +1,80 @@
+"""
+Append-only audit log for privileged operations.
+
+Every command, file read and blocked operation can be recorded as one JSON
+object per line. Logging is best effort: an unwritable log must never break the
+operation, but it is reported once.
+"""
+
+import json
+import logging
+import threading
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+REDACTED = "***REDACTED***"
+SENSITIVE_KEY_PARTS = ("password", "token", "secret", "api_key", "apikey", "key")
+
+
+def _redact(value: Any, key: str = "") -> Any:
+    if any(part in key.lower() for part in SENSITIVE_KEY_PARTS):
+        return REDACTED
+    if isinstance(value, dict):
+        return {k: _redact(v, str(k)) for k, v in value.items()}
+    if isinstance(value, list | tuple):
+        return [_redact(item) for item in value]
+    return value
+
+
+class AuditLogger:
+    """Write JSONL audit records to ``path`` when enabled."""
+
+    def __init__(self, path: str | Path | None = None, *, enabled: bool = False):
+        self.enabled = bool(enabled and path)
+        self.path = Path(path).expanduser() if path else None
+        self._lock = threading.Lock()
+        self._warned = False
+
+    def log(self, event: str, **fields: Any) -> None:
+        if not self.enabled or self.path is None:
+            return
+
+        record = {
+            "ts": datetime.now(UTC).isoformat(timespec="milliseconds"),
+            "event": event,
+            **_redact(fields),
+        }
+        try:
+            parent = self.path.parent
+            parent_existed = parent.exists()
+            parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+            if not parent_existed:
+                # mkdir honours the umask; make the new audit directory private.
+                parent.chmod(0o700)
+
+            line = json.dumps(record, default=str)
+            with self._lock, self.path.open("a", encoding="utf-8") as handle:
+                # The file may have been created by an older release with the
+                # default mode; tighten it on every write.
+                self.path.chmod(0o600)
+                handle.write(line + "\n")
+        except OSError as e:  # pragma: no cover - environment dependent
+            if not self._warned:
+                logger.warning("Cannot write audit log %s: %s", self.path, e)
+                self._warned = True
+
+
+def create_audit_logger(config: dict) -> AuditLogger:
+    """Build an :class:`AuditLogger` from the ``audit`` config section.
+
+    The HTTP clients receive the same logger as the executors so query
+    metadata is recorded in one audit log.
+    """
+    audit_config = config.get("audit", {}) or {}
+    return AuditLogger(
+        audit_config.get("path"),
+        enabled=audit_config.get("enabled", False),
+    )

server_management_lib/base.py

@@ -0,0 +1,55 @@
+"""
+Shared executor primitives.
+
+An executor runs validated commands and reads remote/local files. SSH and local
+implementations share output limits, audit logging and path-confinement rules.
+"""
+
+from dataclasses import dataclass
+
+from .audit import create_audit_logger
+from .output import DEFAULT_MAX_OUTPUT_BYTES
+from .security import SecurityValidator
+
+
+class ExecutorError(RuntimeError):
+    """Base class for executor errors."""
+
+
+class RemotePathError(ExecutorError):
+    """Raised when a path escapes its allowed base directory."""
+
+
+class RemoteFileError(ExecutorError):
+    """Raised when a file cannot be read safely."""
+
+
+@dataclass(frozen=True)
+class RemoteDirEntry:
+    """A single directory entry returned by an executor."""
+
+    name: str
+    longname: str
+    size: int
+
+
+def is_within(path: str, base: str) -> bool:
+    """Return True when ``path`` is ``base`` or below it (component-aware)."""
+    base = base.rstrip("/")
+    return path == base or path.startswith(base + "/")
+
+
+class ExecutorBase:
+    """Configuration, output limits and audit logging shared by executors."""
+
+    def __init__(self, config: dict, security: SecurityValidator):
+        self.config = config
+        self.security = security
+        self.services_base_path = security.services_base_path
+
+        output_config = config.get("output", {}) or {}
+        self.max_output_bytes = int(
+            output_config.get("max_bytes", DEFAULT_MAX_OUTPUT_BYTES)
+        )
+
+        self.audit = create_audit_logger(config)

server_management_lib/config.py

@@ -0,0 +1,385 @@
+"""
+Configuration loader for Server Management Library.
+
+Loads YAML configuration with sensible defaults for SSH, security,
+InfluxDB, Prometheus, and host data source settings.
+
+Resolution order (first match wins):
+
+1. explicit ``config_path`` argument (``--config``)
+2. the path in ``env_var`` (for example ``REMOTE_SERVER_MCP_CONFIG``)
+3. ``$XDG_CONFIG_HOME/<app_name>/config.yaml`` (``~/.config`` by default)
+4. ``./config.yaml`` (repo checkout / local development)
+
+Values from the environment override the YAML file, so secrets can stay out of
+the config file. A ``.env`` file next to the config file is loaded first (when
+``python-dotenv`` is installed), which matches the ``.env.example`` files.
+"""
+
+import copy
+import logging
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from .security import DEFAULT_HOST_UNITS
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_CONFIG: dict[str, Any] = {
+    # "ssh" (default) or "local" (run on the host where the MCP server runs)
+    "executor": "ssh",
+    # Container runtime used by the remote-server MCP operation catalog.
+    "container_runtime": "docker",
+    # MCP transport. stdio is the default; streamable-http is opt-in.
+    "transport": {
+        "type": "stdio",
+        "host": "127.0.0.1",
+        "port": 8000,
+        "path": "/mcp",
+        # Required for a non-loopback bind. Prefer MCP_HTTP_TOKEN over YAML.
+        "token": None,
+    },
+    # Sliding-window limit for destructive/state-changing tool calls.
+    "rate_limit": {
+        "enabled": True,
+        "max_calls": 10,
+        "window_seconds": 60,
+    },
+    "ssh": {
+        "host": "localhost",
+        "port": 22,
+        # None means: use the current user / ~/.ssh/config / ssh-agent.
+        "username": None,
+        "password": None,
+        "key_path": None,
+        # Path to known_hosts, or "none" to disable verification (insecure).
+        "known_hosts": "~/.ssh/known_hosts",
+        "connect_timeout": 10,
+    },
+    "security": {
+        # Service directory base path (for remote-server-mcp)
+        "services_path": "/srv",
+        # NEVER allow generic command execution
+        "allow_generic_commands": False,
+        # Container names that may be managed without a matching service
+        # directory. Containers that belong to a compose project below
+        # services_path do not need to be listed here.
+        "allowed_containers": [],
+        # Host systemd units that get_host_service_status/logs may inspect.
+        "host_units": list(DEFAULT_HOST_UNITS),
+    },
+    "host": {
+        "enabled": False,
+    },
+    "health": {
+        # Absolute mount points reported by remote-server-mcp's
+        # get_server_health. NAS pools are separate mounts, so list each one.
+        "disk_paths": ["/"],
+    },
+    "influxdb": {
+        "enabled": False,
+        "host": "localhost",
+        "port": 8181,
+        "use_https": False,
+        "database": None,
+        "token": None,
+        "query_limit": 1000,
+        # Optional local port forward to a loopback-only InfluxDB. When
+        # enabled, host/port are rewritten to the tunnel endpoint at startup.
+        "ssh_tunnel": {
+            "enabled": False,
+            "remote_host": "127.0.0.1",
+            "remote_port": None,
+            "local_host": "127.0.0.1",
+            "local_port": 0,
+        },
+    },
+    "prometheus": {
+        "enabled": False,
+        "host": "localhost",
+        "port": 9090,
+        "use_https": False,
+        "token": None,
+        "query_timeout": "30s",
+        "ssh_tunnel": {
+            "enabled": False,
+            "remote_host": "127.0.0.1",
+            "remote_port": None,
+            "local_host": "127.0.0.1",
+            "local_port": 0,
+        },
+    },
+    "output": {
+        # Maximum bytes returned to the model per command/file/query.
+        "max_bytes": 64000,
+    },
+    "audit": {
+        "enabled": False,
+        "path": "~/.local/state/server-management/audit.jsonl",
+    },
+}
+
+# Environment variable -> (section, key, converter). ``section`` is ``None``
+# for top-level scalar settings such as ``executor`` and ``container_runtime``.
+ENV_OVERRIDES: dict[str, tuple[str | None, str, type]] = {
+    "EXECUTOR": (None, "executor", str),
+    "CONTAINER_RUNTIME": (None, "container_runtime", str),
+    "SSH_HOST": ("ssh", "host", str),
+    "SSH_PORT": ("ssh", "port", int),
+    "SSH_USERNAME": ("ssh", "username", str),
+    "SSH_PASSWORD": ("ssh", "password", str),
+    "SSH_KEY_PATH": ("ssh", "key_path", str),
+    "SSH_KNOWN_HOSTS": ("ssh", "known_hosts", str),
+    "INFLUXDB_HOST": ("influxdb", "host", str),
+    "INFLUXDB_PORT": ("influxdb", "port", int),
+    "INFLUXDB_USE_HTTPS": ("influxdb", "use_https", bool),
+    "INFLUXDB_DATABASE": ("influxdb", "database", str),
+    "INFLUXDB_TOKEN": ("influxdb", "token", str),
+    "PROMETHEUS_HOST": ("prometheus", "host", str),
+    "PROMETHEUS_PORT": ("prometheus", "port", int),
+    "PROMETHEUS_USE_HTTPS": ("prometheus", "use_https", bool),
+    "PROMETHEUS_TOKEN": ("prometheus", "token", str),
+    "MCP_TRANSPORT": ("transport", "type", str),
+    "MCP_HTTP_HOST": ("transport", "host", str),
+    "MCP_HTTP_PORT": ("transport", "port", int),
+    "MCP_HTTP_PATH": ("transport", "path", str),
+    "MCP_HTTP_TOKEN": ("transport", "token", str),
+    "OUTPUT_MAX_BYTES": ("output", "max_bytes", int),
+    "AUDIT_ENABLED": ("audit", "enabled", bool),
+    "AUDIT_LOG_PATH": ("audit", "path", str),
+}
+
+
+class ConfigError(Exception):
+    """Base class for configuration problems."""
+
+
+class ConfigNotFoundError(ConfigError, FileNotFoundError):
+    """No configuration file could be located."""
+
+
+def _as_bool(value: str) -> bool:
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _convert(value: str, converter: type) -> Any:
+    if converter is bool:
+        return _as_bool(value)
+    return converter(value)
+
+
+def _deep_merge(base: Mapping[str, Any], override: Mapping[str, Any]) -> dict:
+    """Merge ``override`` on top of ``base`` without mutating either."""
+    result: dict[str, Any] = copy.deepcopy(dict(base))
+    for key, value in override.items():
+        current = result.get(key)
+        if value is None and isinstance(current, dict):
+            # An empty YAML section (e.g. ``influxdb:``) keeps the defaults.
+            continue
+        if isinstance(value, Mapping) and isinstance(current, Mapping):
+            result[key] = _deep_merge(current, value)
+        else:
+            result[key] = copy.deepcopy(value)
+    return result
+
+
+def resolve_config_path(
+    explicit: Path | str | None = None,
+    *,
+    env_var: str | None = None,
+    app_name: str | None = None,
+) -> Path | None:
+    """Return the configuration file path, or ``None`` if none was found.
+
+    An explicit path is returned even if the file does not exist; the caller
+    decides whether that is an error.
+    """
+    if explicit is not None:
+        return Path(explicit).expanduser()
+
+    if env_var:
+        value = os.environ.get(env_var)
+        if value:
+            return Path(value).expanduser()
+
+    if app_name:
+        xdg_home = os.environ.get("XDG_CONFIG_HOME")
+        base = Path(xdg_home).expanduser() if xdg_home else Path.home() / ".config"
+        candidate = base / app_name / "config.yaml"
+        if candidate.exists():
+            return candidate
+
+    cwd_candidate = Path.cwd() / "config.yaml"
+    if cwd_candidate.exists():
+        return cwd_candidate
+
+    return None
+
+
+def _apply_env_overrides(
+    config: dict[str, Any],
+    env: Mapping[str, str],
+) -> None:
+    for env_name, (section, key, converter) in ENV_OVERRIDES.items():
+        value = env.get(env_name)
+        if value is None or value == "":
+            continue
+        try:
+            converted = _convert(value, converter)
+            if section is None:
+                config[key] = converted
+                continue
+            section_config = config.get(section)
+            if not isinstance(section_config, dict):
+                section_config = {}
+                config[section] = section_config
+            section_config[key] = converted
+        except (TypeError, ValueError):
+            logger.warning("Ignoring invalid value for %s", env_name)
+
+
+def _load_dotenv(config_file: Path) -> None:
+    """Load ``.env`` next to the config file (best effort)."""
+    try:
+        from dotenv import load_dotenv
+    except ImportError:  # pragma: no cover - optional dependency
+        return
+
+    env_file = config_file.parent / ".env"
+    if env_file.exists():
+        load_dotenv(env_file)
+
+
+def load_config(
+    config_path: Path | str | None = None,
+    *,
+    env_var: str | None = None,
+    app_name: str | None = None,
+    required: bool = False,
+    env: Mapping[str, str] | None = None,
+    use_dotenv: bool = True,
+    log_missing: bool = True,
+) -> dict:
+    """Load configuration from YAML, merged over :data:`DEFAULT_CONFIG`.
+
+    Args:
+        config_path: Explicit path; when ``None`` the usual locations are probed.
+        env_var: Environment variable holding a config path.
+        app_name: Application name used for the XDG location.
+        required: Raise :class:`ConfigNotFoundError` instead of using defaults.
+        env: Environment mapping for overrides (defaults to ``os.environ``).
+        use_dotenv: Load a ``.env`` file next to the resolved config file.
+        log_missing: Log a warning when no config file is found. Disable this
+            for the best-effort import-time load in servers.
+
+    Raises:
+        ConfigNotFoundError: No config found (or explicit path missing) and
+            ``required`` is true.
+        ConfigError: The config file exists but cannot be parsed, and
+            ``required`` is true.
+    """
+    resolved = resolve_config_path(config_path, env_var=env_var, app_name=app_name)
+
+    searched = _describe_search_paths(config_path, env_var, app_name)
+    environment = os.environ if env is None else env
+
+    def defaults_with_overrides() -> dict:
+        config = _deep_merge(DEFAULT_CONFIG, {})
+        _apply_env_overrides(config, environment)
+        return config
+
+    if resolved is None or not resolved.exists():
+        if required:
+            raise ConfigNotFoundError(
+                "No configuration file found. Searched: "
+                f"{searched}. Create one from config.example.yaml or pass "
+                "--config / set the config environment variable."
+            )
+        if log_missing:
+            logger.warning(
+                "No configuration file found (searched: %s); using defaults",
+                searched,
+            )
+        return defaults_with_overrides()
+
+    if use_dotenv and env is None:
+        _load_dotenv(resolved)
+
+    try:
+        with open(resolved) as f:
+            loaded = yaml.safe_load(f)
+    except Exception as e:
+        if required:
+            raise ConfigError(f"Error loading config from {resolved}: {e}") from e
+        logger.error("Error loading config from %s: %s", resolved, e)
+        logger.warning("Using default configuration")
+        return defaults_with_overrides()
+
+    if loaded is None:
+        loaded = {}
+    if not isinstance(loaded, Mapping):
+        message = f"Configuration in {resolved} must be a YAML mapping"
+        if required:
+            raise ConfigError(message)
+        logger.error(message)
+        return defaults_with_overrides()
+
+    config = _deep_merge(DEFAULT_CONFIG, loaded)
+    _apply_env_overrides(config, environment)
+    logger.info("Loaded configuration from %s", resolved)
+    return config
+
+
+# Values that must never be published by the config-schema MCP resource.
+SECRET_CONFIG_KEYS = frozenset({"token", "password"})
+
+
+def redact_config_values(value: Any) -> Any:
+    """Return a copy of a config mapping with credential-like values masked."""
+    if isinstance(value, Mapping):
+        return {
+            key: (
+                "***"
+                if str(key).lower() in SECRET_CONFIG_KEYS
+                else redact_config_values(item)
+            )
+            for key, item in value.items()
+        }
+    if isinstance(value, list):
+        return [redact_config_values(item) for item in value]
+    return value
+
+
+def config_schema() -> dict[str, Any]:
+    """Describe the configuration defaults and environment overrides.
+
+    Used by the MCP config resource. Credential-like values are masked, and
+    environment variable names are listed without their values.
+    """
+    return {
+        "defaults": redact_config_values(DEFAULT_CONFIG),
+        "environment_overrides": {
+            name: {"section": key if section is None else section, "key": key}
+            for name, (section, key, _converter) in sorted(ENV_OVERRIDES.items())
+        },
+    }
+
+
+def _describe_search_paths(
+    config_path: Path | str | None,
+    env_var: str | None,
+    app_name: str | None,
+) -> str:
+    if config_path is not None:
+        return str(Path(config_path).expanduser())
+    parts = []
+    if env_var:
+        parts.append(f"${env_var}")
+    if app_name:
+        parts.append(f"$XDG_CONFIG_HOME/{app_name}/config.yaml (~/.config fallback)")
+    parts.append("./config.yaml")
+    return ", ".join(parts)

server_management_lib/executor.py

@@ -0,0 +1,53 @@
+"""
+Executor factory.
+
+Selects the SSH or local implementation from ``config["executor"]``. Both
+implement the same command/file interface, so MCP tools do not need to know
+where they run.
+"""
+
+from typing import Protocol
+
+from .base import RemoteDirEntry
+from .local_executor import LocalExecutor
+from .security import SecurityValidator
+from .ssh_manager import SSHManager
+
+
+class Executor(Protocol):
+    """Interface shared by :class:`SSHManager` and :class:`LocalExecutor`."""
+
+    services_base_path: str
+    max_output_bytes: int
+
+    async def connect(self) -> None: ...
+
+    async def disconnect(self) -> None: ...
+
+    async def execute_safe_command(self, command: str, timeout: int = 30) -> str: ...
+
+    async def check_service_exists(self, service: str) -> bool: ...
+
+    async def read_remote_file(
+        self,
+        path: str,
+        *,
+        allowed_base: str | None = None,
+        max_bytes: int | None = None,
+    ) -> str: ...
+
+    async def list_remote_dir(
+        self, path: str, *, allowed_base: str | None = None
+    ) -> list[RemoteDirEntry]: ...
+
+
+def create_executor(
+    config: dict, security: SecurityValidator
+) -> SSHManager | LocalExecutor:
+    """Create the executor selected by ``config["executor"]`` (default: ssh)."""
+    mode = str(config.get("executor", "ssh")).strip().lower()
+    if mode == "local":
+        return LocalExecutor(config, security)
+    if mode == "ssh":
+        return SSHManager(config, security)
+    raise ValueError(f"Unknown executor {mode!r}; expected 'ssh' or 'local'")