qualys-cli 0.1.7__tar.gz → 0.1.8__tar.gz

{qualys_cli-0.1.7 → qualys_cli-0.1.8}/CHANGELOG.md

@@ -6,6 +6,24 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.1.8] — 2026-07-21
+
+### Added
+- Every API request now carries client-identification headers so server-side
+  operators can attribute traffic to the CLI and count calls per install/user:
+  a descriptive `User-Agent` (`qualys-cli/<version> (python/<ver>; <os> <arch>)`
+  in place of the opaque `python-httpx/*` default), plus `X-Client-Id`,
+  `X-Client-Version`, `X-Install-Id`, and `X-User-Id`.
+- `X-Install-Id` is a stable, opaque per-installation UUID persisted to
+  `~/.config/qualys-cli/install_id` (mode `0600`); it encodes no username,
+  hostname, or other host information. Resolution is best-effort — a read-only
+  or unwritable home degrades to an ephemeral id and never fails a request.
+- The two identifying headers (`X-Install-Id`, `X-User-Id`) can be suppressed
+  with `QUALYS_NO_TELEMETRY_HEADERS=1`; the non-identifying `User-Agent` /
+  `X-Client-*` headers are always sent. The `X-User-Id` value is sanitised
+  (control characters and non-latin-1 bytes stripped) so an unusual username
+  can neither break client construction nor enable header injection.
+
 ## [0.1.7] — 2026-07-17
 
 ### Fixed

{qualys_cli-0.1.7 → qualys_cli-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qualys-cli
-Version: 0.1.7
+Version: 0.1.8
 Summary: Unified command-line interface for the Qualys Cloud Platform REST APIs (VM, PC, PM, ETM, WAS, TotalCloud, Cloud Agent, Container Security, CSAM, Subscription, Asset, and User management).
 Project-URL: Homepage, https://www.qualys.com
 Author-email: Qualys <support@qualys.com>

{qualys_cli-0.1.7 → qualys_cli-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qualys-cli"
-version = "0.1.7"
+version = "0.1.8"
 description = "Unified command-line interface for the Qualys Cloud Platform REST APIs (VM, PC, PM, ETM, WAS, TotalCloud, Cloud Agent, Container Security, CSAM, Subscription, Asset, and User management)."
 readme = { file = "README.md", content-type = "text/markdown" }
 license = { file = "LICENSE" }

qualys_cli-0.1.8/src/qualys_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.8"

{qualys_cli-0.1.7 → qualys_cli-0.1.8}/src/qualys_cli/_docs/usage.html

@@ -612,7 +612,7 @@ body.filtering.no-match section.module{display:none}
 <aside class="sidebar" aria-label="Documentation navigation">
   <div class="side-header">
     <img src="https://ik.imagekit.io/qualys/image/logo/qualys.svg" alt="Qualys">
-    <span class="ver">v0.1.7</span>
+    <span class="ver">v0.1.8</span>
   </div>
   <div class="side-search">
     <input type="search" id="filter" placeholder="Search commands…"
@@ -696,7 +696,7 @@ body.filtering.no-match section.module{display:none}
     <div class="hero-stats">
       <div class="hero-stat"><span class="n">28</span><span class="l">Modules</span></div>
       <div class="hero-stat"><span class="n">228</span><span class="l">Commands</span></div>
-      <div class="hero-stat"><span class="n">v0.1.7</span><span class="l">Version</span></div>
+      <div class="hero-stat"><span class="n">v0.1.8</span><span class="l">Version</span></div>
       <div class="hero-stat"><span class="n">3.12+</span><span class="l">Python</span></div>
       <div class="hero-stat"><span class="n">MIT</span><span class="l">License</span></div>
     </div>

{qualys_cli-0.1.7 → qualys_cli-0.1.8}/src/qualys_cli/cli.py

@@ -13,6 +13,7 @@ from rich.rule import Rule
 from rich.table import Table
 from rich.text import Text
 
+from . import __version__ as _VERSION
 from . import audit as _audit
 from . import config as _cfg
 from . import extras as _extras
@@ -57,7 +58,7 @@ def _print_banner() -> None:
         from importlib.metadata import version
         ver = version("qualys-cli")
     except Exception:
-        ver = "0.1.0"
+        ver = _VERSION
 
     _err.print()
     _err.print(Align.center(Text(_WORDMARK, style=f"bold {_QUALYS_RED}")))
@@ -198,7 +199,7 @@ def _version_callback(value: bool) -> None:
             from importlib.metadata import version
             ver = version("qualys-cli")
         except Exception:
-            ver = "0.1.0"
+            ver = _VERSION
         _err.print(f"[bold]qualys-cli[/bold] [cyan]{ver}[/cyan]")
         raise typer.Exit()
 

{qualys_cli-0.1.7 → qualys_cli-0.1.8}/src/qualys_cli/client.py

@@ -32,6 +32,7 @@ from __future__ import annotations
 
 import json as _json
 import os
+import platform as _platform
 import random
 import threading
 import time
@@ -45,6 +46,7 @@ import httpx
 import xmltodict
 from rich.console import Console
 
+from . import __version__ as _VERSION
 from . import audit as _audit
 from . import flair as _flair
 from .auth import basic_auth, bearer_header, get_jwt
@@ -52,11 +54,72 @@ from .config import Profile
 
 _console = Console(stderr=True)
 
+# A descriptive User-Agent lets the server attribute traffic to the CLI (tool,
+# version, platform) instead of the opaque default ``python-httpx/x.y.z``.
+_USER_AGENT = (
+    f"qualys-cli/{_VERSION} "
+    f"(python/{_platform.python_version()}; "
+    f"{_platform.system() or 'unknown'} {_platform.machine() or 'unknown'})"
+)
+
+# Static identity headers sent on every request. The per-installation
+# ``X-Install-Id`` and per-user ``X-User-Id`` headers are added dynamically in
+# ``QualysClient.__init__`` (they depend on config / the active profile).
 _BASE_HEADERS = {
     "X-Requested-With": "qualys-cli",
     "Accept-Encoding": "br, gzip, zstd",
+    "User-Agent": _USER_AGENT,
+    "X-Client-Id": "qualys-cli",
+    "X-Client-Version": _VERSION,
 }
 
+
+def _telemetry_headers_enabled() -> bool:
+    """Whether the *identifying* headers (X-Install-Id / X-User-Id) are sent.
+
+    Enabled by default. Set ``QUALYS_NO_TELEMETRY_HEADERS=1`` to suppress the
+    two headers that identify the installation and user; the non-identifying
+    User-Agent / X-Client-* headers are always sent.
+    """
+    return os.environ.get("QUALYS_NO_TELEMETRY_HEADERS", "").strip().lower() \
+        not in {"1", "true", "yes", "on"}
+
+
+def _identity_headers(profile: Profile) -> dict[str, str]:
+    """Build the per-installation / per-user identity headers for *profile*.
+
+    Returns an empty dict when the user has opted out via
+    ``QUALYS_NO_TELEMETRY_HEADERS``. Fully best-effort: any failure resolving
+    the install id degrades to omitting that header rather than raising.
+    """
+    if not _telemetry_headers_enabled():
+        return {}
+    from .config import get_install_id
+
+    headers: dict[str, str] = {}
+    try:
+        install_id = get_install_id()
+        if install_id:
+            headers["X-Install-Id"] = install_id
+    except Exception:
+        pass
+    user = _header_safe(profile.username)
+    if user:
+        headers["X-User-Id"] = user
+    return headers
+
+
+def _header_safe(v: str) -> str:
+    """Coerce *v* into a value safe to use as an HTTP header.
+
+    Header values must be latin-1 encodable and must not contain CR/LF (which
+    would allow header injection). Strips control characters and drops any
+    byte that cannot be latin-1 encoded, so an unusual username can never make
+    ``httpx`` raise while constructing the client.
+    """
+    cleaned = "".join(ch for ch in v if ch >= " " and ch != "\x7f")
+    return cleaned.encode("latin-1", "ignore").decode("latin-1")
+
 _METHOD_STYLE: dict[str, str] = {
     "GET": "cyan", "POST": "yellow", "PUT": "blue",
     "DELETE": "red", "PATCH": "magenta",
@@ -283,6 +346,7 @@ class QualysClient:
             headers={
                 **_BASE_HEADERS,
                 "X-Correlation-ID": _audit.CORRELATION_ID or "uninitialized",
+                **_identity_headers(profile),
             },
             timeout=httpx.Timeout(read_t, connect=connect_t),
             limits=httpx.Limits(

{qualys_cli-0.1.7 → qualys_cli-0.1.8}/src/qualys_cli/config.py

@@ -20,6 +20,7 @@ from __future__ import annotations
 import contextlib
 import os
 import tomllib
+import uuid
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
@@ -32,6 +33,7 @@ except Exception:
 
 CONFIG_DIR = Path.home() / ".config" / "qualys-cli"
 _CONFIG_FILE = CONFIG_DIR / "config.toml"
+_INSTALL_ID_FILE = CONFIG_DIR / "install_id"
 QUERIES_DIR = CONFIG_DIR / "queries"
 CACHE_DIR = CONFIG_DIR / "cache"
 HISTORY_DIR = CONFIG_DIR / "history"
@@ -193,6 +195,42 @@ def validate_profile_dict(name: str, body: dict[str, Any]) -> list[str]:
 # Public API
 # ---------------------------------------------------------------------------
 
+def get_install_id() -> str:
+    """Return a stable, opaque per-installation identifier.
+
+    Generated once and persisted to ``~/.config/qualys-cli/install_id`` so the
+    server can attribute CLI traffic to a single installation across
+    invocations. It is a random UUID hex — it encodes no username, hostname,
+    or other host-identifying information.
+
+    Stored in its own file rather than ``config.toml`` because
+    :func:`_save_file` only serializes the ``profiles`` table; a top-level key
+    would be dropped on the next profile save.
+
+    Best-effort: if the file cannot be read or written (read-only home,
+    permission error, …) a fresh ephemeral id is returned instead of raising,
+    so header construction never breaks a request.
+    """
+    with contextlib.suppress(OSError):
+        if _INSTALL_ID_FILE.exists():
+            existing = _INSTALL_ID_FILE.read_text(encoding="utf-8").strip()
+            if existing:
+                return existing
+
+    new_id = uuid.uuid4().hex
+    with contextlib.suppress(OSError):
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        fd = os.open(_INSTALL_ID_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        try:
+            with os.fdopen(fd, "w") as fh:
+                fh.write(new_id)
+        except BaseException:
+            with contextlib.suppress(OSError):
+                os.close(fd)
+            raise
+    return new_id
+
+
 def get_profile(name: str = "default") -> Profile:
     """Load a profile, auto-detecting platform URLs from the username.
 

qualys_cli-0.1.7/src/qualys_cli/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.7"