qualys-cli 0.1.1__py3-none-any.whl

qualys_cli/auth.py

@@ -0,0 +1,187 @@
+"""
+Authentication helpers.
+
+  basic  – httpx.BasicAuth passed directly to the client
+  jwt    – username+password exchanged for a Bearer token via /auth endpoint;
+           token is cached on the Profile object for the lifetime of the command
+           and written back to ~/.config/qualys-cli/config.toml for reuse
+
+Stability features
+------------------
+- :func:`token_is_fresh` decodes the cached JWT's ``exp`` claim and refuses to
+  reuse a token that is within ``leeway`` seconds of expiry.
+- :func:`force_refresh` clears the cached token and exchanges a fresh one;
+  used by ``qualys-cli rotate-jwt``.
+- All exchanges are serialised by a per-profile lock so parallel workers
+  (``paginate_json_parallel``, ``batch --parallel``) cannot clobber each
+  other's tokens. After acquiring the lock we re-check the cached token, so
+  the second concurrent caller sees the first one's fresh result instead of
+  performing a duplicate ``/auth`` round trip.
+- :func:`exchange_no_cache` performs the network exchange without writing to
+  disk — used by ``qualys-cli doctor`` so a preflight stays read-only.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import threading
+import time
+
+import httpx
+from rich.console import Console
+
+from .config import Profile, cache_token
+
+_console = Console(stderr=True)
+
+_JWT_PATH = "/auth"
+
+_DEFAULT_LEEWAY_SECONDS = 60
+
+# Per-profile lock for /auth exchanges. The map itself is guarded by
+# ``_exchange_locks_guard`` so two callers with the same brand-new profile
+# name don't race on the dict insertion.
+_exchange_locks: dict[str, threading.Lock] = {}
+_exchange_locks_guard = threading.Lock()
+
+
+def basic_auth(profile: Profile) -> httpx.BasicAuth:
+    return httpx.BasicAuth(profile.username, profile.password)
+
+
+def _b64url_decode(s: str) -> bytes:
+    pad = "=" * (-len(s) % 4)
+    return base64.urlsafe_b64decode(s + pad)
+
+
+def jwt_exp(token: str) -> int | None:
+    """Return the ``exp`` claim of a JWT (Unix timestamp), or None on
+    malformed / unsigned / claim-less tokens. Never raises."""
+    if not token or token.count(".") < 2:
+        return None
+    try:
+        payload_b64 = token.split(".")[1]
+        payload = json.loads(_b64url_decode(payload_b64))
+    except (ValueError, json.JSONDecodeError):
+        return None
+    exp = payload.get("exp")
+    if isinstance(exp, (int, float)):
+        return int(exp)
+    return None
+
+
+def token_is_fresh(token: str, *, leeway: int = _DEFAULT_LEEWAY_SECONDS) -> bool:
+    """True iff the token's ``exp`` is at least *leeway* seconds in the future.
+
+    A structurally-malformed token (not 3 dot-separated segments) is treated
+    as stale so we re-exchange instead of sending garbage as a Bearer.
+    Some Qualys services answer with 500 ("JWT parsing failed") rather than
+    401 for an unparseable token, so we cannot rely on the 401-refresh path
+    to recover.
+
+    A well-formed token without an ``exp`` claim is treated as fresh — the
+    401-refresh path catches that case safely.
+    """
+    if not token or token.count(".") != 2:
+        return False
+    exp = jwt_exp(token)
+    if exp is None:
+        return True
+    return exp - time.time() > leeway
+
+
+def _profile_lock(name: str) -> threading.Lock:
+    with _exchange_locks_guard:
+        return _exchange_locks.setdefault(name, threading.Lock())
+
+
+def get_jwt(profile: Profile) -> str:
+    """Return a valid JWT, exchanging credentials only if the cached one is
+    stale or absent. Concurrent calls for the same profile share one
+    exchange via :func:`_profile_lock`."""
+    if profile.token and token_is_fresh(profile.token):
+        return profile.token
+    return _exchange(profile)
+
+
+def force_refresh(profile: Profile) -> str:
+    """Drop any cached token and force a fresh credential exchange.
+    The new token is persisted to ``config.toml`` for subsequent runs."""
+    profile.token = ""
+    return _exchange(profile)
+
+
+def exchange_no_cache(profile: Profile) -> str:
+    """Run a fresh ``/auth`` exchange but do NOT persist the result.
+
+    Used by ``qualys-cli doctor`` so a preflight check is fully read-only —
+    the caller's on-disk profile stays byte-identical, and any other
+    concurrent users of the profile keep their cached token.
+    """
+    return _exchange(profile, persist=False)
+
+
+def _exchange(profile: Profile, *, persist: bool = True) -> str:
+    """Perform a credential exchange under a per-profile lock.
+
+    On lock acquisition we re-check the cached token: if another thread
+    beat us to the refresh, we return its result instead of doing a
+    duplicate exchange. ``persist=False`` keeps the result in memory only
+    (used by the read-only doctor preflight).
+    """
+    if not profile.password:
+        raise ValueError(
+            "JWT auth requires a password. "
+            "Run `qualys-cli configure` or set QUALYS_PASSWORD."
+        )
+
+    lock = _profile_lock(profile.name)
+    with lock:
+        # Double-checked locking: another thread may have refreshed while we
+        # were waiting for the lock. Only honour fresh-enough tokens (small
+        # leeway so we don't accept one that's about to expire mid-call).
+        if persist and profile.token and token_is_fresh(profile.token, leeway=5):
+            return profile.token
+
+        # Qualys exposes /auth on the gateway host (e.g.
+        # gateway.qg2.apps.qualys.com), not on the API host
+        # (qualysapi.qg2.apps.qualys.com) — the API host returns a 404 HTML
+        # page for POSTs to /auth.
+        auth_base = (profile.gateway_url or profile.url).rstrip("/")
+        with _console.status(
+            "[bold cyan]Forging secure session token…[/bold cyan]  "
+            "[dim]exchanging credentials with Qualys[/dim]",
+            spinner="dots",
+        ):
+            try:
+                resp = httpx.post(
+                    f"{auth_base}{_JWT_PATH}",
+                    data={
+                        "username": profile.username,
+                        "password": profile.password,
+                        "token": "true",
+                    },
+                    headers={"X-Requested-With": "qualys-cli"},
+                    timeout=30.0,
+                )
+                resp.raise_for_status()
+            except httpx.HTTPStatusError as exc:
+                raise RuntimeError(
+                    f"JWT exchange failed ({exc.response.status_code}): "
+                    f"{exc.response.text[:200]}"
+                ) from exc
+            except httpx.RequestError as exc:
+                raise RuntimeError(
+                    f"JWT exchange failed (network error): {exc}"
+                ) from exc
+
+        token = resp.text.strip()
+        if persist:
+            profile.token = token
+            cache_token(profile.name, profile.username, token)
+        return token
+
+
+def bearer_header(token: str) -> dict[str, str]:
+    return {"Authorization": f"Bearer {token}"}

qualys_cli/cache.py

@@ -0,0 +1,123 @@
+"""
+ETag-aware response cache for catalog-style endpoints.
+
+Some Qualys endpoints (KB, patch catalog, organization list, …) return tens
+of MB of mostly-static data. This module provides a tiny SQLite-backed cache
+keyed on (method, full URL) that stores the last response body and its ETag /
+Last-Modified header. The :class:`QualysClient` doesn't auto-cache — callers
+opt in by wrapping a request with :func:`cached_get`.
+
+Design constraints:
+
+- Pure stdlib (sqlite3) — no extra dependency.
+- Cache is per-host and per-user (``~/.config/qualys-cli/cache/cache.sqlite``,
+  mode ``0600``).
+- A separate ``QUALYS_CACHE`` env var lets users opt out (``off``) or relocate
+  the file. ``QUALYS_CACHE_TTL`` caps fall-back age when the upstream returns
+  no validators.
+- Cache misses degrade silently to a fresh request — never break a command.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import sqlite3
+import time
+from pathlib import Path
+
+from .config import CACHE_DIR
+
+_DEFAULT_PATH = CACHE_DIR / "cache.sqlite"
+_DEFAULT_TTL_SECONDS = 24 * 60 * 60  # 24 h fallback when no validators
+
+
+def _path() -> Path | None:
+    raw = os.environ.get("QUALYS_CACHE", "").strip()
+    if raw.lower() in {"off", "none", "false", "0", "disabled", "no"}:
+        return None
+    if raw and raw.lower() != "default":
+        return Path(raw).expanduser()
+    return _DEFAULT_PATH
+
+
+def _ttl() -> int:
+    raw = os.environ.get("QUALYS_CACHE_TTL", "").strip()
+    if raw.isdigit():
+        n = int(raw)
+        if n > 0:
+            return n
+    return _DEFAULT_TTL_SECONDS
+
+
+def _connect() -> sqlite3.Connection | None:
+    p = _path()
+    if p is None:
+        return None
+    try:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        conn = sqlite3.connect(str(p), timeout=2.0, isolation_level=None)
+        conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS cache(
+              key       TEXT PRIMARY KEY,
+              etag      TEXT,
+              modified  TEXT,
+              ts        INTEGER NOT NULL,
+              body      BLOB    NOT NULL,
+              status    INTEGER NOT NULL
+            )
+            """
+        )
+        with contextlib.suppress(Exception):
+            p.chmod(0o600)
+        return conn
+    except Exception:
+        return None
+
+
+def get(key: str) -> tuple[bytes, str, str, int, int] | None:
+    """Return ``(body, etag, modified, ts, status)`` for *key* or None on miss."""
+    conn = _connect()
+    if conn is None:
+        return None
+    try:
+        cur = conn.execute(
+            "SELECT body, etag, modified, ts, status FROM cache WHERE key = ?", (key,),
+        )
+        row = cur.fetchone()
+        if row is None:
+            return None
+        return (row[0], row[1] or "", row[2] or "", int(row[3]), int(row[4]))
+    finally:
+        conn.close()
+
+
+def put(key: str, body: bytes, etag: str, modified: str, status: int) -> None:
+    conn = _connect()
+    if conn is None:
+        return
+    try:
+        conn.execute(
+            "INSERT OR REPLACE INTO cache(key, etag, modified, ts, body, status) "
+            "VALUES (?, ?, ?, ?, ?, ?)",
+            (key, etag, modified, int(time.time()), body, int(status)),
+        )
+    finally:
+        conn.close()
+
+
+def is_fresh(ts: int) -> bool:
+    return (time.time() - ts) < _ttl()
+
+
+def clear() -> int:
+    """Remove all cache entries. Returns the number of rows deleted."""
+    conn = _connect()
+    if conn is None:
+        return 0
+    try:
+        cur = conn.execute("DELETE FROM cache")
+        return int(cur.rowcount or 0)
+    finally:
+        conn.close()