exploitgraph 1.0.0__py3-none-any.whl

core/correlator.py

@@ -0,0 +1,476 @@
+"""
+ExploitGraph - Data Correlation Engine
+Links findings across modules into a coherent attack narrative.
+
+Instead of treating findings independently, this engine:
+  - Connects S3 exposure → CloudTrail logs → credentials → IAM identity
+  - Builds a structured attack timeline
+  - Generates the "attack story" for the final report
+  - Prioritizes attack paths by impact
+  - Maps credential usage across modules
+
+This is what transforms raw findings into intelligence.
+"""
+from __future__ import annotations
+from typing import TYPE_CHECKING, Optional
+from dataclasses import dataclass, field
+
+if TYPE_CHECKING:
+    from core.session_manager import Session
+
+
+@dataclass
+class AttackStep:
+    """A single step in the correlated attack chain."""
+    step:        int
+    title:       str
+    description: str
+    module:      str
+    severity:    str
+    evidence:    list[str] = field(default_factory=list)
+    leads_to:    list[str] = field(default_factory=list)
+    mitre:       str       = ""
+    aws_parallel:str       = ""
+    guardduty:   bool      = False  # Would this trigger GuardDuty?
+
+
+@dataclass
+class CredentialNode:
+    """A discovered credential with all its associated context."""
+    key_id:       str
+    secret_key:   str = ""
+    session_token:str = ""
+    source:       str = ""         # Where it came from (S3, CloudTrail, .env, etc.)
+    iam_identity: str = ""         # ARN once validated
+    account_id:   str = ""
+    username:     str = ""
+    privilege:    str = "unknown"  # admin | user | readonly | unknown
+    valid:        Optional[bool] = None
+    permissions:  list[str] = field(default_factory=list)
+    services:     list[str] = field(default_factory=list)
+
+
+class CorrelationEngine:
+    """
+    Correlates findings across all modules into a structured attack narrative.
+    Call correlate(session) after all modules have run to build the full picture.
+    """
+
+    def correlate(self, session: "Session") -> dict:
+        """
+        Main entry point. Returns a structured correlation report.
+        """
+        narrative   = self._build_narrative(session)
+        credentials = self._extract_credential_nodes(session)
+        timeline    = self._build_timeline(session)
+        attack_path = self._build_attack_path(session, narrative)
+        impact      = self._assess_impact(session, credentials)
+
+        return {
+            "narrative":    narrative,
+            "credentials":  [self._cred_to_dict(c) for c in credentials],
+            "timeline":     timeline,
+            "attack_path":  attack_path,
+            "impact":       impact,
+            "summary":      self._executive_summary(session, credentials, impact),
+        }
+
+    # ── Narrative Building ─────────────────────────────────────────────────────
+
+    def _build_narrative(self, session: "Session") -> list[dict]:
+        """
+        Build ordered attack steps from session findings.
+        Each step connects to the next — this IS the attack story.
+        """
+        steps = []
+        step_num = 0
+
+        def add_step(title, desc, module, severity, evidence=None,
+                      leads_to=None, mitre="", aws="", guardduty=False):
+            nonlocal step_num
+            step_num += 1
+            steps.append({
+                "step":        step_num,
+                "title":       title,
+                "description": desc,
+                "module":      module,
+                "severity":    severity,
+                "evidence":    evidence or [],
+                "leads_to":    leads_to or [],
+                "mitre":       mitre,
+                "aws_parallel":aws,
+                "guardduty_risk": guardduty,
+            })
+
+        # Step 1: Initial reconnaissance
+        endpoints = session.endpoints
+        if endpoints:
+            interesting = [e for e in endpoints if e.get("interesting")]
+            add_step(
+                title    = "Target Reconnaissance",
+                desc     = f"HTTP enumeration discovered {len(endpoints)} endpoints on the target. "
+                           f"Server fingerprinting revealed cloud infrastructure.",
+                module   = "discovery/http_enum",
+                severity = "INFO",
+                evidence = [e["url"] for e in endpoints[:5]],
+                leads_to = ["Cloud Storage Exposure"],
+                mitre    = "T1595.003",
+                aws      = "Equivalent to nmap/curl against EC2 or CloudFront",
+                guardduty = False,
+            )
+
+        # Step 2: Cloud storage exposure
+        buckets = [f for f in session.exposed_files if
+                   f.get("source") in ("s3_enum",) or
+                   "AWSLogs" in f.get("path", "") or
+                   f.get("path", "").endswith(".gz")]
+        if buckets or any("s3_enum" in f.get("source","") for f in session.exposed_files):
+            all_files = session.exposed_files
+            ct_files  = [f for f in all_files if "CloudTrail" in f.get("path","") or
+                         f.get("path","").endswith(".json.gz")]
+            add_step(
+                title    = "Cloud Storage Exposure",
+                desc     = f"Public S3 bucket discovered containing {len(all_files)} accessible files. "
+                           f"{len(ct_files)} CloudTrail audit log files found — "
+                           "these logs record every AWS API call made in the account.",
+                module   = "cloud/s3_enum",
+                severity = "CRITICAL",
+                evidence = [f.get("url", f.get("path", "")) for f in all_files[:5]],
+                leads_to = ["CloudTrail Log Analysis"] if ct_files else ["Secret Extraction"],
+                mitre    = "T1530",
+                aws      = "aws s3 ls s3://bucket --no-sign-request",
+                guardduty = True,  # Anonymous S3 access triggers GuardDuty
+            )
+
+        # Step 3: CloudTrail analysis
+        ct_findings = [f for f in session.findings if "CloudTrail" in f.get("title","")]
+        if ct_findings:
+            creds_in_ct = [s for s in session.secrets
+                           if "CloudTrail" in s.get("source","") or
+                              "cloudtrail" in s.get("source","").lower()]
+            add_step(
+                title    = "CloudTrail Log Analysis",
+                desc     = f"AWS CloudTrail audit logs parsed from downloaded .json.gz files. "
+                           f"Log analysis revealed {len(creds_in_ct)} AWS access key(s) and "
+                           f"detailed API call history including IAM usernames and source IPs.",
+                module   = "cloud/cloudtrail_analyzer",
+                severity = "CRITICAL",
+                evidence = [f["title"] for f in ct_findings[:3]],
+                leads_to = ["Credential Validation"] if creds_in_ct else [],
+                mitre    = "T1530,T1552.005",
+                aws      = "CloudTrail logs reveal complete AWS API history",
+                guardduty = False,  # Reading already-public logs
+            )
+
+        # Step 4: Secret extraction
+        secrets_by_type: dict[str, int] = {}
+        for s in session.secrets:
+            t = s.get("secret_type","")
+            secrets_by_type[t] = secrets_by_type.get(t, 0) + 1
+
+        if session.secrets:
+            add_step(
+                title    = "Credential Extraction",
+                desc     = f"Secret scanning of {len(session.exposed_files)} exposed files "
+                           f"yielded {len(session.secrets)} credentials across "
+                           f"{len(secrets_by_type)} types: {', '.join(secrets_by_type.keys())}.",
+                module   = "secrets/file_secrets",
+                severity = "CRITICAL",
+                evidence = [f"{s['secret_type']}: {s['value'][:20]}..." for s in session.secrets[:4]],
+                leads_to = ["AWS Credential Validation"] if any(
+                    s["secret_type"] in ("AWS_ACCESS_KEY","AWS_SECRET_KEY")
+                    for s in session.secrets
+                ) else [],
+                mitre    = "T1552.001",
+                aws      = "Secrets exposed in S3 instead of AWS Secrets Manager",
+                guardduty = False,
+            )
+
+        # Step 5: Credential validation
+        validated = [r for r in session.exploit_results
+                     if "credential_validator" in r.get("module","") and r.get("success")]
+        if validated:
+            cred_data = validated[0].get("data", {})
+            arn = cred_data.get("arn", "unknown")
+            add_step(
+                title    = f"AWS Credential Validated: {arn.split('/')[-1] if arn != 'unknown' else 'IAM User'}",
+                desc     = f"Discovered AWS credentials confirmed valid via STS GetCallerIdentity. "
+                           f"Identity: {arn}. "
+                           f"This grants real AWS API access equivalent to that IAM identity.",
+                module   = "cloud/aws_credential_validator",
+                severity = "CRITICAL",
+                evidence = [f"ARN: {arn}", f"Account: {cred_data.get('account','')}"],
+                leads_to = ["IAM Permission Enumeration", "Privilege Escalation"],
+                mitre    = "T1078.004",
+                aws      = "aws sts get-caller-identity (stolen credentials)",
+                guardduty = True,  # GetCallerIdentity from unknown IP triggers GuardDuty
+            )
+
+        # Step 6: IAM enumeration
+        iam_findings = [f for f in session.findings
+                        if any(kw in f.get("module","")
+                               for kw in ("iam_enum","iam_privilege"))]
+        if iam_findings:
+            privesc = [f for f in iam_findings if "escal" in f.get("title","").lower() or
+                       f.get("severity") == "CRITICAL"]
+            add_step(
+                title    = "IAM Permission Enumeration & Privilege Escalation",
+                desc     = f"IAM enumeration with stolen credentials revealed {len(iam_findings)} "
+                           f"security issues. {len(privesc)} privilege escalation path(s) identified.",
+                module   = "cloud/iam_privilege_escalation",
+                severity = "CRITICAL" if privesc else "HIGH",
+                evidence = [f["title"] for f in iam_findings[:4]],
+                leads_to = ["Full Account Compromise"] if privesc else [],
+                mitre    = "T1078.004,T1548",
+                aws      = "aws iam list-attached-user-policies (unauthorized)",
+                guardduty = True,  # IAM enumeration is very noisy
+            )
+
+        # Step 7: Full compromise
+        critical_findings = [f for f in session.findings if f.get("severity") == "CRITICAL"]
+        if len(critical_findings) >= 3 and session.secrets:
+            add_step(
+                title    = "Full AWS Account Compromise",
+                desc     = "Complete attack chain demonstrated: misconfigured S3 bucket exposed "
+                           "CloudTrail logs → IAM credentials extracted → credentials validated → "
+                           "IAM permissions enumerated. Account is fully compromised.",
+                module   = "framework",
+                severity = "CRITICAL",
+                evidence = [f"Total CRITICAL findings: {len(critical_findings)}",
+                            f"Credentials extracted: {len(session.secrets)}",
+                            f"Validated credentials: {len(validated)}"],
+                leads_to = [],
+                mitre    = "T1078.004,T1530,T1552",
+                aws      = "Complete kill chain — Capital One breach pattern",
+                guardduty = True,
+            )
+
+        return steps
+
+    # ── Credential Nodes ───────────────────────────────────────────────────────
+
+    def _extract_credential_nodes(self, session: "Session") -> list[CredentialNode]:
+        """Build rich credential objects by correlating secrets with validation results."""
+        nodes = []
+        # Pair access keys with secret keys
+        access_keys = [s for s in session.secrets if s["secret_type"] == "AWS_ACCESS_KEY"]
+        secret_keys = [s for s in session.secrets if s["secret_type"] == "AWS_SECRET_KEY"]
+
+        for ak in access_keys:
+            node = CredentialNode(
+                key_id = ak["value"],
+                source = ak.get("source", ""),
+            )
+            # Find matching secret key
+            for sk in secret_keys:
+                node.secret_key = sk["value"]
+                break
+
+            # Enrich from validation results
+            for result in session.exploit_results:
+                if "credential_validator" in result.get("module", "") and result.get("success"):
+                    data = result.get("data", {})
+                    node.iam_identity = data.get("arn", "")
+                    node.account_id   = data.get("account", "")
+                    node.username     = node.iam_identity.split("/")[-1] if node.iam_identity else ""
+                    node.privilege    = data.get("privilege", "unknown")
+                    node.valid        = True
+                    node.services     = data.get("accessible_services", [])
+
+            # Check CloudTrail findings for this key
+            for f in session.findings:
+                if ak["value"] in f.get("evidence", "") and "CloudTrail" in f.get("title", ""):
+                    if not node.iam_identity:
+                        # Try to extract from evidence
+                        import re
+                        arn_match = re.search(r'arn:aws:\S+', f.get("evidence", ""))
+                        if arn_match:
+                            node.iam_identity = arn_match.group()
+
+            nodes.append(node)
+
+        return nodes
+
+    # ── Timeline ───────────────────────────────────────────────────────────────
+
+    def _build_timeline(self, session: "Session") -> list[dict]:
+        """Build chronological timeline of findings and events."""
+        events = []
+        for f in session.findings:
+            events.append({
+                "time":     f.get("created_at", "")[:19].replace("T", " "),
+                "type":     "finding",
+                "severity": f.get("severity", "INFO"),
+                "title":    f.get("title", ""),
+                "module":   f.get("module", ""),
+            })
+        for s in session.secrets:
+            events.append({
+                "time":     s.get("created_at", "")[:19].replace("T", " "),
+                "type":     "secret",
+                "severity": s.get("severity", "HIGH"),
+                "title":    f"Secret found: {s['secret_type']}",
+                "module":   "secrets",
+            })
+        # Sort by time
+        events.sort(key=lambda x: x.get("time", ""))
+        return events
+
+    # ── Attack Path ────────────────────────────────────────────────────────────
+
+    def _build_attack_path(self, session: "Session", narrative: list[dict]) -> dict:
+        """Build the primary attack path — the highest-impact chain."""
+        if not narrative:
+            return {}
+
+        steps = [n["title"] for n in narrative]
+        total_severity = sum(
+            {"CRITICAL": 4, "HIGH": 3, "MEDIUM": 2, "LOW": 1, "INFO": 0}.get(
+                n.get("severity", "INFO"), 0
+            )
+            for n in narrative
+        )
+        guardduty_steps = [n["title"] for n in narrative if n.get("guardduty_risk")]
+
+        return {
+            "steps":           steps,
+            "length":          len(steps),
+            "total_impact":    total_severity,
+            "guardduty_risks": guardduty_steps,
+            "is_complete":     len(steps) >= 4,
+            "chain_summary":   " → ".join(steps),
+        }
+
+    # ── Impact Assessment ──────────────────────────────────────────────────────
+
+    def _assess_impact(self, session: "Session",
+                        credentials: list[CredentialNode]) -> dict:
+        """Assess the real-world impact of what was found."""
+        has_valid_creds = any(c.valid for c in credentials)
+        admin_creds     = any(c.privilege == "admin" for c in credentials)
+
+        impact_level = "LOW"
+        impact_desc  = "Limited exposure detected."
+
+        if admin_creds:
+            impact_level = "CRITICAL"
+            impact_desc  = (
+                "Administrative AWS credentials are compromised. "
+                "Attacker has full control of the AWS account including "
+                "all services, data, and the ability to create backdoor accounts."
+            )
+        elif has_valid_creds:
+            impact_level = "HIGH"
+            impact_desc  = (
+                "Valid AWS credentials are compromised. "
+                "Attacker can access all services permitted to this IAM identity. "
+                "Lateral movement to other services is possible."
+            )
+        elif session.secrets:
+            impact_level = "HIGH"
+            impact_desc  = (
+                f"{len(session.secrets)} credentials were extracted from exposed files. "
+                "Immediate rotation required."
+            )
+        elif session.exposed_files:
+            impact_level = "MEDIUM"
+            impact_desc  = (
+                f"{len(session.exposed_files)} sensitive files are publicly accessible. "
+                "Data exposure and credential leakage risk."
+            )
+
+        return {
+            "level":            impact_level,
+            "description":      impact_desc,
+            "valid_credentials":has_valid_creds,
+            "admin_access":     admin_creds,
+            "data_exposed":     len(session.exposed_files),
+            "secrets_found":    len(session.secrets),
+            "lateral_movement": has_valid_creds,
+            "immediate_actions": self._remediation_priority(session, credentials),
+        }
+
+    def _remediation_priority(self, session: "Session",
+                               credentials: list[CredentialNode]) -> list[str]:
+        """Return prioritized list of immediate actions."""
+        actions = []
+        if any(c.valid for c in credentials):
+            for c in credentials:
+                if c.valid and c.key_id:
+                    actions.append(
+                        f"IMMEDIATE: Deactivate IAM key {c.key_id[:12]}... "
+                        f"(aws iam update-access-key --access-key-id {c.key_id} --status Inactive)"
+                    )
+        if session.exposed_files:
+            bucket_sources = {f.get("source","") for f in session.exposed_files}
+            if "s3_enum" in bucket_sources:
+                actions.append(
+                    "IMMEDIATE: Enable S3 Block Public Access on all buckets "
+                    "(aws s3api put-public-access-block --bucket BUCKET ...)"
+                )
+        if session.secrets:
+            actions.append("HIGH: Rotate all extracted credentials — assume they are compromised")
+            actions.append("HIGH: Enable CloudTrail in all regions if not already active")
+        actions.append("MEDIUM: Enable GuardDuty for ongoing threat detection")
+        actions.append("MEDIUM: Review IAM policies — apply least-privilege principle")
+        return actions
+
+    # ── Executive Summary ──────────────────────────────────────────────────────
+
+    def _executive_summary(self, session: "Session",
+                            credentials: list[CredentialNode],
+                            impact: dict) -> str:
+        """One-paragraph executive summary for the report header."""
+        target = session.target
+        n_findings = len(session.findings)
+        n_secrets  = len(session.secrets)
+        n_files    = len(session.exposed_files)
+        impact_lvl = impact.get("level", "UNKNOWN")
+
+        parts = [
+            f"ExploitGraph security assessment of {target} identified "
+            f"{n_findings} findings with overall impact level {impact_lvl}."
+        ]
+
+        if n_files:
+            parts.append(
+                f"{n_files} sensitive files were accessible from publicly exposed "
+                f"cloud storage without authentication."
+            )
+        if n_secrets:
+            parts.append(
+                f"Secret scanning extracted {n_secrets} credentials from these files, "
+                f"including AWS access keys and API tokens."
+            )
+        if credentials:
+            valid = [c for c in credentials if c.valid]
+            if valid:
+                arns = [c.iam_identity for c in valid if c.iam_identity]
+                parts.append(
+                    f"{'Credential validation confirmed' if valid else 'Extracted credentials'} "
+                    f"{'active access as: ' + ', '.join(arns[:2]) if arns else 'valid AWS access'}. "
+                    "Immediate credential rotation is required."
+                )
+
+        parts.append(impact.get("description", ""))
+        return " ".join(parts)
+
+    # ── Helpers ────────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _cred_to_dict(c: CredentialNode) -> dict:
+        return {
+            "key_id":       c.key_id,
+            "secret_key":   c.secret_key[:8] + "..." if c.secret_key else "",
+            "source":       c.source,
+            "iam_identity": c.iam_identity,
+            "account_id":   c.account_id,
+            "username":     c.username,
+            "privilege":    c.privilege,
+            "valid":        c.valid,
+            "services":     c.services,
+        }
+
+
+# Global singleton
+correlator = CorrelationEngine()