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

server_management_lib/tunnel.py

@@ -0,0 +1,380 @@
+"""
+Optional SSH local port forwarding for loopback-only metric endpoints.
+
+A metric service (InfluxDB, Prometheus) may listen only on the target host's
+loopback interface.  In that case the MCP cannot reach it directly: the normal
+mode is an HTTPS reverse proxy with a token.  This module lets the MCP create a
+local tunnel through the configured SSH connection instead of requiring the
+operator to keep ``ssh -N -L`` running by hand.
+
+The tunnel is deliberately narrow:
+
+- it listens on a loopback address only (never ``0.0.0.0``);
+- it forwards to the host/port configured in the database section;
+- it uses the same SSH settings (host key verification, key, agent) as the
+  executor.
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import asyncssh
+
+from .security import SecurityValidator
+from .ssh_manager import SSHManager
+
+logger = logging.getLogger(__name__)
+
+LOOPBACK_HOSTS = frozenset({"127.0.0.1", "::1", "localhost"})
+MAX_PORT = 65535
+
+# Section name -> default remote port.  The database port is the remote port
+# when ``ssh_tunnel.remote_port`` is not set.
+METRIC_SECTIONS: tuple[tuple[str, int], ...] = (
+    ("influxdb", 8181),
+    ("prometheus", 9090),
+)
+
+
+class SSHTunnelError(RuntimeError):
+    """Raised when an SSH tunnel cannot be configured or opened."""
+
+
+@dataclass(frozen=True)
+class TunnelEndpoint:
+    """Local address a tunnel is listening on."""
+
+    host: str
+    port: int
+
+
+@dataclass(frozen=True)
+class TunnelConfig:
+    """Validated ``ssh_tunnel`` settings for one metric section."""
+
+    remote_host: str
+    remote_port: int
+    local_host: str = "127.0.0.1"
+    local_port: int = 0
+
+    @classmethod
+    def from_config(
+        cls,
+        value: Any,
+        *,
+        default_remote_port: int,
+    ) -> "TunnelConfig":
+        """Validate a raw ``ssh_tunnel`` mapping.
+
+        ``default_remote_port`` is the database section's ``port`` (or its
+        built-in default), so a minimal configuration only needs
+        ``enabled: true``.
+        """
+        if not isinstance(value, dict):
+            raise SSHTunnelError("ssh_tunnel must be a mapping")
+
+        remote_host = _validate_host(
+            value.get("remote_host", "127.0.0.1"),
+            "ssh_tunnel.remote_host",
+        )
+        raw_remote_port = value.get("remote_port")
+        if raw_remote_port is None:
+            raw_remote_port = default_remote_port
+        remote_port = _validate_port(
+            raw_remote_port,
+            "ssh_tunnel.remote_port",
+            allow_zero=False,
+        )
+        local_host = _validate_host(
+            value.get("local_host", "127.0.0.1"),
+            "ssh_tunnel.local_host",
+        )
+        if local_host not in LOOPBACK_HOSTS:
+            raise SSHTunnelError(
+                "ssh_tunnel.local_host must be a loopback address "
+                f"({', '.join(sorted(LOOPBACK_HOSTS))})"
+            )
+        local_port = _validate_port(
+            value.get("local_port", 0),
+            "ssh_tunnel.local_port",
+            allow_zero=True,
+        )
+        return cls(
+            remote_host=remote_host,
+            remote_port=remote_port,
+            local_host=local_host,
+            local_port=local_port,
+        )
+
+
+def _validate_host(value: Any, name: str) -> str:
+    if not isinstance(value, str):
+        raise SSHTunnelError(f"{name} must be a hostname or IP address")
+    host = value.strip()
+    if not host:
+        raise SSHTunnelError(f"{name} must not be empty")
+    if len(host) > 253 or any(char.isspace() or ord(char) < 32 for char in host):
+        raise SSHTunnelError(f"{name} contains an invalid character")
+    return host
+
+
+def _validate_port(value: Any, name: str, *, allow_zero: bool) -> int:
+    if isinstance(value, bool):
+        raise SSHTunnelError(f"{name} must be an integer between 0 and {MAX_PORT}")
+    try:
+        port = int(value)
+    except (TypeError, ValueError) as e:
+        raise SSHTunnelError(
+            f"{name} must be an integer between 0 and {MAX_PORT}"
+        ) from e
+    minimum = 0 if allow_zero else 1
+    if not minimum <= port <= MAX_PORT:
+        raise SSHTunnelError(f"{name} must be between {minimum} and {MAX_PORT}")
+    return port
+
+
+class SSHTunnel:
+    """One local port forward over a dedicated SSH connection.
+
+    A dropped SSH connection closes the forwarding listener. The tunnel keeps a
+    monitor task that detects the close and re-opens both the connection and
+    the listener on the same local port, so clients that already point at the
+    endpoint keep working. Reconnection is retried until :meth:`close`; while
+    it is failing, ``down`` is true and ``last_error`` describes the failure.
+    """
+
+    def __init__(
+        self,
+        ssh_config: dict[str, Any],
+        tunnel_config: dict[str, Any],
+        *,
+        default_remote_port: int,
+    ):
+        self.ssh_config = dict(ssh_config or {})
+        self.config = TunnelConfig.from_config(
+            tunnel_config,
+            default_remote_port=default_remote_port,
+        )
+        self._manager: SSHManager | None = None
+        self._listener: asyncssh.SSHListener | None = None
+        self._endpoint: TunnelEndpoint | None = None
+        self._monitor_task: asyncio.Task | None = None
+        self._closed = False
+        self.down = False
+        self.last_error: str | None = None
+
+    async def _open(self, local_port: int) -> TunnelEndpoint:
+        """Open one SSH connection and local forward."""
+        manager = SSHManager({"ssh": self.ssh_config}, SecurityValidator({}))
+        try:
+            await manager.connect()
+            connection = manager.connection
+            if connection is None:
+                raise SSHTunnelError("SSH connection failed")
+            listener = await connection.forward_local_port(
+                self.config.local_host,
+                local_port,
+                self.config.remote_host,
+                self.config.remote_port,
+            )
+        except SSHTunnelError:
+            await manager.disconnect()
+            raise
+        except Exception as e:
+            await manager.disconnect()
+            raise SSHTunnelError(f"Could not open SSH tunnel: {e}") from e
+
+        self._manager = manager
+        self._listener = listener
+        port = listener.get_port() or local_port
+        self._endpoint = TunnelEndpoint(self.config.local_host, port)
+        logger.info(
+            "SSH tunnel listening on %s:%s for %s:%s",
+            self.config.local_host,
+            port,
+            self.config.remote_host,
+            self.config.remote_port,
+        )
+        return self._endpoint
+
+    async def start(self) -> TunnelEndpoint:
+        """Open the SSH connection and the local listener."""
+        self._closed = False
+        endpoint = await self._open(self.config.local_port)
+        self._start_monitor()
+        return endpoint
+
+    def _start_monitor(self) -> None:
+        """Watch the current connection and reconnect when it closes."""
+        manager = self._manager
+        connection = manager.connection if manager is not None else None
+        wait_closed = getattr(connection, "wait_closed", None)
+        if connection is None or wait_closed is None:
+            # Test doubles and older asyncssh releases may not expose
+            # wait_closed; reconnection is best effort in that case.
+            return
+        self._monitor_task = asyncio.create_task(
+            self._monitor_connection(connection, wait_closed)
+        )
+
+    async def _monitor_connection(self, connection, wait_closed) -> None:
+        try:
+            await wait_closed()
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:  # pragma: no cover - defensive
+            logger.debug("SSH tunnel connection close reported an error: %s", e)
+
+        if self._closed:
+            return
+        logger.warning(
+            "SSH tunnel connection dropped; reconnecting to %s:%s",
+            self.config.remote_host,
+            self.config.remote_port,
+        )
+        await self._reconnect()
+
+    async def _reconnect(self) -> None:
+        """Re-open the forward on the previously bound local port."""
+        local_port = self._endpoint.port if self._endpoint else self.config.local_port
+        delay = 1.0
+
+        old_listener = self._listener
+        self._listener = None
+        if old_listener is not None:
+            old_listener.close()
+            try:
+                await old_listener.wait_closed()
+            except Exception as e:  # pragma: no cover - best effort
+                logger.debug("Error while closing the dropped tunnel listener: %s", e)
+
+        old_manager = self._manager
+        self._manager = None
+        if old_manager is not None:
+            try:
+                await old_manager.disconnect()
+            except Exception as e:  # pragma: no cover - best effort
+                logger.debug("Error while discarding the dropped SSH tunnel: %s", e)
+
+        while not self._closed:
+            try:
+                await self._open(local_port)
+            except Exception as e:
+                self.down = True
+                self.last_error = str(e)
+                logger.error("SSH tunnel is down (%s); retrying in %.0fs", e, delay)
+                try:
+                    await asyncio.sleep(delay)
+                except asyncio.CancelledError:
+                    raise
+                delay = min(delay * 2, 30.0)
+                continue
+
+            self.down = False
+            self.last_error = None
+            self._start_monitor()
+            return
+
+    async def close(self) -> None:
+        """Close the listener and the SSH connection (idempotent)."""
+        self._closed = True
+        monitor = self._monitor_task
+        self._monitor_task = None
+        if monitor is not None:
+            monitor.cancel()
+            try:
+                await monitor
+            except asyncio.CancelledError:
+                pass
+            except Exception as e:  # pragma: no cover - best effort
+                logger.debug("Error while stopping the SSH tunnel monitor: %s", e)
+
+        listener = self._listener
+        self._listener = None
+        if listener is not None:
+            listener.close()
+            try:
+                await listener.wait_closed()
+            except Exception as e:  # pragma: no cover - best effort
+                logger.debug("Error while closing SSH tunnel listener: %s", e)
+
+        manager = self._manager
+        self._manager = None
+        if manager is not None:
+            await manager.disconnect()
+
+    async def __aenter__(self) -> TunnelEndpoint:
+        return await self.start()
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()
+
+
+@dataclass
+class ActiveTunnel:
+    """A tunnel opened from configuration and the endpoint it replaced."""
+
+    section: str
+    tunnel: SSHTunnel
+    endpoint: TunnelEndpoint
+
+
+async def open_metric_tunnels(config: dict[str, Any]) -> list[ActiveTunnel]:
+    """Open tunnels for enabled ``influxdb``/``prometheus`` sections.
+
+    The section's ``host``/``port`` are rewritten to the local tunnel endpoint
+    so the existing HTTP clients can use them unchanged.  When any tunnel
+    fails, all previously opened tunnels are closed before the error is
+    re-raised.
+    """
+    ssh_config = config.get("ssh", {}) or {}
+    pending: list[tuple[str, dict[str, Any], dict[str, Any], int]] = []
+
+    # Validate every configured tunnel before opening any of them so a typo
+    # cannot leave an earlier tunnel running.
+    for section, default_port in METRIC_SECTIONS:
+        section_config = config.get(section)
+        if not isinstance(section_config, dict):
+            continue
+        if not section_config.get("enabled", False):
+            continue
+        tunnel_config = section_config.get("ssh_tunnel")
+        if tunnel_config is None or tunnel_config is False:
+            continue
+        if not isinstance(tunnel_config, dict):
+            raise SSHTunnelError(
+                f"{section}.ssh_tunnel must be a mapping with enabled: true"
+            )
+        if not tunnel_config.get("enabled"):
+            continue
+        pending.append((section, section_config, tunnel_config, default_port))
+
+    active: list[ActiveTunnel] = []
+    try:
+        for section, section_config, tunnel_config, default_port in pending:
+            tunnel = SSHTunnel(
+                ssh_config,
+                tunnel_config,
+                default_remote_port=section_config.get("port") or default_port,
+            )
+            endpoint = await tunnel.start()
+            section_config["host"] = endpoint.host
+            section_config["port"] = endpoint.port
+            active.append(ActiveTunnel(section, tunnel, endpoint))
+    except Exception:
+        await close_metric_tunnels(active)
+        raise
+
+    return active
+
+
+async def close_metric_tunnels(tunnels: list[ActiveTunnel]) -> None:
+    """Close every tunnel opened by :func:`open_metric_tunnels`."""
+    while tunnels:
+        active = tunnels.pop()
+        try:
+            await active.tunnel.close()
+        except Exception as e:  # pragma: no cover - best effort
+            logger.debug("Error while closing %s tunnel: %s", active.section, e)

server_management_lib-0.2.0.dist-info/METADATA

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: server-management-lib
+Version: 0.2.0
+Summary: Shared security, SSH/local execution, configuration and HTTP clients for the Server MCP suite.
+Author-email: Alessio Elmi <alessio.elmi@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/elmuz/server-mcp
+Project-URL: Repository, https://github.com/elmuz/server-mcp
+Project-URL: Documentation, https://github.com/elmuz/server-mcp/tree/main/docs
+Project-URL: Issues, https://github.com/elmuz/server-mcp/issues
+Project-URL: Changelog, https://github.com/elmuz/server-mcp/blob/main/CHANGELOG.md
+Keywords: mcp,model-context-protocol,linux,server-management,docker,homelab,self-hosting
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Systems Administration
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: asyncssh<3,>=2.22
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: sqlparse>=0.5
+Requires-Dist: pydantic>=2.12
+
+# server-management-lib
+
+Shared core for the Server MCP suite: security validation, SSH and local executors,
+configuration resolution, output limits, audit logging, and read-only InfluxDB/Prometheus
+clients.
+
+Part of the [Server MCP suite](../../README.md).
+
+- [Architecture](../../docs/architecture.md)
+- [Security model](../../docs/security-model.md)
+- [Configuration](../../docs/configuration.md)
+
+The two MCP servers depend on this package through the uv workspace. It has no MCP
+dependency and can be used by other server-management tools.

server_management_lib-0.2.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+server_management_lib/__init__.py,sha256=CC39UORohKcFBrIAf9RVMrMmE9_xx46V5kZF3ByUcAM,2883
+server_management_lib/audit.py,sha256=hcMGLW04aHdeqhC_fX5obbxAUd2FIaCsJgF6dvkJzj4,2791
+server_management_lib/base.py,sha256=moZdJKvaVtlLlNxguDjwq_XCv2DWS7r2djCfnFyQNak,1510
+server_management_lib/config.py,sha256=rykN_Hx5VtX4ssrJHd2DI-7H0CYbfv5G4Tq1Xyy_2CE,13185
+server_management_lib/executor.py,sha256=Npebfva17WK9lvNgGNfpIsPh0npellQH-USOb5Xl0sc,1539
+server_management_lib/http_clients.py,sha256=nXmTgKGWYVdpcUg45oafwFZdHc_3PN9ll4GQln4vq40,24102
+server_management_lib/local_executor.py,sha256=WzEgYQBnZQ5FB8TVb0hwWsjy_7uUYG6VbliNX0GWBdM,7037
+server_management_lib/operations.py,sha256=9u51YxawFeEkWMd47WC8NAePkCNx4EzrMWpl06gr30E,1017
+server_management_lib/output.py,sha256=Z94OzAg5bkeCX70Sm7Ijvie5rXqej-moH7C7aB9iW4s,1980
+server_management_lib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+server_management_lib/rate_limit.py,sha256=K2UJt1L1_kfd92b1UjnIhoR9SrNK2tr2zUilm1kxsTI,3826
+server_management_lib/redaction.py,sha256=sEsT_Nw537JotKU-UsG8Jre1n0YERh5ZIm9mHcofFU8,6390
+server_management_lib/responses.py,sha256=XnFyTRSQ_pNQx8dx8jIDVUqt9Qh9LOldKZuQFzG3gpE,4481
+server_management_lib/security.py,sha256=F969RKY2oif3bp5JQLdaPDMS2bBS2-5a-h_lMR04iQ8,56146
+server_management_lib/ssh_manager.py,sha256=6-2nNGtzDr18lJa0dw8SCW9cDq8Jzua810rBPNyG18w,16339
+server_management_lib/transport.py,sha256=vmfRqdSZc3EuCJEnGm-D16HjGXUr1XPCaN_haVFCGlA,4187
+server_management_lib/tunnel.py,sha256=tmhTrgYWjKfXi--SXc6pJp4Y47EyFEef1ZfFWSSuvHs,13290
+server_management_lib-0.2.0.dist-info/METADATA,sha256=JWOOz6TpSjnRej5lGwG7BMkzo15j2pmhTTIFDWD9Ifk,1989
+server_management_lib-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+server_management_lib-0.2.0.dist-info/top_level.txt,sha256=03qQ0Fx0rrnN6WBTUgRUmoZkiv1oMn6oStik9gl12tk,22
+server_management_lib-0.2.0.dist-info/RECORD,,

server_management_lib-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

server_management_lib-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+server_management_lib