icdev 0.0.3__py3-none-any.whl

tools/audit_engine/ai_advisor.py

@@ -0,0 +1,906 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+# Controlled by: Department of Defense
+# CUI Category: CTI
+# Distribution: D
+# POC: ICDEV System Administrator
+"""AI Advisor — Dual-ranked compliance improvement recommendations.
+
+Analyzes audit results and generates prioritized recommendations ranked
+by both impact (biggest score increase) and effort (easiest to implement).
+Combined view shows optimal path to improve compliance posture.
+
+LLM routing:
+  - Scanner tier: deterministic control-to-recommendation mapping (air-gap safe)
+  - Worker tier: nuanced advice for complex multi-control gaps (LLM-assisted)
+
+Usage:
+    python tools/audit_engine/ai_advisor.py --audit-file result.json --json
+    python tools/audit_engine/ai_advisor.py --audit-file result.json --regime nist_800_53 --json
+"""
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional
+
+BASE_DIR = Path(__file__).resolve().parent.parent.parent
+
+# Effort levels: lower = easier to implement
+EFFORT_LEVELS = {
+    "config_change": 1,      # Change a YAML/config setting
+    "add_file": 2,           # Add a missing file (e.g., .gitignore, SECURITY.md)
+    "code_annotation": 3,    # Add CUI markings, comments, decorators
+    "tool_enable": 4,        # Enable an existing tool/scanner
+    "code_pattern": 5,       # Add logging, error handling patterns
+    "feature_add": 6,        # Implement new feature (auth, encryption)
+    "architecture": 7,       # Architectural change (boundary, mesh)
+    "process_change": 8,     # Organizational/process change
+}
+
+# Control-family to recommendation mapping (deterministic, scanner-tier)
+RECOMMENDATION_CATALOG = {
+    # Access Control
+    "AC-2": {
+        "title": "Implement account management lifecycle",
+        "description": "Add user provisioning, de-provisioning, and periodic review processes. "
+                       "Use RBAC with role assignment and session management.",
+        "effort": "feature_add",
+        "impact": "high",
+        "steps": [
+            "Add user role definitions in config (args/)",
+            "Implement login/session management with timeout",
+            "Add account lockout after failed attempts",
+            "Create periodic access review automation",
+        ],
+    },
+    "AC-3": {
+        "title": "Add access enforcement (RBAC/ABAC)",
+        "description": "Implement role-based or attribute-based access control "
+                       "on all protected endpoints and resources.",
+        "effort": "feature_add",
+        "impact": "high",
+        "steps": [
+            "Define roles and permissions in configuration",
+            "Add @require_auth / @require_role decorators to endpoints",
+            "Implement permission checking middleware",
+            "Test with least-privilege scenarios",
+        ],
+    },
+    "AC-6": {
+        "title": "Enforce least privilege",
+        "description": "Run services as non-root, use read-only filesystems, "
+                       "minimize permissions granted to each component.",
+        "effort": "config_change",
+        "impact": "medium",
+        "steps": [
+            "Set containers to run as non-root user",
+            "Apply read-only root filesystem in K8s pods",
+            "Remove unnecessary capabilities",
+            "Review and minimize IAM permissions",
+        ],
+    },
+    "AC-16": {
+        "title": "Add CUI classification markings",
+        "description": "Apply CUI // SP-CTI header markings to all source files "
+                       "per NIST 800-53 AC-16.",
+        "effort": "code_annotation",
+        "impact": "medium",
+        "steps": [
+            "Run: python tools/compliance/cui_marker.py --file <path> --marking 'CUI // SP-CTI'",
+            "Add CUI header template to file scaffolding tools",
+            "Verify with: python tools/audit_engine/scanner.py --target . --json",
+        ],
+    },
+
+    # Audit and Accountability
+    "AU-2": {
+        "title": "Implement event logging framework",
+        "description": "Add structured logging for security-relevant events including "
+                       "authentication, authorization, data access, and administrative actions.",
+        "effort": "code_pattern",
+        "impact": "high",
+        "steps": [
+            "Import and configure Python logging module",
+            "Log authentication events (login, logout, failed attempts)",
+            "Log authorization decisions (access granted/denied)",
+            "Log data modification events (create, update, delete)",
+        ],
+    },
+    "AU-9": {
+        "title": "Protect audit trail integrity",
+        "description": "Ensure audit logs are append-only and cannot be modified or deleted. "
+                       "ICDEV already uses append-only audit_trail table (D6).",
+        "effort": "config_change",
+        "impact": "high",
+        "steps": [
+            "Verify no UPDATE/DELETE on audit tables",
+            "Enable WAL mode for audit database",
+            "Add audit log backup/rotation",
+        ],
+    },
+
+    # Configuration Management
+    "CM-8": {
+        "title": "Generate Software Bill of Materials",
+        "description": "Generate CycloneDX SBOM for full component inventory.",
+        "effort": "tool_enable",
+        "impact": "medium",
+        "steps": [
+            "Run: python tools/compliance/sbom_generator.py --project-id <id> --project-dir .",
+            "Add SBOM generation to CI/CD pipeline",
+            "Review components for license compliance",
+        ],
+    },
+
+    # Identification and Authentication
+    "IA-5": {
+        "title": "Remove hardcoded secrets",
+        "description": "Eliminate all hardcoded passwords, API keys, and tokens from source code. "
+                       "Use environment variables or secrets manager.",
+        "effort": "code_pattern",
+        "impact": "critical",
+        "steps": [
+            "Run: python tools/security/secret_detector.py --project-dir .",
+            "Move secrets to .env (excluded from git) or K8s secrets",
+            "Use os.environ.get() for all credential access",
+            "Add .env to .gitignore",
+        ],
+    },
+
+    # Risk Assessment
+    "RA-5": {
+        "title": "Enable vulnerability scanning pipeline",
+        "description": "Activate SAST and dependency scanning in CI/CD.",
+        "effort": "tool_enable",
+        "impact": "high",
+        "steps": [
+            "Run: python tools/security/sast_runner.py --project-dir .",
+            "Run: python tools/security/dependency_auditor.py --project-dir .",
+            "Add both to CI/CD pipeline (pre-merge gate)",
+            "Set thresholds: 0 critical, 0 high allowed",
+        ],
+    },
+
+    # System and Services Acquisition
+    "SA-8": {
+        "title": "Apply Secure by Design principles",
+        "description": "Run CISA SbD assessment and address findings.",
+        "effort": "code_pattern",
+        "impact": "medium",
+        "steps": [
+            "Run: python tools/compliance/sbd_assessor.py --project-id <id> --project-dir . --json",
+            "Address each SbD requirement with evidence",
+            "Register exceptions for any accepted risks",
+        ],
+    },
+    "SA-11": {
+        "title": "Add automated developer testing",
+        "description": "Implement test suite with unit tests, integration tests, and SAST.",
+        "effort": "feature_add",
+        "impact": "high",
+        "steps": [
+            "Create tests/ directory with pytest test files",
+            "Add test coverage for critical paths (auth, data access)",
+            "Enable SAST in CI/CD pipeline",
+            "Set minimum coverage threshold (e.g., 80%)",
+        ],
+    },
+
+    # System and Communications Protection
+    "SC-8": {
+        "title": "Enable encryption in transit",
+        "description": "Configure TLS for all network communications.",
+        "effort": "config_change",
+        "impact": "high",
+        "steps": [
+            "Enable HTTPS on all web endpoints",
+            "Configure TLS certificates (Let's Encrypt or CA-signed)",
+            "Enforce HSTS headers",
+            "Disable HTTP fallback",
+        ],
+    },
+    "SC-13": {
+        "title": "Use FIPS-validated cryptography",
+        "description": "Replace non-standard crypto with FIPS 140-3 validated modules.",
+        "effort": "code_pattern",
+        "impact": "high",
+        "steps": [
+            "Use hashlib (SHA-256/384/512) for hashing",
+            "Use cryptography library with FIPS-validated backend",
+            "Avoid MD5, SHA-1, DES for security purposes",
+            "Document crypto inventory",
+        ],
+    },
+
+    # System and Information Integrity
+    "SI-2": {
+        "title": "Remediate known vulnerabilities",
+        "description": "Update dependencies with known CVEs to patched versions.",
+        "effort": "tool_enable",
+        "impact": "critical",
+        "steps": [
+            "Run: python tools/security/dependency_auditor.py --project-dir .",
+            "Update packages with known vulnerabilities",
+            "Pin dependency versions in requirements.txt",
+            "Add dependency audit to CI/CD pipeline",
+        ],
+    },
+    "SI-10": {
+        "title": "Add input validation",
+        "description": "Validate and sanitize all user inputs at system boundaries.",
+        "effort": "code_pattern",
+        "impact": "high",
+        "steps": [
+            "Add input validation on all API endpoints",
+            "Use parameterized queries for all SQL",
+            "Sanitize HTML output to prevent XSS",
+            "Validate file uploads (type, size, content)",
+        ],
+    },
+
+    # Supply Chain
+    "SR-3": {
+        "title": "Implement supply chain controls",
+        "description": "Document software supply chain with SBOM and dependency auditing.",
+        "effort": "tool_enable",
+        "impact": "medium",
+        "steps": [
+            "Generate SBOM: python tools/compliance/sbom_generator.py",
+            "Audit dependencies: python tools/security/dependency_auditor.py",
+            "Review licenses for compatibility",
+            "Add supply chain checks to CI/CD",
+        ],
+    },
+}
+
+# Default recommendations for unmapped controls
+DEFAULT_RECOMMENDATION = {
+    "title": "Assess and implement control",
+    "description": "This control requires manual assessment. Review the control description "
+                   "and implement appropriate technical or procedural controls.",
+    "effort": "process_change",
+    "impact": "medium",
+    "steps": [
+        "Review control requirements in the regime definition",
+        "Assess current implementation status",
+        "Document implementation plan",
+        "Implement and verify",
+    ],
+}
+
+
+def generate_recommendations(
+    audit_result: Dict,
+    regime_id: Optional[str] = None,
+    max_recommendations: int = 20,
+    use_llm: bool = False,
+) -> Dict:
+    """Generate prioritized recommendations from audit results.
+
+    Args:
+        audit_result: Full audit result from engine.run_audit().
+        regime_id: Optional filter to single regime.
+        max_recommendations: Maximum recommendations to return.
+        use_llm: Whether to use LLM for nuanced recommendations.
+
+    Returns:
+        Dict with impact-ranked and effort-ranked recommendation lists.
+    """
+    regime_scores = audit_result.get("regime_scores", {})
+
+    if regime_id:
+        regimes_to_analyze = {regime_id: regime_scores.get(regime_id, {})}
+    else:
+        regimes_to_analyze = regime_scores
+
+    all_recs = []
+    seen_controls = set()
+
+    for rid, scores in regimes_to_analyze.items():
+        if "error" in scores:
+            continue
+
+        for category in scores.get("categories", []):
+            for ctrl in category.get("controls", []):
+                if ctrl["status"] in ("fail", "not_assessed", "partial"):
+                    ctrl_id = ctrl["control_id"]
+
+                    # Deduplicate across regimes (same control, same recommendation)
+                    base_ctrl = ctrl_id.split("-")[0] + "-" + ctrl_id.split("-")[1] if "-" in ctrl_id else ctrl_id
+                    if base_ctrl in seen_controls:
+                        continue
+                    seen_controls.add(base_ctrl)
+
+                    rec = _get_recommendation(ctrl_id, ctrl, rid)
+                    rec["regime_id"] = rid
+                    rec["control_id"] = ctrl_id
+                    rec["control_title"] = ctrl.get("title", "")
+                    rec["current_status"] = ctrl["status"]
+                    rec["severity"] = ctrl.get("severity", "medium")
+                    all_recs.append(rec)
+
+    # Calculate impact scores (how much each fix moves the overall score)
+    for rec in all_recs:
+        rec["impact_score"] = _calculate_impact_score(rec)
+        rec["effort_score"] = EFFORT_LEVELS.get(rec.get("effort", "process_change"), 8)
+        # Combined score: high impact + low effort = best ROI
+        rec["roi_score"] = rec["impact_score"] / max(rec["effort_score"], 1)
+
+    # LLM-enhanced recommendations (worker tier)
+    if use_llm and all_recs:
+        all_recs = _enhance_with_llm(all_recs, audit_result)
+
+    # Sort by different rankings
+    impact_ranked = sorted(all_recs, key=lambda r: r["impact_score"], reverse=True)[:max_recommendations]
+    effort_ranked = sorted(all_recs, key=lambda r: r["effort_score"])[:max_recommendations]
+    roi_ranked = sorted(all_recs, key=lambda r: r["roi_score"], reverse=True)[:max_recommendations]
+
+    # Estimate score improvement if top 5 ROI fixes are applied
+    estimated_improvement = sum(r["impact_score"] for r in roi_ranked[:5])
+
+    return {
+        "success": True,
+        "total_recommendations": len(all_recs),
+        "estimated_improvement_top5": round(min(estimated_improvement, 30), 1),
+        "by_impact": [_format_rec(r, rank + 1) for rank, r in enumerate(impact_ranked)],
+        "by_effort": [_format_rec(r, rank + 1) for rank, r in enumerate(effort_ranked)],
+        "by_roi": [_format_rec(r, rank + 1) for rank, r in enumerate(roi_ranked)],
+        "quick_wins": [
+            _format_rec(r, i + 1) for i, r in enumerate(roi_ranked)
+            if r["effort_score"] <= 3
+        ][:5],
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def _get_recommendation(ctrl_id: str, ctrl_data: Dict, regime_id: str) -> Dict:
+    """Get recommendation for a control from the catalog."""
+    # Direct match
+    if ctrl_id in RECOMMENDATION_CATALOG:
+        return dict(RECOMMENDATION_CATALOG[ctrl_id])
+
+    # Family match (e.g., AC-2(1) -> AC-2)
+    base = ctrl_id.split("(")[0] if "(" in ctrl_id else ctrl_id
+    if base in RECOMMENDATION_CATALOG:
+        return dict(RECOMMENDATION_CATALOG[base])
+
+    # NIST family prefix match
+    family = ctrl_id.split("-")[0] if "-" in ctrl_id else ""
+    family_recs = {k: v for k, v in RECOMMENDATION_CATALOG.items() if k.startswith(family + "-")}
+    if family_recs:
+        # Return the first family match as a starting point
+        rec = dict(next(iter(family_recs.values())))
+        rec["title"] = f"Address {ctrl_id}: {ctrl_data.get('title', '')}"
+        return rec
+
+    # Default
+    rec = dict(DEFAULT_RECOMMENDATION)
+    rec["title"] = f"Implement {ctrl_id}: {ctrl_data.get('title', '')}"
+    return rec
+
+
+def _calculate_impact_score(rec: Dict) -> float:
+    """Calculate the score impact of fixing this control.
+
+    Higher score = fixing this control improves posture more.
+    """
+    severity_weights = {"critical": 10, "high": 7, "medium": 4, "low": 2}
+    status_weights = {"fail": 1.0, "not_assessed": 0.8, "partial": 0.5}
+
+    severity = rec.get("severity", "medium")
+    status = rec.get("current_status", "fail")
+
+    base = severity_weights.get(severity, 4)
+    multiplier = status_weights.get(status, 1.0)
+
+    return round(base * multiplier, 1)
+
+
+def _format_rec(rec: Dict, rank: int) -> Dict:
+    """Format a recommendation for output."""
+    effort_labels = {
+        1: "Quick config change",
+        2: "Add a file",
+        3: "Code annotations",
+        4: "Enable a tool",
+        5: "Add code patterns",
+        6: "New feature",
+        7: "Architecture change",
+        8: "Process change",
+    }
+    return {
+        "rank": rank,
+        "control_id": rec.get("control_id", ""),
+        "control_title": rec.get("control_title", ""),
+        "regime_id": rec.get("regime_id", ""),
+        "severity": rec.get("severity", ""),
+        "current_status": rec.get("current_status", ""),
+        "title": rec.get("title", ""),
+        "description": rec.get("description", ""),
+        "effort_level": rec.get("effort_score", 8),
+        "effort_label": effort_labels.get(rec.get("effort_score", 8), "Process change"),
+        "impact_score": rec.get("impact_score", 0),
+        "roi_score": round(rec.get("roi_score", 0), 2),
+        "steps": rec.get("steps", []),
+    }
+
+
+def _enhance_with_llm(recs: List[Dict], audit_result: Dict) -> List[Dict]:
+    """Enhance recommendations using LLM (worker tier).
+
+    Uses two-tier routing: qwen3.5 drafts, Claude reviews.
+    Only called for complex multi-control gaps.
+    """
+    try:
+        from tools.llm.router import LLMRouter
+        router = LLMRouter()
+
+        # Only enhance top 5 by impact (to conserve tokens)
+        top_recs = sorted(recs, key=lambda r: r.get("impact_score", 0), reverse=True)[:5]
+
+        context = {
+            "target_type": audit_result.get("target_type", "unknown"),
+            "failing_controls": [
+                {"id": r["control_id"], "title": r.get("control_title", ""),
+                 "severity": r.get("severity", ""), "status": r["current_status"]}
+                for r in top_recs
+            ],
+        }
+
+        prompt = (
+            f"You are a compliance advisor. Given these failing controls for a "
+            f"{context['target_type']} target, provide specific, actionable next steps "
+            f"for each. Be concise (2-3 sentences per control).\n\n"
+            f"Failing controls:\n{json.dumps(context['failing_controls'], indent=2)}\n\n"
+            f"For each control, provide: (1) the single most impactful fix, "
+            f"(2) estimated effort in hours."
+        )
+
+        response = router.invoke("compliance_export", {
+            "prompt": prompt,
+            "max_tokens": 1000,
+        })
+
+        if response and response.get("content"):
+            # Append LLM insight to recommendation descriptions
+            for rec in top_recs:
+                rec["ai_insight"] = response["content"][:200]
+                rec["ai_enhanced"] = True
+
+    except (ImportError, Exception) as e:
+        # LLM not available — deterministic recommendations still work
+        pass
+
+    return recs
+
+
+def generate_action_plans(audit_result: Dict) -> Dict:
+    """Generate concrete action plans for regimes scoring below 80%.
+
+    Each plan includes phased steps, ownership assignments, timeline,
+    and expected score improvement per phase.
+    """
+    plans = {}
+    if not audit_result or not audit_result.get("regime_scores"):
+        return {"plans": plans, "regimes_below_threshold": 0}
+
+    for regime_id, regime_data in audit_result["regime_scores"].items():
+        if regime_data.get("error"):
+            continue
+        score = regime_data.get("overall_score", 0)
+        if score >= 80:
+            continue  # Only plan for <80%
+
+        # Collect all failing controls for this regime
+        # Include not_assessed — they count as failed in scoring
+        failing = []
+        for cat in regime_data.get("categories", []):
+            for ctrl in cat.get("controls", []):
+                if ctrl.get("status") in ("fail", "partial", "not_assessed"):
+                    failing.append({
+                        "control_id": ctrl.get("control_id", ""),
+                        "control_name": ctrl.get("control_name", ctrl.get("title", "")),
+                        "status": ctrl.get("status"),
+                        "category": cat.get("category_name", ""),
+                        "severity": ctrl.get("severity", "medium"),
+                    })
+
+        total = regime_data.get("summary", {}).get("total_controls", len(failing))
+        passed = regime_data.get("summary", {}).get("passed", 0)
+
+        # Sort by severity (critical first) then by auto-fixable
+        sev_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+        failing.sort(key=lambda f: sev_order.get(f["severity"], 2))
+
+        # Build phased plan
+        phases = []
+
+        # Phase 1: Quick wins (auto-fixable)
+        auto_fixable = [
+            f for f in failing
+            if _has_auto_fix(f["control_id"])
+        ]
+        manual_only = [
+            f for f in failing
+            if not _has_auto_fix(f["control_id"])
+        ]
+
+        if auto_fixable:
+            phase1_controls = auto_fixable  # No cap — include all auto-fixable
+            new_score_after_p1 = min(100, ((passed + len(phase1_controls)) / max(total, 1)) * 100)
+            phases.append({
+                "phase": 1,
+                "name": "Quick Wins (Auto-Fixable)",
+                "timeline": "1-2 weeks",
+                "effort": "Low",
+                "owner": "Development Team",
+                "controls": [
+                    {
+                        "control_id": c["control_id"],
+                        "control_name": c["control_name"],
+                        "action": _get_fix_description(c["control_id"]),
+                        "auto_fixable": True,
+                    }
+                    for c in phase1_controls
+                ],
+                "expected_score_after": round(new_score_after_p1, 1),
+                "controls_resolved": len(phase1_controls),
+            })
+            passed += len(phase1_controls)
+
+        # Phase 2: Critical & high severity manual controls
+        phase2_controls = [f for f in manual_only if f["severity"] in ("critical", "high")]
+        if phase2_controls:
+            new_score_after_p2 = min(100, ((passed + len(phase2_controls)) / max(total, 1)) * 100)
+            phases.append({
+                "phase": 2,
+                "name": "Critical & High Severity Remediation",
+                "timeline": "2-6 weeks",
+                "effort": "Medium-High",
+                "owner": "Security + Development Team",
+                "controls": [
+                    {
+                        "control_id": c["control_id"],
+                        "control_name": c["control_name"],
+                        "action": _get_concrete_action(c["control_id"], c.get("control_name", "")),
+                        "auto_fixable": False,
+                    }
+                    for c in phase2_controls
+                ],
+                "expected_score_after": round(new_score_after_p2, 1),
+                "controls_resolved": len(phase2_controls),
+            })
+            passed += len(phase2_controls)
+
+        # Phase 3: Medium & low severity controls
+        phase3_controls = [f for f in manual_only if f["severity"] in ("medium", "low")]
+        if phase3_controls:
+            new_score_after_p3 = min(100, ((passed + len(phase3_controls)) / max(total, 1)) * 100)
+            phases.append({
+                "phase": 3,
+                "name": "Medium & Low Severity Hardening",
+                "timeline": "1-3 months",
+                "effort": "Medium",
+                "owner": "Development + Compliance Team",
+                "controls": [
+                    {
+                        "control_id": c["control_id"],
+                        "control_name": c["control_name"],
+                        "action": _get_concrete_action(c["control_id"], c.get("control_name", "")),
+                        "auto_fixable": False,
+                    }
+                    for c in phase3_controls
+                ],
+                "expected_score_after": round(new_score_after_p3, 1),
+                "controls_resolved": len(phase3_controls),
+            })
+
+        plans[regime_id] = {
+            "regime_id": regime_id,
+            "regime_name": regime_data.get("regime_name", regime_id),
+            "current_score": round(score, 1),
+            "current_grade": regime_data.get("grade", "F"),
+            "total_failing": len(failing),
+            "total_controls": total,
+            "phases": phases,
+            "target_score": phases[-1]["expected_score_after"] if phases else score,
+            "estimated_timeline": phases[-1]["timeline"] if phases else "N/A",
+        }
+
+    return {
+        "plans": plans,
+        "regimes_below_threshold": len(plans),
+    }
+
+
+def _has_auto_fix(control_id: str) -> bool:
+    """Check if a control has a direct auto-fix handler.
+
+    Only returns True for controls that directly match a REMEDIATION_ACTIONS
+    key (NIST 800-53 format). Cross-framework controls (CMMC, 800-171, SBD)
+    are routed to concrete manual actions instead, since the auto-fix scope
+    is narrower than the full control requirement.
+    """
+    import re
+    from tools.audit_engine.self_heal import REMEDIATION_ACTIONS
+
+    # Only match direct NIST 800-53 IDs (AC-6, AU-2, etc.)
+    m = re.match(r"^([A-Z]{2})-(\d+)", control_id)
+    if not m:
+        return False  # Non-NIST IDs always go to manual phases
+
+    nist_id = f"{m.group(1)}-{m.group(2)}"
+    if nist_id in REMEDIATION_ACTIONS:
+        action = REMEDIATION_ACTIONS[nist_id]
+        return action.get("action_type") != "manual"
+    return False
+
+
+def _get_fix_description(control_id: str) -> str:
+    """Get the fix description for a control."""
+    from tools.audit_engine.self_heal import REMEDIATION_ACTIONS, _extract_control_family
+    family = _extract_control_family(control_id)
+    if family and family in REMEDIATION_ACTIONS:
+        return REMEDIATION_ACTIONS[family].get("description", "Manual assessment required")
+    return _get_concrete_action(control_id, "")
+
+
+# Concrete remediation actions by control domain — specific, actionable steps
+# Maps control ID patterns to ICDEV-specific implementation guidance
+CONCRETE_ACTIONS = {
+    # Access Control (AC / 3.1.x)
+    "access_control": {
+        "keywords": ["access", "authorized", "privilege", "remote", "transaction", "function", "flow"],
+        "action": "Implement RBAC in Flask dashboard: add @login_required + role decorators to all routes, "
+                  "configure session timeout (15 min), add account lockout after 5 failed attempts. "
+                  "Run: python tools/dashboard/app.py with RBAC_ENABLED=true",
+    },
+    "least_privilege": {
+        "keywords": ["least privilege", "non-privileged", "privileged function"],
+        "action": "Add non-root USER to all Dockerfiles, set readOnlyRootFilesystem=true in K8s pod specs, "
+                  "drop ALL capabilities + add only NET_BIND_SERVICE. "
+                  "Run: python tools/audit_engine/self_heal.py --control AC-6 --target . --apply",
+    },
+    "remote_access": {
+        "keywords": ["remote access", "remote session"],
+        "action": "Enable mTLS for all inter-service communication via service mesh (Istio/Linkerd). "
+                  "Configure VPN requirement for admin access. Add session recording for privileged sessions. "
+                  "Run: python tools/devsecops/service_mesh_generator.py --project-id sparkpilot --mesh istio --json",
+    },
+    "cui_flow": {
+        "keywords": ["cui flow", "information flow"],
+        "action": "Add CUI boundary markers to all data-at-rest and data-in-transit paths. "
+                  "Configure network segmentation with default-deny NetworkPolicy. "
+                  "Run: python tools/devsecops/policy_generator.py --project-id sparkpilot --engine kyverno --json",
+    },
+    # Audit & Accountability (AU / 3.3.x)
+    "audit_logging": {
+        "keywords": ["audit", "log", "accountability", "trace", "user accountability"],
+        "action": "Add structured JSON logging to all API endpoints (auth events, data access, admin actions). "
+                  "Configure append-only audit trail (NIST AU compliant — no UPDATE/DELETE). "
+                  "Run: python tools/audit_engine/self_heal.py --control AU-2 --target . --apply",
+    },
+    "audit_protection": {
+        "keywords": ["protect audit", "audit information", "audit tools"],
+        "action": "Enable WAL mode on audit database, set file permissions to 0640, configure audit log rotation "
+                  "with integrity hashing (SHA-256 per entry). Verify no UPDATE/DELETE on audit_trail table.",
+    },
+    "audit_correlation": {
+        "keywords": ["correlat", "audit record review"],
+        "action": "Deploy observability stack: configure OTel tracing with correlation IDs across all services. "
+                  "Run: python tools/observability/provenance/prov_query.py --entity-id sparkpilot --direction backward --json",
+    },
+    # Awareness & Training (AT / 3.2.x)
+    "training": {
+        "keywords": ["training", "awareness", "role-based risk"],
+        "action": "Create security training program: document role-based training requirements in docs/security-training.md, "
+                  "add training completion tracking to user profiles, schedule quarterly security awareness reviews.",
+    },
+    # Configuration Management (CM / 3.4.x)
+    "baseline_config": {
+        "keywords": ["baseline", "configuration setting", "change track", "change control"],
+        "action": "Generate baseline config with checksums: document all system configs in args/ directory, "
+                  "add git-based change tracking with mandatory PR reviews. "
+                  "Run: python tools/compliance/stig_checker.py --project-id sparkpilot to verify STIG compliance.",
+    },
+    # Identification & Authentication (IA / 3.5.x)
+    "authentication": {
+        "keywords": ["identif", "authenticat", "multifactor", "mfa"],
+        "action": "Implement authentication: add Flask-Login with bcrypt password hashing, enforce MFA via TOTP "
+                  "(pyotp library), require strong passwords (12+ chars, complexity). "
+                  "Add API key rotation with 90-day expiry.",
+    },
+    # Incident Response (IR / 3.6.x)
+    "incident_response": {
+        "keywords": ["incident"],
+        "action": "Create incident response plan: docs/incident-response-plan.md with detection/analysis/containment/"
+                  "eradication/recovery phases. Add automated alerting via monitor agent. "
+                  "Run: python tools/security/threat_modeler.py --project-id sparkpilot --create --name 'IR Plan' --json",
+    },
+    # Maintenance (MA / 3.7.x)
+    "maintenance": {
+        "keywords": ["maintenance"],
+        "action": "Document maintenance procedures: schedule dependency updates (monthly), automate with "
+                  "python tools/security/dependency_auditor.py in CI/CD. Add maintenance window calendar.",
+    },
+    # Media Protection (MP / 3.8.x)
+    "media_protection": {
+        "keywords": ["media protection", "media sanitiz"],
+        "action": "Implement data-at-rest encryption for all CUI storage (AES-256). Add secure deletion procedures. "
+                  "Document media handling in docs/media-protection.md.",
+    },
+    # Physical (PE / 3.10.x)
+    "physical": {
+        "keywords": ["physical"],
+        "action": "Document physical security controls for deployment environment: data center access controls, "
+                  "visitor logs, environmental protections. For cloud: reference AWS GovCloud physical security inheritance.",
+    },
+    # Personnel Security (PS / 3.9.x)
+    "personnel": {
+        "keywords": ["personnel", "screen individual"],
+        "action": "Document personnel screening requirements: background checks for CUI access, "
+                  "access termination procedures within 24 hours of departure, NDA requirements.",
+    },
+    # Risk Assessment (RA / 3.11.x)
+    "risk_assessment": {
+        "keywords": ["risk assess", "vulnerability scan"],
+        "action": "Enable automated vulnerability scanning in CI/CD pipeline: "
+                  "python tools/security/sast_runner.py + python tools/security/dependency_auditor.py. "
+                  "Schedule quarterly risk assessments. "
+                  "Run: python tools/compliance/sbd_assessor.py --project-id sparkpilot --project-dir . --json",
+    },
+    # Recovery (RE / 3.12.x)
+    "recovery": {
+        "keywords": ["backup", "recovery", "data backup"],
+        "action": "Configure automated database backups (daily with 30-day retention). Test restore procedures monthly. "
+                  "Document backup/recovery plan in docs/backup-recovery.md. Add backup verification checksums.",
+    },
+    # System & Comms Protection (SC / 3.13.x)
+    "boundary_protection": {
+        "keywords": ["boundary", "boundary protect"],
+        "action": "Configure network segmentation: deploy default-deny NetworkPolicy, enable WAF for web endpoints, "
+                  "configure egress filtering. "
+                  "Run: python tools/devsecops/policy_generator.py --project-id sparkpilot --engine kyverno --json",
+    },
+    "encryption": {
+        "keywords": ["encrypt", "cryptograph", "fips", "cui in transit"],
+        "action": "Enable TLS 1.3 on all endpoints, configure FIPS 140-3 validated crypto (Python cryptography library), "
+                  "encrypt CUI at rest with AES-256-GCM. Add HSTS headers. "
+                  "Run: python tools/audit_engine/self_heal.py --control SC-13 --target . --apply",
+    },
+    # System & Info Integrity (SI / 3.14.x)
+    "flaw_remediation": {
+        "keywords": ["flaw", "remediat", "patch"],
+        "action": "Run dependency audit and update all packages with known CVEs: "
+                  "python tools/security/dependency_auditor.py --project-dir . "
+                  "Pin versions in requirements.txt, add Dependabot/Renovate for automated PR updates.",
+    },
+    "malicious_code": {
+        "keywords": ["malicious code", "malware"],
+        "action": "Enable SAST scanning in CI/CD to detect code injection patterns. Add pre-commit hooks for "
+                  "secret detection. Configure container image scanning. "
+                  "Run: python tools/security/sast_runner.py --project-dir .",
+    },
+    "monitoring": {
+        "keywords": ["monitor", "unauthorized use", "security alert", "advisory"],
+        "action": "Deploy monitoring stack: configure alerting for failed auth attempts (>5/min), "
+                  "unauthorized API access, anomalous data exfiltration patterns. "
+                  "Run: python tools/security/ai_telemetry_logger.py --anomalies --window-hours 24 --json",
+    },
+    # Supply Chain (SR)
+    "supply_chain": {
+        "keywords": ["supply chain", "sbom", "component"],
+        "action": "Generate SBOM and audit supply chain: "
+                  "python tools/compliance/sbom_generator.py --project-id sparkpilot --project-dir . "
+                  "Run: python tools/supply_chain/scrm_assessor.py --project-id sparkpilot --aggregate --json",
+    },
+}
+
+
+def _get_concrete_action(control_id: str, control_name: str) -> str:
+    """Get concrete, actionable remediation steps for a control.
+
+    For NIST 800-53 IDs: uses self-heal REMEDIATION_ACTIONS directly.
+    For cross-framework IDs (CMMC, 800-171, SBD): uses keyword matching
+    on control name for broader, more accurate remediation guidance.
+    """
+    import re
+    from tools.audit_engine.self_heal import REMEDIATION_ACTIONS, _extract_control_family
+
+    # For direct NIST 800-53 IDs, use self-heal actions (precise match)
+    is_nist = bool(re.match(r"^[A-Z]{2}-\d+", control_id))
+    if is_nist:
+        family = _extract_control_family(control_id)
+        if family and family in REMEDIATION_ACTIONS:
+            return REMEDIATION_ACTIONS[family].get("description", "")
+
+    # For cross-framework IDs, match by control name keywords first
+    name_lower = (control_name or "").lower()
+    id_lower = control_id.lower()
+    search_text = f"{name_lower} {id_lower}"
+
+    best_match = None
+    best_score = 0
+    for _key, entry in CONCRETE_ACTIONS.items():
+        score = sum(1 for kw in entry["keywords"] if kw in search_text)
+        if score > best_score:
+            best_score = score
+            best_match = entry
+
+    if best_match and best_score > 0:
+        return best_match["action"]
+
+    # Fallback: map by NIST family prefix from control ID
+    family_to_domain = {
+        "AC": "access_control", "AU": "audit_logging", "AT": "training",
+        "CM": "baseline_config", "IA": "authentication", "IR": "incident_response",
+        "MA": "maintenance", "MP": "media_protection", "PE": "physical",
+        "PS": "personnel", "RA": "risk_assessment", "SC": "boundary_protection",
+        "SI": "flaw_remediation", "SR": "supply_chain", "CP": "recovery",
+        "RE": "recovery",
+    }
+    family = _extract_control_family(control_id)
+    if family:
+        prefix = family.split("-")[0] if "-" in family else family
+        domain = family_to_domain.get(prefix)
+        if domain and domain in CONCRETE_ACTIONS:
+            return CONCRETE_ACTIONS[domain]["action"]
+
+    return ("Review control requirements and implement: (1) document current state, "
+            "(2) identify gaps against requirement, (3) implement technical/procedural controls, "
+            "(4) collect evidence of implementation, (5) verify with audit rescan")
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Audit AI Advisor")
+    parser.add_argument("--audit-file", type=str, help="Audit result JSON file")
+    parser.add_argument("--regime", type=str, help="Filter to specific regime")
+    parser.add_argument("--max", type=int, default=20, help="Max recommendations")
+    parser.add_argument("--use-llm", action="store_true", help="Use LLM for enhanced advice")
+    parser.add_argument("--json", action="store_true", help="JSON output")
+    args = parser.parse_args()
+
+    if not args.audit_file:
+        # Run a fresh audit
+        from tools.audit_engine.engine import run_audit
+        audit_result = run_audit(target_path=".", store_results=False)
+    else:
+        with open(args.audit_file, "r") as f:
+            audit_result = json.load(f)
+
+    result = generate_recommendations(
+        audit_result,
+        regime_id=args.regime,
+        max_recommendations=args.max,
+        use_llm=args.use_llm,
+    )
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"\n{'='*70}")
+        print(f"  AI ADVISOR — COMPLIANCE IMPROVEMENT RECOMMENDATIONS")
+        print(f"{'='*70}")
+        print(f"  Total: {result['total_recommendations']} recommendations")
+        print(f"  Est. improvement (top 5): +{result['estimated_improvement_top5']}%\n")
+
+        print(f"  TOP 5 QUICK WINS (best ROI):")
+        for rec in result.get("quick_wins", [])[:5]:
+            print(f"    {rec['rank']}. [{rec['severity'].upper()}] {rec['title']}")
+            print(f"       Control: {rec['control_id']} | Effort: {rec['effort_label']}")
+            print(f"       Impact: {rec['impact_score']} | ROI: {rec['roi_score']}")
+            print()
+
+        print(f"  TOP 5 BY IMPACT:")
+        for rec in result.get("by_impact", [])[:5]:
+            print(f"    {rec['rank']}. [{rec['severity'].upper()}] {rec['title']}")
+            print(f"       Control: {rec['control_id']} | Effort: {rec['effort_label']}")
+            print()
+
+        print(f"{'='*70}")
+        print(f"  CUI // SP-CTI")
+        print(f"{'='*70}")