relay-shell 0.1.0__py3-none-any.whl

relay_shell/_deploy/systemd/relay-shell.service

@@ -0,0 +1,28 @@
+[Unit]
+Description=relay-shell - MCP server for shell and SSH operations
+Documentation=https://github.com/rmednitzer/relay-shell
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=relay-shell
+Group=relay-shell
+WorkingDirectory=/var/lib/relay-shell
+# Configuration is environment-driven; keep secrets out of the unit.
+EnvironmentFile=-/etc/relay-shell/relay-shell.env
+Environment=RELAY_SHELL_TRANSPORT=http
+Environment=RELAY_SHELL_HTTP_HOST=127.0.0.1
+Environment=RELAY_SHELL_HTTP_PORT=8080
+Environment=RELAY_SHELL_AUDIT_PATH=/var/log/relay-shell/audit.jsonl
+ExecStart=/var/lib/relay-shell/venv/bin/relay-shell
+Restart=on-failure
+RestartSec=5
+StartLimitBurst=5
+StartLimitIntervalSec=300
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=relay-shell
+
+[Install]
+WantedBy=multi-user.target

relay_shell/_deploy/systemd/relay-shell.service.d/hardening.conf

@@ -0,0 +1,37 @@
+# relay-shell hardening drop-in.
+#
+# DELIBERATELY PARTIAL. relay-shell exists to run arbitrary commands and reach other
+# hosts (see docs/adr/0002-no-sandbox-full-access.md). The directives that
+# would actually confine it - ProtectSystem=strict, NoNewPrivileges,
+# ProtectHome, PrivateDevices, a restrictive SystemCallFilter - would break
+# the shell/SSH/PTY/sudo capability this service is for, while implying a
+# containment guarantee it cannot honour. Those are intentionally OMITTED.
+#
+# What is applied here is the safe envelope: resource caps so a runaway tool
+# cannot exhaust the host, a private /tmp, and the Protect* directives that do
+# not interfere with command execution. The real boundary is the service
+# account and its credentials, plus the audit/policy layer and the network
+# edge - not this drop-in.
+
+[Service]
+# Resource envelope (tune to the host).
+MemoryHigh=768M
+MemoryMax=1024M
+CPUQuota=80%
+TasksMax=128
+LimitNOFILE=8192
+
+# Safe isolation that does not break execution.
+PrivateTmp=true
+ProtectClock=true
+ProtectHostname=true
+ProtectKernelLogs=true
+ProtectKernelModules=true
+RestrictRealtime=true
+LockPersonality=true
+UMask=0077
+
+# Encrypted credential delivery (systemd-creds). Create with:
+#   systemd-creds encrypt plaintext /etc/credstore.encrypted/relay-shell-oauth ...
+# then reference the decrypted path via $CREDENTIALS_DIRECTORY in relay-shell.env.
+# LoadCredentialEncrypted=relay-shell-oauth:/etc/credstore.encrypted/relay-shell-oauth

relay_shell/audit.py

@@ -0,0 +1,199 @@
+"""Append-only, output-hashed audit trail.
+
+One JSON object per line. The output *body* is never written - only its
+SHA-256 and byte length - so the log is safe to ship off-host. Arguments are
+redacted by the caller (see :mod:`relay_shell.redaction`) before they arrive here.
+
+The handler is rotation-safe (:class:`logging.handlers.WatchedFileHandler`):
+make ``audit.jsonl`` append-only on disk with ``chattr +a`` and rotate it with
+the bundled logrotate config; the handler reopens the file after rotation.
+
+Audit failures must never break a tool call: if the sink cannot be opened the
+logger degrades to stderr (or silence) and records ``degraded=True``.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+import sys
+from logging.handlers import WatchedFileHandler
+from pathlib import Path
+from typing import Any
+
+from .util import now_iso, sha256_hex
+
+__all__ = ["AuditLogger"]
+
+
+def _format_jsonl(entry: dict[str, Any]) -> str:
+    return json.dumps(entry, default=str, ensure_ascii=False)
+
+
+def _stringify(value: Any) -> str:
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return str(value)
+    return json.dumps(value, default=str, ensure_ascii=False, separators=(",", ":"))
+
+
+def _cef_escape(value: str) -> str:
+    # CEF extension escaping for separators and line breaks.
+    return (
+        value.replace("\\", "\\\\")
+        .replace("=", "\\=")
+        .replace("|", "\\|")
+        .replace("\n", "\\n")
+        .replace("\r", "\\r")
+    )
+
+
+def _leef_escape(value: str) -> str:
+    # LEEF extension escaping with tab-separated key-value fields.
+    return (
+        value.replace("\\", "\\\\")
+        .replace("=", "\\=")
+        .replace("\t", "\\t")
+        .replace("\n", "\\n")
+        .replace("\r", "\\r")
+    )
+
+
+def _format_cef(entry: dict[str, Any]) -> str:
+    ext = " ".join(f"{k}={_cef_escape(_stringify(v))}" for k, v in sorted(entry.items()))
+    return f"CEF:0|relay-shell|relay-shell|1.0|audit|tool-call|5|{ext}"
+
+
+def _format_leef(entry: dict[str, Any]) -> str:
+    ext = "\t".join(f"{k}={_leef_escape(_stringify(v))}" for k, v in sorted(entry.items()))
+    return f"LEEF:2.0|relay-shell|relay-shell|1.0|audit\t{ext}"
+
+
+_FORMATTERS = {"jsonl": _format_jsonl, "cef": _format_cef, "leef": _format_leef}
+
+
+class AuditLogger:
+    """Writes structured audit records. Construction never raises."""
+
+    def __init__(self, path: str, also_stderr: bool = False, fmt: str = "jsonl") -> None:
+        self.path = path
+        self.degraded = False
+        self.degraded_reason = ""
+        self.format = fmt
+        self._log = logging.getLogger("relay_shell.audit")
+        self._log.setLevel(logging.INFO)
+        self._log.propagate = False
+        for handler in list(self._log.handlers):
+            self._log.removeHandler(handler)
+
+        sink: logging.Handler
+        try:
+            target = Path(path).expanduser()
+            target.parent.mkdir(parents=True, exist_ok=True)
+            # Pre-create using O_APPEND to stay compatible with append-only
+            # hardened files (e.g., chattr +a on Linux).
+            fd = os.open(str(target), os.O_APPEND | os.O_CREAT | os.O_WRONLY, 0o600)
+            os.close(fd)
+            # Defensive for existing files that might already be too permissive.
+            with contextlib.suppress(OSError):
+                target.chmod(0o600)
+            sink = WatchedFileHandler(str(target), encoding="utf-8")
+        except OSError as exc:  # unwritable path -> degrade, never crash
+            self.degraded = True
+            self.degraded_reason = str(exc)
+            sink = logging.StreamHandler(sys.stderr)
+        sink.setFormatter(logging.Formatter("%(message)s"))
+        self._log.addHandler(sink)
+
+        if also_stderr and not self.degraded:
+            echo = logging.StreamHandler(sys.stderr)
+            echo.setFormatter(logging.Formatter("AUDIT %(message)s"))
+            self._log.addHandler(echo)
+
+    def record(
+        self,
+        *,
+        tool: str,
+        args: dict[str, Any],
+        output: str,
+        exit_code: int | None,
+        tier: int,
+        request_id: str = "",
+        client_id: str = "",
+        denied: bool = False,
+    ) -> None:
+        """Append one audit line. Best-effort; swallows its own errors."""
+        entry: dict[str, Any] = {
+            "ts": now_iso(),
+            "tool": tool,
+            "tier": tier,
+            "denied": denied,
+            "args": args,
+            "output_sha256": sha256_hex(output),
+            "output_len": len(output.encode("utf-8", "replace")),
+            "exit_code": exit_code,
+        }
+        if request_id:
+            entry["request_id"] = request_id
+        if client_id:
+            entry["client_id"] = client_id
+        # Audit must never break a tool call.
+        with contextlib.suppress(Exception):
+            formatter = _FORMATTERS.get(self.format, _format_jsonl)
+            self._log.info(formatter(entry))
+
+    def tail(self, lines: int) -> str:
+        """Return the last ``lines`` audit records as on-disk text lines.
+
+        Records are returned in their original on-disk order (oldest first).
+        The empty string is returned if the audit file does not exist, is
+        empty, or cannot be read - this method must never raise; it is
+        consumed by a read-only diagnostic tool and a failure here should
+        not break the caller.
+
+        Reading is opened on a fresh fd; the writer's append-only fd is
+        untouched so this is safe to call concurrently with normal tool
+        execution. ``WatchedFileHandler`` line-buffers each emit, so any
+        record returned here is structurally complete.
+
+        Implementation reads backward from end-of-file in 8 KiB chunks
+        and stops as soon as it has ``lines + 1`` newlines (the +1
+        catches a partial leading line). Worst-case memory is bounded
+        by ``lines * record_size + chunk_size``, not by file size, so
+        the bounded-execution invariant holds even when the audit log
+        has not rotated in a long time.
+        """
+        if lines <= 0:
+            return ""
+        # Outer `except Exception` keeps the contract literal: even an
+        # exotic OSError subclass, a ValueError from a path with an
+        # embedded NUL, or an unexpected decoding failure must collapse
+        # to "" rather than propagate to the diagnostic tool's caller.
+        try:
+            path = Path(self.path).expanduser()
+            with path.open("rb") as fh:
+                fh.seek(0, os.SEEK_END)
+                size = fh.tell()
+                if size == 0:
+                    return ""
+
+                chunk_size = 8192
+                data = b""
+                offset = size
+                # Read backward until we have at least one more newline
+                # than requested, or we hit the start of the file.
+                while offset > 0 and data.count(b"\n") <= lines:
+                    read = min(chunk_size, offset)
+                    offset -= read
+                    fh.seek(offset)
+                    data = fh.read(read) + data
+
+            text = data.decode("utf-8", errors="replace")
+            # Drop blank trailing lines (logger does not write them, but
+            # a caller might tail a partial write window) and strip the
+            # line terminator on each record for consistent line output.
+            records = [ln for ln in text.splitlines() if ln.strip()]
+            return "\n".join(records[-lines:])
+        except Exception:  # noqa: BLE001 - contract is "never raise"
+            return ""

relay_shell/auth/__init__.py

@@ -0,0 +1,7 @@
+"""Optional OAuth 2.1 surface for the HTTP transport."""
+
+from __future__ import annotations
+
+from .oauth import FileOAuthProvider, build_auth_settings, make_oauth_provider
+
+__all__ = ["FileOAuthProvider", "build_auth_settings", "make_oauth_provider"]

relay_shell/auth/oauth.py

@@ -0,0 +1,295 @@
+"""File-backed OAuth 2.1 authorization-server provider.
+
+Modeled on a production MCP gateway's provider: dynamic client registration
+with optional single-client lockdown, PKCE (the SDK enforces the challenge),
+short-lived authorization codes, rotating refresh tokens, and lazy expiry on
+read. State is three JSON files under ``auth_state_dir``; no database.
+
+This is optional and only constructed for the HTTP transport when
+``RELAY_SHELL_AUTH_ENABLED=true``. Errors here must surface as auth failures, never
+as a crashed transport, so reconstruction is defensive.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import secrets
+import time
+from pathlib import Path
+from typing import Any
+
+from mcp.server.auth.provider import (
+    AccessToken,
+    AuthorizationCode,
+    AuthorizationParams,
+    OAuthAuthorizationServerProvider,
+    RefreshToken,
+    construct_redirect_uri,
+)
+from mcp.server.auth.settings import (
+    AuthSettings,
+    ClientRegistrationOptions,
+    RevocationOptions,
+)
+from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
+from pydantic import AnyHttpUrl
+
+__all__ = ["FileOAuthProvider", "build_auth_settings", "make_oauth_provider"]
+
+_SCOPES = ["mcp:tools"]
+_REFRESH_PREFIX = "refresh:"
+
+
+def _now() -> int:
+    return int(time.time())
+
+
+_DIR_MODE = 0o700
+_FILE_MODE = 0o600
+
+
+class _Store:
+    """Tiny JSON file store. Each call reads/writes the whole file.
+
+    Directory and file permissions are set explicitly so the security
+    expectation does not depend on the caller's umask. systemd's
+    ``UMask=0077`` in the hardening drop-in matches this, but an operator
+    running the HTTP transport ad-hoc (tests, dev shells) gets the same
+    private permissions for free.
+    """
+
+    def __init__(self, path: Path) -> None:
+        self._path = path
+        parent = self._path.parent
+        parent.mkdir(parents=True, exist_ok=True)
+        # mkdir(mode=...) only applies when the directory is freshly
+        # created and never to existing parents; chmod is idempotent and
+        # covers both. Best-effort: a parent we cannot chmod (e.g. owned
+        # by another user) is the operator's responsibility, not fatal.
+        with contextlib.suppress(OSError):
+            parent.chmod(_DIR_MODE)
+
+    def load(self) -> dict[str, Any]:
+        try:
+            data: Any = json.loads(self._path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            return {}
+        return data if isinstance(data, dict) else {}
+
+    def save(self, data: dict[str, Any]) -> None:
+        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
+        payload = json.dumps(data, indent=2, default=str)
+        # Race-free: create the temp file with 0o600 atomically rather than
+        # writing first and chmod'ing after.
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, _FILE_MODE)
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(payload)
+        tmp.replace(self._path)
+
+
+class FileOAuthProvider(OAuthAuthorizationServerProvider):  # type: ignore[type-arg]
+    """OAuth 2.1 AS provider with file-backed state."""
+
+    def __init__(
+        self,
+        state_dir: str,
+        *,
+        single_client: bool,
+        access_ttl: int,
+        refresh_ttl: int,
+        code_ttl: int,
+    ) -> None:
+        base = Path(state_dir).expanduser()
+        self._clients = _Store(base / "clients.json")
+        self._codes = _Store(base / "codes.json")
+        self._tokens = _Store(base / "tokens.json")
+        self._single_client = single_client
+        self._access_ttl = access_ttl
+        self._refresh_ttl = refresh_ttl
+        self._code_ttl = code_ttl
+
+    # --- clients ---
+    async def get_client(self, client_id: str) -> OAuthClientInformationFull | None:
+        data = self._clients.load().get(client_id)
+        if not data:
+            return None
+        try:
+            return OAuthClientInformationFull.model_validate(data)
+        except Exception:  # noqa: BLE001
+            return None
+
+    async def register_client(self, client_info: OAuthClientInformationFull) -> None:
+        cid = client_info.client_id or ""
+        if not cid:
+            raise ValueError("client_id is required")
+        clients = self._clients.load()
+        if self._single_client and clients and cid not in clients:
+            raise ValueError("Dynamic client registration is closed (single-client lockdown).")
+        clients[cid] = json.loads(client_info.model_dump_json())
+        self._clients.save(clients)
+
+    # --- authorization codes ---
+    async def authorize(
+        self, client: OAuthClientInformationFull, params: AuthorizationParams
+    ) -> str:
+        code = secrets.token_urlsafe(48)
+        codes = self._codes.load()
+        codes[code] = {
+            "code": code,
+            "client_id": client.client_id or "",
+            "scopes": list(getattr(params, "scopes", None) or _SCOPES),
+            "expires_at": _now() + self._code_ttl,
+            "code_challenge": getattr(params, "code_challenge", ""),
+            "redirect_uri": str(params.redirect_uri),
+            "redirect_uri_provided_explicitly": bool(
+                getattr(params, "redirect_uri_provided_explicitly", True)
+            ),
+            "resource": getattr(params, "resource", None),
+        }
+        self._codes.save(codes)
+        return construct_redirect_uri(
+            str(params.redirect_uri), code=code, state=getattr(params, "state", None)
+        )
+
+    def _build_auth_code(self, rec: dict[str, Any]) -> AuthorizationCode | None:
+        try:
+            return AuthorizationCode(
+                code=rec["code"],
+                scopes=rec["scopes"],
+                expires_at=float(rec["expires_at"]),
+                client_id=rec["client_id"],
+                code_challenge=rec.get("code_challenge", ""),
+                redirect_uri=rec["redirect_uri"],
+                redirect_uri_provided_explicitly=rec.get("redirect_uri_provided_explicitly", True),
+            )
+        except Exception:  # noqa: BLE001
+            return None
+
+    async def load_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: str
+    ) -> AuthorizationCode | None:
+        codes = self._codes.load()
+        rec = codes.get(authorization_code)
+        if not rec or rec.get("client_id") != (client.client_id or ""):
+            return None
+        if int(rec.get("expires_at", 0)) < _now():
+            codes.pop(authorization_code, None)
+            self._codes.save(codes)
+            return None
+        return self._build_auth_code(rec)
+
+    async def exchange_authorization_code(
+        self, client: OAuthClientInformationFull, authorization_code: AuthorizationCode
+    ) -> OAuthToken:
+        codes = self._codes.load()
+        codes.pop(authorization_code.code, None)
+        self._codes.save(codes)
+        scopes = list(authorization_code.scopes or _SCOPES)
+        return self._issue(client.client_id or "", scopes)
+
+    # --- tokens ---
+    def _issue(self, client_id: str, scopes: list[str]) -> OAuthToken:
+        access = secrets.token_urlsafe(48)
+        refresh = secrets.token_urlsafe(48)
+        tokens = self._tokens.load()
+        tokens[access] = {
+            "token": access,
+            "client_id": client_id,
+            "scopes": scopes,
+            "expires_at": _now() + self._access_ttl,
+        }
+        tokens[_REFRESH_PREFIX + refresh] = {
+            "token": refresh,
+            "client_id": client_id,
+            "scopes": scopes,
+            "expires_at": _now() + self._refresh_ttl,
+        }
+        self._tokens.save(tokens)
+        return OAuthToken(
+            access_token=access,
+            token_type="Bearer",
+            expires_in=self._access_ttl,
+            refresh_token=refresh,
+            scope=" ".join(scopes),
+        )
+
+    async def load_access_token(self, token: str) -> AccessToken | None:
+        tokens = self._tokens.load()
+        rec = tokens.get(token)
+        if not rec:
+            return None
+        if int(rec.get("expires_at", 0)) < _now():
+            tokens.pop(token, None)
+            self._tokens.save(tokens)
+            return None
+        try:
+            return AccessToken(
+                token=rec["token"],
+                client_id=rec["client_id"],
+                scopes=rec["scopes"],
+                expires_at=int(rec["expires_at"]),
+            )
+        except Exception:  # noqa: BLE001
+            return None
+
+    async def load_refresh_token(
+        self, client: OAuthClientInformationFull, refresh_token: str
+    ) -> RefreshToken | None:
+        rec = self._tokens.load().get(_REFRESH_PREFIX + refresh_token)
+        if not rec or rec.get("client_id") != (client.client_id or ""):
+            return None
+        if int(rec.get("expires_at", 0)) < _now():
+            return None
+        try:
+            return RefreshToken(
+                token=rec["token"],
+                client_id=rec["client_id"],
+                scopes=rec["scopes"],
+                expires_at=int(rec["expires_at"]),
+            )
+        except Exception:  # noqa: BLE001
+            return None
+
+    async def exchange_refresh_token(
+        self,
+        client: OAuthClientInformationFull,
+        refresh_token: RefreshToken,
+        scopes: list[str],
+    ) -> OAuthToken:
+        tokens = self._tokens.load()
+        tokens.pop(_REFRESH_PREFIX + refresh_token.token, None)
+        self._tokens.save(tokens)
+        effective = list(scopes or refresh_token.scopes or _SCOPES)
+        return self._issue(client.client_id or "", effective)
+
+    async def revoke_token(self, token: AccessToken | RefreshToken) -> None:
+        tokens = self._tokens.load()
+        raw = getattr(token, "token", "")
+        tokens.pop(raw, None)
+        tokens.pop(_REFRESH_PREFIX + raw, None)
+        self._tokens.save(tokens)
+
+
+def build_auth_settings(issuer: str) -> AuthSettings:
+    url = AnyHttpUrl(issuer)
+    return AuthSettings(
+        issuer_url=url,
+        resource_server_url=url,
+        client_registration_options=ClientRegistrationOptions(
+            enabled=True, valid_scopes=_SCOPES, default_scopes=_SCOPES
+        ),
+        revocation_options=RevocationOptions(enabled=True),
+        required_scopes=_SCOPES,
+    )
+
+
+def make_oauth_provider(settings: Any) -> FileOAuthProvider:
+    return FileOAuthProvider(
+        settings.auth_state_dir,
+        single_client=settings.auth_single_client,
+        access_ttl=settings.auth_access_ttl,
+        refresh_ttl=settings.auth_refresh_ttl,
+        code_ttl=settings.auth_code_ttl,
+    )

relay_shell/config.py

@@ -0,0 +1,109 @@
+"""Typed, environment-driven configuration.
+
+All settings are read from ``RELAY_SHELL_*`` environment variables (and an optional
+``.env``). Invalid values fail fast at startup rather than mid-run.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+__all__ = ["Settings", "get_settings"]
+
+_TRANSPORTS = {"stdio", "http"}
+_POLICY_MODES = {"open", "guarded", "readonly"}
+_KNOWN_HOSTS = {"strict", "accept-new", "ignore"}
+_AUDIT_FORMATS = {"jsonl", "cef", "leef"}
+
+
+class Settings(BaseSettings):
+    """Effective server configuration. Immutable after load."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="RELAY_SHELL_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        frozen=True,
+    )
+
+    # Transport
+    transport: str = "stdio"
+    http_host: str = "127.0.0.1"
+    http_port: int = Field(default=8080, ge=1, le=65535)
+
+    # Limits
+    max_output: int = Field(default=65536, ge=1024)
+    max_output_hard: int = Field(default=1_048_576, ge=4096)
+    default_timeout: int = Field(default=60, ge=1)
+    max_timeout: int = Field(default=900, ge=1)
+    max_sessions: int = Field(default=64, ge=1, le=1024)
+    session_idle_timeout: int = Field(default=1800, ge=10)
+    session_buffer_bytes: int = Field(default=262_144, ge=4096)
+
+    # Policy
+    policy_mode: str = "open"
+    policy_deny: str = ""
+    policy_allow: str = ""
+
+    # Audit
+    audit_path: str = "/var/log/relay-shell/audit.jsonl"
+    audit_stderr: bool = False
+    audit_format: str = "jsonl"
+
+    # SSH
+    ssh_config: str = "~/.ssh/config"
+    inventory: str = ""
+    ssh_known_hosts: str = "accept-new"
+    ssh_connect_timeout: int = Field(default=10, ge=1, le=120)
+    ssh_keepalive: int = Field(default=30, ge=0, le=600)
+
+    # OAuth 2.1 (HTTP transport only)
+    auth_enabled: bool = False
+    auth_issuer: str = "https://localhost:8080"
+    auth_state_dir: str = "/var/lib/relay-shell/oauth"
+    auth_single_client: bool = True
+    auth_access_ttl: int = Field(default=3600, ge=60)
+    auth_refresh_ttl: int = Field(default=2_592_000, ge=300)
+    auth_code_ttl: int = Field(default=300, ge=30)
+
+    @field_validator("transport")
+    @classmethod
+    def _v_transport(cls, v: str) -> str:
+        v = v.strip().lower()
+        if v not in _TRANSPORTS:
+            raise ValueError(f"transport must be one of {sorted(_TRANSPORTS)}")
+        return v
+
+    @field_validator("policy_mode")
+    @classmethod
+    def _v_policy(cls, v: str) -> str:
+        v = v.strip().lower()
+        if v not in _POLICY_MODES:
+            raise ValueError(f"policy_mode must be one of {sorted(_POLICY_MODES)}")
+        return v
+
+    @field_validator("ssh_known_hosts")
+    @classmethod
+    def _v_known_hosts(cls, v: str) -> str:
+        v = v.strip().lower()
+        if v not in _KNOWN_HOSTS:
+            raise ValueError(f"ssh_known_hosts must be one of {sorted(_KNOWN_HOSTS)}")
+        return v
+
+    @field_validator("audit_format")
+    @classmethod
+    def _v_audit_format(cls, v: str) -> str:
+        v = v.strip().lower()
+        if v not in _AUDIT_FORMATS:
+            raise ValueError(f"audit_format must be one of {sorted(_AUDIT_FORMATS)}")
+        return v
+
+
+@lru_cache(maxsize=1)
+def get_settings() -> Settings:
+    """Process-wide cached settings instance."""
+    return Settings()