icdev 0.0.3__py3-none-any.whl

tools/compliance/cssp_report_generator.py

@@ -0,0 +1,1103 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+"""Generate a CSSP (Cybersecurity Service Provider) Certification Report.
+
+Queries assessment results, incidents, vulnerability management data,
+certifications, STIG findings, control implementations, SSP status,
+and POA&M items from icdev.db. Fills {{variables}} in the CSSP report
+template, applies CUI markings, saves to the project compliance directory,
+records the version in cssp_certifications, and logs an audit event."""
+
+import argparse
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from tools.db.storage import get_connection
+DB_PATH = None  # Storage layer handles path resolution (D-DB-20)
+
+BASE_DIR = Path(__file__).resolve().parent.parent.parent
+CSSP_TEMPLATE_PATH = BASE_DIR / "context" / "compliance" / "cssp_report_template.md"
+
+# CSSP functional areas per DoD Instruction 8530.01
+FUNCTIONAL_AREAS = ["Identify", "Protect", "Detect", "Respond", "Sustain"]
+
+# Severity ordering for consistent output
+SEVERITY_ORDER = ["critical", "high", "moderate", "low"]
+
+# STIG severity categories
+STIG_CATEGORIES = ["CAT1", "CAT2", "CAT3"]
+
+
+# ---------------------------------------------------------------------------
+# Helper functions
+# ---------------------------------------------------------------------------
+
+
+def _load_template(template_path=None):
+    """Load the CSSP report template markdown.
+
+    If the template file does not exist a minimal built-in template is
+    returned so the generator can still produce a useful report.
+    """
+    path = template_path or CSSP_TEMPLATE_PATH
+    if path.exists():
+        with open(path, "r", encoding="utf-8") as f:
+            return f.read()
+
+    # Fallback minimal template when file is missing
+    return _builtin_template()
+
+
+def _builtin_template():
+    """Return a minimal built-in CSSP report template."""
+    return (
+        "{{cui_banner_top}}\n\n"
+        "# CSSP Certification Report\n\n"
+        "**Project:** {{project_name}}  \n"
+        "**Project ID:** {{project_id}}  \n"
+        "**Classification:** {{classification}}  \n"
+        "**Report Version:** {{report_version}}  \n"
+        "**Date Prepared:** {{date_prepared}}  \n"
+        "**Prepared By:** {{prepared_by}}  \n"
+        "**CSSP Provider:** {{cssp_provider}}  \n"
+        "**ATO Boundary:** {{ato_boundary}}  \n\n"
+        "---\n\n"
+        "## 1. Executive Summary\n\n"
+        "**Overall Compliance Score:** {{overall_score}}%  \n"
+        "**Overall Status:** {{overall_status}}  \n"
+        "**Certification Status:** {{certification_status}}  \n"
+        "**Risk Level:** {{risk_level}}  \n\n"
+        "### Functional Area Scores\n\n"
+        "{{functional_area_scores_table}}\n\n"
+        "---\n\n"
+        "## 2. Functional Area Details\n\n"
+        "{{functional_area_details}}\n\n"
+        "---\n\n"
+        "## 3. STIG Compliance Summary\n\n"
+        "{{stig_summary_table}}\n\n"
+        "**STIG Gate (0 CAT1 Open):** {{stig_gate_status}}  \n\n"
+        "---\n\n"
+        "## 4. Vulnerability Management\n\n"
+        "{{vuln_summary_table}}\n\n"
+        "**SLA Compliance:** {{vuln_sla_status}}  \n\n"
+        "---\n\n"
+        "## 5. Incident History\n\n"
+        "{{incident_summary_table}}\n\n"
+        "**Open Incidents:** {{open_incidents_count}}  \n"
+        "**Mean Time to Contain:** {{mean_time_to_contain}}  \n\n"
+        "---\n\n"
+        "## 6. Control Implementation Status\n\n"
+        "**Total Controls Mapped:** {{controls_mapped}}  \n"
+        "**Implemented:** {{controls_implemented}}  \n"
+        "**Planned / Partial:** {{controls_planned}}  \n"
+        "**Not Applicable:** {{controls_na}}  \n\n"
+        "---\n\n"
+        "## 7. SSP & POA&M Status\n\n"
+        "**SSP Version:** {{ssp_version}}  \n"
+        "**SSP Status:** {{ssp_status}}  \n"
+        "**POA&M Total Items:** {{poam_total}}  \n"
+        "**POA&M Open:** {{poam_open}}  \n"
+        "**POA&M Overdue:** {{poam_overdue}}  \n\n"
+        "---\n\n"
+        "## 8. Findings Requiring Remediation\n\n"
+        "{{findings_table}}\n\n"
+        "---\n\n"
+        "## 9. Evidence Artifacts\n\n"
+        "{{evidence_summary_table}}\n\n"
+        "---\n\n"
+        "## 10. Remediation Plan\n\n"
+        "{{remediation_table}}\n\n"
+        "---\n\n"
+        "## 11. Continuous Monitoring\n\n"
+        "**Next Assessment Date:** {{next_assessment_date}}  \n"
+        "**Continuous Monitoring Plan:** {{continuous_monitoring_plan}}  \n\n"
+        "---\n\n"
+        "*Generated by ICDEV Compliance Engine v{{icdev_version}} on {{generation_timestamp}}*\n\n"
+        "{{cui_banner_bottom}}\n"
+    )
+
+
+def _get_project_data(conn, project_id):
+    """Load project record from database."""
+    row = conn.execute(
+        "SELECT * FROM projects WHERE id = ?", (project_id,)
+    ).fetchone()
+    if not row:
+        raise ValueError(f"Project '{project_id}' not found in database.")
+    return dict(row)
+
+
+def _load_cui_config():
+    """Load CUI marking configuration.
+
+    Attempts to import load_cui_config from the cui_marker module;
+    falls back to sensible defaults if unavailable.
+    """
+    try:
+        from tools.compliance.cui_marker import load_cui_config as _load
+        return _load()
+    except Exception:
+        pass
+
+    # Try relative import
+    try:
+        cui_marker_path = Path(__file__).resolve().parent / "cui_marker.py"
+        if cui_marker_path.exists():
+            import importlib.util
+            spec = importlib.util.spec_from_file_location("cui_marker", cui_marker_path)
+            mod = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(mod)
+            return mod.load_cui_config()
+    except Exception:
+        pass
+
+    return {
+        "banner_top": "CUI // SP-CTI",
+        "banner_bottom": "CUI // SP-CTI",
+        "document_header": (
+            "////////////////////////////////////////////////////////////////////\n"
+            "CONTROLLED UNCLASSIFIED INFORMATION (CUI) // SP-CTI\n"
+            "Distribution: Distribution D -- Authorized DoD Personnel Only\n"
+            "////////////////////////////////////////////////////////////////////"
+        ),
+        "document_footer": (
+            "////////////////////////////////////////////////////////////////////\n"
+            "CUI // SP-CTI | Department of Defense\n"
+            "////////////////////////////////////////////////////////////////////"
+        ),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Data retrieval
+# ---------------------------------------------------------------------------
+
+def _get_cssp_assessments(conn, project_id):
+    """Retrieve all CSSP assessment results for a project."""
+    rows = conn.execute(
+        """SELECT * FROM cssp_assessments
+           WHERE project_id = ?
+           ORDER BY functional_area, requirement_id""",
+        (project_id,),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def _get_cssp_incidents(conn, project_id):
+    """Retrieve all CSSP incidents for a project."""
+    rows = conn.execute(
+        """SELECT * FROM cssp_incidents
+           WHERE project_id = ?
+           ORDER BY detected_at DESC""",
+        (project_id,),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def _get_cssp_vuln_management(conn, project_id):
+    """Retrieve latest vulnerability scan results for a project."""
+    rows = conn.execute(
+        """SELECT * FROM cssp_vuln_management
+           WHERE project_id = ?
+           ORDER BY scan_date DESC""",
+        (project_id,),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def _get_cssp_certification(conn, project_id):
+    """Retrieve certification status for a project."""
+    row = conn.execute(
+        "SELECT * FROM cssp_certifications WHERE project_id = ?",
+        (project_id,),
+    ).fetchone()
+    return dict(row) if row else {}
+
+
+def _get_stig_findings(conn, project_id):
+    """Retrieve STIG finding counts grouped by severity and status."""
+    rows = conn.execute(
+        """SELECT severity, status, COUNT(*) as cnt
+           FROM stig_findings WHERE project_id = ?
+           GROUP BY severity, status""",
+        (project_id,),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def _get_project_controls(conn, project_id):
+    """Retrieve control implementation status for a project."""
+    rows = conn.execute(
+        """SELECT * FROM project_controls
+           WHERE project_id = ?
+           ORDER BY control_id""",
+        (project_id,),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+def _get_ssp_status(conn, project_id):
+    """Retrieve latest SSP document status."""
+    row = conn.execute(
+        """SELECT version, status, system_name, approved_by, approved_at, created_at
+           FROM ssp_documents WHERE project_id = ?
+           ORDER BY created_at DESC LIMIT 1""",
+        (project_id,),
+    ).fetchone()
+    return dict(row) if row else {}
+
+
+def _get_poam_status(conn, project_id):
+    """Retrieve POA&M item summary."""
+    rows = conn.execute(
+        """SELECT severity, status, COUNT(*) as cnt
+           FROM poam_items WHERE project_id = ?
+           GROUP BY severity, status""",
+        (project_id,),
+    ).fetchall()
+    return [dict(r) for r in rows]
+
+
+# ---------------------------------------------------------------------------
+# Score calculation
+# ---------------------------------------------------------------------------
+
+def _calculate_functional_area_scores(assessments):
+    """Calculate a compliance score for each functional area.
+
+    Score formula:
+        score = 100 * (satisfied + partially*0.5 + risk_accepted*0.75) / total
+
+    Returns:
+        dict mapping functional area name to a dict with score, total, and
+        per-status counts.
+    """
+    area_data = {area: [] for area in FUNCTIONAL_AREAS}
+    for a in assessments:
+        fa = a.get("functional_area")
+        if fa in area_data:
+            area_data[fa].append(a)
+
+    results = {}
+    for area in FUNCTIONAL_AREAS:
+        items = area_data[area]
+        total = len(items)
+        if total == 0:
+            results[area] = {
+                "score": 0.0,
+                "total": 0,
+                "satisfied": 0,
+                "partially_satisfied": 0,
+                "not_satisfied": 0,
+                "not_applicable": 0,
+                "not_assessed": 0,
+                "risk_accepted": 0,
+            }
+            continue
+
+        satisfied = sum(1 for i in items if i["status"] == "satisfied")
+        partially = sum(1 for i in items if i["status"] == "partially_satisfied")
+        not_satisfied = sum(1 for i in items if i["status"] == "not_satisfied")
+        not_applicable = sum(1 for i in items if i["status"] == "not_applicable")
+        not_assessed = sum(1 for i in items if i["status"] == "not_assessed")
+        risk_accepted = sum(1 for i in items if i["status"] == "risk_accepted")
+
+        # Denominator excludes not_applicable
+        scoreable = total - not_applicable
+        if scoreable > 0:
+            score = 100.0 * (
+                satisfied + partially * 0.5 + risk_accepted * 0.75
+            ) / scoreable
+        else:
+            score = 100.0  # All N/A means fully compliant for this area
+
+        results[area] = {
+            "score": round(score, 1),
+            "total": total,
+            "satisfied": satisfied,
+            "partially_satisfied": partially,
+            "not_satisfied": not_satisfied,
+            "not_applicable": not_applicable,
+            "not_assessed": not_assessed,
+            "risk_accepted": risk_accepted,
+        }
+
+    return results
+
+
+def _calculate_overall_status(area_scores):
+    """Determine overall status from area scores.
+
+    Returns:
+        tuple of (overall_score, overall_status_label)
+    """
+    scoreable_areas = [v for v in area_scores.values() if v["total"] > 0]
+    if not scoreable_areas:
+        return 0.0, "Non-Compliant"
+
+    overall = sum(a["score"] for a in scoreable_areas) / len(scoreable_areas)
+    overall = round(overall, 1)
+
+    if overall >= 80:
+        status = "Compliant"
+    elif overall >= 50:
+        status = "Partially Compliant"
+    else:
+        status = "Non-Compliant"
+
+    return overall, status
+
+
+# ---------------------------------------------------------------------------
+# Section builders
+# ---------------------------------------------------------------------------
+
+def _build_functional_area_scores_table(area_scores, overall_score, overall_status):
+    """Build a markdown table summarising per-area scores."""
+    lines = [
+        "| Functional Area | Score | Requirements | Satisfied | Partial | Not Satisfied | Risk Accepted | N/A |",
+        "|-----------------|------:|-------------:|----------:|--------:|--------------:|--------------:|----:|",
+    ]
+    for area in FUNCTIONAL_AREAS:
+        s = area_scores.get(area, {})
+        lines.append(
+            f"| {area} | {s.get('score', 0.0):.1f}% "
+            f"| {s.get('total', 0)} "
+            f"| {s.get('satisfied', 0)} "
+            f"| {s.get('partially_satisfied', 0)} "
+            f"| {s.get('not_satisfied', 0)} "
+            f"| {s.get('risk_accepted', 0)} "
+            f"| {s.get('not_applicable', 0)} |"
+        )
+    lines.append(
+        f"| **Overall** | **{overall_score:.1f}%** | | | | | | |"
+    )
+    lines.append("")
+    lines.append(f"**Overall Status:** {overall_status}")
+    return "\n".join(lines)
+
+
+def _build_functional_area_details(assessments, area_scores):
+    """Build markdown detail sections for each functional area.
+
+    Each area gets a sub-heading and a table listing every requirement
+    with its status, evidence description, and notes.
+    """
+    area_data = {area: [] for area in FUNCTIONAL_AREAS}
+    for a in assessments:
+        fa = a.get("functional_area")
+        if fa in area_data:
+            area_data[fa].append(a)
+
+    sections = []
+    for area in FUNCTIONAL_AREAS:
+        items = area_data[area]
+        s = area_scores.get(area, {})
+        score = s.get("score", 0.0)
+
+        sections.append(f"### {area} ({score:.1f}%)")
+        sections.append("")
+
+        if not items:
+            sections.append("*No assessments recorded for this functional area.*")
+            sections.append("")
+            continue
+
+        sections.append(
+            "| Requirement ID | Status | Evidence | Notes |"
+        )
+        sections.append(
+            "|----------------|--------|----------|-------|"
+        )
+        for item in sorted(items, key=lambda x: x.get("requirement_id", "")):
+            req_id = item.get("requirement_id", "N/A")
+            status = item.get("status", "not_assessed")
+            evidence = (item.get("evidence_description") or "").replace("\n", " ").strip()
+            notes = (item.get("notes") or "").replace("\n", " ").strip()
+            # Truncate long fields for table readability
+            if len(evidence) > 80:
+                evidence = evidence[:77] + "..."
+            if len(notes) > 80:
+                notes = notes[:77] + "..."
+            sections.append(
+                f"| {req_id} | {status} | {evidence} | {notes} |"
+            )
+        sections.append("")
+
+    return "\n".join(sections)
+
+
+def _build_stig_summary_table(stig_findings):
+    """Build a markdown table of STIG findings by severity and status."""
+    # Aggregate
+    counts = {}
+    for cat in STIG_CATEGORIES:
+        counts[cat] = {"Open": 0, "NotAFinding": 0, "Not_Applicable": 0, "Not_Reviewed": 0}
+
+    for row in stig_findings:
+        sev = row.get("severity", "")
+        st = row.get("status", "")
+        cnt = row.get("cnt", 0)
+        if sev in counts and st in counts[sev]:
+            counts[sev][st] += cnt
+
+    lines = [
+        "| Severity | Open | Not a Finding | Not Applicable | Not Reviewed | Total |",
+        "|----------|-----:|--------------:|---------------:|-------------:|------:|",
+    ]
+    grand_total = 0
+    for cat in STIG_CATEGORIES:
+        c = counts[cat]
+        total = sum(c.values())
+        grand_total += total
+        lines.append(
+            f"| {cat} | {c['Open']} | {c['NotAFinding']} "
+            f"| {c['Not_Applicable']} | {c['Not_Reviewed']} | {total} |"
+        )
+    lines.append(f"| **Total** | | | | | **{grand_total}** |")
+
+    cat1_open = counts["CAT1"]["Open"]
+    gate = "PASS" if cat1_open == 0 else "FAIL"
+    return "\n".join(lines), gate, cat1_open
+
+
+def _build_vuln_summary_table(vuln_records):
+    """Build a markdown table summarising vulnerability scan results."""
+    if not vuln_records:
+        return "*No vulnerability scan results recorded.*", "N/A"
+
+    lines = [
+        "| Scan Date | Type | Scanner | Critical | High | Medium | Low | Remediated | Risk Accepted | SLA |",
+        "|-----------|------|---------|--------::|-----:|-------:|----:|-----------:|--------------:|-----|",
+    ]
+    all_sla = True
+    for v in vuln_records:
+        sla_flag = "Yes" if v.get("sla_compliant", 1) else "No"
+        if not v.get("sla_compliant", 1):
+            all_sla = False
+        lines.append(
+            f"| {v.get('scan_date', 'N/A')} "
+            f"| {v.get('scan_type', 'N/A')} "
+            f"| {v.get('scanner', 'N/A')} "
+            f"| {v.get('critical_count', 0)} "
+            f"| {v.get('high_count', 0)} "
+            f"| {v.get('medium_count', 0)} "
+            f"| {v.get('low_count', 0)} "
+            f"| {v.get('remediated_count', 0)} "
+            f"| {v.get('accepted_risk_count', 0)} "
+            f"| {sla_flag} |"
+        )
+
+    sla_status = "Compliant" if all_sla else "Non-Compliant"
+    return "\n".join(lines), sla_status
+
+
+def _build_incident_summary_table(incidents):
+    """Build a markdown table of incidents and compute open count / MTTC."""
+    if not incidents:
+        return "*No incidents recorded.*", 0, "N/A"
+
+    lines = [
+        "| Incident ID | Severity | Category | Status | Detected | Contained | Resolved |",
+        "|-------------|----------|----------|--------|----------|-----------|----------|",
+    ]
+    open_count = 0
+    contain_deltas = []
+
+    for inc in incidents:
+        inc_id = inc.get("incident_id", "N/A")
+        sev = inc.get("severity", "N/A")
+        cat = inc.get("category", "N/A")
+        status = inc.get("status", "N/A")
+        detected = inc.get("detected_at", "N/A")
+        contained = inc.get("contained_at", "")
+        resolved = inc.get("resolved_at", "")
+
+        if status not in ("closed", "lessons_learned", "recovered"):
+            open_count += 1
+
+        # Compute containment time
+        if detected and contained and detected != "N/A":
+            try:
+                dt_detected = datetime.fromisoformat(detected)
+                dt_contained = datetime.fromisoformat(contained)
+                delta_hours = (dt_contained - dt_detected).total_seconds() / 3600.0
+                contain_deltas.append(delta_hours)
+            except (ValueError, TypeError):
+                pass
+
+        lines.append(
+            f"| {inc_id} | {sev} | {cat} "
+            f"| {status} | {detected} | {contained or 'N/A'} | {resolved or 'N/A'} |"
+        )
+
+    if contain_deltas:
+        mean_hours = sum(contain_deltas) / len(contain_deltas)
+        mttc = f"{mean_hours:.1f} hours"
+    else:
+        mttc = "N/A"
+
+    return "\n".join(lines), open_count, mttc
+
+
+def _build_findings_table(assessments):
+    """Build a table of not_satisfied requirements grouped by severity.
+
+    Since CSSP assessments do not have an inherent severity, we infer
+    priority by functional area ordering (Identify > Protect > Detect >
+    Respond > Sustain) and list all findings.
+    """
+    findings = [
+        a for a in assessments if a.get("status") == "not_satisfied"
+    ]
+    if not findings:
+        return "*No findings requiring remediation.*"
+
+    lines = [
+        "| Functional Area | Requirement ID | Evidence | Notes |",
+        "|-----------------|----------------|----------|-------|",
+    ]
+    for area in FUNCTIONAL_AREAS:
+        area_findings = [f for f in findings if f.get("functional_area") == area]
+        for f in sorted(area_findings, key=lambda x: x.get("requirement_id", "")):
+            evidence = (f.get("evidence_description") or "").replace("\n", " ").strip()
+            notes = (f.get("notes") or "").replace("\n", " ").strip()
+            if len(evidence) > 60:
+                evidence = evidence[:57] + "..."
+            if len(notes) > 60:
+                notes = notes[:57] + "..."
+            lines.append(
+                f"| {area} | {f.get('requirement_id', 'N/A')} "
+                f"| {evidence} | {notes} |"
+            )
+
+    return "\n".join(lines)
+
+
+def _build_evidence_summary_table(assessments):
+    """Count evidence artifacts by functional area."""
+    area_counts = {area: {"with_evidence": 0, "without_evidence": 0, "total": 0}
+                   for area in FUNCTIONAL_AREAS}
+
+    for a in assessments:
+        fa = a.get("functional_area")
+        if fa not in area_counts:
+            continue
+        area_counts[fa]["total"] += 1
+        if a.get("evidence_path") or a.get("evidence_description"):
+            area_counts[fa]["with_evidence"] += 1
+        else:
+            area_counts[fa]["without_evidence"] += 1
+
+    lines = [
+        "| Functional Area | Total Requirements | With Evidence | Without Evidence | Coverage |",
+        "|-----------------|-------------------:|--------------:|-----------------:|---------:|",
+    ]
+    for area in FUNCTIONAL_AREAS:
+        c = area_counts[area]
+        coverage = (
+            f"{100.0 * c['with_evidence'] / c['total']:.0f}%"
+            if c["total"] > 0 else "N/A"
+        )
+        lines.append(
+            f"| {area} | {c['total']} | {c['with_evidence']} "
+            f"| {c['without_evidence']} | {coverage} |"
+        )
+
+    total_all = sum(c["total"] for c in area_counts.values())
+    total_with = sum(c["with_evidence"] for c in area_counts.values())
+    total_without = sum(c["without_evidence"] for c in area_counts.values())
+    total_cov = f"{100.0 * total_with / total_all:.0f}%" if total_all > 0 else "N/A"
+    lines.append(
+        f"| **Total** | **{total_all}** | **{total_with}** "
+        f"| **{total_without}** | **{total_cov}** |"
+    )
+
+    return "\n".join(lines)
+
+
+def _build_remediation_table(assessments):
+    """Build table of findings needing remediation with target dates.
+
+    For items without explicit milestone dates we assign default
+    remediation windows: 30 days for Identify/Protect, 14 days for
+    Detect/Respond, 60 days for Sustain.
+    """
+    DEFAULT_WINDOWS = {
+        "Identify": 30,
+        "Protect": 30,
+        "Detect": 14,
+        "Respond": 14,
+        "Sustain": 60,
+    }
+
+    needing_remediation = [
+        a for a in assessments
+        if a.get("status") in ("not_satisfied", "partially_satisfied")
+    ]
+    if not needing_remediation:
+        return "*No items require remediation at this time.*"
+
+    now = datetime.now(timezone.utc)
+    lines = [
+        "| Requirement ID | Functional Area | Current Status | Target Date | Priority |",
+        "|----------------|-----------------|----------------|-------------|----------|",
+    ]
+
+    for item in sorted(needing_remediation,
+                       key=lambda x: (FUNCTIONAL_AREAS.index(x.get("functional_area", "Sustain"))
+                                      if x.get("functional_area") in FUNCTIONAL_AREAS else 99,
+                                      x.get("requirement_id", ""))):
+        req_id = item.get("requirement_id", "N/A")
+        fa = item.get("functional_area", "N/A")
+        status = item.get("status", "N/A")
+
+        # Determine target date
+        window_days = DEFAULT_WINDOWS.get(fa, 30)
+        from datetime import timedelta
+        target = (now + timedelta(days=window_days)).strftime("%Y-%m-%d")
+
+        # Priority based on status and area
+        if status == "not_satisfied" and fa in ("Identify", "Protect"):
+            priority = "High"
+        elif status == "not_satisfied":
+            priority = "Medium"
+        else:
+            priority = "Low"
+
+        lines.append(
+            f"| {req_id} | {fa} | {status} | {target} | {priority} |"
+        )
+
+    return "\n".join(lines)
+
+
+def _build_controls_summary(controls):
+    """Aggregate control implementation counts."""
+    implemented = sum(
+        1 for c in controls if c.get("implementation_status") == "implemented"
+    )
+    planned = sum(
+        1 for c in controls
+        if c.get("implementation_status") in ("planned", "partially_implemented")
+    )
+    na = sum(
+        1 for c in controls if c.get("implementation_status") == "not_applicable"
+    )
+    compensating = sum(
+        1 for c in controls if c.get("implementation_status") == "compensating"
+    )
+    return {
+        "total": len(controls),
+        "implemented": implemented,
+        "planned": planned,
+        "not_applicable": na,
+        "compensating": compensating,
+    }
+
+
+def _build_poam_summary(poam_rows):
+    """Aggregate POA&M item counts."""
+    total = 0
+    open_count = 0
+    in_progress = 0
+    completed = 0
+    accepted_risk = 0
+    datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+    for row in poam_rows:
+        cnt = row.get("cnt", 0)
+        status = row.get("status", "")
+        total += cnt
+        if status == "open":
+            open_count += cnt
+        elif status == "in_progress":
+            in_progress += cnt
+        elif status == "completed":
+            completed += cnt
+        elif status == "accepted_risk":
+            accepted_risk += cnt
+
+    return {
+        "total": total,
+        "open": open_count,
+        "in_progress": in_progress,
+        "completed": completed,
+        "accepted_risk": accepted_risk,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Variable substitution & CUI markings
+# ---------------------------------------------------------------------------
+
+def _apply_cui_markings(content, cui_config):
+    """Apply CUI header and footer banners to the report content."""
+    header = cui_config.get("document_header", "").strip()
+    footer = cui_config.get("document_footer", "").strip()
+    banner_top = cui_config.get("banner_top", "CUI // SP-CTI")
+    cui_config.get("banner_bottom", "CUI // SP-CTI")
+
+    # If the content already contains the banner, skip
+    if banner_top in content:
+        return content
+
+    return f"{header}\n\n{content.strip()}\n\n{footer}\n"
+
+
+def _substitute_variables(template, variables):
+    """Replace {{variable_name}} placeholders in the template."""
+    def replacer(match):
+        key = match.group(1).strip()
+        return str(variables.get(key, match.group(0)))
+    return re.sub(r"\{\{(\w+)\}\}", replacer, template)
+
+
+# ---------------------------------------------------------------------------
+# Audit logging
+# ---------------------------------------------------------------------------
+
+def _log_audit_event(conn, project_id, action, details, file_path):
+    """Log an audit trail event for CSSP report generation."""
+    try:
+        conn.execute(
+            """INSERT INTO audit_trail
+               (project_id, event_type, actor, action, details,
+                affected_files, classification)
+               VALUES (?, ?, ?, ?, ?, ?, ?)""",
+            (
+                project_id,
+                "cssp_report_generated",
+                "icdev-compliance-engine",
+                action,
+                json.dumps(details),
+                json.dumps([str(file_path)]),
+                "CUI",
+            ),
+        )
+        conn.commit()
+    except Exception as e:
+        print(f"Warning: Could not log audit event: {e}", file=sys.stderr)
+
+
+# ---------------------------------------------------------------------------
+# Main generator
+# ---------------------------------------------------------------------------
+
+def generate_cssp_report(project_id, output_path=None, db_path=None):
+    """Generate a CSSP certification report for a project.
+
+    Args:
+        project_id: The project identifier.
+        output_path: Override output directory or file path.
+        db_path: Override database path.
+
+    Returns:
+        dict with ``file_path`` and metadata about the generated report.
+    """
+    conn = get_connection(db_path=db_path)
+    try:
+        # 1. Load project data
+        project = _get_project_data(conn, project_id)
+        project_name = project.get("name", project_id)
+
+        # 2. Load template
+        template = _load_template()
+
+        # 3. Query all supporting data
+        assessments = _get_cssp_assessments(conn, project_id)
+        incidents = _get_cssp_incidents(conn, project_id)
+        vuln_records = _get_cssp_vuln_management(conn, project_id)
+        certification = _get_cssp_certification(conn, project_id)
+        stig_findings = _get_stig_findings(conn, project_id)
+        controls = _get_project_controls(conn, project_id)
+        ssp_data = _get_ssp_status(conn, project_id)
+        poam_rows = _get_poam_status(conn, project_id)
+
+        # 4. Calculate scores per functional area
+        area_scores = _calculate_functional_area_scores(assessments)
+        overall_score, overall_status = _calculate_overall_status(area_scores)
+
+        # 5. Build section content
+        fa_scores_table = _build_functional_area_scores_table(
+            area_scores, overall_score, overall_status
+        )
+        fa_details = _build_functional_area_details(assessments, area_scores)
+        stig_table, stig_gate, cat1_open = _build_stig_summary_table(stig_findings)
+        vuln_table, vuln_sla = _build_vuln_summary_table(vuln_records)
+        incident_table, open_incidents, mttc = _build_incident_summary_table(incidents)
+        findings_table = _build_findings_table(assessments)
+        evidence_table = _build_evidence_summary_table(assessments)
+        remediation_table = _build_remediation_table(assessments)
+        ctrl_summary = _build_controls_summary(controls)
+        poam_summary = _build_poam_summary(poam_rows)
+
+        # Load CUI config for banner variables
+        cui_config = _load_cui_config()
+
+        # Determine version number
+        conn.execute(
+            """SELECT MAX(CAST(
+                   CASE WHEN status IS NOT NULL THEN 1 ELSE 0 END AS INTEGER
+               )) as cnt FROM cssp_certifications WHERE project_id = ?""",
+            (project_id,),
+        ).fetchone()
+        # Count existing reports to determine version
+        report_count_row = conn.execute(
+            """SELECT COUNT(*) as cnt FROM audit_trail
+               WHERE project_id = ? AND event_type = 'cssp_report_generated'""",
+            (project_id,),
+        ).fetchone()
+        report_count = report_count_row["cnt"] if report_count_row else 0
+        new_version = f"{report_count + 1}.0"
+
+        now = datetime.now(timezone.utc)
+
+        # 6. Build the complete variable substitution dict
+        variables = {
+            # Project info
+            "project_name": project_name,
+            "project_id": project_id,
+            "classification": project.get("classification", "CUI"),
+            "system_type": project.get("type", "webapp"),
+
+            # Report metadata
+            "report_version": new_version,
+            "date_prepared": now.strftime("%Y-%m-%d"),
+            "prepared_by": "ICDEV Compliance Engine",
+            "generation_timestamp": now.strftime("%Y-%m-%d %H:%M UTC"),
+            "icdev_version": "1.0",
+
+            # Certification info
+            "certification_status": certification.get("status", "in_progress"),
+            "cssp_provider": certification.get("cssp_provider", "TBD"),
+            "ato_boundary": certification.get("ato_boundary", "TBD"),
+            "risk_level": certification.get("risk_level", "TBD"),
+            "authorizing_official": certification.get("authorizing_official", "TBD"),
+            "next_assessment_date": certification.get("next_assessment_date", "TBD"),
+            "continuous_monitoring_plan": certification.get(
+                "continuous_monitoring_plan", "Continuous monitoring plan pending."
+            ),
+            "certified_date": certification.get("certified_date", "N/A"),
+            "expiration_date": certification.get("expiration_date", "N/A"),
+            "conditions": certification.get("conditions", "None"),
+
+            # Overall scores
+            "overall_score": f"{overall_score:.1f}",
+            "overall_status": overall_status,
+
+            # Functional area tables
+            "functional_area_scores_table": fa_scores_table,
+            "functional_area_details": fa_details,
+
+            # STIG
+            "stig_summary_table": stig_table,
+            "stig_gate_status": stig_gate,
+            "cat1_open_count": str(cat1_open),
+
+            # Vulnerability management
+            "vuln_summary_table": vuln_table,
+            "vuln_sla_status": vuln_sla,
+            "total_vuln_scans": str(len(vuln_records)),
+            "total_vuln_critical": str(sum(v.get("critical_count", 0) for v in vuln_records)),
+            "total_vuln_high": str(sum(v.get("high_count", 0) for v in vuln_records)),
+
+            # Incidents
+            "incident_summary_table": incident_table,
+            "open_incidents_count": str(open_incidents),
+            "total_incidents": str(len(incidents)),
+            "mean_time_to_contain": mttc,
+
+            # Controls
+            "controls_mapped": str(ctrl_summary["total"]),
+            "controls_implemented": str(ctrl_summary["implemented"]),
+            "controls_planned": str(ctrl_summary["planned"]),
+            "controls_na": str(ctrl_summary["not_applicable"]),
+            "controls_compensating": str(ctrl_summary["compensating"]),
+
+            # SSP
+            "ssp_version": ssp_data.get("version", "N/A"),
+            "ssp_status": ssp_data.get("status", "Not Generated"),
+            "ssp_system_name": ssp_data.get("system_name", "N/A"),
+
+            # POAM
+            "poam_total": str(poam_summary["total"]),
+            "poam_open": str(poam_summary["open"]),
+            "poam_in_progress": str(poam_summary["in_progress"]),
+            "poam_completed": str(poam_summary["completed"]),
+            "poam_accepted_risk": str(poam_summary["accepted_risk"]),
+            "poam_overdue": "0",  # Computed separately if needed
+
+            # Findings and evidence
+            "findings_table": findings_table,
+            "evidence_summary_table": evidence_table,
+            "remediation_table": remediation_table,
+
+            # Assessment counts
+            "total_assessments": str(len(assessments)),
+            "assessments_satisfied": str(sum(
+                1 for a in assessments if a.get("status") == "satisfied"
+            )),
+            "assessments_not_satisfied": str(sum(
+                1 for a in assessments if a.get("status") == "not_satisfied"
+            )),
+
+            # CUI banners
+            "cui_banner_top": cui_config.get("document_header", cui_config.get("banner_top", "CUI // SP-CTI")),
+            "cui_banner_bottom": cui_config.get("document_footer", cui_config.get("banner_bottom", "CUI // SP-CTI")),
+        }
+
+        # Per-area score variables (e.g., identify_score, protect_score, ...)
+        for area in FUNCTIONAL_AREAS:
+            key_prefix = area.lower()
+            s = area_scores.get(area, {})
+            variables[f"{key_prefix}_score"] = f"{s.get('score', 0.0):.1f}"
+            variables[f"{key_prefix}_total"] = str(s.get("total", 0))
+            variables[f"{key_prefix}_satisfied"] = str(s.get("satisfied", 0))
+            variables[f"{key_prefix}_not_satisfied"] = str(s.get("not_satisfied", 0))
+
+        # Compute POA&M overdue count directly
+        today = now.strftime("%Y-%m-%d")
+        overdue_row = conn.execute(
+            """SELECT COUNT(*) as cnt FROM poam_items
+               WHERE project_id = ? AND status IN ('open', 'in_progress')
+               AND milestone_date < ? AND milestone_date IS NOT NULL""",
+            (project_id, today),
+        ).fetchone()
+        variables["poam_overdue"] = str(overdue_row["cnt"] if overdue_row else 0)
+
+        # 7. Substitute variables in template
+        report_content = _substitute_variables(template, variables)
+
+        # 8. Apply CUI markings
+        report_content = _apply_cui_markings(report_content, cui_config)
+
+        # 9. Determine output file path
+        if output_path:
+            out_path = Path(output_path)
+            if out_path.is_dir() or str(output_path).endswith("/") or str(output_path).endswith("\\"):
+                out_dir = out_path
+                out_file = out_dir / f"cssp-report-v{new_version}.md"
+            else:
+                out_file = out_path
+        else:
+            dir_path = project.get("directory_path", "")
+            if dir_path:
+                out_dir = Path(dir_path) / "compliance"
+            else:
+                out_dir = BASE_DIR / "projects" / project_name / "compliance"
+            out_file = out_dir / f"cssp-report-v{new_version}.md"
+
+        out_file.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(out_file, "w", encoding="utf-8") as f:
+            f.write(report_content)
+
+        # 10. Record version in cssp_certifications table
+        try:
+            conn.execute(
+                """INSERT OR REPLACE INTO cssp_certifications
+                   (project_id, certification_type, status, cssp_provider,
+                    ato_boundary, risk_level, authorizing_official,
+                    next_assessment_date, continuous_monitoring_plan,
+                    updated_at)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                (
+                    project_id,
+                    certification.get("certification_type", "CSSP+ATO"),
+                    certification.get("status", "in_progress"),
+                    certification.get("cssp_provider", "TBD"),
+                    certification.get("ato_boundary", "TBD"),
+                    certification.get("risk_level", "moderate"),
+                    certification.get("authorizing_official", "TBD"),
+                    certification.get("next_assessment_date"),
+                    certification.get("continuous_monitoring_plan"),
+                    now.strftime("%Y-%m-%d %H:%M:%S"),
+                ),
+            )
+            conn.commit()
+        except Exception as e:
+            print(
+                f"Warning: Could not update cssp_certifications: {e}",
+                file=sys.stderr,
+            )
+
+        # 11. Log audit event
+        audit_details = {
+            "version": new_version,
+            "overall_score": overall_score,
+            "overall_status": overall_status,
+            "total_assessments": len(assessments),
+            "total_incidents": len(incidents),
+            "total_vuln_scans": len(vuln_records),
+            "stig_gate": stig_gate,
+            "output_file": str(out_file),
+        }
+        _log_audit_event(
+            conn, project_id,
+            f"CSSP report v{new_version} generated",
+            audit_details,
+            out_file,
+        )
+
+        # 12. Print summary
+        print("CSSP report generated successfully:")
+        print(f"  File:            {out_file}")
+        print(f"  Version:         {new_version}")
+        print(f"  Project:         {project_name}")
+        print(f"  Overall Score:   {overall_score:.1f}%")
+        print(f"  Overall Status:  {overall_status}")
+        print(f"  Assessments:     {len(assessments)}")
+        print(f"  Incidents:       {len(incidents)}")
+        print(f"  Vuln Scans:      {len(vuln_records)}")
+        print(f"  STIG Gate:       {stig_gate}")
+
+        # 13. Return file path and metadata
+        return {
+            "file_path": str(out_file),
+            "version": new_version,
+            "project_id": project_id,
+            "project_name": project_name,
+            "overall_score": overall_score,
+            "overall_status": overall_status,
+            "functional_area_scores": {
+                area: area_scores[area]["score"] for area in FUNCTIONAL_AREAS
+            },
+            "stig_gate": stig_gate,
+            "total_assessments": len(assessments),
+            "total_incidents": len(incidents),
+            "total_vuln_scans": len(vuln_records),
+            "controls_mapped": ctrl_summary["total"],
+            "generated_at": now.isoformat(),
+        }
+
+    finally:
+        conn.close()
+
+
+# ---------------------------------------------------------------------------
+# CLI entry point
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Generate CSSP certification report"
+    )
+    parser.add_argument("--project-id", required=True, help="Project ID")
+    parser.add_argument("--output-dir", help="Output directory")
+    parser.add_argument(
+        "--db-path", type=Path, default=DB_PATH, help="Database path"
+    )
+    parser.add_argument("--json", action="store_true", dest="json_output", help="JSON output")
+    args = parser.parse_args()
+
+    try:
+        result = generate_cssp_report(
+            args.project_id, args.output_dir, args.db_path
+        )
+        print(f"\nCSSP report generated: {result}")
+    except (FileNotFoundError, ValueError) as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        sys.exit(1)