qualys-cli 0.1.1__py3-none-any.whl

qualys_cli/client.py

@@ -0,0 +1,1043 @@
+"""
+Qualys HTTP client — enterprise-grade resiliency and audit.
+
+Responsibilities
+----------------
+- Basic Auth and JWT Bearer, selected per-call (``auth_type=…``).
+- Typed exception hierarchy (see :class:`APIError` and subclasses), including a
+  fine-grained taxonomy for transport failures: DNS, TLS, refused, reset.
+- Retries with exponential backoff and full jitter on transient failures.
+  By default only **idempotent** verbs (GET, HEAD, DELETE) are retried; POST/
+  PUT/PATCH require an explicit ``idempotent=True`` opt-in to avoid the
+  silent double-submit class of bugs (e.g. ``vm scan launch`` issued twice).
+- Honours ``Retry-After`` on 408 / 429 / 503 (delta-seconds and HTTP-date).
+- JWT auto-refresh on 401; a fresh token is also exchanged proactively when
+  the cached one is within ``leeway`` seconds of its ``exp`` claim.
+- Distinct connect / read / write / pool timeouts, configurable via env vars.
+- Connection pooling limits configurable via env vars.
+- Brotli / zstd response decoding (free 50–80 % bandwidth on JSON-heavy APIs).
+- Body-size guard: refuses to load >250 MB into memory unless ``--allow-large``
+  is set or the response is being streamed straight to ``--output-file``.
+- Per-call timing breakdown (connect / TLS / TTFB / total) emitted into the
+  audit log when the underlying transport hooks are available.
+- Spinner on TTY when not verbose (cyber-themed cycle via :mod:`flair`).
+- Per-invocation correlation ID (``X-Correlation-ID``) and per-request ID
+  (``X-Request-ID``) propagated on the wire and into the audit log.
+- ``--dry-run`` / ``--explain`` short-circuit: instead of issuing the HTTP
+  request, the client renders the resolved request shape and raises
+  :class:`DryRunExit`, which the CLI maps to exit code 0.
+"""
+
+from __future__ import annotations
+
+import json as _json
+import os
+import random
+import threading
+import time
+import uuid
+from collections.abc import Generator, Iterator
+from contextlib import contextmanager
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+import httpx
+import xmltodict
+from rich.console import Console
+
+from . import audit as _audit
+from . import flair as _flair
+from .auth import basic_auth, bearer_header, get_jwt
+from .config import Profile
+
+_console = Console(stderr=True)
+
+_BASE_HEADERS = {
+    "X-Requested-With": "qualys-cli",
+    "Accept-Encoding": "br, gzip, zstd",
+}
+
+_METHOD_STYLE: dict[str, str] = {
+    "GET": "cyan", "POST": "yellow", "PUT": "blue",
+    "DELETE": "red", "PATCH": "magenta",
+}
+
+# Status codes that warrant a retry (assuming idempotency).
+_RETRY_STATUSES = frozenset({408, 425, 429, 500, 502, 503, 504})
+_RETRY_AFTER_STATUSES = frozenset({408, 429, 503})
+
+# Verbs that are safe to retry blindly; POST/PUT/PATCH require explicit opt-in.
+_IDEMPOTENT_VERBS = frozenset({"GET", "HEAD", "OPTIONS", "DELETE"})
+
+_DEFAULT_BODY_LIMIT_BYTES = 250 * 1024 * 1024  # 250 MB
+
+
+# ---------------------------------------------------------------------------
+# Module-level switches set by the CLI on startup
+# ---------------------------------------------------------------------------
+
+DRY_RUN: bool = False
+"""When True, requests are not sent — the resolved shape is printed and a
+:class:`DryRunExit` is raised so the command exits cleanly with code 0."""
+
+
+def _env_int(name: str, default: int, *, minimum: int = 0) -> int:
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return default
+    try:
+        n = int(raw)
+    except ValueError:
+        return default
+    return max(minimum, n)
+
+
+def _env_float(name: str, default: float, *, minimum: float = 0.0) -> float:
+    raw = os.environ.get(name, "").strip()
+    if not raw:
+        return default
+    try:
+        n = float(raw)
+    except ValueError:
+        return default
+    return max(minimum, n)
+
+
+def _fmt_bytes(n: int) -> str:
+    if n < 1024:
+        return f"{n} B"
+    if n < 1024 ** 2:
+        return f"{n/1024:.1f} KB"
+    return f"{n/1024**2:.1f} MB"
+
+
+# ---------------------------------------------------------------------------
+# Exception hierarchy
+# ---------------------------------------------------------------------------
+
+class APIError(Exception):
+    exit_code: int = 1
+    hint: str = ""
+
+    def __init__(
+        self, status: int, message: str, *,
+        correlation: str = "", request_id: str = "",
+    ) -> None:
+        self.status = status
+        self.message = message
+        self.correlation = correlation
+        self.request_id = request_id
+        super().__init__(f"HTTP {status}: {message}" if status else message)
+
+
+class AuthError(APIError):
+    exit_code = 3
+    hint = (
+        "Authentication failed. Run [cyan]qualys-cli configure[/cyan] to refresh "
+        "credentials, or check that your account has access to this API."
+    )
+
+
+class NotFoundError(APIError):
+    exit_code = 4
+    hint = "The resource was not found. Verify IDs, scope, and that the right profile is selected."
+
+
+class RateLimitError(APIError):
+    exit_code = 5
+    hint = (
+        "The Qualys rate limit was exceeded after retries. Wait a few minutes "
+        "and retry, or split the request into smaller batches."
+    )
+
+
+class ServerError(APIError):
+    exit_code = 7
+    hint = (
+        "Qualys reported a server-side error. If it persists, capture the "
+        "correlation ID and contact Qualys Support."
+    )
+
+
+class NetworkError(APIError):
+    exit_code = 6
+    hint = (
+        "Could not reach the Qualys API. Check network connectivity, proxy "
+        "settings, and that the platform URL is correct for your subscription."
+    )
+
+
+class DNSError(NetworkError):
+    hint = "DNS lookup failed. Verify the platform URL and your DNS resolver."
+
+
+class TLSError(NetworkError):
+    hint = (
+        "TLS handshake failed. Check the system trust store, proxy CA bundle, "
+        "and that the platform URL is HTTPS."
+    )
+
+
+class ConnectionResetError_(NetworkError):
+    """Connection reset by peer (TCP RST)."""
+    hint = "Connection was reset by the server — retry, or check for an interfering middlebox/proxy."
+
+
+class ConnectionRefusedError_(NetworkError):
+    hint = "Connection refused. Verify the URL and that nothing is filtering outbound 443."
+
+
+class TimeoutError(APIError):  # noqa: A001 — shadows builtin but the name is correct here
+    exit_code = 6
+    hint = (
+        "The request timed out. Set [cyan]QUALYS_TIMEOUT=120[/cyan] (seconds) "
+        "for slow endpoints or narrow the query (filters, smaller --limit)."
+    )
+
+
+class BodyTooLargeError(APIError):
+    exit_code = 8
+    hint = (
+        "Response exceeded the in-memory body cap. Pass [cyan]--output-file[/cyan] "
+        "to stream to disk, or set [cyan]QUALYS_BODY_LIMIT_BYTES=0[/cyan] to disable."
+    )
+
+
+import typer as _typer  # noqa: E402  — imported here to avoid a circular
+
+
+class DryRunExit(_typer.Exit):
+    """Raised by ``request()`` when ``DRY_RUN`` is set, instead of issuing the
+    HTTP call. Subclasses :class:`typer.Exit` so the CLI runner treats it as a
+    clean exit-with-code-0 rather than an unhandled exception."""
+
+    def __init__(self) -> None:
+        super().__init__(code=0)
+
+
+def _classify_transport(exc: httpx.RequestError, *, correlation: str, request_id: str) -> APIError:
+    """Map an httpx transport exception to the most specific NetworkError subclass."""
+    kw = {"correlation": correlation, "request_id": request_id}
+    msg = str(exc) or exc.__class__.__name__
+    if isinstance(exc, (httpx.ConnectTimeout, httpx.ReadTimeout)):
+        return TimeoutError(0, f"Request timed out: {msg}", **kw)
+    if isinstance(exc, httpx.ConnectError):
+        low = msg.lower()
+        if "name or service" in low or "name resolution" in low or "nodename" in low \
+                or "getaddrinfo" in low or "no address" in low:
+            return DNSError(0, f"DNS lookup failed: {msg}", **kw)
+        if "ssl" in low or "tls" in low or "certificate" in low or "verify failed" in low:
+            return TLSError(0, f"TLS handshake failed: {msg}", **kw)
+        if "refused" in low:
+            return ConnectionRefusedError_(0, f"Connection refused: {msg}", **kw)
+        return NetworkError(0, f"Connection error: {msg}", **kw)
+    if isinstance(exc, (httpx.ReadError, httpx.WriteError)):
+        low = msg.lower()
+        if "reset" in low:
+            return ConnectionResetError_(0, f"Connection reset: {msg}", **kw)
+        return NetworkError(0, f"Transport error: {msg}", **kw)
+    return NetworkError(0, f"Network error: {msg}", **kw)
+
+
+def _classify(status: int, message: str, *, correlation: str, request_id: str) -> APIError:
+    kw = {"correlation": correlation, "request_id": request_id}
+    if status in (401, 403):
+        return AuthError(status, message, **kw)
+    if status == 404:
+        return NotFoundError(status, message, **kw)
+    if status == 429:
+        return RateLimitError(status, message, **kw)
+    if 500 <= status < 600:
+        return ServerError(status, message, **kw)
+    return APIError(status, message, **kw)
+
+
+# ---------------------------------------------------------------------------
+# Client
+# ---------------------------------------------------------------------------
+
+class QualysClient:
+    def __init__(
+        self,
+        profile: Profile,
+        auth_type: str = "basic",
+        verbose: int = 0,
+    ) -> None:
+        self.profile = profile
+        self.auth_type = auth_type
+        self.verbose = verbose
+
+        self.max_retries = _env_int("QUALYS_MAX_RETRIES", 4, minimum=1)
+        self.backoff_base = _env_float("QUALYS_BACKOFF_BASE", 1.0, minimum=0.0)
+        self.backoff_cap = _env_float("QUALYS_BACKOFF_CAP", 30.0, minimum=0.0)
+        connect_t = _env_float("QUALYS_CONNECT_TIMEOUT", 10.0, minimum=0.1)
+        read_t = _env_float("QUALYS_TIMEOUT", 60.0, minimum=1.0)
+        max_connections = _env_int("QUALYS_MAX_CONNECTIONS", 20, minimum=1)
+        max_keepalive = _env_int("QUALYS_MAX_KEEPALIVE", 10, minimum=1)
+        self.body_limit = _env_int(
+            "QUALYS_BODY_LIMIT_BYTES", _DEFAULT_BODY_LIMIT_BYTES, minimum=0,
+        )
+
+        self._http = httpx.Client(
+            base_url=profile.url,
+            headers={
+                **_BASE_HEADERS,
+                "X-Correlation-ID": _audit.CORRELATION_ID or "uninitialized",
+            },
+            timeout=httpx.Timeout(read_t, connect=connect_t),
+            limits=httpx.Limits(
+                max_connections=max_connections,
+                max_keepalive_connections=max_keepalive,
+            ),
+            follow_redirects=True,
+        )
+        if auth_type == "basic":
+            self._http.auth = basic_auth(profile)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release connection pool resources."""
+        self._http.close()
+
+    def __enter__(self) -> QualysClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Spinner
+    # ------------------------------------------------------------------
+
+    @contextmanager
+    def _spin(self, method: str, path: str) -> Generator[None, None, None]:
+        if self.verbose != 0 or not _console.is_terminal:
+            yield
+            return
+        if os.environ.get("QUALYS_NO_FLAIR", "").strip().lower() in {"1", "true", "yes", "on"}:
+            ep = path.split("?")[0]
+            label = (
+                f"[bold cyan]Calling Qualys[/bold cyan]  "
+                f"[dim]{method} {ep}[/dim]"
+            )
+            with _console.status(label, spinner="dots"):
+                yield
+            return
+
+        endpoint = path.split("?")[0]
+        messages = _flair.cycle_for_path(endpoint)
+
+        def render(msg: str) -> str:
+            return f"[bold cyan]{msg}…[/bold cyan]  [dim]{method} {endpoint}[/dim]"
+
+        cadence = _env_float("QUALYS_FLAIR_CADENCE", 0.7, minimum=0.1)
+        stop = threading.Event()
+
+        with _console.status(render(messages[0]), spinner="dots") as status:
+            def cycle() -> None:
+                idx = 0
+                while not stop.wait(cadence):
+                    idx = (idx + 1) % len(messages)
+                    status.update(render(messages[idx]))
+
+            thread = threading.Thread(target=cycle, daemon=True, name="qcli-spinner")
+            thread.start()
+            try:
+                yield
+            finally:
+                stop.set()
+                # The cycler is sleeping in `stop.wait(cadence)` — ensure the
+                # join timeout is generous enough for it to wake up cleanly,
+                # otherwise the daemon thread can write to the rich Console
+                # *after* the request finished and garble stderr output.
+                thread.join(timeout=cadence + 0.1)
+
+    # ------------------------------------------------------------------
+    # Backoff
+    # ------------------------------------------------------------------
+
+    def _backoff(self, attempt: int) -> float:
+        ceiling = min(self.backoff_cap, self.backoff_base * (2 ** attempt))
+        if ceiling <= 0:
+            return 0.0
+        return random.uniform(0, ceiling)
+
+    # Conservative wait when the server sent ``Retry-After:`` but the value
+    # is unparseable — better than falling through to sub-second backoff.
+    _RETRY_AFTER_FALLBACK_SECONDS = 60.0
+
+    @staticmethod
+    def _parse_retry_after(value: str) -> float | None:
+        """Parse a Retry-After header value. Returns seconds-to-wait.
+
+        Returns ``None`` only when the header is absent / empty. Garbage
+        values (``please-wait``, malformed dates) return the conservative
+        :data:`_RETRY_AFTER_FALLBACK_SECONDS` instead, because the server
+        clearly *intended* to signal a wait — falling through to short
+        backoff would hammer a rate-limited endpoint.
+        """
+        if not value:
+            return None
+        v = value.strip()
+        try:
+            n = float(v)
+            return max(0.0, n)
+        except ValueError:
+            pass
+        try:
+            dt = parsedate_to_datetime(v)
+            if dt is not None:
+                return max(0.0, dt.timestamp() - time.time())
+        except (TypeError, ValueError):
+            pass
+        # Header present but neither numeric nor a valid HTTP-date — degrade
+        # to a safe fallback rather than fast-retrying.
+        return QualysClient._RETRY_AFTER_FALLBACK_SECONDS
+
+    # ------------------------------------------------------------------
+    # Dry-run rendering
+    # ------------------------------------------------------------------
+
+    def _emit_dry_run(self, method: str, path: str, kwargs: dict[str, Any]) -> None:
+        """Print the resolved request shape and do NOT send anything.
+
+        Output contract (agentic / non-TTY mode)
+        ---------------------------------------
+        A single JSON object on stdout with these keys::
+
+            method   HTTP verb
+            url      fully-qualified request URL (profile + path)
+            auth     "basic" or "jwt"
+            params   query string as a JSON object (redacted)
+            body     request body normalised to a JSON object whenever
+                     possible. If the original body was a JSON string we
+                     parse it back so callers see structure, not a string.
+                     If the body is non-JSON (XML, form-encoded), it is
+                     surfaced as a string preview. ``null`` if no body.
+            headers  request headers (Authorization redacted)
+
+        This contract is the public surface that MCP / serve / batch
+        callers parse — keep it stable.
+        """
+        from rich.panel import Panel
+
+        url = f"{self.profile.url.rstrip('/')}{path}"
+        body: Any = kwargs.get("json")
+        if body is None:
+            body = kwargs.get("data")
+        if body is None:
+            body = kwargs.get("content")
+            if isinstance(body, bytes):
+                with __import__("contextlib").suppress(Exception):
+                    body = body.decode("utf-8", "ignore")
+
+        # Redact secrets in the rendered body / params
+        params = _audit.redact_mapping(dict(kwargs.get("params") or {}))
+        if isinstance(body, dict):
+            body = _audit.redact_mapping(body)
+        elif isinstance(body, str):
+            # Try to round-trip a string body back into a dict — ``post_xml``
+            # passes XML as a string and ``post_json`` already passed dicts,
+            # but generic callers may have stringified a dict before us.
+            stripped = body.lstrip()
+            if stripped.startswith(("{", "[")):
+                try:
+                    parsed = _json.loads(body)
+                    if isinstance(parsed, (dict, list)):
+                        body = _audit.redact_mapping(parsed)
+                except _json.JSONDecodeError:
+                    pass  # leave as string preview
+        # Headers — copy, redact Authorization
+        hdrs = dict(kwargs.get("headers") or {})
+        if "Authorization" in hdrs:
+            scheme = hdrs["Authorization"].split(" ", 1)[0] if " " in hdrs["Authorization"] else "***"
+            hdrs["Authorization"] = f"{scheme} ***REDACTED***"
+
+        lines: list[str] = []
+        lines.append(f"[bold cyan]{method}[/bold cyan]  [white]{url}[/white]")
+        lines.append(f"[dim]auth:[/dim] {self.auth_type}")
+        if params:
+            lines.append(f"[dim]params:[/dim] {_json.dumps(params, default=str)}")
+        if isinstance(body, dict):
+            lines.append(f"[dim]body:[/dim] {_json.dumps(body, default=str, indent=2)}")
+        elif isinstance(body, str):
+            preview = body if len(body) < 400 else body[:400] + "…"
+            lines.append(f"[dim]body:[/dim] {preview}")
+        if hdrs:
+            redacted = ", ".join(f"{k}={v}" for k, v in hdrs.items())
+            lines.append(f"[dim]headers:[/dim] {redacted}")
+        if not _console.is_terminal:
+            payload = {
+                "method": method, "url": url, "auth": self.auth_type,
+                "params": params, "body": body if isinstance(body, (dict, str)) else None,
+                "headers": hdrs,
+            }
+            print(_json.dumps(payload, default=str))
+        else:
+            _console.print(Panel(
+                "\n".join(lines),
+                title="[bold yellow] DRY-RUN — request was NOT sent [/bold yellow]",
+                border_style="yellow",
+                expand=False,
+            ))
+
+    # ------------------------------------------------------------------
+    # Core request
+    # ------------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        idempotent: bool | None = None,
+        allow_status: frozenset[int] | set[int] | tuple[int, ...] = (),
+        **kwargs: Any,
+    ) -> httpx.Response:
+        """Issue an HTTP request with retries, audit, error classification.
+
+        ``idempotent`` controls retry eligibility. By default GET/HEAD/OPTIONS/
+        DELETE are retried; POST/PUT/PATCH are not. Pass ``idempotent=True`` for
+        retry-safe POSTs (e.g. read-shaped /search endpoints).
+
+        ``allow_status`` is an opt-in set of additional status codes that
+        should be treated as success (i.e. returned to the caller instead
+        of raising). Used by :meth:`cached_get_json` to handle 304 Not
+        Modified, which is a valid (and expected) response when an
+        ``If-None-Match`` header is present.
+        """
+        request_id = uuid.uuid4().hex[:12]
+        kwargs.setdefault("headers", {})
+        kwargs["headers"]["X-Request-ID"] = request_id
+
+        if self.auth_type == "jwt":
+            token = get_jwt(self.profile)
+            kwargs["headers"].update(bearer_header(token))
+
+        # Dry-run / explain — render and exit before any network I/O.
+        if DRY_RUN:
+            self._emit_dry_run(method, path, kwargs)
+            raise DryRunExit()
+
+        retry_eligible = idempotent if idempotent is not None else (method.upper() in _IDEMPOTENT_VERBS)
+
+        if self.verbose >= 1:
+            style = _METHOD_STYLE.get(method, "white")
+            params_str = ""
+            if kwargs.get("params"):
+                p = _audit.redact_mapping(dict(kwargs["params"]))
+                params_str = f" {p}"
+            # Redact Authorization header for verbose output too
+            hdrs = kwargs.get("headers", {}) or {}
+            redacted_auth = ""
+            if "Authorization" in hdrs:
+                scheme = hdrs["Authorization"].split(" ", 1)[0] if " " in hdrs["Authorization"] else "***"
+                redacted_auth = f"  [dim](auth: {scheme} ***)[/dim]"
+            _console.print(
+                f"  [bold {style}]{method}[/bold {style}] [dim]{path}{params_str}[/dim]"
+                f"  [dim](req {request_id})[/dim]{redacted_auth}"
+            )
+
+        start = time.monotonic()
+        resp: httpx.Response | None = None
+        last_exc: Exception | None = None
+        attempts_made = 0
+        jwt_refreshed = False  # Track JWT refresh to prevent infinite loops
+
+        with self._spin(method, path):
+            attempt = 0
+            while attempt < self.max_retries:
+                attempts_made = attempt + 1
+                try:
+                    resp = self._http.request(method, path, **kwargs)
+                except httpx.RequestError as exc:
+                    last_exc = exc
+                    resp = None
+                    if retry_eligible and attempt < self.max_retries - 1:
+                        wait = self._backoff(attempt)
+                        if self.verbose >= 1:
+                            _console.print(
+                                f"  [yellow]⚠  Transport error, retrying in "
+                                f"{wait:.1f}s ({attempt + 1}/{self.max_retries - 1})…[/yellow]"
+                            )
+                        time.sleep(wait)
+                        attempt += 1
+                        continue
+                    self._record_http(method, path, None, start, attempts_made, 0, str(exc))
+                    raise _classify_transport(exc, correlation=_audit.CORRELATION_ID,
+                                              request_id=request_id) from exc
+
+                # 401 on JWT — refresh once without consuming the retry budget.
+                # The single refresh is gated by `jwt_refreshed`, so re-running
+                # without bumping `attempt` cannot infinite-loop and still leaves
+                # the full `max_retries` budget available for the retried call.
+                if resp.status_code == 401 and self.auth_type == "jwt" and not jwt_refreshed:
+                    self.profile.token = ""
+                    token = get_jwt(self.profile)
+                    kwargs["headers"].update(bearer_header(token))
+                    jwt_refreshed = True
+                    continue
+
+                if resp.status_code in _RETRY_AFTER_STATUSES and retry_eligible \
+                        and attempt < self.max_retries - 1:
+                    hint = self._parse_retry_after(resp.headers.get("Retry-After", ""))
+                    wait = hint if hint is not None else self._backoff(attempt)
+                    if self.verbose >= 1:
+                        kind = {429: "Rate-limited", 503: "Service unavailable",
+                                408: "Request timeout"}.get(resp.status_code, "Retry")
+                        _console.print(
+                            f"  [yellow]⚠  {kind} ({resp.status_code}) — retrying in "
+                            f"{wait:.1f}s[/yellow]"
+                        )
+                    time.sleep(wait)
+                    attempt += 1
+                    continue
+
+                if resp.status_code in _RETRY_STATUSES and retry_eligible \
+                        and attempt < self.max_retries - 1:
+                    wait = self._backoff(attempt)
+                    if self.verbose >= 1:
+                        _console.print(
+                            f"  [yellow]⚠  Server error {resp.status_code}, retrying in "
+                            f"{wait:.1f}s ({attempt + 1}/{self.max_retries - 1})…[/yellow]"
+                        )
+                    time.sleep(wait)
+                    attempt += 1
+                    continue
+
+                break
+
+        if resp is None:
+            raise NetworkError(
+                0, f"Request failed: {last_exc}",
+                correlation=_audit.CORRELATION_ID, request_id=request_id,
+            )
+
+        elapsed = time.monotonic() - start
+        size = len(resp.content)
+
+        if self.body_limit > 0 and size > self.body_limit:
+            self._record_http(method, path, resp.status_code, start, attempts_made,
+                              size, "body too large")
+            raise BodyTooLargeError(
+                resp.status_code,
+                f"Response body {_fmt_bytes(size)} exceeds cap of "
+                f"{_fmt_bytes(self.body_limit)}",
+                correlation=_audit.CORRELATION_ID, request_id=request_id,
+            )
+
+        if self.verbose >= 2:
+            size_str = _fmt_bytes(size)
+            _console.print(
+                f"  [dim]← {resp.status_code} {resp.reason_phrase}"
+                f"  ({elapsed * 1000:.0f} ms, {size_str})[/dim]"
+            )
+        elif self.verbose >= 1:
+            _console.print(f"  [dim]← {resp.status_code}  ({elapsed * 1000:.0f} ms)[/dim]")
+
+        # Per-call timing breakdown (httpx exposes Response.elapsed; finer
+        # phases require transport hooks which we register by default).
+        timing = {"total": int(elapsed * 1000)}
+        try:
+            ext = getattr(resp, "extensions", {}) or {}
+            for k in ("connect", "tls", "ttfb"):
+                v = ext.get(k)
+                if v is not None:
+                    timing[k] = int(v * 1000) if isinstance(v, float) else int(v)
+        except Exception:
+            pass
+
+        self._record_http(method, path, resp.status_code, start, attempts_made,
+                          size, None, timing)
+
+        if not resp.is_success and resp.status_code not in allow_status:
+            raise _classify(
+                resp.status_code, _extract_error(resp),
+                correlation=_audit.CORRELATION_ID, request_id=request_id,
+            )
+
+        return resp
+
+    def _record_http(
+        self,
+        method: str,
+        path: str,
+        status: int | None,
+        start: float,
+        attempts: int,
+        size: int,
+        error: str | None,
+        timing: dict[str, int] | None = None,
+    ) -> None:
+        if "?" in path:
+            base, _, qs = path.partition("?")
+            redacted_path = f"{base}?{_audit.redact_query_string(qs)}"
+        else:
+            redacted_path = path
+        _audit.log_http(
+            method=method, path=redacted_path, status=status,
+            duration_ms=int((time.monotonic() - start) * 1000),
+            attempts=attempts, response_bytes=size, error=error, timing=timing,
+        )
+
+    # ------------------------------------------------------------------
+    # Typed helpers
+    # ------------------------------------------------------------------
+
+    def get_xml(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        resp = self.request("GET", path, params=_clean(params))
+        return _parse_xml(resp.text)
+
+    def post_xml(
+        self, path: str,
+        params: dict[str, Any] | None = None,
+        data: dict[str, Any] | str | None = None,
+    ) -> dict[str, Any]:
+        if isinstance(data, str):
+            resp = self.request(
+                "POST", path,
+                params=_clean(params),
+                content=data.encode(),
+                headers={"Content-Type": "text/xml"},
+            )
+        else:
+            resp = self.request("POST", path, params=_clean(params), data=_clean(data))
+        return _parse_xml(resp.text)
+
+    def get_json(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        resp = self.request(
+            "GET", path,
+            params=_clean(params),
+            headers={"Accept": "application/json"},
+        )
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        return resp.json()
+
+    def post_json(
+        self, path: str,
+        body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        idempotent: bool = False,
+    ) -> Any:
+        # Some search-shaped POST endpoints are read-only and safe to retry.
+        # Callers can opt in with idempotent=True.
+        resp = self.request(
+            "POST", path,
+            json=body, params=_clean(params),
+            headers={"Accept": "application/json", "Content-Type": "application/json"},
+            idempotent=idempotent or _looks_search_shaped(path),
+        )
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        return resp.json()
+
+    def delete_json(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        resp = self.request(
+            "DELETE", path,
+            params=_clean(params),
+            headers={"Accept": "application/json"},
+        )
+        if resp.status_code == 204:
+            return {}
+        return resp.json()
+
+    def put_json(
+        self, path: str,
+        body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        resp = self.request(
+            "PUT", path,
+            json=body, params=_clean(params),
+            headers={"Accept": "application/json", "Content-Type": "application/json"},
+        )
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        return resp.json()
+
+    def patch_json(
+        self, path: str,
+        body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        resp = self.request(
+            "PATCH", path,
+            json=body, params=_clean(params),
+            headers={"Accept": "application/json", "Content-Type": "application/json"},
+        )
+        if resp.status_code == 204 or not resp.content:
+            return {}
+        return resp.json()
+
+    # ------------------------------------------------------------------
+    # Pagination
+    # ------------------------------------------------------------------
+
+    def paginate_xml(
+        self, path: str, params: dict[str, Any] | None = None,
+        list_key: str = "",
+    ) -> Iterator[dict[str, Any]]:
+        p = dict(params or {})
+        while True:
+            data = self.get_xml(path, p)
+            yield data
+            warning_url = _qualys_next_url(data)
+            if not warning_url:
+                break
+            from urllib.parse import parse_qs, urlparse
+            parsed = urlparse(warning_url)
+            p = {k: v[0] for k, v in parse_qs(parsed.query).items()}
+            path = parsed.path
+
+    def paginate_json(
+        self, path: str, params: dict[str, Any] | None = None,
+        page_param: str = "pageNumber", size_param: str = "pageSize",
+        page_size: int = 100,
+    ) -> Iterator[Any]:
+        """Yield JSON pages until the upstream signals the end.
+
+        Termination logic
+        -----------------
+        We trust the explicit ``hasMore`` / ``hasNextPage`` flag whenever the
+        server provides it. Earlier versions OR-ed it with the size heuristic
+        (``len(items) < page_size``), which prematurely stopped pagination
+        when an API set ``hasMore: True`` but the final page happened to be
+        full. The size heuristic is now only used as a fallback when no
+        ``has_more`` flag is present at all.
+        """
+        p = dict(params or {})
+        p[size_param] = page_size
+        page = 0
+        while True:
+            p[page_param] = page
+            data = self.get_json(path, p)
+            yield data
+            items = _extract_list(data)
+            has_more: bool | None = None
+            if isinstance(data, dict):
+                if "hasMore" in data:
+                    has_more = bool(data["hasMore"])
+                elif "hasNextPage" in data:
+                    has_more = bool(data["hasNextPage"])
+            # Server says no more → stop. Server says yes → keep going,
+            # even if the page is empty (a server-side filter may have culled
+            # the page while later pages still have rows). No flag at all →
+            # fall back to the page-size heuristic, and also stop if the page
+            # has no rows (otherwise we'd loop forever on a truly-empty result).
+            if has_more is False:
+                break
+            if has_more is None and (not items or len(items) < page_size):
+                break
+            page += 1
+
+    def paginate_json_parallel(
+        self, path: str, params: dict[str, Any] | None = None,
+        *, page_count: int, workers: int = 4,
+        page_param: str = "pageNumber", size_param: str = "pageSize",
+        page_size: int = 100,
+    ) -> list[Any]:
+        """Fetch *page_count* known pages with a small thread pool.
+
+        Use when total page count is known up-front (e.g. after one cheap GET
+        that returns ``totalCount``). Output is in deterministic page order.
+        """
+        import concurrent.futures as _f
+
+        def _one(page: int) -> Any:
+            p = dict(params or {})
+            p[size_param] = page_size
+            p[page_param] = page
+            return self.get_json(path, p)
+
+        with _f.ThreadPoolExecutor(max_workers=max(1, min(workers, page_count))) as ex:
+            return list(ex.map(_one, range(page_count)))
+
+    # ------------------------------------------------------------------
+    # ETag-aware GET (catalog-style endpoints)
+    # ------------------------------------------------------------------
+
+    def cached_get_json(
+        self, path: str, params: dict[str, Any] | None = None,
+    ) -> Any:
+        """GET *path* using the local ETag cache when available.
+
+        Sends ``If-None-Match`` / ``If-Modified-Since`` based on what the cache
+        knows; on a 304 we return the cached body (without overwriting the
+        cache — 304 responses have no body), on a 200 we update the cache,
+        and on anything else we degrade to a fresh response without touching
+        the cache so a transient bad-state doesn't poison subsequent calls.
+        """
+        from . import cache as _cache
+
+        clean_params = _clean(params) or {}
+        key = f"GET {self.profile.url}{path}?{_json.dumps(clean_params, sort_keys=True)}"
+        cached = _cache.get(key)
+        headers: dict[str, str] = {"Accept": "application/json"}
+        if cached is not None:
+            body_bytes, etag, modified, ts, _status = cached
+            if etag:
+                headers["If-None-Match"] = etag
+            if modified:
+                headers["If-Modified-Since"] = modified
+            # Soft-TTL fallback when no validators come back from the upstream.
+            if _cache.is_fresh(ts) and not (etag or modified):
+                try:
+                    return _json.loads(body_bytes) if body_bytes else {}
+                except _json.JSONDecodeError:
+                    # Corrupted cache entry — fall through to fresh request
+                    pass
+
+        resp = self.request(
+            "GET", path,
+            params=clean_params, headers=headers,
+            allow_status=frozenset({304}),
+        )
+
+        # 304 Not Modified — the response body is empty by spec; serve the
+        # previously-cached body and DO NOT overwrite the cache (which would
+        # replace good data with empty bytes).
+        if resp.status_code == 304:
+            if cached is not None and cached[0]:
+                try:
+                    return _json.loads(cached[0])
+                except _json.JSONDecodeError:
+                    # Corrupted cache — fall through to re-fetch
+                    pass
+            # Edge case: 304 without a prior cache entry. Re-issue without
+            # validators rather than caching emptiness.
+            resp = self.request(
+                "GET", path, params=clean_params,
+                headers={"Accept": "application/json"},
+            )
+
+        # Only refresh the cache on a clean 200 with a body. Other 2xx codes
+        # (e.g. 202 Accepted) and any non-success response stay out of cache.
+        if resp.status_code == 200 and resp.content:
+            _cache.put(
+                key, resp.content,
+                resp.headers.get("ETag", ""),
+                resp.headers.get("Last-Modified", ""),
+                resp.status_code,
+            )
+        if not resp.content:
+            return {}
+        return resp.json()
+
+
+# ---------------------------------------------------------------------------
+# Factory
+# ---------------------------------------------------------------------------
+
+def make(
+    ctx_obj: dict[str, Any],
+    auth_type: str = "basic",
+    verbose: int = 0,
+    use_gateway: bool = False,
+) -> QualysClient:
+    from .config import get_profile
+    name = ctx_obj.get("profile_name", "default")
+    profile = ctx_obj.get("profile") or get_profile(name)
+    if use_gateway:
+        import dataclasses
+        profile = dataclasses.replace(profile, url=profile.gateway_url)
+    # Locked-mode profiles refuse verbose request logging (SOC2/FIPS-aligned):
+    # -v/-vv would otherwise print request params, status lines, and timing
+    # to the console even though Authorization is redacted.
+    if profile.locked_mode:
+        verbose = 0
+    return QualysClient(profile, auth_type=auth_type, verbose=verbose)
+
+
+# ---------------------------------------------------------------------------
+# Private helpers
+# ---------------------------------------------------------------------------
+
+def _clean(d: dict[str, Any] | None) -> dict[str, Any] | None:
+    if d is None:
+        return None
+    return {k: v for k, v in d.items() if v is not None}
+
+
+_MUTATING_PATH_TOKENS = (
+    "delete", "/import", "/create", "launch", "activate", "deactivate",
+    "cancel", "purge", "reset", "update", "modify", "start", "stop",
+    "/run", "submit", "revoke", "rotate", "enable", "disable",
+)
+
+
+def _looks_search_shaped(path: str) -> bool:
+    """Heuristic: read-only POST search endpoints are safe to retry. We refuse
+    to retry destructive paths even if they look search-shaped.
+
+    This is opt-out, not opt-in — a false negative here just costs one lost
+    retry (caller can still pass ``idempotent=True`` explicitly); a false
+    positive risks silently double-submitting a mutating POST, so the
+    exclusion list below is intentionally broad.
+    """
+    p = path.lower()
+    if "/search/" in p or "/count/" in p or p.endswith("/search"):
+        return not any(tok in p for tok in _MUTATING_PATH_TOKENS)
+    return False
+
+
+def _parse_xml(text: str) -> dict[str, Any]:
+    _fl = (
+        "HOST", "SCAN", "REPORT", "ITEM", "TICKET",
+        "WebApp", "WasScan", "Finding", "WasScanSchedule",
+        "WebAppAuthRecord", "OptionProfile", "Report",
+        "HostAsset", "AssetGroup", "DnsOverride",
+        "Connector", "Rule", "Exception",
+    )
+    parsed: dict[str, Any] = xmltodict.parse(text, force_list=_fl)
+    return parsed
+
+
+def _extract_error(resp: httpx.Response) -> str:
+    ct = resp.headers.get("content-type", "")
+    try:
+        if "xml" in ct:
+            d = xmltodict.parse(resp.text)
+            sr = d.get("SIMPLE_RETURN", {})
+            return (
+                sr.get("RESPONSE", {}).get("TEXT", "")
+                or d.get("ServiceResponse", {})
+                    .get("responseErrorDetails", {})
+                    .get("errorMessage", "")
+                or resp.text[:300]
+            )
+        else:
+            d = resp.json()
+            return (
+                d.get("message")
+                or d.get("error")
+                or d.get("errorMessage")
+                or str(d)[:300]
+            )
+    except Exception:
+        return resp.text[:300]
+
+
+def _qualys_next_url(data: dict[str, Any]) -> str:
+    for v in data.values():
+        if isinstance(v, dict):
+            resp = v.get("RESPONSE", v)
+            warning = resp.get("WARNING", {})
+            if isinstance(warning, dict):
+                url = warning.get("URL", "")
+                if url:
+                    return str(url)
+            deeper = _qualys_next_url(v)
+            if deeper:
+                return deeper
+    return ""
+
+
+def _extract_list(data: Any) -> list[Any]:
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        for key in ("data", "items", "content", "list", "results"):
+            if isinstance(data.get(key), list):
+                items: list[Any] = data[key]
+                return items
+    return []