command-gate 0.2.4__py3-none-any.whl

cgate/mcp_server/tools.py

@@ -0,0 +1,351 @@
+"""Sync business logic for the three MCP tools."""
+from __future__ import annotations
+
+import getpass
+from typing import TYPE_CHECKING, NotRequired, TypedDict
+
+from cgate.db.commands import all_terminal
+from cgate.db.mode import AppModeNotSetError, Mode
+from cgate.db.types import BatchId, CommandStatus
+from cgate.executor import selector
+from cgate.mcp_server.auto_resolution import resolve_auto_behavior
+from cgate.risk import find_risk
+
+if TYPE_CHECKING:
+    from cgate.connections.store import ConnectionsRepo
+    from cgate.db.batches import BatchesRepo
+    from cgate.db.commands import CommandsRepo
+    from cgate.db.mode import AppModeRepo
+    from cgate.db.server_settings import ServerSettingsRepo
+    from cgate.db.types import Command, Connection
+    from cgate.mcp_server.auto_resolution import BehaviorDecision
+
+
+class ProposeCommandResult(TypedDict):
+    """JSON-compatible result returned after queueing a command."""
+
+    batch_id: str
+    command_id: str
+    position: int
+    status: str
+    mode: NotRequired[str | None]
+    server_auto_allowed: NotRequired[bool | None]
+    effective_reason: NotRequired[str | None]
+    result: NotRequired[str | None]
+    approved_by: NotRequired[str | None]
+    reason: NotRequired[str | None]
+    risk_label: NotRequired[str | None]
+
+
+class ConnectionResult(TypedDict):
+    """JSON-compatible saved connection details."""
+
+    alias: str
+    hostname: str
+    server_type: str
+    detection_ssh: bool
+    detection_winrm: bool
+    auto_allowed: bool
+
+
+class ModeResult(TypedDict):
+    """JSON-compatible global mode and per-server auto-execution opt-ins."""
+
+    mode: str
+    auto_allowed_servers: list[str]
+
+
+class CommandStatusResult(TypedDict):
+    """JSON-compatible status and audit details for one command."""
+
+    id: str
+    position: int
+    server_alias: str
+    server_type: str
+    command: str
+    status: str
+    result: str | None
+    approved_by: str | None
+    created_at: str
+    resolved_at: str | None
+    reason: str | None
+    risk_label: str | None
+
+
+class BatchStatusResult(TypedDict):
+    """JSON-compatible batch metadata and ordered command statuses."""
+
+    batch_id: str
+    title: str
+    description: str | None
+    created_at: str
+    resolved_at: str | None
+    requested_by_agent: str | None
+    commands: list[CommandStatusResult]
+
+
+class ToolError(Exception):
+    """Domain error converted into MCP error content by the async boundary."""
+
+    code: str
+    message: str
+
+    def __init__(self, code: str, message: str) -> None:
+        """Create an error with a stable machine code and human-readable message."""
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+def _require_batch_title(batch_title: str | None) -> str:
+    if not batch_title or not batch_title.strip():
+        code = "missing_batch_title"
+        message = "batch_title is required"
+        raise ToolError(code, message)
+    return batch_title.strip()
+
+
+def _require_known_alias(connections_repo: ConnectionsRepo, alias: str) -> Connection:
+    connection = connections_repo.get(alias)
+    if connection is None:
+        code = "unknown_alias"
+        message = f"unknown alias '{alias}'"
+        raise ToolError(code, message)
+    return connection
+
+
+def _auto_approve_by() -> str:
+    """Audit identity for auto-approvals.
+
+    Inlined replication of watch/approval.py's ``_approve_by()`` fallback
+    pattern (KeyError/OSError -> constant), prefixed so auto-decisions are
+    distinguishable from human ones in the audit column.
+    """
+    try:
+        return f"auto:watch:{getpass.getuser()}"
+    except (KeyError, OSError):
+        return "auto:mcp"
+
+
+def _execute_auto(
+    *,
+    batches_repo: BatchesRepo,
+    commands_repo: CommandsRepo,
+    connection: Connection,
+    queued: Command,
+    decision: BehaviorDecision,
+) -> ProposeCommandResult:
+    """Mirror watch/approval.approve_one's transition cycle for an auto-approved command.
+
+    The connection is guaranteed present: ``_require_known_alias`` already
+    converted a missing alias into ToolError("unknown_alias") before insert,
+    so approve_one's ConnectionNotFoundError path is unreachable here.
+    """
+    approver = _auto_approve_by()
+    approved = commands_repo.update_status(
+        queued.id,
+        status=CommandStatus.APPROVED,
+        approved_by=approver,
+        expected_status=CommandStatus.PENDING,
+    )
+    if not approved:
+        # Lost a race with another decision on this command since the insert --
+        # report its current state, don't execute (mirrors approve_one).
+        current = commands_repo.get(queued.id)
+        return {
+            "batch_id": queued.batch_id,
+            "command_id": queued.id,
+            "position": queued.position,
+            "status": current.status.value if current is not None else queued.status.value,
+            "mode": decision["mode"],
+            "server_auto_allowed": decision["server_auto_allowed"],
+            "effective_reason": decision["reason"],
+            "result": current.result if current is not None else None,
+            "approved_by": current.approved_by if current is not None else None,
+            "reason": queued.reason,
+            "risk_label": queued.risk_label,
+        }
+    execution = selector.execute_command(connection, queued.command)
+    status = CommandStatus.EXECUTED if execution.ok else CommandStatus.FAILED
+    output = execution.stdout
+    if execution.stderr:
+        separator = "\n" if output else ""
+        output = f"{output}{separator}--- stderr ---\n{execution.stderr}"
+    _ = commands_repo.update_status(
+        queued.id,
+        status=status,
+        approved_by=approver,
+        result=output,
+    )
+    # Auto-execution bypasses watch/approval.py entirely, so nothing else
+    # ever stamps `resolved_at` for this batch -- without this, a fully
+    # terminal batch sits at the head of the FIFO queue forever, blocking
+    # every batch behind it from ever becoming approvable.
+    if all_terminal(commands_repo.list_for_batch(queued.batch_id)):
+        batches_repo.mark_resolved(queued.batch_id)
+    return {
+        "batch_id": queued.batch_id,
+        "command_id": queued.id,
+        "position": queued.position,
+        "status": status.value,
+        "mode": decision["mode"],
+        "server_auto_allowed": decision["server_auto_allowed"],
+        "effective_reason": decision["reason"],
+        "result": output,
+        "approved_by": approver,
+        "reason": queued.reason,
+        "risk_label": queued.risk_label,
+    }
+
+
+def propose_command(  # noqa: PLR0913 - boundary mirrors the specified MCP tool arguments.
+    *,
+    batches_repo: BatchesRepo,
+    commands_repo: CommandsRepo,
+    connections_repo: ConnectionsRepo,
+    mode_repo: AppModeRepo,
+    settings_repo: ServerSettingsRepo,
+    server_alias: str,
+    command: str,
+    batch_title: str | None,
+    batch_description: str | None = None,
+    batch_id: str | None = None,
+    reason: str | None = None,
+    requested_by_agent: str = "mcp",
+) -> ProposeCommandResult:
+    """Register a proposed command in the queue.
+
+    Executes it immediately instead when the global mode is AUTO and the
+    server alias has explicitly opted in.
+    """
+    title = _require_batch_title(batch_title)
+    connection = _require_known_alias(connections_repo, server_alias)
+
+    if batch_id is None:
+        batch = batches_repo.create(
+            title=title,
+            description=batch_description,
+            requested_by_agent=requested_by_agent,
+        )
+    else:
+        batch = batches_repo.get(BatchId(batch_id))
+        if batch is None:
+            # An unknown optional ID is a stale hint, so create a fresh UUID-backed batch.
+            batch = batches_repo.create(
+                title=title,
+                description=batch_description,
+                requested_by_agent=requested_by_agent,
+            )
+
+    risk_label = find_risk(command, connection.server_type)
+    queued = commands_repo.add(
+        batch_id=batch.id,
+        server_alias=connection.alias,
+        server_type=connection.server_type,
+        command=command,
+        reason=reason,
+        risk_label=risk_label,
+    )
+    decision = resolve_auto_behavior(
+        mode_repo=mode_repo,
+        settings_repo=settings_repo,
+        server_alias=connection.alias,
+        risk_label=risk_label,
+    )
+    if decision["action"] == "execute":
+        return _execute_auto(
+            batches_repo=batches_repo,
+            commands_repo=commands_repo,
+            connection=connection,
+            queued=queued,
+            decision=decision,
+        )
+    return {
+        "batch_id": batch.id,
+        "command_id": queued.id,
+        "position": queued.position,
+        "status": queued.status.value,
+        "mode": decision["mode"],
+        "server_auto_allowed": decision["server_auto_allowed"],
+        "effective_reason": decision["reason"],
+        "result": None,
+        "approved_by": None,
+        "reason": queued.reason,
+        "risk_label": queued.risk_label,
+    }
+
+
+def list_connections(
+    *, connections_repo: ConnectionsRepo, settings_repo: ServerSettingsRepo
+) -> list[ConnectionResult]:
+    """Return saved connections, their server dialect metadata, and auto-execution opt-in."""
+    return [
+        {
+            "alias": connection.alias,
+            "hostname": connection.hostname,
+            "server_type": connection.server_type.value,
+            "detection_ssh": connection.detection_ssh,
+            "detection_winrm": connection.detection_winrm,
+            "auto_allowed": settings_repo.get_or_default(connection.alias).auto_allowed,
+        }
+        for connection in connections_repo.list_all()
+    ]
+
+
+def get_mode(*, mode_repo: AppModeRepo, settings_repo: ServerSettingsRepo) -> ModeResult:
+    """Report the global mode and which servers are opted in for auto-execution.
+
+    Read-only: an unset global mode is reported as PROPOSE, matching
+    ``resolve_auto_behavior``'s safe default.
+    """
+    try:
+        mode = mode_repo.get().mode
+    except AppModeNotSetError:
+        mode = Mode.PROPOSE
+    return {
+        "mode": mode.value,
+        "auto_allowed_servers": [
+            setting.server_alias for setting in settings_repo.list_all() if setting.auto_allowed
+        ],
+    }
+
+
+def check_status(
+    *,
+    batches_repo: BatchesRepo,
+    commands_repo: CommandsRepo,
+    batch_id: str,
+) -> BatchStatusResult:
+    """Return batch metadata and ordered per-command status and audit fields."""
+    typed_batch_id = BatchId(batch_id)
+    batch = batches_repo.get(typed_batch_id)
+    if batch is None:
+        code = "unknown_batch"
+        message = f"unknown batch '{batch_id}'"
+        raise ToolError(code, message)
+
+    return {
+        "batch_id": batch.id,
+        "title": batch.title,
+        "description": batch.description,
+        "created_at": batch.created_at.isoformat(),
+        "resolved_at": batch.resolved_at.isoformat() if batch.resolved_at else None,
+        "requested_by_agent": batch.requested_by_agent,
+        "commands": [
+            {
+                "id": command.id,
+                "position": command.position,
+                "server_alias": command.server_alias,
+                "server_type": command.server_type.value,
+                "command": command.command,
+                "status": command.status.value,
+                "result": command.result,
+                "approved_by": command.approved_by,
+                "created_at": command.created_at.isoformat(),
+                "resolved_at": command.resolved_at.isoformat() if command.resolved_at else None,
+                "reason": command.reason,
+                "risk_label": command.risk_label,
+            }
+            for command in commands_repo.list_for_batch(typed_batch_id)
+        ],
+    }

cgate/risk.py

@@ -0,0 +1,129 @@
+"""Heuristic detection of high-blast-radius commands.
+
+Not a security boundary: a regex-based safety net, easy to defeat with
+obfuscation (variables, aliases, unusual quoting/flag ordering, encoding).
+Its job is narrower -- catch the common, obvious forms of "this could wipe
+a disk or kill recovery" so AUTO mode's opt-in never silently runs one
+unattended, and so a human scanning the queue sees a clear warning even in
+PROPOSE mode. A command that matches nothing here is not "safe"; it just
+didn't trip this particular tripwire.
+
+Patterns cover Windows/PowerShell and Linux -- the latter also catches an
+SSH-connected macOS box, since `cgate` has no separate macOS `ServerType`
+and macOS shares the same Unix shell family (plus a few macOS-specific
+tools: `diskutil`, `csrutil`, `spctl`).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+from cgate.db.types import ServerType
+
+# Sourced from widely-cited "dangerous commands" references (rm -rf, dd,
+# mkfs, fork bombs) and MITRE ATT&CK T1490 "Inhibit System Recovery"
+# (vssadmin/wbadmin/bcdedit/REAgentC -- the standard ransomware precursor
+# set that deletes shadow copies and disables recovery before encrypting).
+_LINUX_PATTERNS: Final[tuple[tuple[str, re.Pattern[str]], ...]] = (
+    ("fork bomb", re.compile(r":\(\)\s*\{\s*:\s*\|\s*:\s*&?\s*\}\s*;\s*:")),
+    ("delete with --no-preserve-root", re.compile(r"--no-preserve-root", re.IGNORECASE)),
+    (
+        "writes directly to a raw disk device",
+        re.compile(
+            r"(\bdd\b[^\n;|&]*\bof=|[>]{1,2}\s*)/dev/(sd|nvme|hd|xvd|disk|rdisk)\w*", re.IGNORECASE
+        ),
+    ),
+    ("formats a block device", re.compile(r"\bmkfs(\.\w+)?\s+[^\n;|&]*/dev/", re.IGNORECASE)),
+    ("wipes/erases a device", re.compile(r"\b(wipefs|shred)\b[^\n;|&]*/dev/", re.IGNORECASE)),
+    (
+        "recursive chmod on the filesystem root",
+        re.compile(
+            r"\bchmod\b[^\n;|&]*-[a-zA-Z]*[Rr][a-zA-Z]*\b[^\n;|&]*\s/(\s|\*|$)", re.IGNORECASE
+        ),
+    ),
+    (
+        "disables macOS System Integrity Protection",
+        re.compile(r"\bcsrutil\s+disable\b", re.IGNORECASE),
+    ),
+    ("disables macOS Gatekeeper", re.compile(r"\bspctl\b[^\n;|&]*--master-disable", re.IGNORECASE)),
+    (
+        "erases a macOS disk/volume",
+        re.compile(r"\bdiskutil\s+erase(disk|volume|all)?\b", re.IGNORECASE),
+    ),
+)
+
+_WINDOWS_PATTERNS: Final[tuple[tuple[str, re.Pattern[str]], ...]] = (
+    (
+        "deletes shadow copies (blocks recovery)",
+        re.compile(r"\bvssadmin\b[^\n;|&]*\bdelete\b[^\n;|&]*\bshadows\b", re.IGNORECASE),
+    ),
+    (
+        "deletes Windows backups (blocks recovery)",
+        re.compile(r"\bwbadmin\b[^\n;|&]*\bdelete\b", re.IGNORECASE),
+    ),
+    (
+        "disables startup recovery",
+        re.compile(r"\bbcdedit\b[^\n;|&]*(recoveryenabled\s+no|ignoreallfailures)", re.IGNORECASE),
+    ),
+    ("disables System Restore", re.compile(r"\bDisable-ComputerRestore\b", re.IGNORECASE)),
+    (
+        "disables Windows Recovery Environment",
+        re.compile(r"\breagentc\b[^\n;|&]*/disable", re.IGNORECASE),
+    ),
+    ("deletes volume shadow copies", re.compile(r"\bdiskshadow\b", re.IGNORECASE)),
+    (
+        "wipes/formats a disk",
+        re.compile(r"\b(Format-Volume|Clear-Disk|Remove-Partition)\b", re.IGNORECASE),
+    ),
+    ("uses the low-level disk partitioning tool", re.compile(r"\bdiskpart\b", re.IGNORECASE)),
+    (
+        "disables real-time antivirus protection",
+        re.compile(r"\bSet-MpPreference\b[^\n;|&]*DisableRealtimeMonitoring", re.IGNORECASE),
+    ),
+    (
+        "turns off the Windows Firewall",
+        re.compile(r"\bnetsh\s+advfirewall\s+set\s+allprofiles\s+state\s+off\b", re.IGNORECASE),
+    ),
+    (
+        "recursive force-delete (Remove-Item -Recurse -Force)",
+        re.compile(r"\bRemove-Item\b(?=[^\n;|&]*-Recurse\b)(?=[^\n;|&]*-Force\b)", re.IGNORECASE),
+    ),
+    (
+        "recursive force-delete of a drive root or folder",
+        re.compile(
+            r"\b(rd|rmdir)\b[^\n;|&]*/s[^\n;|&]*/q|\bdel\b[^\n;|&]*/f[^\n;|&]*/s[^\n;|&]*/q",
+            re.IGNORECASE,
+        ),
+    ),
+)
+
+
+def _is_rm_rf(command: str) -> bool:
+    """`rm` with both recursive and force flags, in any order or spelling."""
+    if not re.search(r"\brm\b", command, re.IGNORECASE):
+        return False
+    combined_short_flags = re.search(
+        r"-[a-zA-Z]*r[a-zA-Z]*f\b|-[a-zA-Z]*f[a-zA-Z]*r\b", command, re.IGNORECASE
+    )
+    long_flags = re.search(r"--recursive\b", command, re.IGNORECASE) and re.search(
+        r"--force\b", command, re.IGNORECASE
+    )
+    return bool(combined_short_flags) or bool(long_flags)
+
+
+def find_risk(command: str, server_type: ServerType) -> str | None:
+    """Return a short human-readable label for a matched high-blast-radius pattern.
+
+    None otherwise -- which is not the same as "safe" (see the module docstring).
+    """
+    patterns = _WINDOWS_PATTERNS if server_type is ServerType.WINDOWS else _LINUX_PATTERNS
+    for label, pattern in patterns:
+        if pattern.search(command):
+            return label
+    if server_type is ServerType.LINUX and _is_rm_rf(command):
+        return "recursive force delete (rm -rf)"
+    return None
+
+
+__all__ = ["find_risk"]