qualys-cli 0.1.1__py3-none-any.whl

qualys_cli/history.py

@@ -0,0 +1,133 @@
+"""
+Per-profile invocation history — feeds ``qualys-cli last`` and ``replay``.
+
+Each successful invocation that produced output writes a small JSON record at
+``~/.config/qualys-cli/history/<profile>/<correlation>.json``. We keep the
+last 200 invocations per profile (oldest pruned on write); enough for "I just
+ran this with --format table, give me the same data as JSON" without unbounded
+disk growth.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from .config import HISTORY_DIR
+
+_MAX_PER_PROFILE = 200
+
+
+def _safe_component(value: str, *, what: str) -> str:
+    """Reject any path-separator or traversal sequence in a filename component.
+
+    ``profile`` names and correlation IDs both end up interpolated directly
+    into a filesystem path. Without this guard a crafted ``--profile`` or
+    ``qualys-cli replay <id>`` argument (e.g. ``../../../../etc/passwd``)
+    could escape :data:`HISTORY_DIR` and read/write arbitrary files.
+    """
+    v = value or ""
+    if not v or ".." in v or "/" in v or "\\" in v or "\x00" in v:
+        raise ValueError(f"Invalid {what}: {value!r}")
+    return v
+
+
+def _dir(profile: str) -> Path:
+    name = _safe_component(profile or "default", what="profile name")
+    d = HISTORY_DIR / name
+    # Defence in depth — even if the check above is ever loosened, refuse to
+    # operate on anything that resolves outside HISTORY_DIR.
+    try:
+        d.resolve().relative_to(HISTORY_DIR.resolve())
+    except ValueError as exc:
+        raise ValueError(
+            f"Refusing to operate on {d} — path escapes the history directory"
+        ) from exc
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def record(
+    profile: str,
+    correlation: str,
+    argv: list[str],
+    response: Any,
+) -> None:
+    """Persist one invocation result for later replay."""
+    if not correlation:
+        return
+    try:
+        corr = _safe_component(correlation, what="correlation ID")
+        d = _dir(profile)
+        d.parent.chmod(0o700)
+        with contextlib.suppress(Exception):
+            d.chmod(0o700)
+        rec = {
+            "ts": int(time.time()),
+            "argv": argv,
+            "correlation": correlation,
+            "response": response,
+        }
+        path = d / f"{corr}.json"
+        path.write_text(json.dumps(rec, default=str))
+        with contextlib.suppress(Exception):
+            path.chmod(0o600)
+        # Prune oldest if we exceed the cap.
+        # Use a safe sort that handles concurrent deletions (file may vanish
+        # between glob and stat).
+        files_with_mtime: list[tuple[float, Path]] = []
+        for f in d.glob("*.json"):
+            try:
+                files_with_mtime.append((f.stat().st_mtime, f))
+            except (OSError, FileNotFoundError):
+                continue
+        files_with_mtime.sort(reverse=True)
+        for _, old in files_with_mtime[_MAX_PER_PROFILE:]:
+            with contextlib.suppress(OSError, FileNotFoundError):
+                old.unlink()
+    except Exception:
+        # Never let history persistence break a command.
+        pass
+
+
+def latest(profile: str) -> dict[str, Any] | None:
+    """Return the most recent invocation record for *profile*, or None."""
+    try:
+        d = _dir(profile)
+        files = sorted(d.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)
+        if not files:
+            return None
+        rec_obj = json.loads(files[0].read_text())
+        return rec_obj if isinstance(rec_obj, dict) else None
+    except Exception:
+        return None
+
+
+def lookup(profile: str, correlation: str) -> dict[str, Any] | None:
+    try:
+        corr = _safe_component(correlation, what="correlation ID")
+        p = _dir(profile) / f"{corr}.json"
+        if not p.exists():
+            return None
+        rec: dict[str, Any] = json.loads(p.read_text())
+        return rec
+    except Exception:
+        return None
+
+
+def list_recent(profile: str, n: int = 25) -> list[dict[str, Any]]:
+    try:
+        d = _dir(profile)
+    except ValueError:
+        return []
+    files = sorted(d.glob("*.json"), key=lambda p: p.stat().st_mtime, reverse=True)[:n]
+    out: list[dict[str, Any]] = []
+    for f in files:
+        try:
+            out.append(json.loads(f.read_text()))
+        except Exception:
+            continue
+    return out

qualys_cli/http_server.py

@@ -0,0 +1,126 @@
+"""
+Minimal local HTTP server that exposes the CLI as a JSON-in / JSON-out API.
+
+Why minimal: stdlib ``http.server`` is enough for a localhost-only operator
+tool — no need to pull FastAPI / uvicorn into the runtime dependency set.
+
+Endpoints:
+
+  GET  /                     Health probe (returns {"ok": true})
+  GET  /tools                List every registered command + JSONSchema
+  POST /run                  Run one command. Body:
+                                {"argv": ["vm", "host", "list"], "profile": "prod"}
+                             Returns: {"ok": ..., "exit_code": N, "stdout": ..., "stderr": ...}
+
+Defaults bind to 127.0.0.1 — there's no auth on the wire, so do NOT expose
+this server to a network. Operators who want network access should put it
+behind a reverse proxy that adds AuthN/Z.
+
+No CORS headers are sent. A wildcard ``Access-Control-Allow-Origin: *``
+would let any website the operator's browser visits issue cross-origin
+requests to this server (a classic "drive-by RCE against localhost tooling"
+pattern) since ``POST /run`` executes arbitrary ``qualys-cli`` commands.
+Browser-based clients must be served from the same origin or proxied.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any
+
+
+def _build_handler(profile: str) -> type:
+    from .mcp_server import _build_catalog
+
+    catalog = _build_catalog()
+
+    class Handler(BaseHTTPRequestHandler):
+        # Quiet: the default logger spams stderr — we already audit centrally.
+        def log_message(self, fmt: str, *args: Any) -> None:  # noqa: A003
+            return
+
+        def _send_json(self, obj: dict[str, Any], status: int = 200) -> None:
+            body = json.dumps(obj, default=str).encode("utf-8")
+            self.send_response(status)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            # No CORS headers — see module docstring. A wildcard origin here
+            # would let any web page the operator's browser visits drive
+            # POST /run (arbitrary command execution) cross-origin.
+            self.end_headers()
+            self.wfile.write(body)
+
+        def do_OPTIONS(self) -> None:  # noqa: N802 — http.server contract
+            """No CORS preflight support — cross-origin browser clients are
+            intentionally not supported. See module docstring."""
+            self._send_json({"error": "not found"}, status=404)
+
+        def do_GET(self) -> None:  # noqa: N802 — http.server contract
+            if self.path == "/":
+                self._send_json({"ok": True, "service": "qualys-cli", "tools": len(catalog)})
+            elif self.path.startswith("/tools"):
+                self._send_json({"tools": catalog})
+            else:
+                self._send_json({"error": "not found"}, status=404)
+
+        def do_POST(self) -> None:  # noqa: N802
+            if self.path != "/run":
+                self._send_json({"error": "not found"}, status=404)
+                return
+            length = int(self.headers.get("Content-Length", "0") or 0)
+            try:
+                body = json.loads(self.rfile.read(length) or b"{}")
+            except json.JSONDecodeError:
+                self._send_json({"error": "invalid JSON body"}, status=400)
+                return
+            argv = list(body.get("argv") or [])
+            if not argv:
+                self._send_json({"error": "argv is required"}, status=400)
+                return
+            # Validate argv elements are strings and don't contain shell metacharacters
+            # that could be exploited if subprocess were ever changed to use shell=True
+            for arg in argv:
+                if not isinstance(arg, str):
+                    self._send_json({"error": "argv elements must be strings"}, status=400)
+                    return
+                # Block any attempt to inject shell commands or escape sequences
+                if any(c in arg for c in [";", "|", "&", "`", "$", "\n", "\r", "\x00"]):
+                    self._send_json({"error": "argv contains invalid characters"}, status=400)
+                    return
+            run_profile = str(body.get("profile") or profile)
+            # Validate profile name doesn't contain path traversal or injection
+            if any(c in run_profile for c in ["/", "\\", ";", "|", "&", "`", "$", "\n", "\r", "\x00"]):
+                self._send_json({"error": "invalid profile name"}, status=400)
+                return
+            full = ["qualys-cli", "--profile", run_profile, *argv]
+            env = os.environ | {"QUALYS_OUTPUT_MODE": "agentic"}
+            proc = subprocess.run(full, capture_output=True, text=True, env=env, check=False)
+            try:
+                stdout: Any = json.loads(proc.stdout) if proc.stdout.strip() else None
+            except json.JSONDecodeError:
+                stdout = proc.stdout
+            self._send_json({
+                "ok": proc.returncode == 0,
+                "exit_code": proc.returncode,
+                "stdout": stdout,
+                "stderr": proc.stderr.strip()[-500:] if proc.stderr else "",
+            }, status=200 if proc.returncode == 0 else 207)
+
+    return Handler
+
+
+def run(*, host: str = "127.0.0.1", port: int = 8765, profile: str = "default") -> None:
+    handler = _build_handler(profile)
+    server = HTTPServer((host, port), handler)
+    print(f"qualys-cli HTTP server listening on http://{host}:{port}")
+    print(f"  GET  http://{host}:{port}/         health probe")
+    print(f"  GET  http://{host}:{port}/tools    tool catalog")
+    print(f"  POST http://{host}:{port}/run      run a command")
+    print("Press Ctrl-C to stop.")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        server.server_close()

qualys_cli/mcp_server.py

@@ -0,0 +1,341 @@
+"""
+Minimal MCP (Model Context Protocol) server adapter.
+
+Why minimal: we want this feature to ship without adding the MCP SDK as a
+runtime dependency. The MCP wire protocol is JSON-RPC 2.0 over stdio with a
+small set of methods (``initialize``, ``tools/list``, ``tools/call``). We
+implement only those methods — sufficient for Claude Desktop, Cursor, and
+the official MCP inspector to drive the CLI.
+
+Each registered Typer command becomes one MCP tool. The tool name is the
+dotted command path with hyphens (``vm.host.list``); the input schema is
+generated from the command's option signature via the same introspection
+the HTML doc generator uses. Tool execution shells out to ``qualys-cli`` in
+agentic mode and returns the parsed JSON response as the tool result.
+
+Run with ``qualys-cli mcp``. To wire it into Claude Desktop, add::
+
+    {
+      "mcpServers": {
+        "qualys-cli": {
+          "command": "qualys-cli",
+          "args": ["mcp"]
+        }
+      }
+    }
+
+to ``~/Library/Application Support/Claude/claude_desktop_config.json``.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import os
+import subprocess
+import sys
+import types
+import typing
+from typing import Any
+
+import typer
+
+
+def _get_version() -> str:
+    """Get the package version dynamically."""
+    try:
+        from importlib.metadata import version
+        return version("qualys-cli")
+    except Exception:
+        return "0.0.0"
+
+
+def _walk(t: typer.Typer, prefix: str = "") -> list[tuple[str, Any]]:
+    out: list[tuple[str, Any]] = []
+    for c in (t.registered_commands or []):
+        if c.callback is None:
+            continue
+        cname = c.name if isinstance(c.name, str) else c.callback.__name__.replace("_", "-")
+        full = f"{prefix} {cname}".strip()
+        out.append((full, c.callback))
+    for g in (t.registered_groups or []):
+        sub = g.typer_instance
+        if sub is None:
+            continue
+        gname = sub.info.name if sub.info and isinstance(sub.info.name, str) else g.name
+        if not isinstance(gname, str):
+            continue
+        out.extend(_walk(sub, f"{prefix} {gname}".strip()))
+    return out
+
+
+def _type_to_jsonschema(annotation: object) -> dict[str, Any]:
+    a = annotation
+    if isinstance(a, types.UnionType) or typing.get_origin(a) is typing.Union:
+        args = [t for t in typing.get_args(a) if t is not type(None)]
+        if args:
+            a = args[0]
+    if a is bool:
+        return {"type": "boolean"}
+    if a is int:
+        return {"type": "integer"}
+    if a is float:
+        return {"type": "number"}
+    if typing.get_origin(a) is list:
+        return {"type": "array", "items": {"type": "string"}}
+    return {"type": "string"}
+
+
+def _schema_for(callback: Any) -> dict[str, Any]:
+    sig = inspect.signature(callback)
+    try:
+        hints = typing.get_type_hints(callback)
+    except Exception:
+        hints = {}
+    props: dict[str, Any] = {}
+    required: list[str] = []
+    for pname, p in sig.parameters.items():
+        annot = hints.get(pname, p.annotation)
+        if annot is typer.Context:
+            continue
+        info = p.default
+        if not isinstance(info, (typer.models.OptionInfo, typer.models.ArgumentInfo)):
+            continue
+        is_arg = isinstance(info, typer.models.ArgumentInfo)
+        decls = info.param_decls or ((pname.upper(),) if is_arg else (f"--{pname.replace('_', '-')}",))
+        flag = decls[0]
+        # MCP tool argument names mirror the long-flag form, normalised
+        key = flag.lstrip("-").replace("-", "_")
+        sch = _type_to_jsonschema(annot)
+        if info.help:
+            sch["description"] = info.help
+        props[key] = sch
+        if info.default is ...:
+            required.append(key)
+    return {"type": "object", "properties": props, "required": required}
+
+
+def _normalise_tool_name(full: str) -> str:
+    """Convert a CLI command path into an MCP tool name.
+
+    Anthropic's tool-name validator (FrontendRemoteMcpToolDefinition) requires
+    ``^[a-zA-Z0-9_-]{1,64}$`` — dots are rejected. We map space-separators in
+    the command path to underscores and any leftover dots to underscores too.
+    Hyphens that occur naturally in CLI verbs (e.g. ``rotate-jwt``,
+    ``list-easm``) are kept since they are inside the allowed character set.
+    The 64-character limit is plenty for every real Qualys command path.
+    """
+    name = full.replace(" ", "_").replace(".", "_")
+    # Defensive scrub: replace anything outside the allowed alphabet with `_`
+    # so an unexpected docstring-derived character can't break the validator.
+    safe = "".join(ch if (ch.isalnum() or ch in {"_", "-"}) else "_" for ch in name)
+    return safe[:64]
+
+
+def _denormalise_tool_name(tool_name: str) -> list[str]:
+    """Inverse of :func:`_normalise_tool_name` for argv reconstruction.
+
+    A tool name like ``vm_scan_launch`` maps back to the argv ``["vm", "scan",
+    "launch"]``. Verbs that contain hyphens stay intact (``rotate-jwt`` →
+    ``["rotate-jwt"]``) because we only split on the underscore separator.
+    """
+    return [seg for seg in tool_name.split("_") if seg]
+
+
+def _build_catalog() -> list[dict[str, Any]]:
+    """Build the MCP tool catalog by walking the live Typer app."""
+    from .cli import app as root_app
+    tools: list[dict[str, Any]] = []
+    for grp in (root_app.registered_groups or []):
+        sub = grp.typer_instance
+        if sub is None:
+            continue
+        mod_key = sub.info.name if sub.info else grp.name
+        if not isinstance(mod_key, str):
+            continue
+        for full, cb in _walk(sub, mod_key):
+            doc = (cb.__doc__ or "").strip().splitlines()
+            summary = doc[0].strip() if doc else full
+            tools.append({
+                "name": _normalise_tool_name(full),
+                "description": summary,
+                "inputSchema": _schema_for(cb),
+            })
+    return tools
+
+
+def _argv_for(tool_name: str, args: dict[str, Any]) -> list[str]:
+    parts = ["qualys-cli", *_denormalise_tool_name(tool_name)]
+    for k, v in args.items():
+        if v is None:
+            continue
+        flag = "--" + k.replace("_", "-")
+        if isinstance(v, bool):
+            if v:
+                parts.append(flag)
+        elif isinstance(v, list):
+            for item in v:
+                parts.append(flag)
+                parts.append(str(item))
+        else:
+            parts.append(flag)
+            parts.append(str(v))
+    return parts
+
+
+# subprocess.run is invoked with a list (no shell) below, so traditional
+# shell-metachar blocking is not needed for safety. We only reject NULs
+# (which subprocess can't carry anyway) and ASCII control characters that
+# would corrupt the audit log or terminal output.
+def _validate_arg(arg: str) -> bool:
+    """Reject only characters that could corrupt downstream logging or that
+    cannot be safely transported by ``subprocess.run`` with a list argv.
+
+    Shell metacharacters (``;|&`` etc.) are *not* rejected — list-form
+    subprocess never invokes a shell, so injecting them does nothing. Blocking
+    them previously rejected legitimate inputs like single-quoted JSON bodies,
+    regex predicates, and shell-style globs.
+    """
+    if "\x00" in arg:
+        return False
+    return all(c >= " " or c in ("\t",) for c in arg)
+
+
+def _invoke(tool_name: str, args: dict[str, Any], profile: str) -> dict[str, Any]:
+    if not _validate_arg(tool_name) or (profile and not _validate_arg(profile)):
+        return {
+            "ok": False,
+            "exit_code": 1,
+            "stdout": None,
+            "stderr": "Argument contains NUL or unprintable control characters",
+        }
+    for k, v in args.items():
+        if isinstance(v, str) and not _validate_arg(v):
+            return {
+                "ok": False,
+                "exit_code": 1,
+                "stdout": None,
+                "stderr": f"Argument contains NUL or unprintable control characters: {k}",
+            }
+        if isinstance(v, list):
+            for item in v:
+                if isinstance(item, str) and not _validate_arg(item):
+                    return {
+                        "ok": False,
+                        "exit_code": 1,
+                        "stdout": None,
+                        "stderr": f"Argument contains NUL or unprintable control characters: {k}",
+                    }
+    argv = _argv_for(tool_name, args)
+    if profile and "--profile" not in argv:
+        argv.insert(1, "--profile")
+        argv.insert(2, profile)
+    env = os.environ | {"QUALYS_OUTPUT_MODE": "agentic"}
+    proc = subprocess.run(argv, capture_output=True, text=True, env=env, check=False)
+    try:
+        data: Any = json.loads(proc.stdout) if proc.stdout.strip() else None
+    except json.JSONDecodeError:
+        data = proc.stdout
+    return {
+        "ok": proc.returncode == 0,
+        "exit_code": proc.returncode,
+        "stdout": data,
+        "stderr": proc.stderr.strip()[-500:] if proc.stderr else "",
+    }
+
+
+# ---------------------------------------------------------------------------
+# JSON-RPC stdio loop
+# ---------------------------------------------------------------------------
+
+_PROTOCOL_VERSION = "2024-11-05"
+
+
+def _send(obj: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(obj, default=str) + "\n")
+    sys.stdout.flush()
+
+
+def _is_notification(msg: dict[str, Any]) -> bool:
+    """JSON-RPC 2.0: a notification is a request without an ``id`` field.
+
+    The spec is explicit — servers MUST NOT respond to notifications. Sending
+    any frame back (even an error) violates strict validators (Anthropic's
+    MCP validator rejects ``id: null`` outright, and ``id`` is missing here)
+    so we silently ignore them.
+    """
+    return "id" not in msg
+
+
+def run(*, profile: str = "default") -> None:
+    """Read JSON-RPC requests from stdin, write responses to stdout.
+
+    Implements the request/response side of MCP (initialize, tools/list,
+    tools/call, ping) and silently absorbs the standard notifications that
+    Claude Desktop / Cursor / other clients emit during their boot dance
+    (notifications/initialized, prompts/list, resources/list, …).
+    """
+    catalog = _build_catalog()
+
+    for raw in sys.stdin:
+        raw = raw.strip()
+        if not raw:
+            continue
+        try:
+            msg = json.loads(raw)
+        except json.JSONDecodeError:
+            # Per JSON-RPC, a parse error gets a response with id=null. We
+            # write one only if this looks like a real attempt at JSON; bare
+            # newlines / control chars get silently dropped.
+            continue
+        if not isinstance(msg, dict):
+            continue
+        method = msg.get("method")
+        if not isinstance(method, str) or not method:
+            # Not a valid JSON-RPC request/notification — ignore.
+            continue
+
+        # Notifications never get a response. This includes Claude Desktop's
+        # post-handshake "notifications/initialized" frame and any other
+        # unsolicited message the client sends without an id.
+        if _is_notification(msg):
+            continue
+
+        rpc_id = msg["id"]
+
+        if method == "initialize":
+            _send({
+                "jsonrpc": "2.0", "id": rpc_id,
+                "result": {
+                    "protocolVersion": _PROTOCOL_VERSION,
+                    "capabilities": {"tools": {"listChanged": False}},
+                    "serverInfo": {"name": "qualys-cli", "version": _get_version()},
+                },
+            })
+        elif method == "tools/list":
+            _send({"jsonrpc": "2.0", "id": rpc_id, "result": {"tools": catalog}})
+        elif method == "tools/call":
+            params = msg.get("params") or {}
+            tool_name = params.get("name", "")
+            args = params.get("arguments") or {}
+            result = _invoke(tool_name, args, profile)
+            content = [{"type": "text", "text": json.dumps(result, default=str, indent=2)}]
+            _send({
+                "jsonrpc": "2.0", "id": rpc_id,
+                "result": {"content": content, "isError": not result["ok"]},
+            })
+        elif method == "ping":
+            _send({"jsonrpc": "2.0", "id": rpc_id, "result": {}})
+        elif method in ("prompts/list", "resources/list", "resources/templates/list"):
+            # Capabilities we don't expose. Return an empty list rather than
+            # method-not-found so clients that probe these on startup get a
+            # clean answer and don't log warnings.
+            key = "prompts" if "prompts" in method else (
+                "resourceTemplates" if "templates" in method else "resources"
+            )
+            _send({"jsonrpc": "2.0", "id": rpc_id, "result": {key: []}})
+        else:
+            _send({
+                "jsonrpc": "2.0", "id": rpc_id,
+                "error": {"code": -32601, "message": f"Method not found: {method}"},
+            })