apisec-code-bolt 0.1.0__py3-none-any.whl

apisec_code_bolt/core/telemetry.py

@@ -0,0 +1,451 @@
+"""
+Opt-in anonymous telemetry for the surface CLI.
+
+DESIGN:
+- Fully opt-in: disabled by default, enabled with `surface telemetry on`
+- Consent stored in ~/.config/apisec/telemetry.txt
+- Payload scrubbed of PII before transmission
+- Silently swallows all errors (telemetry must never break the CLI)
+- Fire-and-forget: does not block on network I/O
+
+PII GUARD:
+- Only allowlisted keys are included in the payload
+- String values are checked for forbidden patterns (paths, @, credentials, etc.)
+- Any violation raises TelemetryPIIError and the whole send is aborted
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# =============================================================================
+# Constants
+# =============================================================================
+
+_CONSENT_FILE = Path.home() / ".config" / "apisec" / "telemetry.txt"
+_INSTALLATION_ID_FILE = Path.home() / ".config" / "apisec" / "installation_id"
+_REGISTRATION_CODE_FILE = Path.home() / ".config" / "apisec" / "registration_code"
+
+_ALLOWED_KEYS: frozenset[str] = frozenset(
+    {
+        "event",
+        "probe_version",
+        "python_version",
+        "platform",
+        "files_analyzed",
+        "files_failed",
+        "files_skipped",
+        "frameworks",
+        "languages",
+        "routes_found",
+        "routes_by_framework",
+        "analysis_time_ms",
+        "parse_time_ms",
+        "extraction_time_ms",
+        "stage_times_ms",
+        "extractor_times_ms",
+        "framework_count",
+        "has_errors",
+        "error_type",
+        "installation_id",
+        "registration_code",
+    }
+)
+
+# Patterns that indicate PII in a string value
+_FORBIDDEN_VALUE_PATTERNS: tuple[str, ...] = (
+    "/",  # File paths
+    "@",  # Email addresses
+    "://",  # URLs
+    "password",
+    "secret",
+    "token",
+    "key",
+    "private",
+    "credential",
+)
+
+
+# =============================================================================
+# PII Guard
+# =============================================================================
+
+
+class TelemetryPIIError(ValueError):
+    """Raised when a payload value fails the PII check."""
+
+    pass
+
+
+def _scrub_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    """
+    Strip non-allowlisted keys and check string values for forbidden patterns.
+
+    Raises TelemetryPIIError if a string value contains a forbidden pattern.
+    Returns the scrubbed payload dict.
+    """
+    scrubbed: dict[str, Any] = {}
+
+    for key, value in payload.items():
+        # Only include allowlisted keys
+        if key not in _ALLOWED_KEYS:
+            continue
+
+        if isinstance(value, str):
+            value_lower = value.lower()
+            for pattern in _FORBIDDEN_VALUE_PATTERNS:
+                if pattern in value_lower:
+                    raise TelemetryPIIError(
+                        f"Payload key {key!r} contains forbidden pattern {pattern!r}"
+                    )
+            scrubbed[key] = value
+
+        elif isinstance(value, (int, float, bool)):
+            scrubbed[key] = value
+
+        elif isinstance(value, list):
+            # Filter list items that would fail the string check
+            clean_list = []
+            for item in value:
+                if isinstance(item, str):
+                    item_lower = item.lower()
+                    if any(p in item_lower for p in _FORBIDDEN_VALUE_PATTERNS):
+                        continue  # Drop the item, don't fail the whole payload
+                    clean_list.append(item)
+                elif isinstance(item, (int, float, bool)):
+                    clean_list.append(item)
+            scrubbed[key] = clean_list
+
+        elif isinstance(value, dict):
+            # Dicts of {str: int} are safe (timing maps, route counts).
+            # Only allow int values — drop any string values that could be PII.
+            clean_dict = {
+                k: v
+                for k, v in value.items()
+                if isinstance(k, str) and isinstance(v, (int, float, bool))
+            }
+            scrubbed[key] = clean_dict
+
+        # None and other types are silently dropped
+
+    return scrubbed
+
+
+def _safe_payload(**kwargs: Any) -> dict[str, Any] | None:
+    """Build a clean payload dict, returning None if scrubbing raises."""
+    try:
+        return _scrub_payload(kwargs)
+    except TelemetryPIIError as exc:
+        logger.debug("Telemetry PII check failed: %s", exc)
+        return None
+
+
+# =============================================================================
+# Consent Management
+# =============================================================================
+
+
+def is_telemetry_enabled() -> bool:
+    """Return True unless the user has explicitly opted out."""
+    try:
+        if not _CONSENT_FILE.exists():
+            return True  # opt-out model: enabled until the user says otherwise
+        content = _CONSENT_FILE.read_text(encoding="utf-8").strip().lower()
+        return content != "disabled"
+    except Exception:
+        return True
+
+
+def set_telemetry_consent(enabled: bool) -> None:
+    """Write consent status to the consent file."""
+    try:
+        _CONSENT_FILE.parent.mkdir(parents=True, exist_ok=True)
+        _CONSENT_FILE.write_text(
+            "enabled" if enabled else "disabled",
+            encoding="utf-8",
+        )
+    except Exception as exc:
+        logger.debug("Could not write telemetry consent: %s", exc)
+
+
+_NOTICE = (
+    "ℹ  apisec-code-bolt collects anonymous usage data (framework names, "
+    "file counts, timing) to improve the scanner. No source code or paths "
+    "are ever sent. Run `surface telemetry off` to opt out."
+)
+
+
+def check_first_run_notice(quiet: bool = False, json_mode: bool = False) -> bool:
+    """
+    On the very first run (no consent file), show the opt-out notice and
+    write the consent file so the notice is only shown once.
+
+    Returns True if this was the first run.
+    """
+    if _CONSENT_FILE.exists():
+        return False
+    try:
+        set_telemetry_consent(True)
+        if not quiet and not json_mode:
+            print(_NOTICE, flush=True)
+        elif json_mode:
+            # Emit as a structured record so pipelines can surface it
+            import json as _json
+            import sys
+
+            sys.stderr.write(
+                _json.dumps({"level": "info", "event": "telemetry_notice", "message": _NOTICE})
+                + "\n"
+            )
+            sys.stderr.flush()
+    except Exception:
+        pass
+    return True
+
+
+def get_telemetry_status() -> str:
+    """Return 'enabled', 'disabled', or 'not_set'."""
+    try:
+        if not _CONSENT_FILE.exists():
+            return "not_set"
+        content = _CONSENT_FILE.read_text(encoding="utf-8").strip().lower()
+        if content == "enabled":
+            return "enabled"
+        return "disabled"
+    except Exception:
+        return "not_set"
+
+
+# =============================================================================
+# Installation Identity
+# =============================================================================
+
+
+def get_installation_id() -> str:
+    """
+    Return a stable, one-way hash that identifies this installation.
+
+    On first call a random UUID is generated and stored at
+    ~/.config/apisec/installation_id. Every subsequent call returns the
+    SHA-256 hex digest of that UUID — the raw UUID never leaves the machine.
+
+    The hash lets Mohsin filter CloudWatch events by customer after mapping
+    installation IDs out-of-band during onboarding. Returns "" on any error
+    so telemetry is never blocked by a filesystem issue.
+
+    SHA-256 hex is safe through the PII scrubber: it only contains [0-9a-f],
+    so none of the forbidden patterns (which all contain non-hex chars) match.
+    """
+    import hashlib
+    import uuid
+
+    try:
+        if _INSTALLATION_ID_FILE.exists():
+            raw = _INSTALLATION_ID_FILE.read_text(encoding="utf-8").strip()
+        else:
+            raw = str(uuid.uuid4())
+            _INSTALLATION_ID_FILE.parent.mkdir(parents=True, exist_ok=True)
+            _INSTALLATION_ID_FILE.write_text(raw, encoding="utf-8")
+        return hashlib.sha256(raw.encode()).hexdigest()
+    except Exception:
+        return ""
+
+
+# =============================================================================
+# Registration Code
+# =============================================================================
+
+
+def get_registration_code() -> str:
+    """Return the stored registration code, or '' if not yet set.
+
+    Checks APISEC_REGISTRATION_CODE env var first so CI/automated environments
+    can bypass the interactive first-run prompt without writing a config file.
+    """
+    import os
+
+    env_code = os.environ.get("APISEC_REGISTRATION_CODE", "").strip()
+    if env_code:
+        return env_code
+    try:
+        if _REGISTRATION_CODE_FILE.exists():
+            return _REGISTRATION_CODE_FILE.read_text(encoding="utf-8").strip()
+    except Exception:
+        pass
+    return ""
+
+
+def set_registration_code(code: str) -> None:
+    """Persist the registration code."""
+    try:
+        _REGISTRATION_CODE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        _REGISTRATION_CODE_FILE.write_text(code.strip(), encoding="utf-8")
+    except Exception as exc:
+        logger.debug("Could not write registration code: %s", exc)
+
+
+def needs_registration() -> bool:
+    """Return True if no registration code has been stored yet."""
+    return not bool(get_registration_code())
+
+
+# =============================================================================
+# Event Emission
+# =============================================================================
+
+
+def emit_install_event(*, probe_version: str = "") -> None:
+    """
+    Fire-and-forget event on first-ever run of the CLI.
+
+    Captures timestamp (via the server's receipt time), probe version,
+    platform, installation ID, and registration code so Mohsin can see
+    exactly when each customer installation went live.
+    """
+    if not is_telemetry_enabled():
+        return
+
+    import platform as _platform
+    import sys
+
+    payload = _safe_payload(
+        event="install",
+        probe_version=probe_version,
+        python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
+        platform=_platform.system().lower(),
+        installation_id=get_installation_id(),
+        registration_code=get_registration_code(),
+    )
+    if payload is None:
+        return
+
+    def _send() -> None:
+        try:
+            import httpx
+
+            httpx.post(_TELEMETRY_ENDPOINT, json=payload, timeout=5.0)
+        except Exception:
+            pass
+
+    threading.Thread(target=_send, daemon=True).start()
+
+
+_TELEMETRY_ENDPOINT = "https://api.apisec.ai/v1/surface/telemetry/events"
+
+
+def emit_analyze_event(
+    *,
+    probe_version: str = "",
+    files_analyzed: int = 0,
+    files_failed: int = 0,
+    files_skipped: int = 0,
+    frameworks: list[str] | None = None,
+    languages: list[str] | None = None,
+    routes_found: int = 0,
+    routes_by_framework: dict[str, int] | None = None,
+    analysis_time_ms: int = 0,
+    parse_time_ms: int = 0,
+    extraction_time_ms: int = 0,
+    stage_times_ms: dict[str, int] | None = None,
+    extractor_times_ms: dict[str, int] | None = None,
+    has_errors: bool = False,
+) -> None:
+    """
+    Fire-and-forget telemetry event for a completed analysis run.
+
+    Does nothing if telemetry is disabled or not yet consented.
+    Silently catches all errors.
+    """
+    if not is_telemetry_enabled():
+        return
+
+    import platform as _platform
+    import sys
+
+    payload = _safe_payload(
+        event="analyze",
+        probe_version=probe_version,
+        python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
+        platform=_platform.system().lower(),
+        installation_id=get_installation_id(),
+        files_analyzed=files_analyzed,
+        files_failed=files_failed,
+        files_skipped=files_skipped,
+        frameworks=frameworks or [],
+        languages=languages or [],
+        routes_found=routes_found,
+        routes_by_framework=routes_by_framework or {},
+        framework_count=len(frameworks or []),
+        analysis_time_ms=analysis_time_ms,
+        parse_time_ms=parse_time_ms,
+        extraction_time_ms=extraction_time_ms,
+        stage_times_ms=stage_times_ms or {},
+        extractor_times_ms=extractor_times_ms or {},
+        has_errors=has_errors,
+    )
+    if payload is None:
+        return
+
+    def _send() -> None:
+        try:
+            import httpx
+
+            httpx.post(
+                _TELEMETRY_ENDPOINT,
+                json=payload,
+                timeout=5.0,
+            )
+        except Exception:
+            pass  # Telemetry must never surface errors
+
+    t = threading.Thread(target=_send, daemon=True)
+    t.start()
+
+
+def emit_error_event(
+    *,
+    probe_version: str = "",
+    error_type: str = "",
+) -> None:
+    """
+    Fire-and-forget telemetry event for an unhandled scan crash.
+
+    Only the exception class name is sent — never the message, which could
+    contain file paths or other PII. Does nothing if telemetry is disabled.
+    Silently catches all errors.
+    """
+    if not is_telemetry_enabled():
+        return
+
+    import platform as _platform
+    import sys
+
+    payload = _safe_payload(
+        event="analyze_error",
+        probe_version=probe_version,
+        python_version=f"{sys.version_info.major}.{sys.version_info.minor}",
+        platform=_platform.system().lower(),
+        installation_id=get_installation_id(),
+        error_type=error_type,
+    )
+    if payload is None:
+        return
+
+    def _send() -> None:
+        try:
+            import httpx
+
+            httpx.post(
+                _TELEMETRY_ENDPOINT,
+                json=payload,
+                timeout=5.0,
+            )
+        except Exception:
+            pass
+
+    threading.Thread(target=_send, daemon=True).start()