qualys-cli 0.1.1__py3-none-any.whl

qualys_cli/__init__.py

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

qualys_cli/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m qualys_cli`` and PyInstaller.
+
+This module exists so PyInstaller (and ``python -m``) have a stable target.
+"""
+from qualys_cli.cli import main
+
+if __name__ == "__main__":
+    main()

qualys_cli/audit.py

@@ -0,0 +1,616 @@
+"""
+Append-only JSONL audit log for every CLI invocation and HTTP call.
+
+Design goals
+------------
+- Always-on by default. Operators expect an audit trail for compliance review.
+- Cheap on the hot path: single-process append, line-buffered, ~µs per record.
+- Never logs secrets. Passwords, tokens, Authorization headers, and any
+  param/body field whose key matches the redaction list are replaced with
+  the literal string ``"***REDACTED***"``. JWT tokens are summarised as a
+  ``jwt:<sha256-prefix>`` fingerprint so the same token can be correlated
+  across log lines without exposing it.
+- Tolerant of failures. If the log file can't be opened (read-only filesystem,
+  permissions, etc.) the audit machinery silently degrades to a no-op rather
+  than breaking the user's command.
+- Size-based rotation. When the active file grows past ``ROTATE_AT_BYTES``
+  it is renamed to ``audit.log.1`` (older ``.1`` is dropped) and a fresh
+  file is opened. One generation of history is kept; that is enough for the
+  short-window tail-and-investigate workflow we expect, without unbounded disk
+  growth on long-running CI hosts.
+
+Configuration
+-------------
+``QUALYS_AUDIT_LOG`` env var:
+  - unset / empty / ``default``  → ``~/.config/qualys-cli/audit.log``
+  - ``off`` / ``none`` / ``disabled``  → audit is disabled
+  - ``-`` or ``stderr``          → write to stderr (one JSON object per line)
+  - any other value              → treated as a path
+
+``QUALYS_AUDIT_MAX_BYTES`` env var (optional):
+  Override the rotation threshold (default 10 MB).
+
+Record shape
+------------
+Each record is a single-line JSON object with these keys (some are optional):
+
+    ts            ISO-8601 UTC timestamp with millisecond precision
+    event         one of "command", "http", "error"
+    correlation   per-invocation correlation ID (also sent as request header)
+    profile       active credential profile name
+    user          Qualys username for the active profile (no password)
+    pid           OS pid of the CLI process (helps de-interleave concurrent runs)
+    version       qualys-cli version string
+
+Per ``event``:
+
+  command:
+    argv          full command line with secret arguments redacted
+    duration_ms   wall time of the entire invocation (only on the closing record)
+    exit_code     process exit code (only on the closing record)
+    phase         "start" or "end"
+
+  http:
+    method        HTTP method
+    path          path (no host); query string preserved with secrets redacted
+    status        response status code (omitted on transport failure)
+    duration_ms   wall time of the call including any retries
+    attempts      number of attempts made (1 = success first try)
+    bytes         size of the response body in bytes
+    error         transport-level error message (omitted on success)
+
+  error:
+    type          short error class name
+    message       redacted error message
+    status        HTTP status if applicable
+"""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import sys
+import threading
+import time
+import uuid
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, TextIO
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_DEFAULT_PATH = Path.home() / ".config" / "qualys-cli" / "audit.log"
+_DEFAULT_ROTATE_AT_BYTES = 10 * 1024 * 1024  # 10 MB
+_OFF_SENTINELS = {"off", "none", "false", "0", "disabled", "no"}
+_HMAC_KEY_PATH = Path.home() / ".config" / "qualys-cli" / ".audit-hmac-key"
+
+# Keys whose values must be redacted before the record is written. Match is
+# case-insensitive on the bare key name.
+_SECRET_KEYS = {
+    "password", "token", "secret", "secret_id", "api_token", "api_key",
+    "apikey", "client_secret", "private_key", "credential", "credentials",
+    "auth", "authorization", "x-api-key", "passwd", "access_token",
+    "refresh_token", "bearer", "session_token", "session_id", "cookie",
+    "x-auth-token", "x-access-token", "jwt", "api_secret", "secret_key",
+    "signing_key", "encryption_key", "ssh_key", "passphrase",
+}
+
+_REDACTED = "***REDACTED***"
+
+# ---------------------------------------------------------------------------
+# Public mutable state — set by the CLI on startup
+# ---------------------------------------------------------------------------
+
+CORRELATION_ID: str = ""
+"""Per-invocation correlation ID. Same value is sent as `X-Correlation-ID`
+header and recorded against every audit line for the run. Set by cli.main()."""
+
+PROFILE_NAME: str = ""
+USERNAME: str = ""
+
+# ---------------------------------------------------------------------------
+# Internal: lazy file handle
+# ---------------------------------------------------------------------------
+
+_lock = threading.Lock()
+_handle: TextIO | None = None
+_handle_path: Path | None = None
+_handle_is_stderr = False
+_disabled = False
+_init_done = False
+_prev_hmac: str = ""        # tamper-evident chain — sha of last line's signature
+_hmac_key: bytes | None = None
+_fsync_each_line = False
+
+
+def _resolve_target() -> tuple[Path | None, bool, bool]:
+    """Return (path, is_stderr, disabled) based on QUALYS_AUDIT_LOG."""
+    raw = os.environ.get("QUALYS_AUDIT_LOG", "").strip()
+    if not raw or raw.lower() == "default":
+        return _DEFAULT_PATH, False, False
+    low = raw.lower()
+    if low in _OFF_SENTINELS:
+        return None, False, True
+    if raw == "-" or low == "stderr":
+        return None, True, False
+    return Path(raw).expanduser(), False, False
+
+
+def _rotate_at_bytes() -> int:
+    raw = os.environ.get("QUALYS_AUDIT_MAX_BYTES", "").strip()
+    if raw.isdigit():
+        n = int(raw)
+        if n > 0:
+            return n
+    return _DEFAULT_ROTATE_AT_BYTES
+
+
+def _load_hmac_key() -> bytes | None:
+    """Load (or create) the per-host HMAC key used for tamper-evident chaining.
+
+    The key lives at ``~/.config/qualys-cli/.audit-hmac-key`` (mode 0600).
+    Failures degrade gracefully: chaining becomes a no-op rather than crashing.
+    """
+    try:
+        if _HMAC_KEY_PATH.exists():
+            return _HMAC_KEY_PATH.read_bytes()
+        _HMAC_KEY_PATH.parent.mkdir(parents=True, exist_ok=True)
+        key = secrets.token_bytes(32)
+        _HMAC_KEY_PATH.write_bytes(key)
+        with contextlib.suppress(Exception):
+            _HMAC_KEY_PATH.chmod(0o600)
+        return key
+    except Exception:
+        return None
+
+
+def _current_handle() -> TextIO | None:
+    """Return the already-initialised handle (or stderr) — no I/O, no init."""
+    if _disabled:
+        return None
+    if _handle_is_stderr:
+        return sys.stderr
+    return _handle
+
+
+def _ensure_handle() -> TextIO | None:
+    """Open the log file once per process. Returns the open handle, or None
+    if audit is disabled or the file cannot be opened.
+
+    Thread-safety: the entire init must run under `_lock` — two threads racing
+    here previously could both pass the `_init_done` check, both open `_handle`
+    in append mode (leaking the loser's fd), and both read `_prev_hmac` as the
+    empty seed, producing two records with the same `prev` and breaking the
+    HMAC chain that `verify_chain` walks.
+    """
+    global _handle, _handle_path, _handle_is_stderr, _disabled, _init_done
+    global _hmac_key, _fsync_each_line
+
+    # Fast path: already initialised. Reads of plain assignments under CPython's
+    # GIL are atomic, so checking `_init_done` without the lock is safe; the
+    # lock only protects the one-shot init below.
+    if _init_done:
+        return _current_handle()
+
+    with _lock:
+        if _init_done:
+            return _current_handle()
+
+        _fsync_each_line = os.environ.get("QUALYS_AUDIT_FSYNC", "").strip().lower() in {
+            "1", "true", "yes", "on",
+        }
+        if os.environ.get("QUALYS_AUDIT_HMAC", "1").strip().lower() not in {
+            "0", "false", "no", "off", "disabled",
+        }:
+            _hmac_key = _load_hmac_key()
+
+        target, is_stderr, disabled = _resolve_target()
+        if disabled:
+            _disabled = True
+        elif is_stderr:
+            _handle_is_stderr = True
+        else:
+            assert target is not None
+            try:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                # Append, line-buffered. Best-effort tighten perms; not fatal.
+                _handle = target.open("a", buffering=1, encoding="utf-8")
+                _handle_path = target
+                with contextlib.suppress(Exception):
+                    target.chmod(0o600)
+            except Exception:
+                # If we can't write, silently disable rather than break the CLI.
+                _disabled = True
+                _handle = None
+                _handle_path = None
+
+        # Publish init flag last so any concurrent reader that observes
+        # `_init_done == True` also observes a consistent `_handle` /
+        # `_handle_is_stderr` / `_disabled` triple.
+        _init_done = True
+        return _current_handle()
+
+
+def _maybe_rotate() -> None:
+    """Rotate the active file if it has grown past the threshold.
+
+    Only applies to file-backed handles. Single generation of history kept
+    (``audit.log`` → ``audit.log.1``).
+    """
+    if _handle is None or _handle_path is None or _handle_is_stderr:
+        return
+    threshold = _rotate_at_bytes()
+    try:
+        size = _handle_path.stat().st_size
+    except OSError:
+        return
+    if size < threshold:
+        return
+    backup = _handle_path.with_name(_handle_path.name + ".1")
+    try:
+        if _handle is not None:
+            _handle.flush()
+            _handle.close()
+        if backup.exists():
+            backup.unlink()
+        _handle_path.rename(backup)
+    except OSError:
+        # If rotation fails we just leave the existing file growing — better
+        # than silently dropping audit lines.
+        pass
+    try:
+        new_handle = _handle_path.open("a", buffering=1, encoding="utf-8")
+        with contextlib.suppress(Exception):
+            _handle_path.chmod(0o600)
+        globals()["_handle"] = new_handle
+    except OSError:
+        # Couldn't reopen — disable audit for the remainder of the run.
+        globals()["_handle"] = None
+        globals()["_disabled"] = True
+
+
+# ---------------------------------------------------------------------------
+# Redaction helpers
+# ---------------------------------------------------------------------------
+
+def _is_secret_key(name: str) -> bool:
+    return name.lower() in _SECRET_KEYS
+
+
+def _redact_value(_v: Any) -> str:
+    return _REDACTED
+
+
+def fingerprint_token(token: str) -> str:
+    """Return a stable short fingerprint of a JWT/API token without leaking it.
+
+    Useful for correlating which token was used across log lines without
+    exposing the raw value.
+    """
+    if not token:
+        return ""
+    h = hashlib.sha256(token.encode("utf-8", "ignore")).hexdigest()
+    return f"jwt:{h[:12]}"
+
+
+def redact_mapping(d: Any) -> Any:
+    """Return a deep copy of *d* with secret values replaced.
+
+    Works for dicts (recursing into nested dicts/lists), lists, and scalars.
+    Non-mapping inputs are returned unchanged.
+    """
+    if isinstance(d, dict):
+        out: dict[str, Any] = {}
+        for k, v in d.items():
+            if isinstance(k, str) and _is_secret_key(k):
+                out[k] = _REDACTED
+            else:
+                out[k] = redact_mapping(v)
+        return out
+    if isinstance(d, list):
+        return [redact_mapping(x) for x in d]
+    return d
+
+
+def redact_query_string(qs: str) -> str:
+    """Redact secret values in a URL query string (key=value&...)."""
+    if not qs or "=" not in qs:
+        return qs
+    parts: list[str] = []
+    for chunk in qs.split("&"):
+        if "=" not in chunk:
+            parts.append(chunk)
+            continue
+        k, _, v = chunk.partition("=")
+        if _is_secret_key(k) and v:
+            parts.append(f"{k}={_REDACTED}")
+        else:
+            parts.append(chunk)
+    return "&".join(parts)
+
+
+def redact_argv(argv: list[str]) -> list[str]:
+    """Redact secret-bearing flag values in an argv list.
+
+    Recognises both ``--flag value`` and ``--flag=value`` forms. The flag
+    *name* itself is not redacted (so reviewers can still see which option
+    was used); only the value is replaced.
+    """
+    out: list[str] = []
+    i = 0
+    while i < len(argv):
+        tok = argv[i]
+        if tok.startswith("--") and "=" in tok:
+            name, _, _val = tok.partition("=")
+            bare = name.lstrip("-").replace("-", "_")
+            if _is_secret_key(bare):
+                out.append(f"{name}={_REDACTED}")
+            else:
+                out.append(tok)
+            i += 1
+            continue
+        if tok.startswith("--"):
+            bare = tok.lstrip("-").replace("-", "_")
+            if _is_secret_key(bare) and i + 1 < len(argv):
+                out.append(tok)
+                out.append(_REDACTED)
+                i += 2
+                continue
+        out.append(tok)
+        i += 1
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Write helpers
+# ---------------------------------------------------------------------------
+
+def _now_iso() -> str:
+    # Millisecond precision keeps lines short while staying ordered.
+    now = datetime.now(UTC)
+    return now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"
+
+
+def _emit(record: dict[str, Any]) -> None:
+    """Serialise and write a single record. Swallows all I/O errors.
+
+    When HMAC chaining is enabled the record gains a ``sig`` field that depends
+    on the previous line's signature, so any tampering or truncation is
+    detectable by :func:`verify_chain`.
+
+    Concurrency note
+    ----------------
+    The handle is resolved *inside* :data:`_lock` so a concurrent rotation
+    from another thread cannot leave us writing to a closed file. The HMAC
+    chain mutation of ``_prev_hmac`` also happens under the lock — without
+    this both writers would compute their signature against the same prior
+    state, breaking the chain on the second write.
+    """
+    global _prev_hmac
+
+    # Cheap pre-flight outside the lock — avoids paying the lock overhead
+    # for every call when audit is disabled.
+    if _disabled:
+        return
+    if _ensure_handle() is None:
+        return
+
+    try:
+        with _lock:
+            # Re-resolve under the lock — if another thread rotated us, the
+            # module-level _handle now points at the new file; the previously
+            # cached `handle` may be closed.
+            handle = sys.stderr if _handle_is_stderr else _handle
+            if _disabled or handle is None:
+                return
+
+            if _hmac_key is not None:
+                try:
+                    base = json.dumps(
+                        record, default=str, separators=(",", ":"), sort_keys=True,
+                    )
+                    mac = hmac.new(
+                        _hmac_key,
+                        (_prev_hmac + base).encode("utf-8", "ignore"),
+                        hashlib.sha256,
+                    ).hexdigest()[:32]
+                    record = {**record, "sig": mac}
+                    _prev_hmac = mac
+                except Exception:
+                    pass
+
+            try:
+                line = json.dumps(record, default=str, separators=(",", ":"))
+            except (TypeError, ValueError):
+                line = json.dumps(
+                    {"ts": record.get("ts"), "event": "audit_serialize_error"},
+                )
+
+            handle.write(line)
+            handle.write("\n")
+            if _fsync_each_line and not _handle_is_stderr:
+                with contextlib.suppress(Exception):
+                    handle.flush()
+                    if hasattr(handle, "fileno"):
+                        os.fsync(handle.fileno())
+            _maybe_rotate()
+    except Exception:
+        pass
+
+
+def verify_chain(path: str | Path) -> tuple[int, int, list[int]]:
+    """Verify the HMAC chain of an audit log. Returns ``(ok, total, broken)``.
+
+    *ok* is the count of records whose signature matches the chain; *total* is
+    the total number of records read; *broken* is a list of 0-indexed record
+    positions where the chain breaks. A chain is intact iff ``broken == []``.
+
+    Records without a ``sig`` field are skipped (they predate HMAC chaining
+    or were written with the chain disabled).
+    """
+    p = Path(path)
+    if not p.exists():
+        return (0, 0, [])
+    key = _load_hmac_key()
+    if key is None:
+        return (0, 0, [])
+    ok = 0
+    total = 0
+    broken: list[int] = []
+    prev = ""
+    for i, raw in enumerate(p.read_text().splitlines()):
+        if not raw.strip():
+            continue
+        total += 1
+        try:
+            rec = json.loads(raw)
+        except json.JSONDecodeError:
+            broken.append(i)
+            continue
+        sig = rec.pop("sig", None)
+        if sig is None:
+            # Pre-chain line — accept silently
+            continue
+        base = json.dumps(rec, default=str, separators=(",", ":"), sort_keys=True)
+        expected = hmac.new(
+            key, (prev + base).encode("utf-8", "ignore"), hashlib.sha256,
+        ).hexdigest()[:32]
+        if hmac.compare_digest(expected, sig):
+            ok += 1
+            prev = sig
+        else:
+            broken.append(i)
+            prev = sig  # advance anyway to detect a single edit, not a cascade
+    return (ok, total, broken)
+
+
+def _base_record(event: str) -> dict[str, Any]:
+    rec: dict[str, Any] = {
+        "ts": _now_iso(),
+        "event": event,
+        "pid": os.getpid(),
+    }
+    if CORRELATION_ID:
+        rec["correlation"] = CORRELATION_ID
+    if PROFILE_NAME:
+        rec["profile"] = PROFILE_NAME
+    if USERNAME:
+        rec["user"] = USERNAME
+    return rec
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def new_correlation_id() -> str:
+    """Generate a fresh correlation ID (hex, 16 chars). Cheap and unique enough
+    for human-readable cross-referencing."""
+    return uuid.uuid4().hex[:16]
+
+
+def init(profile: str = "", username: str = "") -> str:
+    """Initialise the audit subsystem for the current invocation.
+
+    Sets the module-level correlation ID, profile name, and username, and
+    returns the correlation ID. Safe to call multiple times — only the
+    first call sets the correlation ID.
+    """
+    global CORRELATION_ID, PROFILE_NAME, USERNAME
+    if not CORRELATION_ID:
+        CORRELATION_ID = new_correlation_id()
+    if profile:
+        PROFILE_NAME = profile
+    if username:
+        USERNAME = username
+    return CORRELATION_ID
+
+
+def reset_for_tests() -> None:
+    """Tear down audit state. Tests use this to ensure a clean per-test slate."""
+    global CORRELATION_ID, PROFILE_NAME, USERNAME, _handle, _handle_path
+    global _handle_is_stderr, _disabled, _init_done, _prev_hmac, _hmac_key
+    global _fsync_each_line
+    with _lock:
+        if _handle is not None and not _handle_is_stderr:
+            with contextlib.suppress(Exception):
+                _handle.close()
+        CORRELATION_ID = ""
+        PROFILE_NAME = ""
+        USERNAME = ""
+        _handle = None
+        _handle_path = None
+        _handle_is_stderr = False
+        _disabled = False
+        _init_done = False
+        _prev_hmac = ""
+        _hmac_key = None
+        _fsync_each_line = False
+
+
+def log_command_start(argv: list[str], version: str) -> float:
+    """Record the start of a CLI invocation. Returns the start time so the
+    caller can pass it back to :func:`log_command_end` for accurate duration.
+    """
+    rec = _base_record("command")
+    rec["phase"] = "start"
+    rec["argv"] = redact_argv(argv)
+    rec["version"] = version
+    _emit(rec)
+    return time.monotonic()
+
+
+def log_command_end(start: float, exit_code: int, version: str) -> None:
+    rec = _base_record("command")
+    rec["phase"] = "end"
+    rec["duration_ms"] = int((time.monotonic() - start) * 1000)
+    rec["exit_code"] = int(exit_code)
+    rec["version"] = version
+    _emit(rec)
+
+
+def log_http(
+    method: str,
+    path: str,
+    status: int | None,
+    duration_ms: int,
+    attempts: int,
+    response_bytes: int,
+    error: str | None = None,
+    timing: dict[str, int] | None = None,
+) -> None:
+    """Record one HTTP call. ``path`` should already have its query string
+    redacted (use :func:`redact_query_string`).
+
+    ``timing`` (optional) is a dict of fine-grained phase durations
+    (e.g. ``{"connect": 12, "tls": 87, "ttfb": 220}``) merged into the record
+    as a nested object so SIEM tooling can analyse latency components.
+    """
+    rec = _base_record("http")
+    rec["method"] = method
+    rec["path"] = path
+    if status is not None:
+        rec["status"] = int(status)
+    rec["duration_ms"] = int(duration_ms)
+    rec["attempts"] = int(attempts)
+    rec["bytes"] = int(response_bytes)
+    if error:
+        rec["error"] = error[:500]
+    if timing:
+        rec["timing"] = timing
+    _emit(rec)
+
+
+def log_error(error_type: str, message: str, status: int | None = None) -> None:
+    rec = _base_record("error")
+    rec["type"] = error_type
+    rec["message"] = message[:500]
+    if status is not None:
+        rec["status"] = int(status)
+    _emit(rec)