runbooks 0.7.9__py3-none-any.whl → 0.9.0__py3-none-any.whl

runbooks/common/enterprise_audit_integration.py

@@ -0,0 +1,634 @@
+#!/usr/bin/env python3
+"""
+Enterprise Audit Integration Framework - Comprehensive Compliance Tracking
+
+This module provides enterprise-grade audit integration across all CloudOps modules,
+enabling comprehensive compliance tracking, regulatory reporting, and governance.
+
+Features:
+- Real-time audit trail generation across all modules
+- Multi-framework compliance support (SOC2, PCI-DSS, HIPAA, AWS Well-Architected)
+- Executive-ready reporting with business impact analysis
+- Cross-module audit correlation and analysis
+- Automated compliance validation and gap analysis
+
+Modules Integrated:
+- inventory: Resource discovery audit trails
+- operate: Operational change audit trails
+- security: Security findings and remediation audit trails
+- cfat: Cloud foundations assessment audit trails
+- vpc: Network configuration audit trails
+- remediation: Security remediation audit trails
+- finops: Cost optimization audit trails
+
+Author: CloudOps Runbooks Team
+Version: 0.8.0
+Architecture: Phase 4 Multi-Module Integration - Enterprise Audit Framework
+"""
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from runbooks.common.cross_module_integration import DataFlowType, EnterpriseCrossModuleIntegrator
+from runbooks.common.mcp_integration import EnterpriseMCPIntegrator, MCPValidationResult
+from runbooks.common.rich_utils import (
+    console,
+    create_panel,
+    create_table,
+    format_cost,
+    print_error,
+    print_info,
+    print_success,
+    print_warning,
+)
+
+
+class ComplianceFramework(Enum):
+    """Supported compliance frameworks."""
+
+    SOC2 = "soc2"
+    PCI_DSS = "pci_dss"
+    HIPAA = "hipaa"
+    AWS_WELL_ARCHITECTED = "aws_well_architected"
+    ISO27001 = "iso27001"
+    GDPR = "gdpr"
+    CUSTOM = "custom"
+
+
+class AuditSeverity(Enum):
+    """Audit event severity levels."""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFORMATIONAL = "informational"
+
+
+@dataclass
+class AuditEvent:
+    """Individual audit event record."""
+
+    timestamp: str
+    module: str
+    event_type: str
+    severity: AuditSeverity
+    resource_id: Optional[str]
+    account_id: Optional[str]
+    region: Optional[str]
+    user_profile: Optional[str]
+    description: str
+    compliance_frameworks: List[ComplianceFramework] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    correlation_id: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert audit event to dictionary."""
+        return {
+            "timestamp": self.timestamp,
+            "module": self.module,
+            "event_type": self.event_type,
+            "severity": self.severity.value,
+            "resource_id": self.resource_id,
+            "account_id": self.account_id,
+            "region": self.region,
+            "user_profile": self.user_profile,
+            "description": self.description,
+            "compliance_frameworks": [f.value for f in self.compliance_frameworks],
+            "metadata": self.metadata,
+            "correlation_id": self.correlation_id,
+        }
+
+
+@dataclass
+class ComplianceReport:
+    """Comprehensive compliance report."""
+
+    report_timestamp: str
+    frameworks_assessed: List[ComplianceFramework]
+    total_events: int
+    events_by_severity: Dict[str, int]
+    events_by_module: Dict[str, int]
+    compliance_score: float
+    critical_findings: List[AuditEvent]
+    recommendations: List[str]
+    business_impact_analysis: Dict[str, Any] = field(default_factory=dict)
+    audit_trail_summary: Dict[str, Any] = field(default_factory=dict)
+
+
+class EnterpriseAuditIntegrator:
+    """
+    Enterprise audit integration framework for comprehensive compliance tracking.
+
+    Provides real-time audit trail generation, compliance validation, and
+    executive-ready reporting across all CloudOps modules.
+    """
+
+    def __init__(
+        self, user_profile: Optional[str] = None, compliance_frameworks: Optional[List[ComplianceFramework]] = None
+    ):
+        """
+        Initialize enterprise audit integrator.
+
+        Args:
+            user_profile: User profile for audit attribution
+            compliance_frameworks: List of compliance frameworks to assess
+        """
+        self.user_profile = user_profile
+        self.compliance_frameworks = compliance_frameworks or [
+            ComplianceFramework.SOC2,
+            ComplianceFramework.AWS_WELL_ARCHITECTED,
+            ComplianceFramework.ISO27001,
+        ]
+
+        # Initialize integrators
+        self.mcp_integrator = EnterpriseMCPIntegrator(user_profile)
+        self.cross_module_integrator = EnterpriseCrossModuleIntegrator(user_profile)
+
+        # Audit storage
+        self.audit_events: List[AuditEvent] = []
+        self.compliance_history: List[ComplianceReport] = []
+
+        # Performance tracking
+        self.start_time = time.time()
+
+        print_info(
+            f"Enterprise audit integrator initialized for {len(self.compliance_frameworks)} compliance frameworks"
+        )
+
+    def record_audit_event(
+        self,
+        module: str,
+        event_type: str,
+        description: str,
+        severity: AuditSeverity = AuditSeverity.INFORMATIONAL,
+        resource_id: Optional[str] = None,
+        account_id: Optional[str] = None,
+        region: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        correlation_id: Optional[str] = None,
+    ) -> AuditEvent:
+        """
+        Record a new audit event.
+
+        Args:
+            module: Source module name
+            event_type: Type of audit event
+            description: Human-readable description
+            severity: Event severity level
+            resource_id: Associated AWS resource ID
+            account_id: AWS account ID
+            region: AWS region
+            metadata: Additional metadata
+            correlation_id: Correlation ID for related events
+
+        Returns:
+            Created audit event
+        """
+        # Determine applicable compliance frameworks
+        applicable_frameworks = self._determine_applicable_frameworks(event_type, module)
+
+        audit_event = AuditEvent(
+            timestamp=datetime.now().isoformat(),
+            module=module,
+            event_type=event_type,
+            severity=severity,
+            resource_id=resource_id,
+            account_id=account_id,
+            region=region,
+            user_profile=self.user_profile,
+            description=description,
+            compliance_frameworks=applicable_frameworks,
+            metadata=metadata or {},
+            correlation_id=correlation_id,
+        )
+
+        self.audit_events.append(audit_event)
+
+        # Log critical events immediately
+        if severity in [AuditSeverity.CRITICAL, AuditSeverity.HIGH]:
+            print_warning(f"🚨 {severity.value.upper()} audit event: {description}")
+
+        return audit_event
+
+    async def generate_comprehensive_compliance_report(
+        self, time_period_days: int = 30, include_business_impact: bool = True
+    ) -> ComplianceReport:
+        """
+        Generate comprehensive compliance report across all modules.
+
+        Args:
+            time_period_days: Number of days to include in report
+            include_business_impact: Whether to include business impact analysis
+
+        Returns:
+            Comprehensive compliance report
+        """
+        print_info(f"Generating comprehensive compliance report for {time_period_days} days")
+
+        # Filter events by time period
+        cutoff_date = datetime.now() - timedelta(days=time_period_days)
+        recent_events = [event for event in self.audit_events if datetime.fromisoformat(event.timestamp) >= cutoff_date]
+
+        # Analyze events by severity
+        events_by_severity = {}
+        for severity in AuditSeverity:
+            events_by_severity[severity.value] = len([e for e in recent_events if e.severity == severity])
+
+        # Analyze events by module
+        events_by_module = {}
+        for event in recent_events:
+            events_by_module[event.module] = events_by_module.get(event.module, 0) + 1
+
+        # Calculate compliance score
+        compliance_score = self._calculate_compliance_score(recent_events)
+
+        # Identify critical findings
+        critical_findings = [
+            event for event in recent_events if event.severity in [AuditSeverity.CRITICAL, AuditSeverity.HIGH]
+        ]
+
+        # Generate recommendations
+        recommendations = self._generate_compliance_recommendations(recent_events, critical_findings)
+
+        # Business impact analysis
+        business_impact = {}
+        if include_business_impact:
+            business_impact = await self._analyze_business_impact(recent_events)
+
+        # Create compliance report
+        report = ComplianceReport(
+            report_timestamp=datetime.now().isoformat(),
+            frameworks_assessed=self.compliance_frameworks,
+            total_events=len(recent_events),
+            events_by_severity=events_by_severity,
+            events_by_module=events_by_module,
+            compliance_score=compliance_score,
+            critical_findings=critical_findings,
+            recommendations=recommendations,
+            business_impact_analysis=business_impact,
+            audit_trail_summary=self._generate_audit_trail_summary(recent_events),
+        )
+
+        # Store in history
+        self.compliance_history.append(report)
+
+        print_success(
+            f"Compliance report generated: {compliance_score:.1f}% compliance score with {len(critical_findings)} critical findings"
+        )
+
+        return report
+
+    async def audit_inventory_operations(self, inventory_results: Dict[str, Any]) -> List[AuditEvent]:
+        """
+        Generate audit events for inventory operations.
+
+        Args:
+            inventory_results: Results from inventory collection
+
+        Returns:
+            List of generated audit events
+        """
+        audit_events = []
+
+        # Record inventory discovery event
+        total_resources = inventory_results.get("summary", {}).get("total_resources", 0)
+        accounts_scanned = len(inventory_results.get("metadata", {}).get("account_ids", []))
+
+        audit_event = self.record_audit_event(
+            module="inventory",
+            event_type="resource_discovery",
+            description=f"Discovered {total_resources} resources across {accounts_scanned} accounts",
+            severity=AuditSeverity.INFORMATIONAL,
+            metadata={
+                "total_resources": total_resources,
+                "accounts_scanned": accounts_scanned,
+                "resource_types": inventory_results.get("metadata", {}).get("resource_types", []),
+            },
+        )
+        audit_events.append(audit_event)
+
+        # Audit resource compliance
+        compliance_issues = self._identify_inventory_compliance_issues(inventory_results)
+        for issue in compliance_issues:
+            audit_event = self.record_audit_event(
+                module="inventory",
+                event_type="compliance_issue",
+                description=issue["description"],
+                severity=AuditSeverity.HIGH if issue["critical"] else AuditSeverity.MEDIUM,
+                resource_id=issue.get("resource_id"),
+                account_id=issue.get("account_id"),
+                metadata=issue.get("metadata", {}),
+            )
+            audit_events.append(audit_event)
+
+        return audit_events
+
+    async def audit_security_operations(self, security_results: Dict[str, Any]) -> List[AuditEvent]:
+        """
+        Generate audit events for security operations.
+
+        Args:
+            security_results: Results from security assessment
+
+        Returns:
+            List of generated audit events
+        """
+        audit_events = []
+
+        # Record security assessment event
+        findings = security_results.get("findings", [])
+        critical_findings = [f for f in findings if f.get("severity") == "CRITICAL"]
+
+        audit_event = self.record_audit_event(
+            module="security",
+            event_type="security_assessment",
+            description=f"Security assessment completed with {len(findings)} findings ({len(critical_findings)} critical)",
+            severity=AuditSeverity.CRITICAL if critical_findings else AuditSeverity.INFORMATIONAL,
+            metadata={
+                "total_findings": len(findings),
+                "critical_findings": len(critical_findings),
+                "assessment_timestamp": datetime.now().isoformat(),
+            },
+        )
+        audit_events.append(audit_event)
+
+        # Record individual critical findings
+        for finding in critical_findings:
+            audit_event = self.record_audit_event(
+                module="security",
+                event_type="critical_security_finding",
+                description=finding.get("description", "Critical security finding identified"),
+                severity=AuditSeverity.CRITICAL,
+                resource_id=finding.get("resource_id"),
+                account_id=finding.get("account_id"),
+                metadata=finding,
+            )
+            audit_events.append(audit_event)
+
+        return audit_events
+
+    async def audit_operate_operations(self, operation_results: List[Dict[str, Any]]) -> List[AuditEvent]:
+        """
+        Generate audit events for operational activities.
+
+        Args:
+            operation_results: Results from operate module
+
+        Returns:
+            List of generated audit events
+        """
+        audit_events = []
+
+        for operation in operation_results:
+            # Determine severity based on operation type and outcome
+            severity = (
+                AuditSeverity.HIGH if operation.get("type") in ["terminate", "delete"] else AuditSeverity.INFORMATIONAL
+            )
+            if not operation.get("success", True):
+                severity = AuditSeverity.HIGH
+
+            audit_event = self.record_audit_event(
+                module="operate",
+                event_type=f"operation_{operation.get('type', 'unknown')}",
+                description=f"Operation {operation.get('type', 'unknown')} on {operation.get('resource_id', 'unknown')} {'succeeded' if operation.get('success') else 'failed'}",
+                severity=severity,
+                resource_id=operation.get("resource_id"),
+                account_id=operation.get("account_id"),
+                region=operation.get("region"),
+                metadata=operation,
+            )
+            audit_events.append(audit_event)
+
+        return audit_events
+
+    def _determine_applicable_frameworks(self, event_type: str, module: str) -> List[ComplianceFramework]:
+        """Determine which compliance frameworks apply to an event."""
+        applicable = []
+
+        # All events apply to SOC2 and ISO27001 for general security controls
+        if ComplianceFramework.SOC2 in self.compliance_frameworks:
+            applicable.append(ComplianceFramework.SOC2)
+        if ComplianceFramework.ISO27001 in self.compliance_frameworks:
+            applicable.append(ComplianceFramework.ISO27001)
+
+        # AWS Well-Architected applies to all AWS operations
+        if ComplianceFramework.AWS_WELL_ARCHITECTED in self.compliance_frameworks:
+            applicable.append(ComplianceFramework.AWS_WELL_ARCHITECTED)
+
+        # Security and data handling events may apply to PCI-DSS and HIPAA
+        if event_type in ["security_assessment", "data_access", "encryption_change"]:
+            if ComplianceFramework.PCI_DSS in self.compliance_frameworks:
+                applicable.append(ComplianceFramework.PCI_DSS)
+            if ComplianceFramework.HIPAA in self.compliance_frameworks:
+                applicable.append(ComplianceFramework.HIPAA)
+
+        return applicable
+
+    def _calculate_compliance_score(self, events: List[AuditEvent]) -> float:
+        """Calculate overall compliance score based on audit events."""
+        if not events:
+            return 100.0
+
+        # Weight events by severity
+        severity_weights = {
+            AuditSeverity.CRITICAL: -10,
+            AuditSeverity.HIGH: -5,
+            AuditSeverity.MEDIUM: -2,
+            AuditSeverity.LOW: -1,
+            AuditSeverity.INFORMATIONAL: 0,
+        }
+
+        total_impact = sum(severity_weights.get(event.severity, 0) for event in events)
+
+        # Calculate score (100 is perfect, penalties reduce score)
+        base_score = 100.0
+        penalty = abs(total_impact) / len(events) * 10  # Scale penalty
+
+        compliance_score = max(0.0, base_score - penalty)
+        return min(100.0, compliance_score)
+
+    def _generate_compliance_recommendations(
+        self, events: List[AuditEvent], critical_findings: List[AuditEvent]
+    ) -> List[str]:
+        """Generate compliance recommendations based on audit events."""
+        recommendations = []
+
+        if critical_findings:
+            recommendations.append(f"Address {len(critical_findings)} critical security findings immediately")
+
+        # Analyze event patterns
+        module_event_counts = {}
+        for event in events:
+            if event.severity in [AuditSeverity.CRITICAL, AuditSeverity.HIGH]:
+                module_event_counts[event.module] = module_event_counts.get(event.module, 0) + 1
+
+        # Recommend focus areas
+        if module_event_counts:
+            top_module = max(module_event_counts, key=module_event_counts.get)
+            recommendations.append(
+                f"Focus security improvements on {top_module} module ({module_event_counts[top_module]} high-priority events)"
+            )
+
+        # Generic recommendations
+        recommendations.extend(
+            [
+                "Implement automated security remediation for common findings",
+                "Establish regular compliance monitoring and reporting",
+                "Enhance access controls and monitoring for critical operations",
+                "Review and update security policies based on audit findings",
+            ]
+        )
+
+        return recommendations
+
+    async def _analyze_business_impact(self, events: List[AuditEvent]) -> Dict[str, Any]:
+        """Analyze business impact of audit events."""
+        # Estimate potential cost impact
+        critical_events = [e for e in events if e.severity == AuditSeverity.CRITICAL]
+        high_events = [e for e in events if e.severity == AuditSeverity.HIGH]
+
+        # Rough cost estimates for different types of findings
+        estimated_cost_impact = len(critical_events) * 10000 + len(high_events) * 2500
+
+        return {
+            "estimated_cost_impact_usd": estimated_cost_impact,
+            "critical_business_risks": len(critical_events),
+            "compliance_violations": len([e for e in events if "compliance" in e.event_type]),
+            "operational_disruptions": len(
+                [e for e in events if e.module == "operate" and not e.metadata.get("success", True)]
+            ),
+            "security_exposure_level": "HIGH" if critical_events else "MEDIUM" if high_events else "LOW",
+        }
+
+    def _generate_audit_trail_summary(self, events: List[AuditEvent]) -> Dict[str, Any]:
+        """Generate audit trail summary statistics."""
+        return {
+            "total_events": len(events),
+            "unique_resources": len(set(e.resource_id for e in events if e.resource_id)),
+            "unique_accounts": len(set(e.account_id for e in events if e.account_id)),
+            "event_types": list(set(e.event_type for e in events)),
+            "time_span_days": (
+                datetime.fromisoformat(max(e.timestamp for e in events))
+                - datetime.fromisoformat(min(e.timestamp for e in events))
+            ).days
+            if events
+            else 0,
+        }
+
+    def _identify_inventory_compliance_issues(self, inventory_results: Dict[str, Any]) -> List[Dict[str, Any]]:
+        """Identify compliance issues from inventory results."""
+        issues = []
+
+        # Example compliance checks
+        resources = inventory_results.get("resources", {})
+
+        # Check for untagged resources
+        for resource_type, accounts_data in resources.items():
+            for account_id, account_data in accounts_data.items():
+                if resource_type == "ec2" and "instances" in account_data:
+                    for instance in account_data["instances"]:
+                        if not instance.get("tags"):
+                            issues.append(
+                                {
+                                    "description": f"Untagged EC2 instance {instance.get('instance_id')}",
+                                    "resource_id": instance.get("instance_id"),
+                                    "account_id": account_id,
+                                    "critical": False,
+                                    "metadata": {"compliance_rule": "required_tagging"},
+                                }
+                            )
+
+        return issues
+
+    def display_compliance_dashboard(self, report: ComplianceReport) -> None:
+        """Display comprehensive compliance dashboard using Rich formatting."""
+
+        # Main compliance score panel
+        score_color = "green" if report.compliance_score >= 95 else "yellow" if report.compliance_score >= 80 else "red"
+        score_panel = create_panel(
+            f"[{score_color}]{report.compliance_score:.1f}%[/{score_color}]", title="Overall Compliance Score"
+        )
+        console.print(score_panel)
+
+        # Events by severity table
+        severity_table = create_table(
+            title="Events by Severity", columns=[("Severity", "cyan"), ("Count", "magenta"), ("Percentage", "green")]
+        )
+
+        total_events = report.total_events
+        for severity, count in report.events_by_severity.items():
+            percentage = (count / total_events * 100) if total_events > 0 else 0
+            severity_table.add_row(severity.upper(), str(count), f"{percentage:.1f}%")
+
+        console.print(severity_table)
+
+        # Critical findings summary
+        if report.critical_findings:
+            console.print(
+                f"\n[red]🚨 {len(report.critical_findings)} Critical Findings Requiring Immediate Attention:[/red]"
+            )
+            for finding in report.critical_findings[:5]:  # Show top 5
+                console.print(f"  • {finding.description}")
+            if len(report.critical_findings) > 5:
+                console.print(f"  • ... and {len(report.critical_findings) - 5} more")
+
+        # Business impact
+        if report.business_impact_analysis:
+            impact = report.business_impact_analysis
+            cost_impact = impact.get("estimated_cost_impact_usd", 0)
+
+            if cost_impact > 0:
+                impact_panel = create_panel(
+                    f"Estimated Cost Impact: {format_cost(cost_impact)}\n"
+                    f"Security Exposure: {impact.get('security_exposure_level', 'UNKNOWN')}\n"
+                    f"Compliance Violations: {impact.get('compliance_violations', 0)}",
+                    title="Business Impact Analysis",
+                )
+                console.print(impact_panel)
+
+        # Recommendations
+        if report.recommendations:
+            console.print(f"\n[cyan]📋 Top Recommendations:[/cyan]")
+            for i, rec in enumerate(report.recommendations[:3], 1):
+                console.print(f"  {i}. {rec}")
+
+    def export_audit_report(self, report: ComplianceReport, format: str = "json") -> str:
+        """Export compliance report in specified format."""
+        if format.lower() == "json":
+            import json
+
+            return json.dumps(
+                {
+                    "compliance_report": {
+                        "report_timestamp": report.report_timestamp,
+                        "frameworks_assessed": [f.value for f in report.frameworks_assessed],
+                        "compliance_score": report.compliance_score,
+                        "total_events": report.total_events,
+                        "events_by_severity": report.events_by_severity,
+                        "events_by_module": report.events_by_module,
+                        "critical_findings": [finding.to_dict() for finding in report.critical_findings],
+                        "recommendations": report.recommendations,
+                        "business_impact_analysis": report.business_impact_analysis,
+                        "audit_trail_summary": report.audit_trail_summary,
+                    }
+                },
+                indent=2,
+            )
+
+        # Add other formats as needed (CSV, PDF, etc.)
+        return str(report)
+
+
+# Export public interface
+__all__ = [
+    "EnterpriseAuditIntegrator",
+    "ComplianceFramework",
+    "AuditSeverity",
+    "AuditEvent",
+    "ComplianceReport",
+]