icdev 0.0.3__py3-none-any.whl

tools/audit_engine/cli.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+# Controlled by: Department of Defense
+# CUI Category: CTI
+# Distribution: D
+# POC: ICDEV System Administrator
+"""Audit Engine CLI — Unified compliance audit command-line interface.
+
+Provides a single entry point for all audit engine operations:
+scan, compare, advise, manage regimes, and BYOS.
+
+Usage:
+    # Run audit on current directory
+    python tools/audit_engine/cli.py scan --json
+
+    # Run audit on BYOS (directory)
+    python tools/audit_engine/cli.py scan --target /path/to/code --type byos --json
+
+    # Run audit on BYOS (git URL, private)
+    python tools/audit_engine/cli.py scan --target https://github.com/org/repo.git \\
+        --type byos --auth token --token ghp_xxx --json
+
+    # Compare two regimes
+    python tools/audit_engine/cli.py compare --baseline nist_800_171 --target nist_800_53 --json
+
+    # Get AI recommendations
+    python tools/audit_engine/cli.py advise --regime nist_800_53 --json
+
+    # List available regimes
+    python tools/audit_engine/cli.py regimes --json
+
+    # Import a custom regime
+    python tools/audit_engine/cli.py regime-import --file /path/to/regime.json --json
+
+    # Export regimes
+    python tools/audit_engine/cli.py regime-export --output /path/to/export --json
+
+    # Score trend
+    python tools/audit_engine/cli.py trend --regime nist_800_53 --json
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+# Ensure ICDEV root is on sys.path for tools.* imports
+_ROOT = Path(__file__).resolve().parent.parent.parent
+if str(_ROOT) not in sys.path:
+    sys.path.insert(0, str(_ROOT))
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="ICDEV Audit Engine — Unified Compliance Report Card",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Command to run")
+
+    # ── scan ──
+    scan_p = subparsers.add_parser("scan", help="Run audit scan")
+    scan_p.add_argument("--target", default=".", help="Target path or git URL")
+    scan_p.add_argument("--type", default="auto",
+                        choices=["icdev", "module", "child_app", "byos", "auto"])
+    scan_p.add_argument("--project-id", help="ICDEV project ID")
+    scan_p.add_argument("--regimes", nargs="*", help="Specific regime IDs")
+    scan_p.add_argument("--skip", nargs="*", help="Scanners to skip")
+    scan_p.add_argument("--no-store", action="store_true")
+    scan_p.add_argument("--auth", default="auto",
+                        choices=["auto", "ssh", "token", "public"],
+                        help="Git auth method (for BYOS git URLs)")
+    scan_p.add_argument("--token", help="HTTPS personal access token")
+    scan_p.add_argument("--ssh-key", help="SSH private key path")
+    scan_p.add_argument("--branch", help="Git branch to clone")
+    scan_p.add_argument("--format", default="terminal",
+                        choices=["json", "terminal", "markdown"])
+    scan_p.add_argument("--json", action="store_true")
+
+    # ── compare ──
+    cmp_p = subparsers.add_parser("compare", help="Compare two regimes")
+    cmp_p.add_argument("--baseline", required=True)
+    cmp_p.add_argument("--target", required=True)
+    cmp_p.add_argument("--scan-target", default=".", help="Path to scan")
+    cmp_p.add_argument("--project-id", help="ICDEV project ID")
+    cmp_p.add_argument("--json", action="store_true")
+
+    # ── advise ──
+    adv_p = subparsers.add_parser("advise", help="Get AI recommendations")
+    adv_p.add_argument("--regime", help="Filter to single regime")
+    adv_p.add_argument("--scan-target", default=".", help="Path to scan")
+    adv_p.add_argument("--project-id", help="ICDEV project ID")
+    adv_p.add_argument("--use-llm", action="store_true")
+    adv_p.add_argument("--max", type=int, default=20)
+    adv_p.add_argument("--json", action="store_true")
+
+    # ── regimes ──
+    reg_p = subparsers.add_parser("regimes", help="List available regimes")
+    reg_p.add_argument("--json", action="store_true")
+
+    # ── regime-import ──
+    imp_p = subparsers.add_parser("regime-import", help="Import a regime file")
+    imp_p.add_argument("--file", required=True, help="Path to regime JSON")
+    imp_p.add_argument("--json", action="store_true")
+
+    # ── regime-export ──
+    exp_p = subparsers.add_parser("regime-export", help="Export all regimes")
+    exp_p.add_argument("--output", required=True, help="Output directory")
+    exp_p.add_argument("--json", action="store_true")
+
+    # ── trend ──
+    trn_p = subparsers.add_parser("trend", help="Show score trend")
+    trn_p.add_argument("--regime", help="Filter by regime ID")
+    trn_p.add_argument("--limit", type=int, default=10)
+    trn_p.add_argument("--json", action="store_true")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    if args.command == "scan":
+        _cmd_scan(args)
+    elif args.command == "compare":
+        _cmd_compare(args)
+    elif args.command == "advise":
+        _cmd_advise(args)
+    elif args.command == "regimes":
+        _cmd_regimes(args)
+    elif args.command == "regime-import":
+        _cmd_regime_import(args)
+    elif args.command == "regime-export":
+        _cmd_regime_export(args)
+    elif args.command == "trend":
+        _cmd_trend(args)
+
+
+def _cmd_scan(args):
+    from tools.audit_engine.engine import run_audit
+    from tools.audit_engine.report_card import generate_report_card
+
+    target = args.target
+    clone_path = None
+
+    # Handle git URLs for BYOS
+    if args.type == "byos" and (target.startswith("http") or target.startswith("git@")):
+        from tools.audit_engine.git_fetcher import fetch_repo, cleanup_clone
+        print(f"Cloning {target}...", file=sys.stderr)
+        fetch = fetch_repo(
+            url=target,
+            auth_method=args.auth,
+            token=args.token,
+            ssh_key=args.ssh_key,
+            branch=args.branch,
+        )
+        if not fetch.get("success"):
+            print(f"Error: {fetch.get('error')}", file=sys.stderr)
+            sys.exit(1)
+        clone_path = fetch["clone_path"]
+        target = clone_path
+        print(f"Cloned to {clone_path}", file=sys.stderr)
+
+    result = run_audit(
+        target_path=target,
+        target_type=args.type,
+        project_id=args.project_id,
+        regime_ids=args.regimes,
+        skip_tools=args.skip,
+        store_results=not args.no_store,
+    )
+
+    # Clean up clone
+    if clone_path:
+        from tools.audit_engine.git_fetcher import cleanup_clone
+        cleanup_clone(clone_path)
+
+    fmt = "json" if args.json else args.format
+    report = generate_report_card(result, output_format=fmt)
+    print(report["formatted_output"])
+
+
+def _cmd_compare(args):
+    from tools.audit_engine.engine import run_audit
+    from tools.audit_engine.comparator import compare_regimes
+
+    audit_result = run_audit(
+        target_path=args.scan_target,
+        project_id=args.project_id,
+        regime_ids=[args.baseline, args.target],
+        store_results=False,
+    )
+    result = compare_regimes(audit_result, args.baseline, args.target)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        if "error" in result:
+            print(f"Error: {result['error']}", file=sys.stderr)
+            sys.exit(1)
+        b = result["baseline"]
+        t = result["target"]
+        print(f"\n{'='*70}")
+        print(f"  REGIME COMPARISON: {b['regime_name']} vs {t['regime_name']}")
+        print(f"{'='*70}")
+        print(f"  Baseline: {b['score']:.1f}% ({b['grade']}) | Target: {t['score']:.1f}% ({t['grade']})")
+        print(f"  Delta: {result['score_delta']:+.1f}% | Gaps: {result['gap_count']}")
+        print(f"\n  {result['recommendation']}")
+        print(f"\n{'='*70}")
+
+
+def _cmd_advise(args):
+    from tools.audit_engine.engine import run_audit
+    from tools.audit_engine.ai_advisor import generate_recommendations
+
+    audit_result = run_audit(
+        target_path=args.scan_target,
+        project_id=args.project_id,
+        store_results=False,
+    )
+    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  TOP RECOMMENDATIONS (by ROI):")
+        for rec in result.get("by_roi", [])[:10]:
+            print(f"  {rec['rank']:2d}. [{rec['severity'].upper():8s}] {rec['title']}")
+            print(f"      Control: {rec['control_id']} | Effort: {rec['effort_label']} | Impact: {rec['impact_score']}")
+        if result.get("estimated_improvement_top5"):
+            print(f"\n  Est. improvement (top 5): +{result['estimated_improvement_top5']}%")
+
+
+def _cmd_regimes(args):
+    from tools.audit_engine.regime_loader import list_regimes
+    result = list_regimes()
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"\n  Available Regimes ({len(result)}):")
+        for r in result:
+            print(f"    {r['id']:25s} {r['name']:40s} v{r['version']} ({r['category_count']} cats)")
+
+
+def _cmd_regime_import(args):
+    from tools.audit_engine.regime_updater import import_regime
+    result = import_regime(args.file)
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        if result.get("success"):
+            print(f"  Imported: {result['name']} ({result['action']})")
+        else:
+            print(f"  Error: {result.get('error')}", file=sys.stderr)
+
+
+def _cmd_regime_export(args):
+    from tools.audit_engine.regime_updater import export_regimes
+    result = export_regimes(args.output)
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        print(f"  Exported {result['exported_count']} regimes to {result['output_dir']}")
+
+
+def _cmd_trend(args):
+    from tools.audit_engine.report_card import get_score_trend
+    result = get_score_trend(regime_id=args.regime, limit=args.limit)
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        if not result:
+            print("  No historical data yet. Run an audit first.")
+        else:
+            for t in result:
+                print(f"  {t.get('timestamp', '')[:19]}  {t.get('regime_id', ''):25s}  "
+                      f"{t.get('overall_score', 0):5.1f}%  {t.get('grade', '?')}")
+
+
+if __name__ == "__main__":
+    main()

tools/audit_engine/comparator.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+# Controlled by: Department of Defense
+# CUI Category: CTI
+# Distribution: D
+# POC: ICDEV System Administrator
+"""Regime Comparator — Side-by-side gap analysis between compliance frameworks.
+
+Enables users to see their compliance posture across two regimes simultaneously,
+highlighting gaps, overlaps, and controls unique to each framework. Key use case:
+"I'm 800-171 compliant — what do I need for 800-53?"
+
+Usage:
+    python tools/audit_engine/comparator.py --baseline nist_800_171 --target nist_800_53 \\
+        --audit-result audit_result.json --json
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from tools.audit_engine.regime_loader import load_regime, get_regime_controls
+
+
+def compare_regimes(
+    audit_result: Dict,
+    baseline_regime_id: str,
+    target_regime_id: str,
+) -> Dict:
+    """Compare two regime scores side-by-side from an audit result.
+
+    Args:
+        audit_result: Full audit result from engine.run_audit().
+        baseline_regime_id: Current/baseline regime ID.
+        target_regime_id: Target regime to compare against.
+
+    Returns:
+        Comparison dict with gap analysis, shared controls, and delta scores.
+    """
+    regime_scores = audit_result.get("regime_scores", {})
+    baseline_scores = regime_scores.get(baseline_regime_id, {})
+    target_scores = regime_scores.get(target_regime_id, {})
+
+    if not baseline_scores or "error" in baseline_scores:
+        return {"error": f"No scores for baseline regime '{baseline_regime_id}'"}
+    if not target_scores or "error" in target_scores:
+        return {"error": f"No scores for target regime '{target_regime_id}'"}
+
+    # Build control-level maps
+    baseline_controls = _extract_control_map(baseline_scores)
+    target_controls = _extract_control_map(target_scores)
+
+    # Identify crosswalk overlaps
+    crosswalk_map = _build_crosswalk_map(baseline_regime_id, target_regime_id)
+
+    # Classify controls
+    shared = []       # Controls in both regimes (via crosswalk)
+    baseline_only = []  # Controls only in baseline
+    target_only = []    # Controls only in target (the "gap")
+
+    matched_target_ids = set()
+
+    for ctrl_id, ctrl_data in baseline_controls.items():
+        # Check if this control maps to target via crosswalk
+        mapped_target_id = crosswalk_map.get(ctrl_id)
+        if mapped_target_id and mapped_target_id in target_controls:
+            target_ctrl = target_controls[mapped_target_id]
+            matched_target_ids.add(mapped_target_id)
+            shared.append({
+                "baseline_control": ctrl_id,
+                "target_control": mapped_target_id,
+                "baseline_status": ctrl_data["status"],
+                "target_status": target_ctrl["status"],
+                "baseline_title": ctrl_data["title"],
+                "target_title": target_ctrl["title"],
+                "status_match": ctrl_data["status"] == target_ctrl["status"],
+                "gap": ctrl_data["status"] == "pass" and target_ctrl["status"] != "pass",
+            })
+        else:
+            baseline_only.append({
+                "control_id": ctrl_id,
+                "title": ctrl_data["title"],
+                "status": ctrl_data["status"],
+                "severity": ctrl_data["severity"],
+            })
+
+    for ctrl_id, ctrl_data in target_controls.items():
+        if ctrl_id not in matched_target_ids:
+            target_only.append({
+                "control_id": ctrl_id,
+                "title": ctrl_data["title"],
+                "status": ctrl_data["status"],
+                "severity": ctrl_data["severity"],
+            })
+
+    # Score delta
+    baseline_score = baseline_scores.get("overall_score", 0)
+    target_score = target_scores.get("overall_score", 0)
+
+    # Gap analysis: target_only controls that are failing
+    gaps = [c for c in target_only if c["status"] in ("fail", "not_assessed")]
+    gaps_by_severity = {
+        "critical": [g for g in gaps if g["severity"] == "critical"],
+        "high": [g for g in gaps if g["severity"] == "high"],
+        "medium": [g for g in gaps if g["severity"] == "medium"],
+        "low": [g for g in gaps if g["severity"] == "low"],
+    }
+
+    return {
+        "baseline": {
+            "regime_id": baseline_regime_id,
+            "regime_name": baseline_scores.get("regime_name", baseline_regime_id),
+            "score": baseline_score,
+            "grade": baseline_scores.get("grade", "?"),
+            "total_controls": baseline_scores.get("summary", {}).get("total_controls", 0),
+        },
+        "target": {
+            "regime_id": target_regime_id,
+            "regime_name": target_scores.get("regime_name", target_regime_id),
+            "score": target_score,
+            "grade": target_scores.get("grade", "?"),
+            "total_controls": target_scores.get("summary", {}).get("total_controls", 0),
+        },
+        "score_delta": round(target_score - baseline_score, 1),
+        "shared_controls": len(shared),
+        "baseline_only_controls": len(baseline_only),
+        "target_only_controls": len(target_only),
+        "gap_count": len(gaps),
+        "gaps_by_severity": {k: len(v) for k, v in gaps_by_severity.items()},
+        "category_comparison": _compare_categories(baseline_scores, target_scores),
+        "shared": shared,
+        "baseline_only": baseline_only,
+        "target_only": target_only,
+        "gaps": gaps,
+        "recommendation": _generate_gap_recommendation(
+            baseline_regime_id, target_regime_id, gaps, baseline_score, target_score
+        ),
+    }
+
+
+def _extract_control_map(regime_score: Dict) -> Dict:
+    """Extract flat control map from regime score data."""
+    controls = {}
+    for category in regime_score.get("categories", []):
+        for ctrl in category.get("controls", []):
+            controls[ctrl["control_id"]] = {
+                "title": ctrl.get("title", ""),
+                "status": ctrl.get("status", "not_assessed"),
+                "severity": ctrl.get("severity", "medium"),
+                "category_id": category.get("category_id", ""),
+                "category_name": category.get("category_name", ""),
+                "evidence_count": ctrl.get("evidence_count", 0),
+            }
+    return controls
+
+
+def _build_crosswalk_map(baseline_id: str, target_id: str) -> Dict:
+    """Build a mapping from baseline control IDs to target control IDs.
+
+    Uses crosswalk data embedded in regime definitions.
+    """
+    mapping = {}
+
+    # Get baseline regime controls with crosswalk data
+    baseline_controls = get_regime_controls(baseline_id)
+    for ctrl in baseline_controls:
+        for xwalk in ctrl.get("crosswalk", []):
+            if xwalk.get("framework") == target_id or \
+               _normalize_framework_id(xwalk.get("framework", "")) == target_id:
+                mapping[ctrl["control_id"]] = xwalk["control"]
+
+    # Also build reverse mapping from target
+    target_controls = get_regime_controls(target_id)
+    for ctrl in target_controls:
+        for xwalk in ctrl.get("crosswalk", []):
+            if xwalk.get("framework") == baseline_id or \
+               _normalize_framework_id(xwalk.get("framework", "")) == baseline_id:
+                # Reverse: target control -> baseline control
+                if xwalk["control"] not in mapping:
+                    mapping[xwalk["control"]] = ctrl["control_id"]
+
+    return mapping
+
+
+def _normalize_framework_id(fw: str) -> str:
+    """Normalize framework IDs for comparison."""
+    aliases = {
+        "nist_800_53": "nist_800_53",
+        "nist_800_171": "nist_800_171",
+        "fedramp_moderate": "fedramp_moderate",
+        "fedramp": "fedramp_moderate",
+        "cmmc_l2": "cmmc_l2",
+        "cmmc_level_2": "cmmc_l2",
+    }
+    return aliases.get(fw, fw)
+
+
+def _compare_categories(baseline: Dict, target: Dict) -> List[Dict]:
+    """Compare category-level scores between two regimes."""
+    baseline_cats = {c["category_id"]: c for c in baseline.get("categories", [])}
+    target_cats = {c["category_id"]: c for c in target.get("categories", [])}
+
+    all_cat_ids = sorted(set(list(baseline_cats.keys()) + list(target_cats.keys())))
+
+    comparisons = []
+    for cat_id in all_cat_ids:
+        b = baseline_cats.get(cat_id, {})
+        t = target_cats.get(cat_id, {})
+        comparisons.append({
+            "category_id": cat_id,
+            "category_name": b.get("category_name") or t.get("category_name", cat_id),
+            "baseline_score": b.get("score", None),
+            "target_score": t.get("score", None),
+            "delta": round((t.get("score", 0) or 0) - (b.get("score", 0) or 0), 1)
+                if b.get("score") is not None and t.get("score") is not None else None,
+            "in_baseline": cat_id in baseline_cats,
+            "in_target": cat_id in target_cats,
+        })
+
+    return comparisons
+
+
+def _generate_gap_recommendation(
+    baseline_id: str, target_id: str,
+    gaps: List[Dict], baseline_score: float, target_score: float
+) -> str:
+    """Generate a human-readable gap recommendation summary."""
+    if not gaps:
+        return (f"Your {baseline_id} posture covers all {target_id} requirements. "
+                f"No additional controls needed.")
+
+    critical = sum(1 for g in gaps if g["severity"] == "critical")
+    high = sum(1 for g in gaps if g["severity"] == "high")
+    medium = sum(1 for g in gaps if g["severity"] == "medium")
+
+    parts = []
+    parts.append(f"To move from {baseline_id} to {target_id}, "
+                 f"you need to address {len(gaps)} additional controls.")
+
+    if critical:
+        parts.append(f"PRIORITY: {critical} critical controls require immediate attention.")
+    if high:
+        parts.append(f"{high} high-severity controls should be addressed next.")
+    if medium:
+        parts.append(f"{medium} medium-severity controls for full compliance.")
+
+    return " ".join(parts)
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Audit Regime Comparator")
+    parser.add_argument("--baseline", required=True, help="Baseline regime ID")
+    parser.add_argument("--target", required=True, help="Target regime ID")
+    parser.add_argument("--audit-file", type=str, help="Path to audit result JSON")
+    parser.add_argument("--json", action="store_true", help="JSON output")
+    args = parser.parse_args()
+
+    if args.audit_file:
+        with open(args.audit_file, "r") as f:
+            audit_result = json.load(f)
+    else:
+        # Run a fresh audit with both regimes
+        from tools.audit_engine.engine import run_audit
+        audit_result = run_audit(
+            target_path=".",
+            regime_ids=[args.baseline, args.target],
+            store_results=False,
+        )
+
+    result = compare_regimes(audit_result, args.baseline, args.target)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        if "error" in result:
+            print(f"Error: {result['error']}")
+            sys.exit(1)
+
+        b = result["baseline"]
+        t = result["target"]
+        print(f"\n{'='*70}")
+        print(f"  REGIME COMPARISON: {b['regime_name']} vs {t['regime_name']}")
+        print(f"{'='*70}\n")
+        print(f"  {'':30s}  {'Baseline':>10s}  {'Target':>10s}  {'Delta':>8s}")
+        print(f"  {'Score':30s}  {b['score']:>9.1f}%  {t['score']:>9.1f}%  {result['score_delta']:>+7.1f}%")
+        print(f"  {'Grade':30s}  {b['grade']:>10s}  {t['grade']:>10s}")
+        print(f"  {'Total Controls':30s}  {b['total_controls']:>10d}  {t['total_controls']:>10d}")
+        print(f"\n  Shared Controls:        {result['shared_controls']}")
+        print(f"  Baseline Only:          {result['baseline_only_controls']}")
+        print(f"  Target Only (gaps):     {result['target_only_controls']}")
+        print(f"  Failing Gaps:           {result['gap_count']}")
+
+        if result["gaps_by_severity"]:
+            print(f"\n  Gap Severity Breakdown:")
+            for sev, count in result["gaps_by_severity"].items():
+                if count > 0:
+                    print(f"    {sev:10s}: {count}")
+
+        print(f"\n  Recommendation: {result['recommendation']}")
+        print(f"\n{'='*70}")
+        print(f"  CUI // SP-CTI")
+        print(f"{'='*70}")