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

server_management_lib/local_executor.py

@@ -0,0 +1,200 @@
+"""
+Local command executor.
+
+Runs the same validated operation catalog as the SSH executor, but on the host
+where the MCP server runs. Commands are executed as argument vectors (never
+through a shell), and file access is confined to the configured service base.
+"""
+
+import asyncio
+import logging
+import shlex
+import stat
+import time
+from datetime import datetime
+from pathlib import Path
+
+from .base import (
+    ExecutorBase,
+    RemoteDirEntry,
+    RemoteFileError,
+    RemotePathError,
+    is_within,
+)
+from .output import sanitize_output
+
+logger = logging.getLogger(__name__)
+
+SHELL_OPERATORS = {
+    "&",
+    "&&",
+    ";",
+    "|",
+    "||",
+    ">",
+    ">>",
+    "<",
+    "<<",
+    "2>",
+    "2>&1",
+}
+
+
+def _read_regular_file(path: Path, limit: int) -> tuple[bytes, int]:
+    """Read a regular file without following special files (FIFOs, devices)."""
+    info = path.stat()
+    if not stat.S_ISREG(info.st_mode):
+        raise RemoteFileError(f"Not a regular file: {path}")
+    with path.open("rb") as handle:
+        return handle.read(limit + 1), info.st_size
+
+
+class LocalExecutor(ExecutorBase):
+    """Execute validated commands and file operations on the local host."""
+
+    async def connect(self) -> None:
+        """No-op; kept for interface parity with the SSH executor."""
+
+    async def disconnect(self) -> None:
+        """No-op; kept for interface parity with the SSH executor."""
+
+    async def execute_safe_command(self, command: str, timeout: int = 30) -> str:
+        """Execute a validated command as an argv vector (no shell)."""
+        if not self.security.is_command_safe(command):
+            logger.error("Attempted to execute unsafe command: %s", command)
+            self.audit.log("command_blocked", command=command, executor="local")
+            return "❌ Security violation: Command blocked by security policy"
+
+        argv = shlex.split(command)
+        if not argv:
+            return "❌ Empty command"
+
+        if any(token in SHELL_OPERATORS for token in argv):
+            self.audit.log("command_blocked", command=command, reason="shell_operator")
+            return (
+                "❌ Shell operators are not supported by the local executor; "
+                "the command must be a plain argv vector."
+            )
+
+        started = time.monotonic()
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *argv,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+        except FileNotFoundError:
+            self.audit.log("command_error", command=command, error="not_found")
+            return f"❌ Command not found: {argv[0]}"
+        except OSError as e:
+            self.audit.log("command_error", command=command, error=str(e))
+            return f"❌ Error executing command: {e}"
+
+        try:
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(), timeout=timeout
+            )
+        except TimeoutError:
+            process.kill()
+            await process.wait()
+            self.audit.log("command_timeout", command=command, timeout=timeout)
+            return f"❌ Command timed out after {timeout}s"
+
+        output = stdout.decode("utf-8", errors="replace")
+        error_output = stderr.decode("utf-8", errors="replace")
+        if error_output:
+            output += ("\n--- STDERR ---\n" if output else "") + error_output
+        if process.returncode:
+            output += f"\n\n⚠️ Exit code: {process.returncode}"
+
+        sanitized = sanitize_output(
+            output, self.max_output_bytes, label="command output"
+        )
+        self.audit.log(
+            "command",
+            command=command,
+            executor="local",
+            exit_status=process.returncode,
+            duration_ms=round((time.monotonic() - started) * 1000, 1),
+            output_bytes=len(output.encode("utf-8")),
+            truncated=sanitized != output,
+        )
+        return sanitized
+
+    async def check_service_exists(self, service: str) -> bool:
+        """Check the local service directory."""
+        return (Path(self.services_base_path) / service).is_dir()
+
+    async def read_remote_file(
+        self,
+        path: str,
+        *,
+        allowed_base: str | None = None,
+        max_bytes: int | None = None,
+    ) -> str:
+        """Read a local file with the same confinement rules as SFTP reads."""
+        limit = max_bytes or self.max_output_bytes
+        real_path = Path(path).resolve()
+        real_base = Path(allowed_base).resolve() if allowed_base else None
+        if real_base is not None and not is_within(str(real_path), str(real_base)):
+            self.audit.log("file_read_blocked", path=path, resolved=str(real_path))
+            raise RemotePathError(f"Path escapes the allowed directory: {real_path}")
+
+        try:
+            # File I/O must not block the event loop; a FIFO would otherwise
+            # hang the whole MCP server.
+            data, size = await asyncio.to_thread(_read_regular_file, real_path, limit)
+        except OSError as e:
+            raise RemoteFileError(f"Cannot read {real_path}: {e}") from e
+
+        text = data.decode("utf-8", errors="replace")
+        sanitized = sanitize_output(text, limit, label="file contents")
+        self.audit.log(
+            "file_read",
+            path=str(real_path),
+            size=size,
+            executor="local",
+            truncated=len(data) > limit or sanitized != text,
+        )
+        return sanitized
+
+    async def list_remote_dir(
+        self,
+        path: str,
+        *,
+        allowed_base: str | None = None,
+    ) -> list[RemoteDirEntry]:
+        """List a local directory with the same confinement rules."""
+        real_path = Path(path).resolve()
+        real_base = Path(allowed_base).resolve() if allowed_base else None
+        if real_base is not None and not is_within(str(real_path), str(real_base)):
+            self.audit.log("dir_list_blocked", path=path, resolved=str(real_path))
+            raise RemotePathError(f"Path escapes the allowed directory: {real_path}")
+
+        try:
+            children = list(real_path.iterdir())
+        except OSError as e:
+            raise RemoteFileError(f"Cannot list {real_path}: {e}") from e
+
+        entries = []
+        for child in children:
+            try:
+                info = child.stat()
+            except OSError:
+                continue
+            modified = datetime.fromtimestamp(info.st_mtime).strftime("%b %e %H:%M")
+            longname = (
+                f"{stat.filemode(info.st_mode)} {info.st_size:>10} "
+                f"{modified} {child.name}"
+            )
+            entries.append(
+                RemoteDirEntry(name=child.name, longname=longname, size=info.st_size)
+            )
+        entries.sort(key=lambda entry: entry.name)
+        self.audit.log(
+            "dir_list",
+            path=str(real_path),
+            entries=len(entries),
+            executor="local",
+        )
+        return entries

server_management_lib/operations.py

@@ -0,0 +1,33 @@
+"""
+Shell-safe command templates shared by the MCP tool catalogs.
+
+Commands are argument vectors, never concatenated shell strings. ``render``
+substitutes values literally and quotes the resulting vector with
+:func:`shlex.join`, so a validated value cannot become shell syntax.
+"""
+
+import shlex
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Operation:
+    """A shell-safe command template.
+
+    ``argv`` items may contain ``$name`` placeholders. Values are substituted
+    literally and the resulting vector is quoted by :func:`shlex.join`.
+    """
+
+    argv: tuple[str, ...]
+    read_only: bool = True
+    destructive: bool = False
+
+    def render(self, **params: str | int) -> str:
+        """Render the template with ``params`` substituted literally."""
+
+        def substitute(part: str) -> str:
+            for key, value in params.items():
+                part = part.replace(f"${key}", str(value))
+            return part
+
+        return shlex.join(substitute(part) for part in self.argv)

server_management_lib/output.py

@@ -0,0 +1,61 @@
+"""
+Output sanitization and size limits.
+
+MCP tool output is fed directly to a model. Remote command output is untrusted:
+it can contain terminal escape sequences, control characters, or megabytes of
+data. Everything returned by the SSH layer and the HTTP clients goes through
+:func:`sanitize_output`.
+"""
+
+import re
+
+DEFAULT_MAX_OUTPUT_BYTES = 64_000
+
+# CSI/OSC-style terminal escapes (colors, cursor movement, hyperlinks, ...)
+ANSI_ESCAPE_PATTERN = re.compile(
+    r"\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1b\\))"
+)
+
+# Control characters except tab, newline and carriage return.
+CONTROL_CHAR_PATTERN = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
+
+# A response that was already truncated at this limit must not be truncated
+# again: composite tools assemble several capped blocks and then apply a final
+# cap, which would otherwise append a second marker.
+TRUNCATION_MARKER_PATTERN = re.compile(r"\n… \[[^\]]+ truncated to (\d+) bytes\]$")
+
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI terminal escape sequences."""
+    return ANSI_ESCAPE_PATTERN.sub("", text)
+
+
+def sanitize_output(
+    text: str,
+    max_bytes: int = DEFAULT_MAX_OUTPUT_BYTES,
+    *,
+    label: str = "output",
+) -> str:
+    """Strip escapes/control characters and cap the encoded size.
+
+    The cap is applied to the UTF-8 encoding so a single response cannot flood
+    the model context. A truncation marker is appended when data was dropped.
+    """
+    if not text:
+        return text
+
+    cleaned = CONTROL_CHAR_PATTERN.sub("", strip_ansi(text))
+
+    if max_bytes <= 0:
+        return cleaned
+
+    existing = TRUNCATION_MARKER_PATTERN.search(cleaned)
+    if existing is not None and int(existing.group(1)) == max_bytes:
+        return cleaned
+
+    encoded = cleaned.encode("utf-8")
+    if len(encoded) <= max_bytes:
+        return cleaned
+
+    truncated = encoded[:max_bytes].decode("utf-8", errors="ignore")
+    return f"{truncated}\n… [{label} truncated to {max_bytes} bytes]"

server_management_lib/rate_limit.py

@@ -0,0 +1,118 @@
+"""A small in-memory rate limiter for state-changing tool calls.
+
+The limiter is scoped to one MCP server process (one client session in
+practice). It is a sliding window over call timestamps: at most ``max_calls``
+calls are allowed in any ``window_seconds`` period. It is deliberately simple
+and local; it is not a substitute for host-level protections.
+"""
+
+import logging
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class RateLimitConfig:
+    """Configuration for the destructive-action rate limiter."""
+
+    enabled: bool = True
+    max_calls: int = 10
+    window_seconds: float = 60.0
+
+    @classmethod
+    def from_config(cls, config: dict) -> "RateLimitConfig":
+        section = config.get("rate_limit")
+        if not isinstance(section, dict):
+            return cls()
+
+        enabled = section.get("enabled", True)
+        if not isinstance(enabled, bool):
+            logger.warning("Ignoring non-boolean rate_limit.enabled")
+            enabled = True
+
+        max_calls = _positive_int(section.get("max_calls", 10), "rate_limit.max_calls")
+        window = _positive_float(
+            section.get("window_seconds", 60), "rate_limit.window_seconds"
+        )
+        return cls(enabled=enabled, max_calls=max_calls, window_seconds=window)
+
+
+def _positive_int(value: object, name: str) -> int:
+    try:
+        parsed = int(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        logger.warning("Ignoring invalid %s: %r", name, value)
+        return 10
+    if parsed < 1:
+        logger.warning("Ignoring non-positive %s: %r", name, value)
+        return 10
+    return parsed
+
+
+def _positive_float(value: object, name: str) -> float:
+    try:
+        parsed = float(value)  # type: ignore[arg-type]
+    except (TypeError, ValueError):
+        logger.warning("Ignoring invalid %s: %r", name, value)
+        return 60.0
+    if parsed <= 0:
+        logger.warning("Ignoring non-positive %s: %r", name, value)
+        return 60.0
+    return parsed
+
+
+class RateLimiter:
+    """Sliding-window limiter with a monotonic clock (injectable for tests)."""
+
+    def __init__(
+        self,
+        max_calls: int,
+        window_seconds: float,
+        *,
+        clock: Callable[[], float] = time.monotonic,
+    ):
+        if max_calls < 1:
+            raise ValueError("max_calls must be at least 1")
+        if window_seconds <= 0:
+            raise ValueError("window_seconds must be positive")
+        self.max_calls = max_calls
+        self.window_seconds = float(window_seconds)
+        self._clock = clock
+        self._calls: deque[float] = deque()
+        self._lock = threading.Lock()
+
+    def _prune(self, now: float) -> None:
+        cutoff = now - self.window_seconds
+        while self._calls and self._calls[0] <= cutoff:
+            self._calls.popleft()
+
+    def check(self) -> float | None:
+        """Record a call; return ``None`` when allowed or the retry delay."""
+        with self._lock:
+            now = self._clock()
+            self._prune(now)
+            if len(self._calls) >= self.max_calls:
+                return max(0.0, self.window_seconds - (now - self._calls[0]))
+            self._calls.append(now)
+            return None
+
+    def reset(self) -> None:
+        """Forget recorded calls (used by tests and session teardown)."""
+        with self._lock:
+            self._calls.clear()
+
+
+def create_rate_limiter(config: dict) -> RateLimiter | None:
+    """Build the destructive-action limiter, or ``None`` when disabled."""
+    settings = RateLimitConfig.from_config(config)
+    if not settings.enabled:
+        return None
+    return RateLimiter(
+        settings.max_calls,
+        settings.window_seconds,
+    )

server_management_lib/redaction.py

@@ -0,0 +1,191 @@
+"""
+Redaction helpers for file contents returned to the model.
+
+``.env`` files are useful for debugging a compose stack, but their values are
+secrets. :func:`redact_env_content` keeps the keys, comments and structure so
+the file stays readable while every assignment value is masked.
+"""
+
+import re
+
+REDACTED_VALUE = "***"
+
+# ``KEY=value`` and ``export KEY=value`` with optional whitespace around ``=``.
+_ASSIGNMENT_PATTERN = re.compile(
+    r"^(?P<prefix>\s*(?:export\s+)?)"
+    r"(?P<key>[A-Za-z_][A-Za-z0-9_.-]*)"
+    r"(?P<sep>\s*=\s*)(?P<value>.*)$"
+)
+
+
+def redact_env_content(text: str) -> str:
+    """Mask the values of dotenv assignments, preserving the file structure.
+
+    Comments and blank lines are kept unchanged. Recognized assignments keep
+    their key and separator (``KEY=***``). Any other non-empty line is treated
+    as a value or a continuation of one (for example a multi-line quoted
+    secret) and is masked entirely, so no value text can leak. A trailing
+    newline in the input is preserved.
+
+    Args:
+        text: Raw file contents.
+
+    Returns:
+        The contents with every assignment value replaced by ``***``.
+    """
+    if not text:
+        return text
+
+    lines: list[str] = []
+    for line in text.splitlines():
+        stripped = line.lstrip()
+        if not stripped or stripped.startswith("#"):
+            lines.append(line)
+            continue
+
+        match = _ASSIGNMENT_PATTERN.match(line)
+        if match is None:
+            lines.append(REDACTED_VALUE)
+            continue
+
+        lines.append(
+            f"{match.group('prefix')}{match.group('key')}"
+            f"{match.group('sep')}{REDACTED_VALUE}"
+        )
+
+    redacted = "\n".join(lines)
+    if text.endswith("\n"):
+        redacted += "\n"
+    return redacted
+
+
+# ============================================================================
+# General secret redaction (service config files and host status/log output)
+# ============================================================================
+
+# Key names whose values are secrets. Matching is on the key itself, so
+# ``POSTGRES_PASSWORD``, ``GITHUB_TOKEN`` and ``api_key`` are covered without
+# treating unrelated ``*.key`` file names as secrets (that policy lives in
+# ``security.BLOCKED_PATH_*``).
+_SENSITIVE_KEY_WORD = re.compile(
+    r"(?:password|passwd|pwd|secret|token|api[_-]?key|private[_-]?key|"
+    r"authorization|access[_-]?key|client[_-]?secret|credential)",
+    re.IGNORECASE,
+)
+
+# JSON object member: "key": "value" or "key": value
+_JSON_MEMBER = re.compile(
+    r'(?P<prefix>"(?P<key>[^"\n]+)"\s*:\s*)'
+    r'(?P<value>"(?:[^"\\]|\\.)*"|[^,}\n]+)'
+)
+
+# YAML/INI/CLI assignment at the start of a line, including ``- KEY=value``.
+_LINE_ASSIGNMENT = re.compile(
+    r"^(?P<prefix>\s*(?:-\s*)?)"
+    r'(?P<key>"?[A-Za-z0-9_.-]+"?)'
+    r"(?P<sep>\s*[:=]\s*)"
+    r"(?P<value>.*)$"
+)
+
+# KEY=value anywhere on the line (environment assignments in command lines).
+_INLINE_ASSIGNMENT = re.compile(
+    r"(?P<key>\b[A-Za-z_][A-Za-z0-9_.-]*)(?P<sep>=)"
+    r'(?P<value>"[^"]*"|\'[^\']*\'|[^\s,;}]+)'
+)
+
+# --token value and --password=value command-line flags.
+_CLI_FLAG = re.compile(
+    r"(?P<key>--?[A-Za-z0-9_.-]+)(?P<sep>[=\s]+)"
+    r'(?P<value>"[^"]*"|\'[^\']*\'|[^\s,;}]+)'
+)
+
+_BEARER_VALUE = re.compile(r"(?i)\bBearer\s+[A-Za-z0-9._~+/=-]+")
+_JWT_VALUE = re.compile(r"\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b")
+_URL_PASSWORD = re.compile(
+    r"(?P<scheme>\b[a-z][a-z0-9+.-]*://)(?P<user>[^/\s:@]+):"
+    r"(?P<password>[^/\s@]+)@",
+    re.IGNORECASE,
+)
+
+
+def _is_sensitive_key(key: str) -> bool:
+    """Return True when an assignment key names a credential."""
+    cleaned = key.strip().strip("\"'").lstrip("-")
+    return bool(cleaned) and _SENSITIVE_KEY_WORD.search(cleaned) is not None
+
+
+def _redact_line(line: str) -> str:
+    if not line:
+        return line
+
+    stripped = line.lstrip()
+    if stripped.startswith(("#", ";", "//")):
+        return line
+
+    json_changed = False
+
+    def json_replacement(match: re.Match[str]) -> str:
+        nonlocal json_changed
+        if _is_sensitive_key(match.group("key")):
+            json_changed = True
+            return f'{match.group("prefix")}"***"'
+        return match.group(0)
+
+    line = _JSON_MEMBER.sub(json_replacement, line)
+
+    if not json_changed:
+        line_match = _LINE_ASSIGNMENT.match(line)
+        if line_match is not None and _is_sensitive_key(line_match.group("key")):
+            line = (
+                f"{line_match.group('prefix')}{line_match.group('key')}"
+                f"{line_match.group('sep')}{REDACTED_VALUE}"
+            )
+
+    def assignment_replacement(match: re.Match[str]) -> str:
+        if _is_sensitive_key(match.group("key")):
+            return f"{match.group('key')}{match.group('sep')}{REDACTED_VALUE}"
+        return match.group(0)
+
+    line = _INLINE_ASSIGNMENT.sub(assignment_replacement, line)
+
+    def flag_replacement(match: re.Match[str]) -> str:
+        if _is_sensitive_key(match.group("key")):
+            return f"{match.group('key')}{match.group('sep')}{REDACTED_VALUE}"
+        return match.group(0)
+
+    line = _CLI_FLAG.sub(flag_replacement, line)
+    line = _BEARER_VALUE.sub(f"Bearer {REDACTED_VALUE}", line)
+    line = _JWT_VALUE.sub(REDACTED_VALUE, line)
+    line = _URL_PASSWORD.sub(
+        lambda match: f"{match.group('scheme')}{match.group('user')}:{REDACTED_VALUE}@",
+        line,
+    )
+    return line
+
+
+def redact_secrets(text: str) -> str:
+    """Mask credentials in service config files and host status/log output.
+
+    The redactor handles YAML/INI/dotenv assignments, JSON members, command-line
+    flags, inline ``KEY=value`` pairs, ``Authorization: Bearer`` values, JWT
+    shapes and credentials embedded in URLs. Keys, comments and the surrounding
+    structure stay readable; only the value is replaced with ``***``.
+
+    This is deliberately applied in addition to, not instead of, the sensitive
+    file policy. Real key material and credential stores are still refused
+    before any content is read.
+
+    Args:
+        text: File contents or command output.
+
+    Returns:
+        The text with recognized secret values masked.
+    """
+    if not text:
+        return text
+
+    lines = [_redact_line(line) for line in text.splitlines()]
+    redacted = "\n".join(lines)
+    if text.endswith("\n"):
+        redacted += "\n"
+    return redacted