command-gate 0.2.4__py3-none-any.whl

cgate/db/types.py

@@ -0,0 +1,77 @@
+"""Domain types for the database layer: enums, NewType IDs, and frozen dataclasses."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING, NewType
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+
+class ServerType(StrEnum):
+    """Type of a target server. Drives dialect (PowerShell vs Bash) and exec backend."""
+
+    WINDOWS = "windows"
+    LINUX = "linux"
+
+
+class CommandStatus(StrEnum):
+    """Lifecycle of a single command in a batch.
+
+    Flow: PENDING -> APPROVED -> EXECUTED (or PENDING -> REJECTED / FAILED).
+    APPROVED and PENDING are non-terminal (resolved_at IS NULL).
+    """
+
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    EXECUTED = "executed"
+    FAILED = "failed"
+
+
+BatchId = NewType("BatchId", str)
+CommandId = NewType("CommandId", str)
+
+
+@dataclass(frozen=True, slots=True)
+class Batch:
+    """A batch of related commands proposed together by one AI invocation."""
+
+    id: BatchId
+    title: str
+    description: str | None
+    requested_by_agent: str | None
+    created_at: datetime
+    resolved_at: datetime | None
+
+
+@dataclass(frozen=True, slots=True)
+class Command:
+    """A single command within a batch, addressed to one server."""
+
+    id: CommandId
+    batch_id: BatchId
+    position: int
+    server_alias: str
+    server_type: ServerType
+    command: str
+    status: CommandStatus
+    result: str | None
+    approved_by: str | None
+    created_at: datetime
+    resolved_at: datetime | None
+    reason: str | None
+    risk_label: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class Connection:
+    """A saved connection from this machine to a remote server, identified by alias."""
+
+    alias: str
+    hostname: str
+    server_type: ServerType
+    detection_ssh: bool
+    detection_winrm: bool
+    created_at: datetime

cgate/executor/__init__.py

@@ -0,0 +1,7 @@
+"""Remote command execution: WinRM for Windows, SSH for Linux."""
+from __future__ import annotations
+
+from cgate.executor.base import DEFAULT_TIMEOUT_SECONDS, ErrorKind, ExecutionResult
+from cgate.executor.selector import execute_command
+
+__all__ = ["DEFAULT_TIMEOUT_SECONDS", "ErrorKind", "ExecutionResult", "execute_command"]

cgate/executor/base.py

@@ -0,0 +1,71 @@
+"""Domain types and exceptions for the executor layer."""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+DEFAULT_TIMEOUT_SECONDS: Final = 30.0
+
+
+class ErrorKind(StrEnum):
+    """How a command execution failed (None on success)."""
+
+    TIMEOUT = "timeout"
+    AUTH_FAILED = "auth_failed"
+    HOST_UNREACHABLE = "host_unreachable"
+    PROTOCOL_ERROR = "protocol_error"
+
+
+class ExecutorError(Exception):
+    """Base for executor errors that should be surfaced as a structured result."""
+
+
+class CommandTimeout(ExecutorError):  # noqa: N818 - public name required by executor API
+    """Execution exceeded the timeout."""
+
+
+class AuthenticationFailed(ExecutorError):  # noqa: N818 - public name required by executor API
+    """Credentials were rejected by the target."""
+
+
+class HostUnreachable(ExecutorError):  # noqa: N818 - public name required by executor API
+    """The target host refused or failed the TCP connection."""
+
+
+class ProtocolError(ExecutorError):
+    """The remote server returned malformed output."""
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionResult:
+    """Outcome of running one command on one server.
+
+    ``error_kind`` is None on any successful connection, regardless of exit code.
+    Use ``ok`` to require both a zero exit code and no executor error.
+    """
+
+    stdout: str
+    stderr: str
+    exit_code: int
+    duration_ms: int
+    error_kind: ErrorKind | None
+
+    @property
+    def ok(self) -> bool:
+        """Return true exactly when execution succeeded with a zero exit code."""
+        return self.error_kind is None and self.exit_code == 0
+
+
+def measure_duration_ms() -> tuple[int, Callable[[], int]]:
+    """Return the monotonic start in milliseconds and an elapsed-time callable."""
+    start = time.monotonic()
+
+    def elapsed() -> int:
+        return int((time.monotonic() - start) * 1000)
+
+    return int(start * 1000), elapsed

cgate/executor/selector.py

@@ -0,0 +1,61 @@
+"""Top-level dispatch for executing a command on a saved connection."""
+from __future__ import annotations
+
+from cgate.connections.auth import StoredCredential, get_credential, is_kerberos_available
+from cgate.db.types import Connection, ServerType
+from cgate.executor.base import DEFAULT_TIMEOUT_SECONDS, ErrorKind, ExecutionResult
+from cgate.executor.ssh import execute_linux
+from cgate.executor.winrm import execute_windows
+
+
+def execute_command(
+    connection: Connection,
+    command: str,
+    *,
+    credential: StoredCredential | None = None,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+) -> ExecutionResult:
+    """Execute a command on a saved connection using its selected backend."""
+    resolved_credential = credential
+    if resolved_credential is None:
+        resolved_credential = get_credential(connection.alias)
+    if resolved_credential is None:
+        return _missing_credential_result(connection)
+
+    match connection.server_type:
+        case ServerType.WINDOWS:
+            return execute_windows(
+                connection.hostname,
+                command,
+                resolved_credential,
+                timeout=timeout,
+            )
+        case ServerType.LINUX:
+            return execute_linux(
+                connection.hostname,
+                command,
+                resolved_credential,
+                timeout=timeout,
+            )
+
+
+def _missing_credential_result(connection: Connection) -> ExecutionResult:
+    match connection.server_type:
+        case ServerType.WINDOWS:
+            kerberos_available = is_kerberos_available()
+        case ServerType.LINUX:
+            kerberos_available = False
+    if kerberos_available:
+        message = (
+            "kerberos passthrough available, but Phase 1 doesn't ship kerberos transport; "
+            "store an NTLM credential with `cgate connections add` first."
+        )
+    else:
+        message = f"no credential for alias '{connection.alias}'"
+    return ExecutionResult(
+        stdout="",
+        stderr=message,
+        exit_code=-1,
+        duration_ms=0,
+        error_kind=ErrorKind.AUTH_FAILED,
+    )

cgate/executor/ssh.py

@@ -0,0 +1,157 @@
+"""Linux command execution over SSH (paramiko)."""
+from __future__ import annotations
+
+import contextlib
+import time
+from typing import TYPE_CHECKING, Final
+
+import paramiko
+from paramiko.ssh_exception import NoValidConnectionsError
+from typing_extensions import override
+
+from cgate.core.paths import data_dir
+from cgate.executor.base import DEFAULT_TIMEOUT_SECONDS, ErrorKind, ExecutionResult
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from cgate.connections.auth import StoredCredential
+
+SSH_PORT: Final = 22
+
+
+class _TrustOnFirstUsePolicy(paramiko.MissingHostKeyPolicy):
+    """Accept an unknown host key once, then pin it to ``known_hosts_path``.
+
+    Unlike ``AutoAddPolicy`` (issue #6), which trusts every connection with
+    no memory at all, paramiko only calls ``missing_host_key`` when the
+    hostname isn't already present in the client's loaded host keys --
+    if it IS present but the presented key doesn't match, paramiko raises
+    ``BadHostKeyException`` on its own before this policy is ever
+    consulted. So preloading a persistent file and only auto-trusting
+    truly new hosts here gives real trust-on-first-use: a key that
+    changes after that first connection (MITM, or the box got rebuilt)
+    is rejected instead of silently accepted again.
+    """
+
+    _known_hosts_path: Path  # class-level annotation required by strict mode
+
+    def __init__(self, known_hosts_path: Path) -> None:
+        """Remember where to persist newly-trusted host keys."""
+        self._known_hosts_path = known_hosts_path
+
+    @override
+    def missing_host_key(
+        self, client: paramiko.SSHClient, hostname: str, key: paramiko.PKey
+    ) -> None:
+        """Trust and persist a host key seen for the first time."""
+        client.get_host_keys().add(hostname, key.get_name(), key)
+        self._known_hosts_path.parent.mkdir(parents=True, exist_ok=True)
+        client.save_host_keys(str(self._known_hosts_path))
+
+
+def _known_hosts_path() -> Path:
+    return data_dir() / "known_hosts"
+
+
+def execute_linux(
+    hostname: str,
+    command: str,
+    credential: StoredCredential,
+    *,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+) -> ExecutionResult:
+    """Run a command on a host via SSH using a key before a password."""
+    started = time.monotonic()
+    client = paramiko.SSHClient()
+    known_hosts_path = _known_hosts_path()
+    if known_hosts_path.exists():
+        client.load_host_keys(str(known_hosts_path))
+    client.set_missing_host_key_policy(_TrustOnFirstUsePolicy(known_hosts_path))
+
+    try:
+        if credential.ssh_key:
+            client.connect(
+                hostname,
+                port=SSH_PORT,
+                username=credential.username,
+                key_filename=credential.ssh_key,
+                timeout=timeout,
+                auth_timeout=timeout,
+                banner_timeout=timeout,
+            )
+        elif credential.password:
+            client.connect(
+                hostname,
+                port=SSH_PORT,
+                username=credential.username,
+                password=credential.password,
+                timeout=timeout,
+                auth_timeout=timeout,
+                banner_timeout=timeout,
+            )
+        else:
+            return _failure(
+                "credential has neither ssh_key nor password",
+                ErrorKind.AUTH_FAILED,
+                started,
+            )
+
+        _stdin, stdout, stderr = client.exec_command(command, timeout=timeout)
+        stdout.channel.settimeout(timeout)
+        try:
+            out_bytes = stdout.read()
+            err_bytes = stderr.read()
+            exit_code = stdout.channel.recv_exit_status()
+        except Exception as exc:  # noqa: BLE001 - Paramiko streams expose generic read errors
+            return _failure(str(exc), ErrorKind.TIMEOUT, started)
+
+        return ExecutionResult(
+            stdout=_decode_output(out_bytes),
+            stderr=_decode_output(err_bytes),
+            exit_code=int(exit_code),
+            duration_ms=int((time.monotonic() - started) * 1000),
+            error_kind=None,
+        )
+    except Exception as exc:  # noqa: BLE001 - Paramiko connect can surface socket subclasses
+        return _failure_from_paramiko_exception(exc, started)
+    finally:
+        with contextlib.suppress(Exception):
+            client.close()
+
+
+def _decode_output(output: str | bytes | bytearray | None) -> str:
+    if isinstance(output, (bytes, bytearray)):
+        return output.decode("utf-8", errors="replace")
+    return output or ""
+
+
+def _failure(message: str, error_kind: ErrorKind, started: float) -> ExecutionResult:
+    return ExecutionResult(
+        stdout="",
+        stderr=message,
+        exit_code=-1,
+        duration_ms=int((time.monotonic() - started) * 1000),
+        error_kind=error_kind,
+    )
+
+
+def _failure_from_paramiko_exception(exc: Exception, started: float) -> ExecutionResult:
+    return _failure(str(exc), _classify_paramiko_exception(exc), started)
+
+
+def _classify_paramiko_exception(exc: Exception) -> ErrorKind:
+    name = type(exc).__name__.lower()
+    message = str(exc).lower()
+    if isinstance(exc, paramiko.AuthenticationException) or "auth" in name:
+        return ErrorKind.AUTH_FAILED
+    if isinstance(exc, NoValidConnectionsError):
+        return ErrorKind.HOST_UNREACHABLE
+    if any(
+        signal in message
+        for signal in ("no route to host", "connection refused", "getaddrinfo failed")
+    ):
+        return ErrorKind.HOST_UNREACHABLE
+    if "timed out" in message or "timeout" in name:
+        return ErrorKind.TIMEOUT
+    return ErrorKind.PROTOCOL_ERROR

cgate/executor/winrm.py

@@ -0,0 +1,129 @@
+"""Windows command execution via WinRM (pywinrm)."""
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, Final
+
+import requests.exceptions
+import winrm
+
+from cgate.executor.base import DEFAULT_TIMEOUT_SECONDS, ErrorKind, ExecutionResult
+
+if TYPE_CHECKING:
+    from cgate.connections.auth import StoredCredential
+
+WINRM_HTTP_PORT: Final = 5985
+WINRM_HTTPS_PORT: Final = 5986
+
+
+def _endpoint(hostname: str, *, https: bool) -> str:
+    port = WINRM_HTTPS_PORT if https else WINRM_HTTP_PORT
+    scheme = "https" if https else "http"
+    return f"{scheme}://{hostname}:{port}/wsman"
+
+
+def execute_windows(
+    hostname: str,
+    command: str,
+    credential: StoredCredential,
+    *,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    https: bool = True,
+) -> ExecutionResult:
+    """Run a command on a host over WinRM with NTLM authentication.
+
+    Prefers the protocol requested by the caller (defaults to HTTPS for
+    the secure WinRM config) but falls back to the other protocol when
+    the primary listener is unreachable. WinRM operators commonly run
+    HTTP on port 5985 for internal/lab hosts where TLS is not wired
+    up, so a connection refused on 5986 should not be fatal when 5985
+    is available.
+
+    ``server_cert_validation`` is passed explicitly (issue #7): pywinrm
+    already defaults to ``"validate"``, but pinning it in code makes the
+    guarantee explicit rather than resting on the library's default. A
+    certificate that fails validation is NOT treated as "try the other
+    protocol" like a refused/unreachable connection is -- something IS
+    listening and presenting an untrusted cert, so falling back to plain
+    HTTP there would silently downgrade a possibly-MITM'd HTTPS attempt
+    into an unauthenticated cleartext one instead of failing loudly.
+
+    Commands are executed via PowerShell (``session.run_ps``) rather
+    than the legacy cmd shell. PowerShell handles both PowerShell
+    cmdlets (``Get-ChildItem``, ``Set-Service``, ...) and classic
+    cmd-line utilities (``dir``, ``type``, ...) transparently, so this
+    covers the common cases without forcing users to wrap commands
+    manually. Per-server shell selection (or cmd-vs-ps fallback) is
+    deferred to a future iteration.
+    """
+    started = time.monotonic()
+    last_exc: Exception | None = None
+    for attempt_https in (https, not https):
+        try:
+            session = winrm.Session(
+                _endpoint(hostname, https=attempt_https),
+                auth=(credential.username, credential.password or ""),
+                transport="ntlm",
+                server_cert_validation="validate",
+                # pywinrm requires ``read_timeout_sec > operation_timeout_sec``;
+                # otherwise it raises ``read_timeout_sec must exceed
+                # operation_timeout_sec``. The operation budget covers the
+                # round-trip + remote execution; the read budget also has
+                # to cover pulling the response back, so we add a fixed
+                # margin.
+                operation_timeout_sec=timeout,
+                read_timeout_sec=timeout + 30,
+            )
+            response = session.run_ps(command)
+            return ExecutionResult(
+                stdout=_decode_output(response.std_out),
+                stderr=_decode_output(response.std_err),
+                exit_code=int(response.status_code),
+                duration_ms=int((time.monotonic() - started) * 1000),
+                error_kind=None,
+            )
+        except requests.exceptions.SSLError as exc:
+            return _failure_from_winrm_exception(exc, started)
+        except Exception as exc:  # noqa: BLE001 - SDK errors lack a closed common hierarchy
+            last_exc = exc
+            continue
+
+    assert last_exc is not None  # loop ran at least once
+    return _failure_from_winrm_exception(last_exc, started)
+
+
+def _decode_output(output: str | bytes | bytearray | None) -> str:
+    if isinstance(output, (bytes, bytearray)):
+        return output.decode("utf-8", errors="replace")
+    return output or ""
+
+
+def _failure_from_winrm_exception(exc: Exception, started: float) -> ExecutionResult:
+    return ExecutionResult(
+        stdout="",
+        stderr=str(exc),
+        exit_code=-1,
+        duration_ms=int((time.monotonic() - started) * 1000),
+        error_kind=_classify_winrm_exception(exc),
+    )
+
+
+def _classify_winrm_exception(exc: Exception) -> ErrorKind:
+    name = type(exc).__name__.lower()
+    message = str(exc).lower()
+    if any(signal in message for signal in ("401", "unauthorized", "auth", "credential")):
+        return ErrorKind.AUTH_FAILED
+    if "timed out" in message or "timeout" in name:
+        return ErrorKind.TIMEOUT
+    if any(
+        signal in message
+        for signal in (
+            "connection refused",
+            "no route to host",
+            "getaddrinfo failed",
+            "name or service not known",
+            "network is unreachable",
+        )
+    ):
+        return ErrorKind.HOST_UNREACHABLE
+    return ErrorKind.PROTOCOL_ERROR

cgate/helper/__init__.py

@@ -0,0 +1,10 @@
+"""Standalone Windows file-swap helper (``cgate-helper.exe``).
+
+Built as its own PyInstaller binary, separate from the main ``cgate.exe``,
+so it never shares an image name with the process it's replacing/deleting
+and there is nothing to disambiguate on Windows's process list. Must not
+import anything from ``cgate.cli`` -- keep this package's dependency graph
+to the standard library plus ``cgate.core`` only.
+"""
+
+from __future__ import annotations

cgate/helper/__main__.py

@@ -0,0 +1,112 @@
+"""Entry point for the standalone ``cgate-helper.exe`` binary.
+
+Fully unattended: never prompts, always exits with a code and a log line.
+Invoked by the main ``cgate.exe`` (see ``cgate.update.spawn_helper``) after
+it has decided a self-lock swap/delete needs to happen from a process that
+isn't ``cgate.exe`` itself.
+
+Usage:
+    cgate-helper.exe replace --target PATH --source PATH --wait-pid N [...]
+    cgate-helper.exe delete  --target PATH --wait-pid N [...]
+    cgate-helper.exe heal   --target PATH [--wait-pid N ...]
+
+``heal`` auto-detects ``<target>.new`` and atomically swaps it onto
+``<target>`` -- the self-healing path used to finish a previously failed
+``update apply`` when the next ``cgate`` invocation notices the staged
+file and no other cgate processes are running.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from cgate.core.update_log import append_log
+from cgate.helper.waiter import (
+    SOURCE_NAMES,
+    is_safe_target,
+    retry_delete,
+    retry_replace,
+    wait_for_pids,
+)
+
+_WAIT_TIMEOUT_SECONDS = 30.0
+_RETRY_TOTAL_SECONDS = 10.0
+
+
+def _helper_dir() -> Path:
+    """Return the directory this helper (or its source, when unfrozen) lives in."""
+    if getattr(sys, "frozen", False):
+        return Path(sys.executable).resolve().parent
+    return Path(__file__).resolve().parent
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the ``replace``/``delete`` subcommand parser."""
+    parser = argparse.ArgumentParser(prog="cgate-helper")
+    subparsers = parser.add_subparsers(dest="operation", required=True)
+
+    replace = subparsers.add_parser("replace", help="Move --source onto --target.")
+    replace.add_argument("--target", required=True, type=Path)
+    replace.add_argument("--source", required=True, type=Path)
+    replace.add_argument("--wait-pid", type=int, action="append", default=[], dest="wait_pids")
+
+    delete = subparsers.add_parser("delete", help="Delete --target.")
+    delete.add_argument("--target", required=True, type=Path)
+    delete.add_argument("--wait-pid", type=int, action="append", default=[], dest="wait_pids")
+
+    heal = subparsers.add_parser(
+        "heal",
+        help="If <target>.new exists, atomically swap it onto <target>.",
+    )
+    heal.add_argument("--target", required=True, type=Path)
+    heal.add_argument("--wait-pid", type=int, action="append", default=[], dest="wait_pids")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run one wait-then-replace/delete operation. Never prompts."""
+    args = build_parser().parse_args(argv)
+    helper_dir = _helper_dir()
+
+    if not is_safe_target(args.target, helper_dir=helper_dir):
+        append_log(f"helper {args.operation}: refusing unsafe target {args.target}")
+        return 3
+    if args.operation == "replace" and not is_safe_target(
+        args.source, helper_dir=helper_dir, allowed_names=SOURCE_NAMES
+    ):
+        append_log(f"helper replace: refusing unsafe source {args.source}")
+        return 3
+
+    if args.wait_pids and not wait_for_pids(args.wait_pids, timeout=_WAIT_TIMEOUT_SECONDS):
+        append_log(
+            f"helper {args.operation}: timed out after {_WAIT_TIMEOUT_SECONDS:g}s waiting for "
+            f"PID(s) {args.wait_pids} to exit; proceeding anyway"
+        )
+
+    if args.operation == "replace":
+        error = retry_replace(args.source, args.target, total_seconds=_RETRY_TOTAL_SECONDS)
+    elif args.operation == "delete":
+        error = retry_delete(args.target, total_seconds=_RETRY_TOTAL_SECONDS)
+    else:
+        staging = args.target.with_name(args.target.name + ".new")
+        if not staging.exists():
+            append_log(f"helper heal: no pending update at {staging}")
+            return 0
+        if not is_safe_target(staging, helper_dir=helper_dir, allowed_names=SOURCE_NAMES):
+            append_log(f"helper heal: refusing unsafe staging {staging}")
+            return 3
+        error = retry_replace(staging, args.target, total_seconds=_RETRY_TOTAL_SECONDS)
+
+    if error is not None:
+        append_log(f"helper {args.operation} failed for {args.target}: {error}")
+        return 2
+
+    append_log(f"helper {args.operation} succeeded for {args.target}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())