qualys-cli 0.1.1__py3-none-any.whl

qualys_cli/flair.py

@@ -0,0 +1,202 @@
+"""
+Status messages for the interactive spinner.
+
+We cycle a small playful banner of Qualys / cybersecurity-themed phrases under
+the spinner while a request is in flight. Two reasons:
+
+1. Long Qualys API calls (large host-list fetches, scan launches, exports)
+   can run for tens of seconds. A static "GET /api/2.0/fo/asset/host/" label
+   feels frozen; a rotating phrase is reassuring without being noisy.
+2. The phrases are drawn from the *actual* Qualys offering — VMDR, TotalCloud,
+   Patch Management, Container Security, EASM, TruRisk, etc. — so each one
+   reinforces what the call is doing. The category is picked from the URL
+   path so the messages line up with the API being called.
+
+Cycling cadence: ~700 ms. Slow enough to read, fast enough to feel alive.
+
+Pure functions only — no I/O — so this module is trivially testable.
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Sequence
+
+# Each entry is a short verb-led phrase. Keep them under ~40 chars so the
+# spinner doesn't wrap on narrow terminals. Trailing ellipsis is added by
+# the renderer, not here.
+
+_VM = [
+    "Scanning for vulnerabilities",
+    "Crunching QIDs",
+    "Detecting CVEs in the wild",
+    "Probing the attack surface",
+    "Hunting zero-days",
+    "Correlating vuln signatures",
+    "Tracing exploit chains",
+]
+
+_PC = [
+    "Auditing compliance controls",
+    "Mapping policy posture",
+    "Evaluating CIS benchmarks",
+    "Checking regulatory drift",
+    "Reconciling control gates",
+]
+
+_WAS = [
+    "Crawling web app surface",
+    "Fuzzing OWASP Top 10",
+    "Inspecting auth records",
+    "Hunting injection points",
+    "Tracing app-layer flaws",
+]
+
+_TC = [
+    "Scanning cloud posture",
+    "Validating IAM blast radius",
+    "Mapping CSPM controls",
+    "Auditing misconfigurations",
+    "Tracing cloud-native risk",
+    "Inspecting Terraform plans",
+]
+
+_CA = [
+    "Pinging cloud agents",
+    "Refreshing host inventory",
+    "Rotating activation keys",
+    "Reconciling agent telemetry",
+]
+
+_CS = [
+    "Inspecting container images",
+    "Scanning Kubernetes layers",
+    "Tracing image provenance",
+    "Hunting in-cluster exposure",
+    "Auditing registry posture",
+]
+
+_CSAM = [
+    "Inventorying cyber assets",
+    "Mapping EASM exposures",
+    "Discovering shadow IT",
+    "Resolving asset criticality",
+    "Painting the attack surface",
+]
+
+_PM = [
+    "Staging patch deployment",
+    "Building remediation job",
+    "Rolling out fixes",
+    "Verifying patch readiness",
+    "Sequencing rollout windows",
+]
+
+_ETM = [
+    "Computing TruRisk score",
+    "Bundling mitigation plan",
+    "Scoring exposure findings",
+    "Prioritising risk in flight",
+]
+
+_ASSET = [
+    "Reconciling asset graph",
+    "Tagging hosts",
+    "Enumerating networks",
+    "Resolving asset criticality",
+]
+
+_USER = [
+    "Enrolling subscription users",
+    "Verifying role assignments",
+    "Reviewing user privileges",
+]
+
+_SUB = [
+    "Inspecting subscription posture",
+    "Loading entitlement matrix",
+    "Reviewing license footprint",
+]
+
+_SCANAUTH = [
+    "Locking down auth records",
+    "Verifying vault handshakes",
+    "Rotating credentials securely",
+]
+
+_AUTH = [
+    "Establishing secure channel",
+    "Forging session token",
+    "Verifying JWT signature",
+    "Authenticating with Qualys",
+]
+
+_GENERIC = [
+    "Talking to Qualys Cloud Platform",
+    "Negotiating TLS handshake",
+    "Streaming response securely",
+    "Decoding telemetry",
+    "Hashing payload integrity",
+    "Holding the line on egress",
+]
+
+
+# Match longest URL fragments first so e.g. "/qps/rest/3.0/" → WAS, not generic.
+_PATH_RULES: list[tuple[str, list[str]]] = [
+    ("/qps/rest/3.0/", _WAS),
+    ("/api/2.0/fo/compliance", _PC),
+    ("/api/2.0/fo/policy", _PC),
+    ("/api/2.0/fo/scan/compliance", _PC),
+    ("/api/2.0/fo/asset/", _ASSET),
+    ("/api/2.0/fo/scan", _VM),
+    ("/api/2.0/fo/knowledge_base", _VM),
+    ("/api/2.0/fo/auth/", _SCANAUTH),
+    ("/api/2.0/fo/vault", _SCANAUTH),
+    ("/api/2.0/fo/user_prefs", _SUB),
+    ("/api/2.0/fo/subscription", _SUB),
+    ("/api/2.0/fo/user", _USER),
+    ("/qps/rest/2.0/", _CA),
+    ("/cloudview-api/", _TC),
+    ("/cloudview/", _TC),
+    ("/cdr-api/", _TC),
+    ("/csapi/", _CS),
+    ("/cs-api/", _CS),
+    ("/csam/", _CSAM),
+    ("/easm/", _CSAM),
+    ("/am/v2/", _CSAM),
+    ("/rest/2.0/search/am", _CSAM),
+    ("/caui/", _CA),
+    ("/pm/", _PM),
+    ("/pcrs/", _PM),
+    ("/etm/", _ETM),
+    ("/auth", _AUTH),
+]
+
+
+def messages_for_path(path: str) -> Sequence[str]:
+    """Pick the message bucket that matches *path*. Falls back to GENERIC."""
+    for prefix, bucket in _PATH_RULES:
+        if prefix in path:
+            return bucket
+    return _GENERIC
+
+
+def cycle_for_path(path: str) -> list[str]:
+    """Return a shuffled cycle of messages for the spinner.
+
+    We mix the path-specific bucket with a couple of generic phrases so even
+    short calls feel a bit varied. The first message is always the most
+    on-topic — the one users see while the call still feels instant — and
+    the rest rotate after that.
+    """
+    primary = list(messages_for_path(path))
+    rng = random.Random()  # not seeded — tests don't assert on order
+    rng.shuffle(primary)
+    extras = rng.sample(_GENERIC, k=min(2, len(_GENERIC)))
+    out: list[str] = []
+    seen: set[str] = set()
+    for m in primary + extras:
+        if m not in seen:
+            out.append(m)
+            seen.add(m)
+    return out