qualys-cli 0.1.1__py3-none-any.whl

qualys_cli/metrics.py

@@ -0,0 +1,106 @@
+"""
+Local audit-log analytics — feeds ``qualys-cli stats``.
+
+Pure local reader: scans ``~/.config/qualys-cli/audit.log`` (and its rotated
+``.1`` companion) and computes:
+
+  - Total commands and HTTP calls
+  - Top endpoints by call count
+  - Latency percentiles (p50 / p90 / p99)
+  - Retry rate
+  - Per-profile error breakdown
+
+No backend required. Failures degrade to "no data" rather than crashing.
+"""
+
+from __future__ import annotations
+
+import json
+import statistics
+from collections import Counter, defaultdict
+from pathlib import Path
+from typing import Any
+
+
+def _audit_paths() -> list[Path]:
+    base = Path.home() / ".config" / "qualys-cli" / "audit.log"
+    paths: list[Path] = []
+    if base.exists():
+        paths.append(base)
+    backup = base.with_name(base.name + ".1")
+    if backup.exists():
+        paths.append(backup)
+    return paths
+
+
+def _records(paths: list[Path]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for p in paths:
+        try:
+            for raw in p.read_text().splitlines():
+                if not raw.strip():
+                    continue
+                try:
+                    out.append(json.loads(raw))
+                except json.JSONDecodeError:
+                    continue
+        except OSError:
+            continue
+    return out
+
+
+def compute() -> dict[str, Any]:
+    """Return a serialisable summary dict of the local audit log."""
+    recs = _records(_audit_paths())
+    if not recs:
+        return {"total": 0}
+
+    cmd_recs = [r for r in recs if r.get("event") == "command"]
+    http_recs = [r for r in recs if r.get("event") == "http"]
+    err_recs = [r for r in recs if r.get("event") == "error"]
+
+    starts = [r for r in cmd_recs if r.get("phase") == "start"]
+    ends = [r for r in cmd_recs if r.get("phase") == "end"]
+    cmd_durations = [int(r.get("duration_ms", 0)) for r in ends if r.get("duration_ms")]
+    exit_codes = Counter(int(r.get("exit_code", 0)) for r in ends)
+
+    durations = [int(r.get("duration_ms", 0)) for r in http_recs if r.get("duration_ms")]
+    retries = sum(1 for r in http_recs if int(r.get("attempts", 1)) > 1)
+
+    top_endpoints = Counter(
+        (r.get("method", "?"), r.get("path", "?").split("?")[0])
+        for r in http_recs
+    ).most_common(15)
+
+    by_profile_errors: dict[str, Counter[str]] = defaultdict(Counter)
+    for r in err_recs:
+        prof = r.get("profile", "default")
+        by_profile_errors[prof][r.get("type", "Error")] += 1
+
+    def pct(values: list[int], p: float) -> int:
+        if not values:
+            return 0
+        srt = sorted(values)
+        idx = max(0, min(len(srt) - 1, int(round((p / 100) * (len(srt) - 1)))))
+        return srt[idx]
+
+    return {
+        "total_commands": len(starts),
+        "total_http_calls": len(http_recs),
+        "total_errors": len(err_recs),
+        "command_duration_ms_p50": int(statistics.median(cmd_durations)) if cmd_durations else 0,
+        "http_duration_ms": {
+            "p50": pct(durations, 50),
+            "p90": pct(durations, 90),
+            "p99": pct(durations, 99),
+            "max": max(durations) if durations else 0,
+        },
+        "retry_rate_pct": round(100 * retries / max(1, len(http_recs)), 2),
+        "exit_codes": dict(exit_codes),
+        "top_endpoints": [
+            {"method": m, "path": p, "count": n} for (m, p), n in top_endpoints
+        ],
+        "errors_by_profile": {
+            prof: dict(types) for prof, types in by_profile_errors.items()
+        },
+    }

qualys_cli/platforms.py

@@ -0,0 +1,67 @@
+"""
+Qualys platform identification from username.
+
+Source: https://www.qualys.com/platform-identification
+
+Username format: quays[IDENTIFIER][rest]
+The platform identifier is the 5th character (index 4) of the username.
+
+Gateway URLs are required for: Asset Inventory, Container Security, EDR, FIM.
+API Server URLs are used for all other apps.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Platform:
+    name: str
+    api_url: str       # API Server URL — used by most apps
+    gateway_url: str   # API Gateway URL — used by CS, CSAM, EDR, FIM
+
+
+_PLATFORMS: dict[str, Platform] = {
+    "_": Platform("US1",  "https://qualysapi.qualys.com",            "https://gateway.qg1.apps.qualys.com"),
+    "2": Platform("US2",  "https://qualysapi.qg2.apps.qualys.com",   "https://gateway.qg2.apps.qualys.com"),
+    "3": Platform("US3",  "https://qualysapi.qg3.apps.qualys.com",   "https://gateway.qg3.apps.qualys.com"),
+    "6": Platform("US4",  "https://qualysapi.qg4.apps.qualys.com",   "https://gateway.qg4.apps.qualys.com"),
+    "C": Platform("GOV1", "https://qualysapi.gov1.qualys.us",         "https://gateway.gov1.qualys.us"),
+    "-": Platform("EU1",  "https://qualysapi.qualys.eu",              "https://gateway.qg1.apps.qualys.eu"),
+    "5": Platform("EU2",  "https://qualysapi.qg2.apps.qualys.eu",    "https://gateway.qg2.apps.qualys.eu"),
+    "!": Platform("EU2",  "https://qualysapi.qg2.apps.qualys.eu",    "https://gateway.qg2.apps.qualys.eu"),
+    "B": Platform("EU3",  "https://qualysapi.qg3.apps.qualys.it",    "https://gateway.qg3.apps.qualys.it"),
+    "8": Platform("IN1",  "https://qualysapi.qg1.apps.qualys.in",    "https://gateway.qg1.apps.qualys.in"),
+    "9": Platform("CA1",  "https://qualysapi.qg1.apps.qualys.ca",    "https://gateway.qg1.apps.qualys.ca"),
+    "7": Platform("AE1",  "https://qualysapi.qg1.apps.qualys.ae",    "https://gateway.qg1.apps.qualys.ae"),
+    "1": Platform("UK1",  "https://qualysapi.qg1.apps.qualys.co.uk", "https://gateway.qg1.apps.qualys.co.uk"),
+    "4": Platform("AU1",  "https://qualysapi.qg1.apps.qualys.com.au","https://gateway.qg1.apps.qualys.com.au"),
+    "A": Platform("KSA1", "https://qualysapi.qg1.apps.qualysksa.com","https://gateway.qg1.apps.qualysksa.com"),
+}
+
+_PREFIX = "quays"
+_ID_INDEX = len(_PREFIX)  # character at index 4
+
+
+def detect(username: str) -> Platform:
+    """Return the Platform for the given Qualys username.
+
+    Raises ValueError if the username is too short or the identifier is unknown.
+    """
+    if len(username) <= _ID_INDEX:
+        raise ValueError(
+            f"Cannot identify platform from username '{username}'. "
+            "Expected Qualys username format: quays[identifier]… "
+            "(see https://www.qualys.com/platform-identification)"
+        )
+    identifier = username[_ID_INDEX]
+    platform = _PLATFORMS.get(identifier)
+    if platform is None:
+        valid = ", ".join(repr(k) for k in _PLATFORMS)
+        raise ValueError(
+            f"Unknown platform identifier '{identifier}' in username '{username}'. "
+            f"Valid identifiers: {valid}. "
+            "See https://www.qualys.com/platform-identification"
+        )
+    return platform

qualys_cli/queries.py

@@ -0,0 +1,137 @@
+"""
+Saved-query library.
+
+Each TOML file under ``~/.config/qualys-cli/queries/<name>.toml`` describes one
+named, shareable invocation. The schema is intentionally minimal:
+
+    name = "prod-criticals"
+    description = "Internet-facing prod hosts with severity-5 vulnerabilities"
+    command = ["vm", "host", "list"]
+    args = ["--ips", "10.0.0.0/8", "--severities", "5"]
+
+The CLI's top-level ``qualys-cli query run prod-criticals`` resolves the file,
+splices ``args`` into argv after the resolved command, and dispatches as if the
+user typed it manually. ``qualys-cli query list`` and ``query show`` provide
+discoverability; ``query save`` writes a query from the current invocation.
+
+Security notes
+--------------
+- Query names are restricted to ``[A-Za-z0-9_-]+`` so they cannot escape the
+  queries directory via ``..`` or absolute-path traversal. Every load / save
+  / delete additionally checks that the resolved path is contained within
+  ``QUERIES_DIR.resolve()`` — defence in depth against future regex slippage.
+- All user-supplied strings (name, description, command and args entries)
+  are serialised through :func:`_toml_str`, which delegates to
+  ``json.dumps``. JSON's basic-string grammar is a strict subset of TOML's,
+  so this gives us correct escaping for backslashes, quotes, control chars,
+  and non-ASCII without re-implementing the TOML spec by hand.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .config import QUERIES_DIR
+
+# `_NAME_RE` deliberately excludes "." — that class allowed `..` traversal in
+# earlier builds. Names today must be filename-safe across platforms.
+_NAME_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+
+
+@dataclass
+class SavedQuery:
+    name: str
+    command: list[str]
+    args: list[str] = field(default_factory=list)
+    description: str = ""
+
+    def to_toml(self) -> str:
+        lines: list[str] = [f"name = {_toml_str(self.name)}"]
+        if self.description:
+            lines.append(f"description = {_toml_str(self.description)}")
+        lines.append("command = [" + ", ".join(_toml_str(c) for c in self.command) + "]")
+        if self.args:
+            lines.append("args = [" + ", ".join(_toml_str(a) for a in self.args) + "]")
+        return "\n".join(lines) + "\n"
+
+
+def _toml_str(s: str) -> str:
+    """Serialise *s* as a TOML basic string.
+
+    JSON's basic-string grammar (RFC 8259 §7) is a strict subset of TOML's
+    basic-string grammar (TOML v1.0 §5), so ``json.dumps(s)`` produces output
+    that's always valid TOML. ``ensure_ascii=False`` keeps Unicode literal
+    rather than \\u-escaping it — TOML accepts both, but the literal form is
+    more readable in saved-query files reviewers will want to skim.
+    """
+    return json.dumps(s, ensure_ascii=False)
+
+
+def _path(name: str) -> Path:
+    if not _NAME_RE.match(name):
+        raise ValueError(
+            f"Invalid query name: {name!r} — must match [A-Za-z0-9_-]+ "
+            "(no dots, slashes, or path separators)"
+        )
+    p = QUERIES_DIR / f"{name}.toml"
+    # Defence in depth: even if the regex is ever loosened, refuse to operate
+    # on anything that resolves outside QUERIES_DIR.
+    try:
+        p.resolve().relative_to(QUERIES_DIR.resolve())
+    except ValueError as exc:
+        raise ValueError(
+            f"Refusing to operate on {p} — path escapes the queries directory"
+        ) from exc
+    return p
+
+
+def list_queries() -> list[SavedQuery]:
+    QUERIES_DIR.mkdir(parents=True, exist_ok=True)
+    out: list[SavedQuery] = []
+    for f in sorted(QUERIES_DIR.glob("*.toml")):
+        try:
+            data = tomllib.loads(f.read_text())
+        except (tomllib.TOMLDecodeError, OSError):
+            continue
+        out.append(SavedQuery(
+            name=str(data.get("name", f.stem)),
+            command=list(data.get("command", [])),
+            args=list(data.get("args", [])),
+            description=str(data.get("description", "")),
+        ))
+    return out
+
+
+def load(name: str) -> SavedQuery:
+    p = _path(name)
+    if not p.exists():
+        raise FileNotFoundError(f"No saved query named {name!r} at {p}")
+    data = tomllib.loads(p.read_text())
+    return SavedQuery(
+        name=str(data.get("name", name)),
+        command=list(data.get("command", [])),
+        args=list(data.get("args", [])),
+        description=str(data.get("description", "")),
+    )
+
+
+def save(q: SavedQuery, *, overwrite: bool = False) -> Path:
+    p = _path(q.name)
+    if p.exists() and not overwrite:
+        raise FileExistsError(f"Query {q.name!r} already exists at {p}")
+    QUERIES_DIR.mkdir(parents=True, exist_ok=True)
+    p.write_text(q.to_toml())
+    p.chmod(0o600)
+    return p
+
+
+def delete(name: str) -> bool:
+    p = _path(name)
+    if p.exists():
+        p.unlink()
+        return True
+    return False