cloudleak 1.0.0__py3-none-any.whl

cloudleak/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version as _version
+
+try:
+    __version__ = _version("cloudleak")
+except PackageNotFoundError:
+    __version__ = "unknown"

cloudleak/auth/session.py

@@ -0,0 +1,53 @@
+import boto3
+import botocore.exceptions
+
+
+class CloudLeakAuthError(Exception):
+    pass
+
+
+def get_session(profile: str | None = None) -> boto3.Session:
+    try:
+        session = boto3.Session(profile_name=profile) if profile else boto3.Session()
+        creds = session.get_credentials()
+        if creds is None:
+            raise CloudLeakAuthError(
+                "No AWS credentials found. Configure via environment variables, "
+                "~/.aws/credentials, or SSO."
+            )
+        return session
+    except botocore.exceptions.ProfileNotFound as exc:
+        raise CloudLeakAuthError(f"AWS profile not found: {exc}") from exc
+    except botocore.exceptions.NoCredentialsError as exc:
+        raise CloudLeakAuthError("No AWS credentials found.") from exc
+
+
+def get_account_id(session: boto3.Session) -> str:
+    try:
+        sts = session.client("sts")
+        return sts.get_caller_identity()["Account"]
+    except botocore.exceptions.ClientError as exc:
+        raise CloudLeakAuthError(f"Failed to call sts:GetCallerIdentity — {exc}") from exc
+    except botocore.exceptions.NoCredentialsError as exc:
+        raise CloudLeakAuthError("No AWS credentials found.") from exc
+
+
+def get_active_regions(session: boto3.Session) -> list[str]:
+    try:
+        ec2 = session.client("ec2", region_name="us-east-1")
+        resp = ec2.describe_regions(
+            Filters=[
+                {
+                    "Name": "opt-in-status",
+                    "Values": ["opt-in-not-required", "opted-in"],
+                }
+            ]
+        )
+        return sorted(r["RegionName"] for r in resp["Regions"])
+    except botocore.exceptions.ClientError as exc:
+        code = exc.response.get("Error", {}).get("Code", "")
+        if code in ("AccessDenied", "UnauthorizedOperation"):
+            raise CloudLeakAuthError(
+                f"Missing permission: ec2:DescribeRegions. Grant it to run --all-regions."
+            ) from exc
+        raise CloudLeakAuthError(f"Failed to list regions: {exc}") from exc

cloudleak/cli/__init__.py

@@ -0,0 +1,531 @@
+from __future__ import annotations
+
+import sys
+
+import click
+from rich.console import Console
+
+# Ensure stdout/stderr can handle Unicode on Windows (cp1252 can't encode emoji severity icons).
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+if hasattr(sys.stderr, "reconfigure"):
+    sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+_console = Console(legacy_windows=False)
+_err = Console(stderr=True, legacy_windows=False)
+
+
+@click.group()
+@click.version_option(package_name="cloudleak")
+def main() -> None:
+    """CloudLeak — read-only AWS FinOps CLI scanner."""
+
+
+# ─── scan ──────────────────────────────────────────────────────────────────────
+
+
+@main.group()
+def scan() -> None:
+    """Scan AWS resources for cost waste."""
+
+
+@scan.group(invoke_without_command=True)
+@click.option("--all-regions", is_flag=True, default=False, help="Scan all active regions.")
+@click.option("--profile", default=None, help="AWS named profile to use.")
+@click.option(
+    "--export",
+    "export_formats",
+    type=click.Choice(["json", "csv", "html", "executive", "all"]),
+    multiple=True,
+    help="Export findings to file (may be specified multiple times; 'all' writes every format).",
+)
+@click.option(
+    "--config",
+    "config_path",
+    default=None,
+    type=click.Path(exists=True),
+    help="Path to cloudleak.yaml config file.",
+)
+@click.option(
+    "--rules",
+    default=None,
+    help="Comma-separated rule groups to run (e.g. ec2,rds,s3).",
+)
+@click.option(
+    "--severity",
+    type=click.Choice(["HIGH", "MEDIUM", "LOW"]),
+    default=None,
+    help="Only emit findings at or above this severity.",
+)
+@click.option(
+    "--output-file",
+    default=None,
+    type=click.Path(),
+    help="Write export output to this file (default: stdout).",
+)
+@click.option("-v", "--verbose", is_flag=True, default=False, help="Verbose scan progress.")
+@click.pass_context
+def aws(
+    ctx: click.Context,
+    all_regions: bool,
+    profile: str | None,
+    export_formats: tuple[str, ...],
+    config_path: str | None,
+    rules: str | None,
+    severity: str | None,
+    output_file: str | None,
+    verbose: bool,
+) -> None:
+    """Scan AWS resources (specify a region subcommand or --all-regions)."""
+    ctx.ensure_object(dict)
+    ctx.obj.update(
+        {
+            "all_regions": all_regions,
+            "profile": profile,
+            "export_formats": export_formats,
+            "config_path": config_path,
+            "rules": rules,
+            "severity": severity,
+            "output_file": output_file,
+            "verbose": verbose,
+        }
+    )
+    if ctx.invoked_subcommand is None:
+        if all_regions:
+            _run_scan(ctx.obj, regions=None)
+        else:
+            _err.print(
+                "[yellow]Specify a region (e.g. cloudleak scan aws region us-east-1) "
+                "or use --all-regions.[/yellow]"
+            )
+            click.echo(ctx.get_help())
+            ctx.exit(1)
+
+
+@aws.command(name="region")
+@click.argument("region_name")
+@click.option(
+    "--export",
+    "export_formats",
+    type=click.Choice(["json", "csv", "html", "executive", "all"]),
+    multiple=True,
+    help="Export findings to file (may be specified multiple times; 'all' writes every format).",
+)
+@click.option(
+    "--config",
+    "config_path",
+    default=None,
+    type=click.Path(exists=True),
+    help="Path to cloudleak.yaml config file.",
+)
+@click.option("--rules", default=None, help="Comma-separated rule groups to run (e.g. ec2,rds,s3).")
+@click.option(
+    "--severity",
+    type=click.Choice(["HIGH", "MEDIUM", "LOW"]),
+    default=None,
+    help="Only emit findings at or above this severity.",
+)
+@click.option(
+    "--output-file",
+    default=None,
+    type=click.Path(),
+    help="Write export output to this file (default: auto-named).",
+)
+@click.option("--profile", default=None, help="AWS named profile to use.")
+@click.option("-v", "--verbose", is_flag=True, default=False, help="Verbose scan progress.")
+@click.pass_obj
+def aws_region(
+    obj: dict,
+    region_name: str,
+    export_formats: tuple[str, ...],
+    config_path: str | None,
+    rules: str | None,
+    severity: str | None,
+    output_file: str | None,
+    profile: str | None,
+    verbose: bool,
+) -> None:
+    """Scan a single AWS REGION (e.g. us-east-1)."""
+    if export_formats:
+        obj["export_formats"] = export_formats
+    if config_path is not None:
+        obj["config_path"] = config_path
+    if rules is not None:
+        obj["rules"] = rules
+    if severity is not None:
+        obj["severity"] = severity
+    if output_file is not None:
+        obj["output_file"] = output_file
+    if profile is not None:
+        obj["profile"] = profile
+    if verbose:
+        obj["verbose"] = verbose
+    _run_scan(obj, regions=[region_name])
+
+
+def _run_scan(opts: dict, regions: list[str] | None) -> None:
+    import time
+    from datetime import datetime, timezone
+    from pathlib import Path
+
+    from cloudleak.auth.session import (
+        CloudLeakAuthError,
+        get_account_id,
+        get_active_regions,
+        get_session,
+    )
+    from cloudleak.config.loader import load_config
+    from cloudleak.output import render_console, render_csv, render_executive, render_html, render_json
+    from cloudleak.output.executive_model import build_executive_summary
+    from cloudleak.pricing.cache import PricingCache
+    from cloudleak.rules import get_rules
+    from cloudleak.scanner.orchestrator import scan_region
+
+    try:
+        session = get_session(opts.get("profile"))
+    except CloudLeakAuthError as exc:
+        _err.print(f"[red]Auth error:[/red] {exc}")
+        sys.exit(2)
+
+    cfg = load_config(opts.get("config_path"))
+
+    cache_path = Path(cfg.pricing.get("cache_file", "~/.cloudleak/prices.json")).expanduser()
+    cache = PricingCache.load(cache_path)
+    warn_days = int(cfg.pricing.get("warn_if_stale_days", 30))
+    if cache.is_empty:
+        _err.print(
+            "[yellow]Warning:[/yellow] Pricing cache not found — "
+            "run [bold]cloudleak prices update[/bold]. All cost estimates will show as unknown."
+        )
+    elif cache.is_stale(warn_days):
+        _err.print(
+            f"[yellow]Warning:[/yellow] Pricing cache is older than {warn_days} days. "
+            f"Run [bold]cloudleak prices update[/bold] to refresh."
+        )
+
+    try:
+        account_id = get_account_id(session)
+    except CloudLeakAuthError as exc:
+        _err.print(f"[red]Auth error:[/red] {exc}")
+        sys.exit(2)
+
+    if regions is None:
+        try:
+            regions = get_active_regions(session)
+        except CloudLeakAuthError as exc:
+            _err.print(f"[red]Auth error:[/red] {exc}")
+            sys.exit(2)
+
+    # Resolve rule filter flags
+    groups = [g.strip().lower() for g in opts["rules"].split(",")] if opts.get("rules") else None
+    severity = opts.get("severity")
+    rules = get_rules(groups=groups, severity=severity)
+
+    _console.print(
+        f"[bold]CloudLeak[/bold] — account [cyan]{account_id}[/cyan] | "
+        f"{len(regions)} region(s) | {len(rules)} rule(s)"
+    )
+    if not rules:
+        _console.print("[yellow]No rules registered. Rule groups are implemented in Epic 4+.[/yellow]")
+
+    scan_time = datetime.now(timezone.utc)
+    wall_start = time.monotonic()
+    all_findings = []
+    all_skipped = []
+    all_rule_runs = []
+
+    for region in regions:
+        result = scan_region(
+            session=session,
+            region=region,
+            account_id=account_id,
+            rules=rules,
+            config=cfg,
+            pricing=cache,
+        )
+        all_findings.extend(result.findings)
+        all_skipped.extend(result.skipped)
+        all_rule_runs.extend(result.rule_runs)
+
+    wall = round(time.monotonic() - wall_start, 1)
+    suppress_skipped = cfg.output.get("suppress_skipped", False) if hasattr(cfg, "output") else False
+
+    # Console output (always shown)
+    render_console(
+        all_findings=all_findings,
+        all_skipped=all_skipped,
+        all_rule_runs=all_rule_runs,
+        account_id=account_id,
+        regions=regions,
+        duration=wall,
+        scan_time=scan_time,
+        console=_console,
+        suppress_skipped=suppress_skipped,
+        verbose=opts.get("verbose", False),
+    )
+
+    # File export(s)
+    raw_formats: tuple[str, ...] = opts.get("export_formats") or ()
+    formats: set[str] = set(raw_formats)
+    if "all" in formats:
+        formats = {"json", "csv", "html", "executive"}
+    if not formats:
+        return
+
+    output_file = opts.get("output_file")
+    date_str = scan_time.strftime("%Y-%m-%d")
+
+    def _write(content: str, ext: str, suffix: str = "") -> None:
+        if output_file and len(formats) == 1:
+            path = Path(output_file)
+        else:
+            base = f"cloudleak-{suffix or 'findings'}-{date_str}"
+            path = Path(f"{base}.{ext}")
+        path.write_text(content, encoding="utf-8")
+        _console.print(f"[dim]Exported {ext.upper()} → {path}[/dim]")
+
+    if "json" in formats:
+        _write(
+            render_json(
+                all_findings=all_findings,
+                all_skipped=all_skipped,
+                account_id=account_id,
+                regions=regions,
+                duration=wall,
+                rules_executed=len(rules),
+                scan_time=scan_time,
+            ),
+            "json",
+        )
+
+    if "csv" in formats:
+        _write(render_csv(all_findings=all_findings), "csv")
+
+    if "html" in formats:
+        _write(
+            render_html(
+                all_findings=all_findings,
+                all_skipped=all_skipped,
+                account_id=account_id,
+                regions=regions,
+                duration=wall,
+                scan_time=scan_time,
+                rules_evaluated=len(all_rule_runs),
+            ),
+            "html",
+        )
+
+    if "executive" in formats:
+        effort_overrides = cfg.get("executive_report", "effort_overrides") or {}
+        summary = build_executive_summary(
+            all_findings=all_findings,
+            all_rule_runs=all_rule_runs,
+            account_id=account_id,
+            regions=regions,
+            duration=wall,
+            scan_time=scan_time.strftime("%Y-%m-%d %H:%M UTC"),
+            effort_overrides={k: float(v) for k, v in effort_overrides.items()},
+        )
+        _write(render_executive(summary), "html", suffix=f"executive-{account_id}-{regions[0] if regions else 'multi'}")
+
+
+# ─── doctor ────────────────────────────────────────────────────────────────────
+
+
+@main.group()
+def doctor() -> None:
+    """Pre-flight checks."""
+
+
+@doctor.command(name="aws")
+@click.option("--profile", default=None, help="AWS named profile to use.")
+@click.option("--region", default=None, help="AWS region to probe (defaults to session region or us-east-1).")
+def doctor_aws(profile: str | None, region: str | None) -> None:
+    """Validate that the caller has all IAM permissions required by cloudleak."""
+    from rich.table import Table
+
+    from cloudleak.auth.session import CloudLeakAuthError, get_session
+    from cloudleak.scanner.doctor import DoctorAuthError, _PROBES, run_doctor
+
+    try:
+        session = get_session(profile)
+    except CloudLeakAuthError as exc:
+        _err.print(f"[red]Auth error:[/red] {exc}")
+        sys.exit(2)
+
+    probe_region = region or session.region_name or "us-east-1"
+
+    _console.print()
+    _console.print("[bold]cloudleak doctor[/bold] — Permission Check")
+    _console.print(f"[dim]Probing {len(_PROBES)} permissions in [cyan]{probe_region}[/cyan] ...[/dim]")
+    _console.print()
+
+    try:
+        result = run_doctor(session, probe_region)
+    except DoctorAuthError as exc:
+        _err.print(f"[red]Auth error:[/red] {exc}")
+        sys.exit(2)
+    except Exception as exc:
+        _err.print(f"[red]Doctor check failed:[/red] {exc}")
+        sys.exit(1)
+
+    _console.print(
+        f"Account: [bold]{result.account_id}[/bold]  ·  "
+        f"Identity: [dim]{result.caller_arn}[/dim]"
+    )
+    _console.print()
+
+    tbl = Table(show_header=True, header_style="bold dim", box=None, padding=(0, 2))
+    tbl.add_column("", width=3)
+    tbl.add_column("Permission")
+    tbl.add_column("Affected Rules", style="dim")
+
+    for r in result.results:
+        icon = "[green]✓[/green]" if r.ok else "[red]✗[/red]"
+        skipped = ", ".join(r.affected_rules) if (not r.ok and r.affected_rules) else ""
+        note_suffix = f"  [dim italic]({r.note})[/dim italic]" if r.note else ""
+        tbl.add_row(icon, r.permission + note_suffix, skipped)
+
+    _console.print(tbl)
+    _console.print()
+
+    if result.missing_count == 0:
+        _console.print(
+            f"[green bold]All {result.total} permissions available.[/green bold] "
+            "cloudleak can run all rules in this region."
+        )
+        sys.exit(0)
+    else:
+        affected = sorted(result.affected_rule_ids)
+        _console.print(
+            f"[yellow]{result.ok_count}/{result.total}[/yellow] permissions available. "
+            f"[red]{result.missing_count} missing.[/red]"
+        )
+        if affected:
+            _console.print(
+                f"[red]{len(affected)} rule(s)[/red] will be SKIPPED: {', '.join(affected)}"
+            )
+        sys.exit(1)
+
+
+# ─── prices ────────────────────────────────────────────────────────────────────
+
+
+@main.group()
+def prices() -> None:
+    """Manage the offline pricing cache."""
+
+
+@prices.command(name="update")
+@click.option("--profile", default=None, help="AWS named profile to use.")
+def prices_update(profile: str | None) -> None:
+    """Fetch current AWS prices and write to the local cache (~/.cloudleak/prices.json)."""
+    from pathlib import Path
+
+    from cloudleak.auth.session import CloudLeakAuthError, get_session
+    from cloudleak.config.loader import load_config
+    from cloudleak.pricing.update import run_update
+
+    try:
+        session = get_session(profile)
+    except CloudLeakAuthError as exc:
+        _err.print(f"[red]Auth error:[/red] {exc}")
+        sys.exit(2)
+
+    cfg = load_config()
+    cache_path = Path(cfg.pricing.get("cache_file", "~/.cloudleak/prices.json")).expanduser()
+
+    try:
+        run_update(session, cache_path)
+    except SystemExit:
+        raise
+    except Exception as exc:
+        _err.print(f"[red]Prices update failed:[/red] {exc}")
+        sys.exit(1)
+
+
+# ─── rules ─────────────────────────────────────────────────────────────────────
+
+
+@main.group()
+def rules() -> None:
+    """List and describe scan rules."""
+
+
+@rules.command(name="list")
+@click.option("--service", "group", default=None, help="Filter by group (e.g. ec2, rds, s3).")
+@click.option(
+    "--severity",
+    type=click.Choice(["HIGH", "MEDIUM", "LOW"]),
+    default=None,
+    help="Minimum severity to include.",
+)
+def rules_list(group: str | None, severity: str | None) -> None:
+    """List all available scan rules."""
+    from rich.table import Table
+
+    from cloudleak.rules import get_rules
+
+    groups = [group.lower()] if group else None
+    ruleset = get_rules(groups=groups, severity=severity)
+
+    if not ruleset:
+        _console.print("[yellow]No rules registered yet (Epic 4+).[/yellow]")
+        return
+
+    tbl = Table(title="CloudLeak Rules", show_lines=False)
+    tbl.add_column("ID", style="bold cyan", no_wrap=True)
+    tbl.add_column("Severity", no_wrap=True)
+    tbl.add_column("Service", no_wrap=True)
+    tbl.add_column("Name")
+    tbl.add_column("Description")
+
+    _sev_colour = {"HIGH": "red", "MEDIUM": "yellow", "LOW": "blue"}
+    for rule in sorted(ruleset, key=lambda r: (r.service, r.rule_id)):
+        colour = _sev_colour.get(rule.severity.value, "white")
+        tbl.add_row(
+            rule.rule_id,
+            f"[{colour}]{rule.severity.value}[/{colour}]",
+            rule.service,
+            rule.name,
+            rule.description,
+        )
+    _console.print(tbl)
+    _console.print(f"[dim]{len(ruleset)} rule(s)[/dim]")
+
+
+@rules.command(name="describe")
+@click.argument("rule_id")
+def rules_describe(rule_id: str) -> None:
+    """Show full specification for a rule (e.g. EC2-001)."""
+    from rich.table import Table
+
+    from cloudleak.rules import ALL_RULES
+
+    target = next(
+        (r for r in ALL_RULES if r.rule_id.upper() == rule_id.upper()), None
+    )
+    if target is None:
+        _err.print(f"[red]Rule not found:[/red] {rule_id}")
+        sys.exit(1)
+
+    _sev_colour = {"HIGH": "red", "MEDIUM": "yellow", "LOW": "blue"}
+    colour = _sev_colour.get(target.severity.value, "white")
+
+    tbl = Table(show_header=False, box=None, padding=(0, 1))
+    tbl.add_column("Field", style="bold", no_wrap=True)
+    tbl.add_column("Value")
+
+    tbl.add_row("ID", target.rule_id)
+    tbl.add_row("Name", target.name)
+    tbl.add_row("Service", target.service)
+    tbl.add_row("Group", getattr(target, "group", target.service.lower()))
+    tbl.add_row("Severity", f"[{colour}]{target.severity.value}[/{colour}]")
+    tbl.add_row("Description", target.description)
+    tbl.add_row("Rationale", target.rationale)
+    tbl.add_row("Permissions", "\n".join(target.permissions))
+    tbl.add_row(
+        "Thresholds",
+        "\n".join(f"{k}: {v}" for k, v in target.thresholds.items()) or "—",
+    )
+    _console.print(tbl)