souleyez 2.43.29__py3-none-any.whl → 3.0.0__py3-none-any.whl

souleyez/reporting/detection_report.py

@@ -28,6 +28,7 @@ from souleyez.storage.database import get_db
 @dataclass
 class RuleRecommendation:
     """Recommendation for improving detection coverage."""
+
     attack_type: str
     gap_description: str
     priority: str  # critical, high, medium, low
@@ -40,6 +41,7 @@ class RuleRecommendation:
 @dataclass
 class HostDetectionStats:
     """Detection statistics for a single host."""
+
     host_ip: str
     total_attacks: int = 0
     detected: int = 0
@@ -53,6 +55,7 @@ class HostDetectionStats:
 @dataclass
 class SeverityBreakdown:
     """Breakdown of alerts by severity level."""
+
     critical: int = 0
     high: int = 0
     medium: int = 0
@@ -64,6 +67,7 @@ class SeverityBreakdown:
 @dataclass
 class TopRule:
     """A frequently triggered rule/sourcetype."""
+
     rule_id: str
     rule_name: str
     count: int
@@ -74,6 +78,7 @@ class TopRule:
 @dataclass
 class SampleAlert:
     """A sample alert for display in the report."""
+
     rule_id: str
     rule_name: str
     severity: str
@@ -86,6 +91,7 @@ class SampleAlert:
 @dataclass
 class HostVulnerability:
     """Vulnerability info for a host."""
+
     cve_id: str
     name: str
     severity: str
@@ -97,6 +103,7 @@ class HostVulnerability:
 @dataclass
 class HostVulnerabilitySummary:
     """Vulnerability summary for a single host."""
+
     host_ip: str
     agent_name: str = ""
     total_vulns: int = 0
@@ -111,6 +118,7 @@ class HostVulnerabilitySummary:
 @dataclass
 class VulnerabilitySection:
     """Vulnerability data for the report."""
+
     total_vulns: int = 0
     hosts_with_vulns: int = 0
     critical_count: int = 0
@@ -124,6 +132,7 @@ class VulnerabilitySection:
 @dataclass
 class DetectionReportData:
     """Complete data structure for a detection coverage report."""
+
     engagement: Dict[str, Any]
     summary: EngagementDetectionSummary
     detection_results: List[DetectionResult]
@@ -143,7 +152,9 @@ class DetectionReportData:
     executive_summary: str = ""
     risk_level: str = "UNKNOWN"  # CRITICAL, HIGH, MEDIUM, LOW
     avg_detection_latency: str = ""
-    vulnerability_section: VulnerabilitySection = field(default_factory=VulnerabilitySection)
+    vulnerability_section: VulnerabilitySection = field(
+        default_factory=VulnerabilitySection
+    )
 
 
 class DetectionReportGatherer:
@@ -226,8 +237,7 @@ class DetectionReportGatherer:
         )
 
     def _build_per_host_analysis(
-        self,
-        results: List[DetectionResult]
+        self, results: List[DetectionResult]
     ) -> Dict[str, HostDetectionStats]:
         """
         Build detection statistics grouped by target host.
@@ -242,21 +252,21 @@ class DetectionReportGatherer:
 
         for result in results:
             # Get target IP - handle both object and dict
-            target_ip = getattr(result, 'target_ip', None)
+            target_ip = getattr(result, "target_ip", None)
             if target_ip is None and isinstance(result, dict):
-                target_ip = result.get('target_ip')
+                target_ip = result.get("target_ip")
             if not target_ip:
                 target_ip = "unknown"
 
             # Get attack type
-            attack_type = getattr(result, 'attack_type', None)
+            attack_type = getattr(result, "attack_type", None)
             if attack_type is None and isinstance(result, dict):
-                attack_type = result.get('attack_type', 'unknown')
+                attack_type = result.get("attack_type", "unknown")
 
             # Get status
-            status = getattr(result, 'status', None)
+            status = getattr(result, "status", None)
             if status is None and isinstance(result, dict):
-                status = result.get('status', 'unknown')
+                status = result.get("status", "unknown")
 
             # Initialize host stats if needed
             if target_ip not in hosts:
@@ -283,16 +293,12 @@ class DetectionReportGatherer:
         for host in hosts.values():
             countable = host.detected + host.not_detected + host.partial
             if countable > 0:
-                host.coverage_percent = round(
-                    (host.detected / countable) * 100, 1
-                )
+                host.coverage_percent = round((host.detected / countable) * 100, 1)
 
         return hosts
 
     def _generate_rule_recommendations(
-        self,
-        gaps: List[DetectionResult],
-        mitre_gaps: List[TechniqueResult]
+        self, gaps: List[DetectionResult], mitre_gaps: List[TechniqueResult]
     ) -> List[RuleRecommendation]:
         """
         Generate SIEM rule recommendations for detection gaps.
@@ -309,9 +315,9 @@ class DetectionReportGatherer:
 
         for gap in gaps:
             # Get attack type
-            attack_type = getattr(gap, 'attack_type', None)
+            attack_type = getattr(gap, "attack_type", None)
             if attack_type is None and isinstance(gap, dict):
-                attack_type = gap.get('attack_type')
+                attack_type = gap.get("attack_type")
             if not attack_type or attack_type in seen_attack_types:
                 continue
 
@@ -361,9 +367,7 @@ class DetectionReportGatherer:
         return recommendations
 
     def _get_detection_guidance(
-        self,
-        attack_type: str,
-        signature: Dict[str, Any]
+        self, attack_type: str, signature: Dict[str, Any]
     ) -> str:
         """
         Generate human-readable detection guidance for an attack type.
@@ -453,13 +457,11 @@ class DetectionReportGatherer:
         }
 
         return category_guidance.get(
-            category,
-            "Review SIEM rule configuration for this attack category."
+            category, "Review SIEM rule configuration for this attack category."
         )
 
     def _build_severity_breakdown(
-        self,
-        results: List[DetectionResult]
+        self, results: List[DetectionResult]
     ) -> SeverityBreakdown:
         """
         Build severity breakdown from detected alerts.
@@ -473,20 +475,20 @@ class DetectionReportGatherer:
         breakdown = SeverityBreakdown()
 
         for result in results:
-            if result.status != 'detected' or not result.alerts:
+            if result.status != "detected" or not result.alerts:
                 continue
 
             for alert in result.alerts:
-                severity = str(alert.get('severity', 'info')).lower()
+                severity = str(alert.get("severity", "info")).lower()
                 breakdown.total += 1
 
-                if severity in ('critical', 'crit'):
+                if severity in ("critical", "crit"):
                     breakdown.critical += 1
-                elif severity == 'high':
+                elif severity == "high":
                     breakdown.high += 1
-                elif severity in ('medium', 'med'):
+                elif severity in ("medium", "med"):
                     breakdown.medium += 1
-                elif severity == 'low':
+                elif severity == "low":
                     breakdown.low += 1
                 else:
                     breakdown.info += 1
@@ -494,9 +496,7 @@ class DetectionReportGatherer:
         return breakdown
 
     def _get_top_rules(
-        self,
-        results: List[DetectionResult],
-        limit: int = 10
+        self, results: List[DetectionResult], limit: int = 10
     ) -> List[TopRule]:
         """
         Get the most frequently triggered rules.
@@ -511,47 +511,43 @@ class DetectionReportGatherer:
         rule_counts: Dict[str, Dict[str, Any]] = {}
 
         for result in results:
-            if result.status != 'detected' or not result.alerts:
+            if result.status != "detected" or not result.alerts:
                 continue
 
             for alert in result.alerts:
-                rule_id = str(alert.get('rule_id', 'unknown'))
-                rule_name = alert.get('rule_name', alert.get('name', 'Unknown Rule'))
-                severity = str(alert.get('severity', 'info')).lower()
-                description = alert.get('description', '')
+                rule_id = str(alert.get("rule_id", "unknown"))
+                rule_name = alert.get("rule_name", alert.get("name", "Unknown Rule"))
+                severity = str(alert.get("severity", "info")).lower()
+                description = alert.get("description", "")
 
                 if rule_id not in rule_counts:
                     rule_counts[rule_id] = {
-                        'rule_id': rule_id,
-                        'rule_name': rule_name,
-                        'severity': severity,
-                        'description': description,
-                        'count': 0
+                        "rule_id": rule_id,
+                        "rule_name": rule_name,
+                        "severity": severity,
+                        "description": description,
+                        "count": 0,
                     }
-                rule_counts[rule_id]['count'] += 1
+                rule_counts[rule_id]["count"] += 1
 
         # Sort by count descending
         sorted_rules = sorted(
-            rule_counts.values(),
-            key=lambda r: r['count'],
-            reverse=True
+            rule_counts.values(), key=lambda r: r["count"], reverse=True
         )[:limit]
 
         return [
             TopRule(
-                rule_id=r['rule_id'],
-                rule_name=r['rule_name'],
-                count=r['count'],
-                severity=r['severity'],
-                description=r['description'][:200] if r['description'] else ""
+                rule_id=r["rule_id"],
+                rule_name=r["rule_name"],
+                count=r["count"],
+                severity=r["severity"],
+                description=r["description"][:200] if r["description"] else "",
             )
             for r in sorted_rules
         ]
 
     def _get_sample_alerts(
-        self,
-        results: List[DetectionResult],
-        limit: int = 5
+        self, results: List[DetectionResult], limit: int = 5
     ) -> List[SampleAlert]:
         """
         Get sample alerts for display in the report.
@@ -566,11 +562,19 @@ class DetectionReportGatherer:
         samples: List[SampleAlert] = []
 
         # Prioritize alerts from detected attacks, favor higher severity
-        severity_order = {'critical': 0, 'crit': 0, 'high': 1, 'medium': 2, 'med': 2, 'low': 3, 'info': 4}
+        severity_order = {
+            "critical": 0,
+            "crit": 0,
+            "high": 1,
+            "medium": 2,
+            "med": 2,
+            "low": 3,
+            "info": 4,
+        }
 
         all_alerts = []
         for result in results:
-            if result.status != 'detected' or not result.alerts:
+            if result.status != "detected" or not result.alerts:
                 continue
             for alert in result.alerts[:3]:  # Max 3 per result
                 all_alerts.append((result.attack_type, alert))
@@ -578,38 +582,40 @@ class DetectionReportGatherer:
         # Sort by severity
         all_alerts.sort(
             key=lambda x: severity_order.get(
-                str(x[1].get('severity', 'info')).lower(), 5
+                str(x[1].get("severity", "info")).lower(), 5
             )
         )
 
         for attack_type, alert in all_alerts[:limit]:
             # Extract raw snippet from alert data
-            raw_data = alert.get('raw_data', {})
+            raw_data = alert.get("raw_data", {})
             raw_snippet = ""
             if isinstance(raw_data, dict):
                 # Try to get meaningful snippet
-                full_log = raw_data.get('full_log', '')
+                full_log = raw_data.get("full_log", "")
                 if full_log:
                     raw_snippet = full_log[:300]
                 else:
                     # Try message or description
-                    raw_snippet = raw_data.get('message', '')[:300]
+                    raw_snippet = raw_data.get("message", "")[:300]
             elif isinstance(raw_data, str):
                 raw_snippet = raw_data[:300]
 
-            timestamp = alert.get('timestamp', '')
-            if hasattr(timestamp, 'isoformat'):
+            timestamp = alert.get("timestamp", "")
+            if hasattr(timestamp, "isoformat"):
                 timestamp = timestamp.isoformat()
 
-            samples.append(SampleAlert(
-                rule_id=str(alert.get('rule_id', 'N/A')),
-                rule_name=alert.get('rule_name', alert.get('name', 'Unknown')),
-                severity=str(alert.get('severity', 'info')),
-                timestamp=str(timestamp),
-                source=attack_type,
-                description=alert.get('description', '')[:200],
-                raw_snippet=raw_snippet
-            ))
+            samples.append(
+                SampleAlert(
+                    rule_id=str(alert.get("rule_id", "N/A")),
+                    rule_name=alert.get("rule_name", alert.get("name", "Unknown")),
+                    severity=str(alert.get("severity", "info")),
+                    timestamp=str(timestamp),
+                    source=attack_type,
+                    description=alert.get("description", "")[:200],
+                    raw_snippet=raw_snippet,
+                )
+            )
 
         return samples
 
@@ -618,7 +624,7 @@ class DetectionReportGatherer:
         summary: EngagementDetectionSummary,
         severity: SeverityBreakdown,
         gaps: List[DetectionResult],
-        mitre_gaps: List[TechniqueResult]
+        mitre_gaps: List[TechniqueResult],
     ) -> str:
         """
         Generate an executive summary paragraph for the report.
@@ -699,9 +705,7 @@ class DetectionReportGatherer:
         return " ".join(parts)
 
     def _calculate_risk_level(
-        self,
-        coverage_percent: float,
-        gaps: List[DetectionResult]
+        self, coverage_percent: float, gaps: List[DetectionResult]
     ) -> str:
         """
         Calculate overall risk level based on coverage and gap severity.
@@ -716,9 +720,9 @@ class DetectionReportGatherer:
         # Check for critical gaps
         critical_gaps = 0
         for gap in gaps:
-            attack_type = gap.attack_type if hasattr(gap, 'attack_type') else ''
+            attack_type = gap.attack_type if hasattr(gap, "attack_type") else ""
             signature = get_signature(attack_type)
-            if signature.get('severity') in ('critical', 'high'):
+            if signature.get("severity") in ("critical", "high"):
                 critical_gaps += 1
 
         # Determine risk level
@@ -732,8 +736,7 @@ class DetectionReportGatherer:
             return "LOW"
 
     def _gather_vulnerability_data(
-        self,
-        per_host_analysis: Dict[str, HostDetectionStats]
+        self, per_host_analysis: Dict[str, HostDetectionStats]
     ) -> VulnerabilitySection:
         """
         Gather vulnerability data for hosts that were attacked.
@@ -756,8 +759,7 @@ class DetectionReportGatherer:
 
             # Get all vulnerabilities for this engagement
             all_vulns = vulns_manager.list_vulnerabilities(
-                engagement_id=self.engagement_id,
-                limit=1000
+                engagement_id=self.engagement_id, limit=1000
             )
 
             if not all_vulns:
@@ -769,12 +771,12 @@ class DetectionReportGatherer:
             # Build summary by severity
             for vuln in all_vulns:
                 section.total_vulns += 1
-                severity = (vuln.get('severity') or 'Low').lower()
-                if severity == 'critical':
+                severity = (vuln.get("severity") or "Low").lower()
+                if severity == "critical":
                     section.critical_count += 1
-                elif severity == 'high':
+                elif severity == "high":
                     section.high_count += 1
-                elif severity == 'medium':
+                elif severity == "medium":
                     section.medium_count += 1
                 else:
                     section.low_count += 1
@@ -782,7 +784,7 @@ class DetectionReportGatherer:
             # Group vulnerabilities by host/agent IP
             host_vulns: Dict[str, List[Dict]] = {}
             for vuln in all_vulns:
-                agent_ip = vuln.get('agent_ip') or vuln.get('host_ip') or 'unknown'
+                agent_ip = vuln.get("agent_ip") or vuln.get("host_ip") or "unknown"
                 if agent_ip not in host_vulns:
                     host_vulns[agent_ip] = []
                 host_vulns[agent_ip].append(vuln)
@@ -795,39 +797,39 @@ class DetectionReportGatherer:
 
                 host_summary = HostVulnerabilitySummary(
                     host_ip=host_ip,
-                    agent_name=vulns[0].get('agent_name', '') if vulns else '',
+                    agent_name=vulns[0].get("agent_name", "") if vulns else "",
                     total_vulns=len(vulns),
-                    was_attacked=was_attacked
+                    was_attacked=was_attacked,
                 )
 
                 # Count by severity for this host
                 for v in vulns:
-                    sev = (v.get('severity') or 'Low').lower()
-                    if sev == 'critical':
+                    sev = (v.get("severity") or "Low").lower()
+                    if sev == "critical":
                         host_summary.critical += 1
-                    elif sev == 'high':
+                    elif sev == "high":
                         host_summary.high += 1
-                    elif sev == 'medium':
+                    elif sev == "medium":
                         host_summary.medium += 1
                     else:
                         host_summary.low += 1
 
                 # Get top 5 vulns for this host (by CVSS score)
                 sorted_vulns = sorted(
-                    vulns,
-                    key=lambda x: x.get('cvss_score') or 0,
-                    reverse=True
+                    vulns, key=lambda x: x.get("cvss_score") or 0, reverse=True
                 )[:5]
 
                 for v in sorted_vulns:
-                    host_summary.top_vulns.append(HostVulnerability(
-                        cve_id=v.get('cve_id', 'N/A'),
-                        name=v.get('name', '')[:100],
-                        severity=v.get('severity', 'Low'),
-                        cvss_score=v.get('cvss_score') or 0.0,
-                        package_name=v.get('package_name', ''),
-                        package_version=v.get('package_version', '')
-                    ))
+                    host_summary.top_vulns.append(
+                        HostVulnerability(
+                            cve_id=v.get("cve_id", "N/A"),
+                            name=v.get("name", "")[:100],
+                            severity=v.get("severity", "Low"),
+                            cvss_score=v.get("cvss_score") or 0.0,
+                            package_name=v.get("package_name", ""),
+                            package_version=v.get("package_version", ""),
+                        )
+                    )
 
                 section.host_summaries.append(host_summary)
 
@@ -839,33 +841,36 @@ class DetectionReportGatherer:
             # Get top 10 CVEs across all hosts
             all_cves: Dict[str, Dict] = {}
             for vuln in all_vulns:
-                cve_id = vuln.get('cve_id')
+                cve_id = vuln.get("cve_id")
                 if not cve_id:
                     continue
                 if cve_id not in all_cves:
                     all_cves[cve_id] = vuln
-                elif (vuln.get('cvss_score') or 0) > (all_cves[cve_id].get('cvss_score') or 0):
+                elif (vuln.get("cvss_score") or 0) > (
+                    all_cves[cve_id].get("cvss_score") or 0
+                ):
                     all_cves[cve_id] = vuln
 
             sorted_cves = sorted(
-                all_cves.values(),
-                key=lambda x: x.get('cvss_score') or 0,
-                reverse=True
+                all_cves.values(), key=lambda x: x.get("cvss_score") or 0, reverse=True
             )[:10]
 
             for v in sorted_cves:
-                section.top_cves.append(HostVulnerability(
-                    cve_id=v.get('cve_id', 'N/A'),
-                    name=v.get('name', '')[:100],
-                    severity=v.get('severity', 'Low'),
-                    cvss_score=v.get('cvss_score') or 0.0,
-                    package_name=v.get('package_name', ''),
-                    package_version=v.get('package_version', '')
-                ))
+                section.top_cves.append(
+                    HostVulnerability(
+                        cve_id=v.get("cve_id", "N/A"),
+                        name=v.get("name", "")[:100],
+                        severity=v.get("severity", "Low"),
+                        cvss_score=v.get("cvss_score") or 0.0,
+                        package_name=v.get("package_name", ""),
+                        package_version=v.get("package_version", ""),
+                    )
+                )
 
         except Exception as e:
             # Log but don't fail the report
             import logging
+
             logging.getLogger(__name__).warning(
                 f"Failed to gather vulnerability data: {e}"
             )
@@ -894,12 +899,10 @@ class DetectionReportGatherer:
 
         # Count tactics with coverage
         tactics_tested = sum(
-            1 for t in data.tactic_summary.values()
-            if t.techniques_tested > 0
+            1 for t in data.tactic_summary.values() if t.techniques_tested > 0
         )
         tactics_with_gaps = sum(
-            1 for t in data.tactic_summary.values()
-            if t.techniques_not_detected > 0
+            1 for t in data.tactic_summary.values() if t.techniques_not_detected > 0
         )
 
         return {
@@ -912,13 +915,11 @@ class DetectionReportGatherer:
             "tactics_with_gaps": tactics_with_gaps,
             "techniques_tested": len(data.mitre_coverage),
             "techniques_detected": sum(
-                1 for t in data.mitre_coverage.values()
-                if t.detected > 0
+                1 for t in data.mitre_coverage.values() if t.detected > 0
             ),
             "hosts_tested": len(data.per_host_analysis),
             "critical_recommendations": sum(
-                1 for r in data.rule_recommendations
-                if r.priority == "critical"
+                1 for r in data.rule_recommendations if r.priority == "critical"
             ),
         }