icdev 0.0.3__py3-none-any.whl

tools/compliance/fedramp_20x_ksi_emitter.py

@@ -0,0 +1,692 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+# ////////////////////////////////////////////////////////////////////
+# CONTROLLED UNCLASSIFIED INFORMATION (CUI) // SP-CTI
+# Distribution: Distribution D -- Authorized DoD Personnel Only
+# ////////////////////////////////////////////////////////////////////
+"""FedRAMP 20x Key Security Indicator (KSI) Emitter — continuous posture reporting.
+
+Consumes cATO evidence streams and produces machine-readable KSI JSON for
+continuous posture reporting under the FedRAMP 20x framework.  Five KSI
+categories are scored deterministically from DB evidence (no LLM).
+
+KSI Categories:
+  1. vulnerability_management — open vulnerability count and severity
+  2. config_compliance — STIG check pass rate
+  3. access_control — MFA enforcement, least-privilege AC-* controls
+  4. encryption_status — FIPS 140-3, TLS enforcement from SC-* controls
+  5. patch_currency — dependency CVE-free percentage
+
+Architecture Decision: D-INV-50
+  - All scoring is deterministic (rule-based, no LLM)
+  - Results appended to audit_trail (NIST AU compliant)
+  - Reads from cato_evidence, compliance_evidence, project_controls, sbom_entries
+
+Usage:
+    python tools/compliance/fedramp_20x_ksi_emitter.py --project-id "sparkpilot" --json
+    python tools/compliance/fedramp_20x_ksi_emitter.py --project-id "sparkpilot" --category vulnerability_management --json
+    python tools/compliance/fedramp_20x_ksi_emitter.py --project-id "sparkpilot" --3pao-package --json
+"""
+
+import argparse
+import json
+import logging
+import sys
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+from tools.db.storage import get_connection
+
+logger = logging.getLogger("icdev.compliance.fedramp_20x_ksi")
+
+BASE_DIR = Path(__file__).resolve().parent.parent.parent
+
+# -----------------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------------
+
+KSI_CATEGORIES = [
+    "vulnerability_management",
+    "config_compliance",
+    "access_control",
+    "encryption_status",
+    "patch_currency",
+]
+
+# Vulnerability severity penalty weights (deducted from 1.0 base)
+VULN_PENALTY = {
+    "critical": 1.0,   # any critical -> score 0
+    "high": 0.20,
+    "medium": 0.05,
+    "low": 0.01,
+}
+
+# Control family prefixes for each KSI category
+AC_FAMILIES = ("AC-",)
+SC_FAMILIES = ("SC-",)
+
+
+# -----------------------------------------------------------------------
+# Audit helper
+# -----------------------------------------------------------------------
+
+def _log_audit_event(conn, project_id, event_type, details):
+    """Log an audit trail event (append-only, NIST AU compliant)."""
+    try:
+        conn.execute(
+            """INSERT INTO audit_trail
+               (project_id, event_type, actor, action, details, classification)
+               VALUES (?, ?, ?, ?, ?, ?)""",
+            (
+                project_id,
+                event_type,
+                "icdev-fedramp-20x-ksi-emitter",
+                event_type,
+                json.dumps(details, default=str),
+                "CUI",
+            ),
+        )
+        conn.commit()
+    except Exception as exc:
+        logger.warning("Could not log audit event: %s", exc)
+
+
+# -----------------------------------------------------------------------
+# Scoring functions — each returns a KSI dict
+# -----------------------------------------------------------------------
+
+def _now_iso():
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _score_vulnerability_management(conn, project_id):
+    """Score based on open vulnerability count and severity.
+
+    Starts at 1.0, deducts per-vulnerability penalty by severity.
+    Any critical vulnerability forces score to 0.
+    """
+    indicators = []
+    score = 1.0
+    evidence_refs = []
+
+    # Query open vulnerabilities from multiple sources
+    vuln_rows = []
+    try:
+        vuln_rows = conn.execute(
+            """SELECT id, severity, status
+               FROM poam_items
+               WHERE project_id = ? AND status NOT IN ('closed', 'completed', 'resolved')
+               ORDER BY severity""",
+            (project_id,),
+        ).fetchall()
+    except Exception:
+        pass
+
+    severity_counts = {"critical": 0, "high": 0, "medium": 0, "low": 0}
+    for row in vuln_rows:
+        sev = (dict(row).get("severity") or "medium").lower()
+        if sev in severity_counts:
+            severity_counts[sev] += 1
+        evidence_refs.append(dict(row).get("id", "unknown"))
+
+    # Apply penalties
+    if severity_counts["critical"] > 0:
+        score = 0.0
+        indicators.append({
+            "check": "no_critical_vulnerabilities",
+            "status": "FAIL",
+            "detail": f"{severity_counts['critical']} critical vulnerability(ies) open",
+        })
+    else:
+        indicators.append({
+            "check": "no_critical_vulnerabilities",
+            "status": "PASS",
+            "detail": "No critical vulnerabilities",
+        })
+
+    if score > 0:
+        score -= severity_counts["high"] * VULN_PENALTY["high"]
+        score -= severity_counts["medium"] * VULN_PENALTY["medium"]
+        score -= severity_counts["low"] * VULN_PENALTY["low"]
+        score = max(score, 0.0)
+
+    indicators.append({
+        "check": "vulnerability_counts",
+        "status": "INFO",
+        "detail": json.dumps(severity_counts),
+    })
+
+    total_open = sum(severity_counts.values())
+    indicators.append({
+        "check": "total_open_vulnerabilities",
+        "status": "PASS" if total_open == 0 else "WARN",
+        "detail": f"{total_open} open vulnerability(ies)",
+    })
+
+    return {
+        "category": "vulnerability_management",
+        "score": round(score, 4),
+        "indicators": indicators,
+        "timestamp": _now_iso(),
+        "evidence_refs": evidence_refs[:50],  # cap refs
+    }
+
+
+def _score_config_compliance(conn, project_id):
+    """Score based on STIG pass rate from compliance_evidence table."""
+    indicators = []
+    evidence_refs = []
+    score = 0.0
+
+    try:
+        rows = conn.execute(
+            """SELECT id, control_id, status
+               FROM compliance_evidence
+               WHERE project_id = ? AND evidence_type = 'stig_check'""",
+            (project_id,),
+        ).fetchall()
+    except Exception:
+        rows = []
+
+    if not rows:
+        # Fallback: check project_controls for CM-* family
+        try:
+            rows = conn.execute(
+                """SELECT control_id, implementation_status AS status
+                   FROM project_controls
+                   WHERE project_id = ? AND control_id LIKE 'CM-%'""",
+                (project_id,),
+            ).fetchall()
+        except Exception:
+            rows = []
+
+    total = len(rows)
+    passed = 0
+    for row in rows:
+        rd = dict(row)
+        st = (rd.get("status") or "").lower()
+        if st in ("pass", "passed", "implemented", "satisfied"):
+            passed += 1
+        evidence_refs.append(rd.get("id") or rd.get("control_id", "unknown"))
+
+    if total > 0:
+        score = passed / total
+    else:
+        score = 0.5  # no data = indeterminate
+
+    indicators.append({
+        "check": "stig_pass_rate",
+        "status": "PASS" if score >= 0.8 else "WARN" if score >= 0.5 else "FAIL",
+        "detail": f"{passed}/{total} checks passed ({score:.1%})",
+    })
+
+    return {
+        "category": "config_compliance",
+        "score": round(score, 4),
+        "indicators": indicators,
+        "timestamp": _now_iso(),
+        "evidence_refs": evidence_refs[:50],
+    }
+
+
+def _score_access_control(conn, project_id):
+    """Score based on AC-* control implementation status.
+
+    Checks MFA enforcement (IA-2 enhancements) and least-privilege (AC-6).
+    """
+    indicators = []
+    evidence_refs = []
+
+    # Load AC-* and IA-2* controls
+    try:
+        rows = conn.execute(
+            """SELECT control_id, implementation_status, implementation_description
+               FROM project_controls
+               WHERE project_id = ?
+                 AND (control_id LIKE 'AC-%' OR control_id LIKE 'IA-2%')
+               ORDER BY control_id""",
+            (project_id,),
+        ).fetchall()
+    except Exception:
+        rows = []
+
+    total = len(rows)
+    implemented = 0
+    mfa_found = False
+    least_priv_found = False
+
+    for row in rows:
+        rd = dict(row)
+        cid = rd.get("control_id", "")
+        st = (rd.get("implementation_status") or "").lower()
+        desc = (rd.get("implementation_description") or "").lower()
+        evidence_refs.append(cid)
+
+        if st in ("implemented", "satisfied", "complete"):
+            implemented += 1
+
+        # MFA check (IA-2(1), IA-2(2), etc.)
+        if cid.startswith("IA-2") and st in ("implemented", "satisfied", "complete"):
+            mfa_found = True
+
+        # Least privilege (AC-6)
+        if cid.startswith("AC-6") and st in ("implemented", "satisfied", "complete"):
+            least_priv_found = True
+
+    score = implemented / total if total > 0 else 0.5
+
+    indicators.append({
+        "check": "ac_control_implementation",
+        "status": "PASS" if score >= 0.8 else "WARN",
+        "detail": f"{implemented}/{total} AC/IA controls implemented",
+    })
+    indicators.append({
+        "check": "mfa_enforcement",
+        "status": "PASS" if mfa_found else "FAIL",
+        "detail": "MFA controls implemented" if mfa_found else "MFA controls not verified",
+    })
+    indicators.append({
+        "check": "least_privilege",
+        "status": "PASS" if least_priv_found else "FAIL",
+        "detail": "AC-6 least privilege implemented" if least_priv_found else "AC-6 not verified",
+    })
+
+    # Penalize missing MFA and least-privilege
+    if not mfa_found:
+        score = max(score - 0.2, 0.0)
+    if not least_priv_found:
+        score = max(score - 0.1, 0.0)
+
+    return {
+        "category": "access_control",
+        "score": round(score, 4),
+        "indicators": indicators,
+        "timestamp": _now_iso(),
+        "evidence_refs": evidence_refs[:50],
+    }
+
+
+def _score_encryption_status(conn, project_id):
+    """Score based on SC-* controls for FIPS 140-3 and TLS enforcement."""
+    indicators = []
+    evidence_refs = []
+
+    try:
+        rows = conn.execute(
+            """SELECT control_id, implementation_status, implementation_description
+               FROM project_controls
+               WHERE project_id = ? AND control_id LIKE 'SC-%'
+               ORDER BY control_id""",
+            (project_id,),
+        ).fetchall()
+    except Exception:
+        rows = []
+
+    total = len(rows)
+    implemented = 0
+    fips_found = False
+    tls_found = False
+
+    for row in rows:
+        rd = dict(row)
+        cid = rd.get("control_id", "")
+        st = (rd.get("implementation_status") or "").lower()
+        desc = (rd.get("implementation_description") or "").lower()
+        evidence_refs.append(cid)
+
+        if st in ("implemented", "satisfied", "complete"):
+            implemented += 1
+
+        # FIPS 140-3 (SC-13)
+        if cid.startswith("SC-13") and st in ("implemented", "satisfied", "complete"):
+            fips_found = True
+        if "fips" in desc and "140" in desc:
+            fips_found = True
+
+        # TLS enforcement (SC-8, SC-12, SC-23)
+        if cid in ("SC-8", "SC-12", "SC-23") and st in ("implemented", "satisfied", "complete"):
+            tls_found = True
+        if "tls" in desc:
+            tls_found = True
+
+    score = implemented / total if total > 0 else 0.5
+
+    indicators.append({
+        "check": "sc_control_implementation",
+        "status": "PASS" if score >= 0.8 else "WARN",
+        "detail": f"{implemented}/{total} SC controls implemented",
+    })
+    indicators.append({
+        "check": "fips_140_3_compliance",
+        "status": "PASS" if fips_found else "FAIL",
+        "detail": "FIPS 140-3 cryptography verified" if fips_found else "FIPS 140-3 not verified",
+    })
+    indicators.append({
+        "check": "tls_enforcement",
+        "status": "PASS" if tls_found else "FAIL",
+        "detail": "TLS enforcement verified" if tls_found else "TLS enforcement not verified",
+    })
+
+    if not fips_found:
+        score = max(score - 0.2, 0.0)
+    if not tls_found:
+        score = max(score - 0.15, 0.0)
+
+    return {
+        "category": "encryption_status",
+        "score": round(score, 4),
+        "indicators": indicators,
+        "timestamp": _now_iso(),
+        "evidence_refs": evidence_refs[:50],
+    }
+
+
+def _score_patch_currency(conn, project_id):
+    """Score based on percentage of dependencies with no known CVEs."""
+    indicators = []
+    evidence_refs = []
+
+    # Check sbom_entries for CVE status
+    try:
+        rows = conn.execute(
+            """SELECT id, package_name, version, cve_ids
+               FROM sbom_entries
+               WHERE project_id = ?""",
+            (project_id,),
+        ).fetchall()
+    except Exception:
+        rows = []
+
+    total = len(rows)
+    clean = 0
+    vulnerable = 0
+
+    for row in rows:
+        rd = dict(row)
+        cve_ids = rd.get("cve_ids") or ""
+        evidence_refs.append(rd.get("id") or rd.get("package_name", "unknown"))
+        if not cve_ids or cve_ids.strip() in ("", "[]", "null", "None"):
+            clean += 1
+        else:
+            vulnerable += 1
+
+    if total > 0:
+        score = clean / total
+    else:
+        # Fallback: check dependency audit results
+        try:
+            dep_rows = conn.execute(
+                """SELECT id, status FROM compliance_evidence
+                   WHERE project_id = ? AND evidence_type = 'dependency_audit'""",
+                (project_id,),
+            ).fetchall()
+        except Exception:
+            dep_rows = []
+
+        if dep_rows:
+            dep_total = len(dep_rows)
+            dep_pass = sum(
+                1 for r in dep_rows
+                if (dict(r).get("status") or "").lower() in ("pass", "passed", "clean")
+            )
+            score = dep_pass / dep_total if dep_total > 0 else 0.5
+            total = dep_total
+            clean = dep_pass
+            vulnerable = dep_total - dep_pass
+        else:
+            score = 0.5  # no data
+
+    indicators.append({
+        "check": "dependency_cve_free_rate",
+        "status": "PASS" if score >= 0.95 else "WARN" if score >= 0.8 else "FAIL",
+        "detail": f"{clean}/{total} dependencies CVE-free ({score:.1%})",
+    })
+    indicators.append({
+        "check": "vulnerable_dependencies",
+        "status": "PASS" if vulnerable == 0 else "WARN",
+        "detail": f"{vulnerable} dependencies with known CVEs",
+    })
+
+    return {
+        "category": "patch_currency",
+        "score": round(score, 4),
+        "indicators": indicators,
+        "timestamp": _now_iso(),
+        "evidence_refs": evidence_refs[:50],
+    }
+
+
+# -----------------------------------------------------------------------
+# Category dispatcher
+# -----------------------------------------------------------------------
+
+_SCORERS = {
+    "vulnerability_management": _score_vulnerability_management,
+    "config_compliance": _score_config_compliance,
+    "access_control": _score_access_control,
+    "encryption_status": _score_encryption_status,
+    "patch_currency": _score_patch_currency,
+}
+
+
+# -----------------------------------------------------------------------
+# Public API
+# -----------------------------------------------------------------------
+
+def emit_ksi(project_id):
+    """Emit all 5 KSI categories for a project.
+
+    Returns:
+        dict with ksi_categories (list of 5 KSI dicts), aggregate_score,
+        project_id, emitted_at, classification.
+    """
+    with get_connection() as conn:
+        categories = []
+        for cat_name in KSI_CATEGORIES:
+            scorer = _SCORERS[cat_name]
+            ksi = scorer(conn, project_id)
+            categories.append(ksi)
+
+        aggregate = sum(c["score"] for c in categories) / len(categories)
+
+        result = {
+            "project_id": project_id,
+            "ksi_categories": categories,
+            "aggregate_score": round(aggregate, 4),
+            "emitted_at": _now_iso(),
+            "fedramp_20x_version": "20x-draft",
+            "classification": "CUI // SP-CTI",
+        }
+
+        _log_audit_event(conn, project_id, "ksi_emitted", {
+            "aggregate_score": result["aggregate_score"],
+            "category_scores": {c["category"]: c["score"] for c in categories},
+        })
+
+        return result
+
+
+def emit_ksi_category(project_id, category):
+    """Emit a single KSI category for a project.
+
+    Args:
+        project_id: Project identifier.
+        category: One of the 5 KSI category names.
+
+    Returns:
+        dict with single KSI category result.
+    """
+    if category not in _SCORERS:
+        raise ValueError(
+            f"Invalid KSI category '{category}'. "
+            f"Valid categories: {', '.join(KSI_CATEGORIES)}"
+        )
+
+    with get_connection() as conn:
+        ksi = _SCORERS[category](conn, project_id)
+
+        result = {
+            "project_id": project_id,
+            "ksi": ksi,
+            "emitted_at": _now_iso(),
+            "fedramp_20x_version": "20x-draft",
+            "classification": "CUI // SP-CTI",
+        }
+
+        _log_audit_event(conn, project_id, "ksi_category_emitted", {
+            "category": category,
+            "score": ksi["score"],
+        })
+
+        return result
+
+
+def generate_3pao_package(project_id):
+    """Generate combined KSI package with metadata for 3PAO validation.
+
+    Returns:
+        dict with all KSI categories, aggregate score, 3PAO metadata,
+        and validation checklist.
+    """
+    ksi_result = emit_ksi(project_id)
+
+    # Build 3PAO validation metadata
+    categories = ksi_result["ksi_categories"]
+    failing_indicators = []
+    for cat in categories:
+        for ind in cat.get("indicators", []):
+            if ind.get("status") == "FAIL":
+                failing_indicators.append({
+                    "category": cat["category"],
+                    "check": ind["check"],
+                    "detail": ind["detail"],
+                })
+
+    passing_categories = [c["category"] for c in categories if c["score"] >= 0.8]
+    at_risk_categories = [c["category"] for c in categories if 0.5 <= c["score"] < 0.8]
+    failing_categories = [c["category"] for c in categories if c["score"] < 0.5]
+
+    package = {
+        "package_id": str(uuid.uuid4()),
+        "project_id": project_id,
+        "package_type": "fedramp_20x_3pao_ksi",
+        "generated_at": _now_iso(),
+        "fedramp_20x_version": "20x-draft",
+        "ksi_categories": categories,
+        "aggregate_score": ksi_result["aggregate_score"],
+        "summary": {
+            "total_categories": len(KSI_CATEGORIES),
+            "passing_categories": len(passing_categories),
+            "at_risk_categories": len(at_risk_categories),
+            "failing_categories": len(failing_categories),
+            "passing": passing_categories,
+            "at_risk": at_risk_categories,
+            "failing": failing_categories,
+        },
+        "failing_indicators": failing_indicators,
+        "validation_checklist": {
+            "all_ksi_scored": all(c["score"] is not None for c in categories),
+            "aggregate_above_threshold": ksi_result["aggregate_score"] >= 0.7,
+            "no_critical_failures": len(failing_categories) == 0,
+            "evidence_refs_present": all(
+                len(c.get("evidence_refs", [])) > 0 for c in categories
+            ),
+        },
+        "recommendation": (
+            "READY for 3PAO review"
+            if ksi_result["aggregate_score"] >= 0.7 and len(failing_categories) == 0
+            else "REMEDIATION required before 3PAO review"
+        ),
+        "classification": "CUI // SP-CTI",
+    }
+
+    with get_connection() as conn:
+        _log_audit_event(conn, project_id, "3pao_package_generated", {
+            "package_id": package["package_id"],
+            "aggregate_score": package["aggregate_score"],
+            "recommendation": package["recommendation"],
+        })
+
+    return package
+
+
+# -----------------------------------------------------------------------
+# CLI
+# -----------------------------------------------------------------------
+
+def main():
+    """CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="FedRAMP 20x Key Security Indicator (KSI) Emitter"
+    )
+    parser.add_argument(
+        "--project-id", required=True, help="Project identifier"
+    )
+    parser.add_argument(
+        "--category", choices=KSI_CATEGORIES,
+        help="Emit a single KSI category"
+    )
+    parser.add_argument(
+        "--3pao-package", dest="three_pao_package", action="store_true",
+        help="Generate full 3PAO validation package"
+    )
+    parser.add_argument(
+        "--json", action="store_true", help="Output as JSON"
+    )
+    args = parser.parse_args()
+
+    try:
+        if args.three_pao_package:
+            result = generate_3pao_package(args.project_id)
+        elif args.category:
+            result = emit_ksi_category(args.project_id, args.category)
+        else:
+            result = emit_ksi(args.project_id)
+
+        if args.json:
+            print(json.dumps(result, indent=2, default=str))
+        else:
+            # Human-readable output
+            print(f"CUI // SP-CTI")
+            print(f"FedRAMP 20x KSI Report — {args.project_id}")
+            print("=" * 60)
+            if args.three_pao_package:
+                print(f"Package ID: {result['package_id']}")
+                print(f"Aggregate Score: {result['aggregate_score']:.2f}")
+                print(f"Recommendation: {result['recommendation']}")
+                print()
+                for cat in result["ksi_categories"]:
+                    _print_category(cat)
+                if result["failing_indicators"]:
+                    print("\nFailing Indicators:")
+                    for fi in result["failing_indicators"]:
+                        print(f"  [{fi['category']}] {fi['check']}: {fi['detail']}")
+            elif args.category:
+                _print_category(result["ksi"])
+            else:
+                print(f"Aggregate Score: {result['aggregate_score']:.2f}")
+                print()
+                for cat in result["ksi_categories"]:
+                    _print_category(cat)
+
+    except Exception as exc:
+        error = {"error": str(exc), "classification": "CUI // SP-CTI"}
+        if args.json:
+            print(json.dumps(error, indent=2))
+        else:
+            print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+def _print_category(cat):
+    """Print a single KSI category in human-readable format."""
+    status_icon = "PASS" if cat["score"] >= 0.8 else "WARN" if cat["score"] >= 0.5 else "FAIL"
+    print(f"  [{status_icon}] {cat['category']}: {cat['score']:.2f}")
+    for ind in cat.get("indicators", []):
+        print(f"        {ind['status']:4s} | {ind['check']}: {ind['detail']}")
+    print()
+
+
+if __name__ == "__main__":
+    main()