certifyclouds 1.2.0__py3-none-any.whl

cc_scanner/__init__.py

@@ -0,0 +1,3 @@
+"""CertifyClouds Scanner — scan Azure Key Vaults for expiring secrets, certificates, and keys."""
+
+__version__ = "1.2.0"

cc_scanner/auth.py

@@ -0,0 +1,93 @@
+"""API key validation and telemetry for CertifyClouds Scanner.
+
+Called after each scan to validate the key and send aggregate usage stats.
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import httpx
+
+from . import __version__
+from . import config as cfg
+
+logger = logging.getLogger(__name__)
+
+LICENSE_SERVER_URL = "https://license.certifyclouds.com"
+VALIDATE_ENDPOINT = f"{LICENSE_SERVER_URL}/api/scanner/validate"
+REQUEST_TIMEOUT = 10.0
+
+
+class ValidationResult:
+    """Result of a key validation call."""
+    def __init__(self, valid: bool, error: str | None = None,
+                 latest_version: str | None = None, offline: bool = False):
+        self.valid = valid
+        self.error = error
+        self.latest_version = latest_version
+        self.offline = offline
+
+
+def validate_key(key: str, stats: dict[str, Any] | None = None) -> ValidationResult:
+    """Validate the API key and send usage stats.
+
+    Args:
+        key: The cc-scan API key
+        stats: Aggregate scan stats (counts only, no names/values)
+
+    Returns:
+        ValidationResult with valid/invalid/offline status
+    """
+    # Check if we can skip validation (cached grace period)
+    if stats is None and cfg.is_validation_fresh():
+        logger.debug("Skipping validation — last validated within grace period")
+        return ValidationResult(valid=True, offline=False)
+
+    payload: dict[str, Any] = {
+        "key": key,
+        "version": __version__,
+    }
+    if stats:
+        payload["stats"] = stats
+
+    try:
+        resp = httpx.post(
+            VALIDATE_ENDPOINT,
+            json=payload,
+            timeout=REQUEST_TIMEOUT,
+        )
+
+        if resp.status_code == 429:
+            # Rate limited — treat as valid (don't block the user)
+            logger.debug("Validation rate limited, treating as valid")
+            return ValidationResult(valid=True)
+
+        data = resp.json() if resp.headers.get("content-type", "").startswith("application/json") else {}
+
+        if resp.status_code == 403 or not data.get("valid", False):
+            error = data.get("error", "Invalid API key")
+            cfg.clear_validation()
+            return ValidationResult(valid=False, error=error)
+
+        # Valid — update cache
+        cfg.update_last_validated()
+        return ValidationResult(
+            valid=True,
+            latest_version=data.get("latestVersion"),
+        )
+
+    except (httpx.ConnectError, httpx.TimeoutException, httpx.HTTPError) as exc:
+        logger.debug("Validation call failed: %s", exc)
+
+        # Offline — check cached validation
+        if cfg.is_validation_fresh():
+            return ValidationResult(valid=True, offline=True)
+
+        # No cached validation but still let them scan
+        return ValidationResult(valid=True, offline=True,
+                                error="Could not reach license server")
+
+    except Exception as exc:
+        logger.debug("Unexpected validation error: %s", exc)
+        return ValidationResult(valid=True, offline=True)

cc_scanner/cli.py

@@ -0,0 +1,287 @@
+"""CertifyClouds Scanner CLI entry point.
+
+Orchestrates: config → register → scan → filter → analyze → format → validate
+"""
+from __future__ import annotations
+
+import logging
+import os
+import sys
+import time
+
+import click
+from rich.console import Console
+from rich.logging import RichHandler
+
+from . import __version__
+from . import config as cfg
+from .auth import validate_key
+from .filters import apply_filters
+from .formatters import get_formatter
+from .registration import register
+from .scanner import scan
+from .security import analyze, has_critical_or_high
+
+console = Console()
+
+
+_LOGO_LINES = [
+    "                                 ▄▄███▄▄                         ",
+    "                             ▄▄███▀▀ ▀▀███▄▄                     ",
+    "                           ███▀▀         ▀▀███                   ",
+    "                          ▄██    ▄▄███▄     ██                   ",
+    "                      ▄▄█████   ██████▀▄██  ███▄▄▄▄             ",
+    "                   ▄███▀▀  ██   ██▄▀▀▄███▀  ██▀▀▀███▄           ",
+    "                   ██      ██▄  ▀███████▀  ▄██     ▀██▄         ",
+    "                   ██      ▀▀██▄▄ ▀▀█▀▀ ▄▄██▀▀       ██        ",
+    "                   ██▄        ▀▀██▄▄ ▄▄██▀▀         ▄██        ",
+    "                   ▀▀███▄▄▄▄▄▄▄▄▄███████▄▄▄▄▄▄▄▄▄▄▄██▀▀       ",
+    "                       ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀          ",
+]
+
+_TEXT_LINES = [
+    "      ▄███ ████ ███▄ ████ ██ ████ ██ ██    ▄███ ██   ▄███▄ ██ ██ ████▄ ▄███",
+    "      ██   ██   ██ █  ██  ██ ██   ██ ██    ██   ██   ██ ██ ██ ██ ██ ██ ██  ",
+    "      ██   ████ ███▀  ██  ██ ████ ▀██▀     ██   ██   ██ ██ ██ ██ ██ ██  ▀█▄",
+    "      ██   ██   ██ █  ██  ██ ██    ██      ██   ██   ██ ██ ██ ██ ██ ██   ██",
+    "      ▀███ ████ ██ █  ██  ██ ██    ██      ▀███ ████ ▀███▀ ▀███▀ ████▀ ███▀",
+]
+
+# Brand gradient from logo SVG: purple → mid-purple → blue → cyan
+_GRADIENT_STOPS = [(137, 63, 254), (83, 83, 254), (40, 118, 254), (6, 182, 212)]
+
+
+def _gradient_text(line: str):
+    """Apply brand gradient colour across a line of text."""
+    from rich.style import Style
+    from rich.text import Text
+
+    text = Text()
+    max_i = max(len(line) - 1, 1)
+    stops = _GRADIENT_STOPS
+    segments = len(stops) - 1
+    for i, ch in enumerate(line):
+        t = i / max_i
+        seg = min(int(t * segments), segments - 1)
+        t2 = (t * segments) - seg
+        c1, c2 = stops[seg], stops[seg + 1]
+        r = int(c1[0] + (c2[0] - c1[0]) * t2)
+        g = int(c1[1] + (c2[1] - c1[1]) * t2)
+        b = int(c1[2] + (c2[2] - c1[2]) * t2)
+        text.append(ch, style=Style(color=f"#{r:02x}{g:02x}{b:02x}", bold=True))
+    return text
+
+
+def _print_banner(email: str | None = None) -> None:
+    """Print a professional startup banner with logo and ASCII art in brand gradient."""
+    console.print()
+    for line in _LOGO_LINES:
+        console.print(_gradient_text(line))
+    for line in _TEXT_LINES:
+        console.print(_gradient_text(line))
+    console.print()
+    console.print(f"  [bold]Scanner[/bold]  [dim]v{__version__}[/dim]  [dim]·[/dim]  [dim]Azure Key Vault security audit[/dim]")
+    if email:
+        console.print(f"  [dim]{email}[/dim]")
+    console.print()
+
+
+def _setup_logging(verbosity: int) -> None:
+    """Configure logging based on verbosity level."""
+    if verbosity >= 2:
+        level = logging.DEBUG
+    elif verbosity >= 1:
+        level = logging.INFO
+    else:
+        level = logging.WARNING
+
+    logging.basicConfig(
+        level=level,
+        format="%(message)s",
+        handlers=[RichHandler(show_time=False, show_path=False, console=Console(stderr=True))],
+    )
+
+    # Suppress noisy Azure SDK and HTTP client logs
+    for name in ("azure", "azure.core", "azure.identity", "azure.mgmt", "azure.keyvault",
+                 "msal", "msal_extensions", "urllib3", "httpx", "httpcore"):
+        logging.getLogger(name).setLevel(logging.WARNING)
+
+
+@click.command()
+@click.option("--format", "fmt", type=click.Choice(["table", "json", "csv", "html"]),
+              default=None, help="Output format (default: table)")
+@click.option("--output", "-o", "output_file", type=str, default=None,
+              help="Write output to file instead of stdout")
+@click.option("--expiring", type=int, default=None,
+              help="Only show items expiring within N days")
+@click.option("--expired", is_flag=True, default=False,
+              help="Only show already-expired items")
+@click.option("--type", "asset_type", type=click.Choice(["secrets", "certificates", "keys"]),
+              default=None, help="Only show this asset type")
+@click.option("--vault", "vault_names", type=str, multiple=True,
+              help="Only scan specific vault(s) (repeatable)")
+@click.option("--subscription", "subscription_ids", type=str, multiple=True,
+              help="Only scan specific subscription(s) (repeatable)")
+@click.option("--security", "security_only", is_flag=True, default=False,
+              help="Show security findings summary only")
+@click.option("--auth", "auth_method", type=click.Choice(["cli", "default"]),
+              default=None, help="Azure auth method (default: cli)")
+@click.option("--workers", type=int, default=None,
+              help="Parallel scan workers (default: 5, max: 20)")
+@click.option("--timeout", type=int, default=None,
+              help="Scan timeout in seconds (default: 300)")
+@click.option("--key", "api_key", type=str, default=None,
+              help="API key (overrides saved config)")
+@click.option("--register", "force_register", is_flag=True, default=False,
+              help="Re-register / change email")
+@click.option("--offline", is_flag=True, default=False,
+              help="Skip license server validation")
+@click.option("-v", "--verbose", count=True,
+              help="Increase verbosity (-v for info, -vv for debug)")
+@click.version_option(version=__version__, prog_name="cc-scan")
+def main(
+    fmt: str | None,
+    output_file: str | None,
+    expiring: int | None,
+    expired: bool,
+    asset_type: str | None,
+    vault_names: tuple[str, ...],
+    subscription_ids: tuple[str, ...],
+    security_only: bool,
+    auth_method: str | None,
+    workers: int | None,
+    timeout: int | None,
+    api_key: str | None,
+    force_register: bool,
+    offline: bool,
+    verbose: int,
+) -> None:
+    """Scan Azure Key Vaults for expiring secrets, certificates, and keys."""
+    _setup_logging(verbose)
+
+    # Resolve settings: flag > env var > default
+    fmt = fmt or os.environ.get("CC_SCAN_FORMAT", "table")
+    auth_method = auth_method or os.environ.get("CC_SCAN_AUTH", "cli")
+    workers = workers or int(os.environ.get("CC_SCAN_WORKERS", "5"))
+    timeout = timeout or int(os.environ.get("CC_SCAN_TIMEOUT", "300"))
+    offline = offline or os.environ.get("CC_SCAN_OFFLINE", "").lower() in ("true", "1")
+    workers = min(max(workers, 1), 20)
+
+    # Resolve API key: flag > env var > config file
+    key = api_key or os.environ.get("CC_SCAN_KEY") or cfg.get_key()
+
+    # Registration flow
+    if force_register or not key:
+        if not force_register and not key:
+            console.print()
+            console.print(f"[bold]CertifyClouds Scanner[/bold] v{__version__}")
+
+        key = register()
+        if not key:
+            sys.exit(3)
+
+    email = cfg.get_email()
+
+    # Print header (table format only)
+    if fmt == "table":
+        _print_banner(email)
+
+    # Run scan
+    if fmt == "table":
+        console.print("[dim]Scanning Azure subscriptions...[/dim]")
+        console.print()
+
+    start_time = time.time()
+
+    try:
+        results = scan(
+            auth_method=auth_method,
+            subscription_filter=list(subscription_ids) if subscription_ids else None,
+            vault_filter=list(vault_names) if vault_names else None,
+            max_workers=workers,
+            timeout=timeout,
+        )
+    except KeyboardInterrupt:
+        console.print()
+        console.print("[yellow]Scan interrupted.[/yellow]")
+        sys.exit(2)
+
+    scan_duration_ms = int((time.time() - start_time) * 1000)
+
+    # Check for fatal scan error
+    if results.get("error") and not results.get("subscriptions"):
+        if fmt == "table":
+            console.print(f"[red]Error: {results['error']}[/red]")
+            console.print()
+            if "credentials" in results["error"].lower() or "login" in results["error"].lower():
+                console.print("Run 'az login' to authenticate with Azure CLI, or set these environment variables")
+                console.print("for service principal auth:")
+                console.print("  AZURE_CLIENT_ID")
+                console.print("  AZURE_CLIENT_SECRET")
+                console.print("  AZURE_TENANT_ID")
+        elif fmt == "json":
+            get_formatter("json")(results, [], output_file)
+        sys.exit(2)
+
+    # Apply filters
+    apply_filters(results, expiring_days=expiring, expired_only=expired, asset_type=asset_type)
+
+    # Security analysis
+    findings = analyze(results)
+
+    # Compute expiry summary before any formatting modifies results
+    from .filters import compute_expiry_summary
+    expiry_summary = compute_expiry_summary(results)
+
+    # Format output
+    formatter = get_formatter(fmt)
+    if security_only and fmt == "table":
+        from .formatters.table import format_table_security_only
+        format_table_security_only(results, findings, output_file)
+    else:
+        formatter(results, findings, output_file)
+
+    # Post-scan validation (telemetry) — only if not offline
+    if not offline:
+        stats = {
+            "subscriptions": len(results.get("subscriptions", [])),
+            "vaults": results.get("totalVaults", 0),
+            "secrets": results.get("totalSecrets", 0),
+            "certificates": results.get("totalCertificates", 0),
+            "keys": results.get("totalKeys", 0),
+            "expired": sum(expiry_summary["expired"].values()),
+            "expiringSoon": sum(expiry_summary["30_days"].values()),
+            "securityFindings": len(findings),
+            "vaultsWithErrors": results.get("vaultsWithErrors", 0),
+            "scanDurationMs": scan_duration_ms,
+        }
+
+        validation = validate_key(key, stats=stats)
+
+        if fmt == "table":
+            if not validation.valid:
+                console.print(f"[yellow]Warning: {validation.error}[/yellow]")
+                console.print("[yellow]Run 'cc-scan --register' to get a new key.[/yellow]")
+                console.print()
+            elif validation.offline and validation.error:
+                console.print(f"[dim]{validation.error}. Scanning in offline mode.[/dim]")
+            elif validation.latest_version and validation.latest_version != __version__:
+                console.print(f"[dim]Update available: cc-scan {__version__} → {validation.latest_version} — pip install --upgrade cc-scanner[/dim]")
+
+    # CTA (table format only, after version nudge per plan section 11.3)
+    if fmt == "table":
+        total_expired = sum(expiry_summary["expired"].values())
+        if total_expired > 5:
+            console.print(f"[dim]{total_expired} expired items found. CertifyClouds Pro auto-rotates these → certifyclouds.com/pro[/dim]")
+        else:
+            console.print("[dim]Automate rotation & compliance → certifyclouds.com[/dim]")
+        console.print()
+
+    # Exit code
+    if has_critical_or_high(findings):
+        sys.exit(1)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

cc_scanner/config.py

@@ -0,0 +1,90 @@
+"""Local configuration management for CertifyClouds Scanner.
+
+Reads/writes ~/.certifyclouds/config.json to persist API key and validation state.
+"""
+from __future__ import annotations
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+CONFIG_DIR = Path.home() / ".certifyclouds"
+CONFIG_FILE = CONFIG_DIR / "config.json"
+
+
+def load_config() -> dict[str, Any]:
+    """Load config from ~/.certifyclouds/config.json. Returns empty dict if missing or corrupt."""
+    if not CONFIG_FILE.exists():
+        return {}
+    try:
+        return json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        logger.warning("Config file corrupt or unreadable (%s), treating as empty", exc)
+        return {}
+
+
+def save_config(data: dict[str, Any]) -> None:
+    """Save config to ~/.certifyclouds/config.json. Creates directory if needed."""
+    CONFIG_DIR.mkdir(mode=0o700, parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    # Set file permissions to owner-only (best-effort on Windows)
+    try:
+        CONFIG_FILE.chmod(0o600)
+    except OSError:
+        pass
+
+
+def get_key() -> str | None:
+    """Return the saved API key, or None."""
+    return load_config().get("key")
+
+
+def get_email() -> str | None:
+    """Return the saved email, or None."""
+    return load_config().get("email")
+
+
+def save_registration(key: str, email: str) -> None:
+    """Save a new registration to config."""
+    config = load_config()
+    config.update({
+        "key": key,
+        "email": email,
+        "registered_at": datetime.now(timezone.utc).isoformat(),
+        "last_validated": datetime.now(timezone.utc).isoformat(),
+    })
+    save_config(config)
+
+
+def update_last_validated() -> None:
+    """Update the last_validated timestamp."""
+    config = load_config()
+    config["last_validated"] = datetime.now(timezone.utc).isoformat()
+    save_config(config)
+
+
+def clear_validation() -> None:
+    """Clear the last_validated timestamp (key became invalid)."""
+    config = load_config()
+    config.pop("last_validated", None)
+    save_config(config)
+
+
+def is_validation_fresh(grace_days: int = 7) -> bool:
+    """Check if last_validated is within grace_days (skip re-validation)."""
+    config = load_config()
+    last = config.get("last_validated")
+    if not last:
+        return False
+    try:
+        last_dt = datetime.fromisoformat(last)
+        if last_dt.tzinfo is None:
+            last_dt = last_dt.replace(tzinfo=timezone.utc)
+        age = datetime.now(timezone.utc) - last_dt
+        return age.days < grace_days
+    except (ValueError, TypeError):
+        return False

cc_scanner/filters.py

@@ -0,0 +1,142 @@
+"""Result filtering for CertifyClouds Scanner.
+
+Filters scan results by expiry, asset type, and vault name.
+Applied after scanning, before formatting.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+def apply_filters(
+    results: dict[str, Any],
+    expiring_days: int | None = None,
+    expired_only: bool = False,
+    asset_type: str | None = None,
+) -> dict[str, Any]:
+    """Apply filters to scan results, modifying the results dict in place.
+
+    Args:
+        results: Scan results dict from scanner.scan()
+        expiring_days: Only show items expiring within N days (None = no filter)
+        expired_only: Only show already-expired items
+        asset_type: Only show this type: "secrets", "certificates", or "keys"
+    """
+    if not expiring_days and not expired_only and not asset_type:
+        return results
+
+    now = datetime.now(timezone.utc)
+
+    for sub in results.get("subscriptions", []):
+        for vault in sub.get("vaults", []):
+            # Type filtering
+            if asset_type:
+                if asset_type != "secrets":
+                    vault["secrets"] = []
+                if asset_type != "certificates":
+                    vault["certificates"] = []
+                if asset_type != "keys":
+                    vault["keys"] = []
+
+            # Expiry filtering
+            if expiring_days is not None or expired_only:
+                vault["secrets"] = [s for s in vault["secrets"] if _passes_expiry_filter(s, now, expiring_days, expired_only)]
+                vault["certificates"] = [c for c in vault["certificates"] if _passes_expiry_filter(c, now, expiring_days, expired_only)]
+                vault["keys"] = [k for k in vault["keys"] if _passes_expiry_filter(k, now, expiring_days, expired_only)]
+
+    # Recount totals
+    results["totalSecrets"] = 0
+    results["totalCertificates"] = 0
+    results["totalKeys"] = 0
+    for sub in results.get("subscriptions", []):
+        for vault in sub.get("vaults", []):
+            results["totalSecrets"] += len(vault.get("secrets", []))
+            results["totalCertificates"] += len(vault.get("certificates", []))
+            results["totalKeys"] += len(vault.get("keys", []))
+
+    return results
+
+
+def _passes_expiry_filter(
+    asset: dict[str, Any],
+    now: datetime,
+    expiring_days: int | None,
+    expired_only: bool,
+) -> bool:
+    """Check if an asset passes the expiry filter."""
+    expires_on = asset.get("expiresOn")
+
+    if expires_on is None:
+        # No expiry — exclude when filtering by expiry
+        return False
+
+    try:
+        expiry = datetime.fromisoformat(expires_on.replace("Z", "+00:00"))
+        if expiry.tzinfo is None:
+            expiry = expiry.replace(tzinfo=timezone.utc)
+    except (ValueError, TypeError):
+        return False
+
+    if expired_only:
+        return expiry < now
+
+    if expiring_days is not None:
+        days_left = (expiry - now).days
+        return days_left <= expiring_days
+
+    return True
+
+
+def compute_expiry_summary(results: dict[str, Any]) -> dict[str, dict[str, int]]:
+    """Compute expiry summary buckets from scan results.
+
+    Returns:
+        Dict with keys: "expired", "7_days", "30_days", "90_days", "ok", "no_expiry"
+        Each value is a dict with keys: "secrets", "certificates", "keys"
+    """
+    now = datetime.now(timezone.utc)
+    buckets = {
+        "expired": {"secrets": 0, "certificates": 0, "keys": 0},
+        "7_days": {"secrets": 0, "certificates": 0, "keys": 0},
+        "30_days": {"secrets": 0, "certificates": 0, "keys": 0},
+        "90_days": {"secrets": 0, "certificates": 0, "keys": 0},
+        "ok": {"secrets": 0, "certificates": 0, "keys": 0},
+        "no_expiry": {"secrets": 0, "certificates": 0, "keys": 0},
+    }
+
+    for sub in results.get("subscriptions", []):
+        for vault in sub.get("vaults", []):
+            for item_type, items in [("secrets", vault.get("secrets", [])), ("certificates", vault.get("certificates", [])), ("keys", vault.get("keys", []))]:
+                for item in items:
+                    bucket = _get_expiry_bucket(item, now)
+                    buckets[bucket][item_type] += 1
+
+    return buckets
+
+
+def _get_expiry_bucket(asset: dict[str, Any], now: datetime) -> str:
+    """Determine which expiry bucket an asset falls into."""
+    expires_on = asset.get("expiresOn")
+
+    if expires_on is None:
+        return "no_expiry"
+
+    try:
+        expiry = datetime.fromisoformat(expires_on.replace("Z", "+00:00"))
+        if expiry.tzinfo is None:
+            expiry = expiry.replace(tzinfo=timezone.utc)
+    except (ValueError, TypeError):
+        return "no_expiry"
+
+    if expiry < now:
+        return "expired"
+
+    days_left = (expiry - now).days
+    if days_left <= 7:
+        return "7_days"
+    if days_left <= 30:
+        return "30_days"
+    if days_left <= 90:
+        return "90_days"
+    return "ok"

cc_scanner/formatters/__init__.py

@@ -0,0 +1,19 @@
+"""Output formatters for scan results."""
+
+from __future__ import annotations
+
+
+def get_formatter(format_name: str):
+    """Return the formatter function for the given format name."""
+    if format_name == "json":
+        from .json_fmt import format_json
+        return format_json
+    elif format_name == "csv":
+        from .csv_fmt import format_csv
+        return format_csv
+    elif format_name == "html":
+        from .html import format_html
+        return format_html
+    else:
+        from .table import format_table
+        return format_table