server-management-lib 0.2.0__tar.gz

server_management_lib-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,14 @@
+# 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/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "server-management-lib"
+version = "0.2.0"
+description = "Shared security, SSH/local execution, configuration and HTTP clients for the Server MCP suite."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = [
+    "asyncssh>=2.22,<3",
+    "pyyaml>=6.0",
+    "aiohttp>=3.9.0",
+    "python-dotenv>=1.0.0",
+    "sqlparse>=0.5",
+    "pydantic>=2.12",
+]
+
+authors = [
+    { name = "Alessio Elmi", email = "alessio.elmi@gmail.com" },
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "linux",
+    "server-management",
+    "docker",
+    "homelab",
+    "self-hosting",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: System Administrators",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: System :: Systems Administration",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/elmuz/server-mcp"
+Repository = "https://github.com/elmuz/server-mcp"
+Documentation = "https://github.com/elmuz/server-mcp/tree/main/docs"
+Issues = "https://github.com/elmuz/server-mcp/issues"
+Changelog = "https://github.com/elmuz/server-mcp/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.package-data]
+server_management_lib = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "--cov=src/server_management_lib --cov-report=term-missing --cov-fail-under=90"
+
+[tool.coverage.run]
+source = ["server_management_lib"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+skip_covered = true

server_management_lib-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

server_management_lib-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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)