kulshan 0.1.0__py3-none-any.whl

kulshan/__init__.py

@@ -0,0 +1,9 @@
+"""
+Kulshan: CLI for AWS cost, security, and waste analysis.
+
+Local-first, non-mutating AWS audits. Optional integrations require explicit invocation.
+"""
+
+from kulshan.__version__ import __version__
+
+__all__ = ["__version__"]

kulshan/__version__.py

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

kulshan/adapter.py

@@ -0,0 +1,244 @@
+"""Adapter layer for converting pack-internal finding dicts to the canonical shape.
+
+Packs can be migrated incrementally. Until a pack emits canonical findings
+directly, this adapter handles the translation from its internal
+representation to the canonical Finding dict shape defined in ``models.py``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+from kulshan.models import (
+    CONFIDENCE_ENUM_MAP,
+    SEVERITY_SCORE_IMPACT,
+    VALID_EFFORT,
+    VALID_RISK,
+    VALID_SEVERITY,
+    compute_fingerprint,
+    make_finding_id,
+)
+
+# ---------------------------------------------------------------------------
+# Mapping tables
+# ---------------------------------------------------------------------------
+
+EFFORT_MINUTES_MAP: Dict[str, tuple] = {
+    "trivial": (0, 15),
+    "low": (16, 60),
+    "medium": (61, 240),
+    "high": (241, None),
+}
+"""Maps effort category → (min_minutes, max_minutes). max=None means unbounded."""
+
+
+def _effort_from_minutes(minutes: int) -> str:
+    """Bucket an effort_minutes integer into a categorical effort string."""
+    if minutes <= 15:
+        return "trivial"
+    elif minutes <= 60:
+        return "low"
+    elif minutes <= 240:
+        return "medium"
+    else:
+        return "high"
+
+
+# Default values for fields missing from the raw finding.
+DEFAULTS: Dict[str, Any] = {
+    "effort": "medium",
+    "risk": "safe",
+    "confidence": 0.5,
+    "estimated_monthly_impact": 0.0,
+    "description": "",
+    "evidence": {},
+    "recommended_action": "",
+    "compliance_frameworks": [],
+    "schema_version": "2.0",
+}
+
+# The canonical keys that belong on a Finding dict (used to detect extras).
+_CANONICAL_KEYS = frozenset({
+    "id", "pack", "kind", "fingerprint",
+    "title", "severity", "score_impact",
+    "estimated_monthly_impact", "confidence",
+    "effort", "risk",
+    "account_id", "region", "resource_arn", "resource_type", "service",
+    "description", "evidence", "recommended_action",
+    "compliance_frameworks", "detected_at", "schema_version",
+})
+
+# Keys that are recognized as aliases/legacy names (not extras).
+_ALIAS_KEYS = frozenset({
+    "tool", "check_id", "monthly_impact_usd", "effort_minutes",
+    "account", "usage_type", "operation", "resource_id",
+    "why_it_matters", "remediation_text", "owner_hint",
+})
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def adapt(pack: str, raw_finding: dict) -> dict:
+    """Convert a pack-internal finding dict to the canonical shape.
+
+    Parameters
+    ----------
+    pack : str
+        The pack name (e.g. "cost", "security"). Used as fallback for the
+        ``pack`` field and for fingerprint computation.
+    raw_finding : dict
+        The raw finding dict emitted by the pack's internal logic.
+
+    Returns
+    -------
+    dict
+        A canonical finding dict suitable for validation and ``Finding.from_dict()``.
+    """
+    raw = dict(raw_finding)  # shallow copy to avoid mutating caller's dict
+    out: Dict[str, Any] = {}
+
+    # --- Identity -----------------------------------------------------------
+
+    # Map tool → pack, check_id → kind
+    out["pack"] = raw.pop("pack", None) or raw.pop("tool", None) or pack
+    out["kind"] = raw.pop("kind", None) or raw.pop("check_id", None) or "unknown"
+
+    # --- Severity -----------------------------------------------------------
+
+    sev_raw = raw.pop("severity", "info")
+    if hasattr(sev_raw, "value"):
+        # Enum instance (e.g. Severity.HIGH)
+        sev_str = str(sev_raw.value).lower()
+    else:
+        sev_str = str(sev_raw).lower()
+
+    if sev_str not in VALID_SEVERITY:
+        sev_str = "info"
+    out["severity"] = sev_str
+
+    # --- score_impact (derived from severity) -------------------------------
+
+    out["score_impact"] = SEVERITY_SCORE_IMPACT.get(out["severity"], 0)
+
+    # --- Confidence ---------------------------------------------------------
+
+    conf_raw = raw.pop("confidence", None)
+    if conf_raw is None:
+        out["confidence"] = DEFAULTS["confidence"]
+    elif isinstance(conf_raw, (int, float)):
+        val = float(conf_raw)
+        out["confidence"] = max(0.0, min(1.0, val))
+    elif isinstance(conf_raw, str):
+        out["confidence"] = CONFIDENCE_ENUM_MAP.get(conf_raw.lower(), DEFAULTS["confidence"])
+    else:
+        out["confidence"] = DEFAULTS["confidence"]
+
+    # --- Impact (monthly_impact_usd Decimal string → float) -----------------
+
+    impact_raw = raw.pop("estimated_monthly_impact", None)
+    if impact_raw is None:
+        impact_raw = raw.pop("monthly_impact_usd", None)
+
+    if impact_raw is not None:
+        try:
+            out["estimated_monthly_impact"] = float(str(impact_raw))
+        except (ValueError, TypeError):
+            out["estimated_monthly_impact"] = DEFAULTS["estimated_monthly_impact"]
+    else:
+        out["estimated_monthly_impact"] = DEFAULTS["estimated_monthly_impact"]
+
+    # --- Effort (effort string or effort_minutes bucketing) -----------------
+
+    effort_raw = raw.pop("effort", None)
+    effort_minutes_raw = raw.pop("effort_minutes", None)
+
+    if effort_raw is not None and str(effort_raw) in VALID_EFFORT:
+        out["effort"] = str(effort_raw)
+    elif effort_minutes_raw is not None:
+        try:
+            minutes = int(effort_minutes_raw)
+            out["effort"] = _effort_from_minutes(minutes)
+        except (ValueError, TypeError):
+            out["effort"] = DEFAULTS["effort"]
+    else:
+        out["effort"] = DEFAULTS["effort"]
+
+    # --- Risk ---------------------------------------------------------------
+
+    risk_raw = raw.pop("risk", None)
+    if risk_raw is not None and str(risk_raw) in VALID_RISK:
+        out["risk"] = str(risk_raw)
+    else:
+        out["risk"] = DEFAULTS["risk"]
+
+    # --- Title --------------------------------------------------------------
+
+    out["title"] = raw.pop("title", "")
+
+    # --- Location -----------------------------------------------------------
+
+    out["account_id"] = raw.pop("account_id", None) or raw.pop("account", None)
+    out["region"] = raw.pop("region", None)
+    out["resource_arn"] = raw.pop("resource_arn", None) or raw.pop("resource_id", None)
+    out["resource_type"] = raw.pop("resource_type", None)
+    out["service"] = raw.pop("service", None)
+
+    # --- Explanation --------------------------------------------------------
+
+    out["description"] = raw.pop("description", None) or raw.pop("why_it_matters", None) or DEFAULTS["description"]
+    out["evidence"] = raw.pop("evidence", None)
+    if not isinstance(out["evidence"], dict):
+        out["evidence"] = {}
+    out["recommended_action"] = raw.pop("recommended_action", None) or raw.pop("remediation_text", None) or DEFAULTS["recommended_action"]
+
+    # --- Metadata -----------------------------------------------------------
+
+    out["compliance_frameworks"] = list(raw.pop("compliance_frameworks", DEFAULTS["compliance_frameworks"]))
+    out["detected_at"] = raw.pop("detected_at", None)
+    out["schema_version"] = raw.pop("schema_version", DEFAULTS["schema_version"])
+
+    # --- Fingerprint (compute if absent) ------------------------------------
+
+    fingerprint = raw.pop("fingerprint", None)
+    if not fingerprint:
+        fingerprint = compute_fingerprint(
+            pack=out["pack"],
+            kind=out["kind"],
+            account=out["account_id"],
+            service=out["service"],
+            usage_type=raw.pop("usage_type", None),
+            period=out["detected_at"],
+        )
+    else:
+        # Still pop usage_type if present to avoid it ending up in extras
+        raw.pop("usage_type", None)
+    out["fingerprint"] = fingerprint
+
+    # --- ID (compute if absent) ---------------------------------------------
+
+    id_raw = raw.pop("id", None)
+    if id_raw:
+        out["id"] = id_raw
+    else:
+        out["id"] = make_finding_id(
+            pack=out["pack"],
+            kind=out["kind"],
+            fingerprint=out["fingerprint"],
+        )
+
+    # --- Preserve unrecognized fields in evidence["extra"] ------------------
+
+    # Remove any remaining known alias keys that were already handled
+    for alias_key in list(raw.keys()):
+        if alias_key in _ALIAS_KEYS:
+            raw.pop(alias_key, None)
+
+    # Whatever remains in raw is unrecognized / extra
+    if raw:
+        extra = out["evidence"].get("extra", {})
+        extra.update(raw)
+        out["evidence"]["extra"] = extra
+
+    return out

kulshan/checks/__init__.py

@@ -0,0 +1,9 @@
+"""Kulshan check packs.
+
+Each subpackage exposes a top-level ``run_scan`` function with the contract:
+    run_scan(session, regions, *, quick: bool = False, **kwargs) -> dict
+
+The orchestrator iterates ``TOOL_ORDER`` (defined in Kulshan.orchestrator) and
+calls each pack's ``run_scan``. Pack keys are the orchestrator keys used in
+TOOL_ORDER, TOOL_LABELS, TOOL_WEIGHTS, and the JSON report shape.
+"""

kulshan/checks/age/__init__.py

@@ -0,0 +1,134 @@
+"""Age check pack, Lambda runtimes, RDS engines, ACM certificates, EBS modernization."""
+from __future__ import annotations
+
+import hashlib
+from typing import List
+
+__version__ = "0.1.0"
+__all__ = ["__version__", "run_scan"]
+
+
+def _fingerprint(pack: str, kind: str, resource_id: str) -> str:
+    raw = f"{pack}|{kind}|{resource_id}"
+    return hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+
+def _extract_findings(result: dict) -> list:
+    """Extract canonical findings from freshness scan results."""
+    findings = []
+
+    # EOL runtimes (Lambda, RDS engines, EKS versions)
+    for item in result.get("eol_runtimes", []):
+        resource_id = item.get("resource_id", "unknown")
+        fp = _fingerprint("age", "eol-runtime", resource_id)
+        days_past = item.get("days_past_eol", 0)
+        severity = "critical" if days_past > 180 else "high" if days_past > 0 else "medium"
+        findings.append({
+            "id": f"age-eol-runtime-{fp}",
+            "pack": "age",
+            "kind": "eol-runtime",
+            "title": f"{item.get('resource_type', 'Resource')} '{resource_id}' uses EOL runtime ({item.get('runtime', '?')})",
+            "severity": severity,
+            "confidence": 0.99,
+            "effort": "medium",
+            "risk": "medium",
+            "resource_id": resource_id,
+            "resource_arn": item.get("resource_arn", ""),
+            "region": item.get("region", "us-east-1"),
+            "description": f"Runtime '{item.get('runtime', '?')}' is end-of-life ({days_past} days past EOL). No security patches.",
+            "recommended_action": f"Upgrade to a supported runtime version.",
+            "estimated_monthly_impact": 0,
+            "fingerprint": fp,
+        })
+
+    # Expiring certificates
+    for item in result.get("expiring_certs", []):
+        resource_id = item.get("resource_id", "unknown")
+        fp = _fingerprint("age", "expiring-certificate", resource_id)
+        days_left = item.get("days_until_expiry", 0)
+        severity = "critical" if days_left <= 7 else "high" if days_left <= 30 else "medium"
+        findings.append({
+            "id": f"age-expiring-certificate-{fp}",
+            "pack": "age",
+            "kind": "expiring-certificate",
+            "title": f"Certificate '{resource_id}' expires in {days_left} days",
+            "severity": severity,
+            "confidence": 0.99,
+            "effort": "low",
+            "risk": "safe",
+            "resource_id": resource_id,
+            "resource_arn": item.get("resource_arn", ""),
+            "region": item.get("region", "us-east-1"),
+            "description": f"ACM certificate expires in {days_left} days. Renew or enable auto-renewal.",
+            "recommended_action": f"aws acm renew-certificate --certificate-arn {item.get('resource_arn', resource_id)}",
+            "estimated_monthly_impact": 0,
+            "fingerprint": fp,
+        })
+
+    # Stale AMIs
+    for item in result.get("stale_amis", []):
+        resource_id = item.get("resource_id", "unknown")
+        fp = _fingerprint("age", "stale-ami", resource_id)
+        age_days = item.get("age_days", 0)
+        findings.append({
+            "id": f"age-stale-ami-{fp}",
+            "pack": "age",
+            "kind": "stale-ami",
+            "title": f"AMI '{resource_id}' is {age_days} days old and unused",
+            "severity": "low",
+            "confidence": 0.70,
+            "effort": "trivial",
+            "risk": "low",
+            "resource_id": resource_id,
+            "resource_arn": "",
+            "region": item.get("region", "us-east-1"),
+            "description": f"AMI is {age_days} days old and not used by any running instance.",
+            "recommended_action": f"aws ec2 deregister-image --image-id {resource_id}",
+            "estimated_monthly_impact": 0,
+            "fingerprint": fp,
+        })
+
+    return findings
+
+
+def run_scan(session, regions: List[str], *, quick: bool = False, **kwargs) -> dict:
+    """Run the lifecycle/staleness scan and return a scored result dict."""
+    from .scanner.freshness import scan_freshness
+    from .scoring.engine import calculate_score
+
+    if quick:
+        regions = regions[:3]
+
+    all_errors: list[str] = []
+    try:
+        result, errors = scan_freshness(session, regions)
+        all_errors.extend(errors)
+    except Exception as e:
+        result = {}
+        all_errors.append(str(e))
+
+    scores = calculate_score(result) if result else {
+        "overall_score": 100, "grade": "A+", "total_aging": 0,
+        "severity_counts": {}, "breakdown": {},
+    }
+
+    findings = _extract_findings(result) if result else []
+
+    sev: dict = {"critical": 0, "high": 0, "medium": 0, "low": 0, "info": 0}
+    for f in findings:
+        s = f.get("severity", "info")
+        if s in sev:
+            sev[s] += 1
+
+    return {
+        "tool": "age",
+        "findings": findings,
+        "scores": {
+            "overall_score": int(scores.get("overall_score", 100)),
+            "grade": scores.get("grade", "A+"),
+            "total_findings": len(findings),
+            "severity_counts": {k: v for k, v in sev.items() if v > 0},
+            "breakdown": scores.get("breakdown", {}),
+        },
+        "errors": all_errors,
+    }

kulshan/checks/age/scanner/eol_db.py

@@ -0,0 +1,124 @@
+"""Embedded EOL/EOS date database for AWS runtimes and engines."""
+
+import json
+import os
+
+LAST_UPDATED = "2026-02-27"
+_OVERRIDES_PATH = os.path.join(os.path.expanduser("~"), ".Kulshan", "age", "eol_overrides.json")
+
+# Lambda runtime EOL dates (Phase 2 = no updates, Phase 3 = no create)
+LAMBDA_EOL = {
+    "python3.8": {"eol": "2024-10-14", "status": "eol", "upgrade": "python3.12"},
+    "python3.9": {"eol": "2025-11-01", "status": "approaching", "upgrade": "python3.12"},
+    "python3.10": {"eol": "2026-07-01", "status": "approaching", "upgrade": "python3.13"},
+    "python3.11": {"eol": "2027-03-01", "status": "current", "upgrade": "python3.13"},
+    "python3.12": {"eol": "2028-03-01", "status": "current", "upgrade": None},
+    "python3.13": {"eol": "2029-03-01", "status": "current", "upgrade": None},
+    "nodejs14.x": {"eol": "2023-12-04", "status": "eol", "upgrade": "nodejs20.x"},
+    "nodejs16.x": {"eol": "2024-06-12", "status": "eol", "upgrade": "nodejs20.x"},
+    "nodejs18.x": {"eol": "2025-09-01", "status": "approaching", "upgrade": "nodejs22.x"},
+    "nodejs20.x": {"eol": "2026-10-01", "status": "current", "upgrade": None},
+    "nodejs22.x": {"eol": "2027-10-01", "status": "current", "upgrade": None},
+    "java8": {"eol": "2024-01-08", "status": "eol", "upgrade": "java21"},
+    "java8.al2": {"eol": "2025-02-01", "status": "approaching", "upgrade": "java21"},
+    "java11": {"eol": "2025-09-01", "status": "approaching", "upgrade": "java21"},
+    "java17": {"eol": "2026-09-01", "status": "current", "upgrade": "java21"},
+    "java21": {"eol": "2028-09-01", "status": "current", "upgrade": None},
+    "dotnet6": {"eol": "2024-07-12", "status": "eol", "upgrade": "dotnet8"},
+    "dotnet8": {"eol": "2026-11-01", "status": "current", "upgrade": None},
+    "ruby3.2": {"eol": "2026-03-01", "status": "current", "upgrade": "ruby3.3"},
+    "ruby3.3": {"eol": "2027-03-01", "status": "current", "upgrade": None},
+    "go1.x": {"eol": "2024-01-08", "status": "eol", "upgrade": "provided.al2023"},
+    "provided": {"eol": "2024-01-08", "status": "eol", "upgrade": "provided.al2023"},
+    "provided.al2": {"eol": "2025-09-01", "status": "approaching", "upgrade": "provided.al2023"},
+    "provided.al2023": {"eol": "2028-03-01", "status": "current", "upgrade": None},
+}
+
+# RDS engine end-of-standard-support dates (after this, Extended Support = 3x cost)
+RDS_EOL = {
+    "mysql": {
+        "5.7": {"eos": "2024-02-29", "status": "extended_support", "upgrade": "8.0", "surcharge": True},
+        "8.0": {"eos": "2026-04-30", "status": "current", "upgrade": "8.4", "surcharge": False},
+    },
+    "postgres": {
+        "11": {"eos": "2024-02-29", "status": "extended_support", "upgrade": "16", "surcharge": True},
+        "12": {"eos": "2025-02-28", "status": "extended_support", "upgrade": "16", "surcharge": True},
+        "13": {"eos": "2025-11-13", "status": "approaching", "upgrade": "16", "surcharge": False},
+        "14": {"eos": "2026-11-12", "status": "current", "upgrade": "16", "surcharge": False},
+        "15": {"eos": "2027-11-11", "status": "current", "upgrade": None, "surcharge": False},
+        "16": {"eos": "2028-11-09", "status": "current", "upgrade": None, "surcharge": False},
+    },
+    "mariadb": {
+        "10.4": {"eos": "2024-02-29", "status": "extended_support", "upgrade": "10.11", "surcharge": True},
+        "10.5": {"eos": "2025-02-28", "status": "approaching", "upgrade": "10.11", "surcharge": False},
+        "10.6": {"eos": "2026-02-28", "status": "current", "upgrade": "10.11", "surcharge": False},
+        "10.11": {"eos": "2028-02-28", "status": "current", "upgrade": None, "surcharge": False},
+    },
+}
+
+# EKS Kubernetes version EOL
+EKS_EOL = {
+    "1.24": {"eos": "2024-01-31", "status": "eol", "upgrade": "1.30"},
+    "1.25": {"eos": "2024-05-01", "status": "eol", "upgrade": "1.30"},
+    "1.26": {"eos": "2024-06-11", "status": "eol", "upgrade": "1.30"},
+    "1.27": {"eos": "2024-07-24", "status": "eol", "upgrade": "1.31"},
+    "1.28": {"eos": "2025-03-01", "status": "approaching", "upgrade": "1.31"},
+    "1.29": {"eos": "2025-06-01", "status": "approaching", "upgrade": "1.31"},
+    "1.30": {"eos": "2025-11-01", "status": "current", "upgrade": "1.31"},
+    "1.31": {"eos": "2026-03-01", "status": "current", "upgrade": None},
+}
+
+# ElastiCache Redis version staleness
+REDIS_EOL = {
+    "5": {"status": "eol", "upgrade": "7"},
+    "6": {"status": "approaching", "upgrade": "7"},
+    "7": {"status": "current", "upgrade": None},
+}
+
+
+def load_eol_overrides():
+    """Load user overrides from ~/.Kulshan/age/eol_overrides.json and merge over defaults."""
+    if not os.path.exists(_OVERRIDES_PATH):
+        return
+
+    try:
+        with open(_OVERRIDES_PATH, "r") as f:
+            overrides = json.load(f)
+
+        # Merge lambda overrides
+        for runtime, info in overrides.get("lambda", {}).items():
+            LAMBDA_EOL[runtime] = info
+
+        # Merge RDS overrides
+        for engine, versions in overrides.get("rds", {}).items():
+            if engine not in RDS_EOL:
+                RDS_EOL[engine] = {}
+            for ver, info in versions.items():
+                RDS_EOL[engine][ver] = info
+
+        # Merge EKS overrides
+        for ver, info in overrides.get("eks", {}).items():
+            EKS_EOL[ver] = info
+
+        # Merge Redis overrides
+        for ver, info in overrides.get("redis", {}).items():
+            REDIS_EOL[ver] = info
+    except Exception:
+        pass  # Silently ignore malformed overrides
+
+
+def check_staleness():
+    """Check if the embedded EOL database is potentially outdated."""
+    from datetime import datetime
+    try:
+        updated = datetime.strptime(LAST_UPDATED, "%Y-%m-%d")
+        age_days = (datetime.now() - updated).days
+        if age_days > 180:
+            return f"EOL database is {age_days} days old."
+    except Exception:
+        pass
+    return None
+
+
+# Auto-load overrides on import
+load_eol_overrides()