exploitgraph 1.0.0__py3-none-any.whl

modules/cloud/cloudtrail_analyzer.py

@@ -0,0 +1,494 @@
+"""
+ExploitGraph Module: CloudTrail Log Analyzer
+Category: cloud
+
+Automatically decompresses and parses AWS CloudTrail logs found in S3 buckets.
+This is the critical next step after s3_enum downloads .json.gz log files.
+
+Real attack scenario (flaws2.cloud):
+  s3_enum finds s3://flaws2-logs → downloads CloudTrail .json.gz files
+  → this module parses them → extracts IAM access keys, usernames, API calls
+  → those credentials feed aws_credential_validator → full compromise
+
+What CloudTrail logs reveal:
+  - Which IAM users/roles made API calls
+  - Access key IDs used (AKIA...)
+  - IP addresses of callers
+  - Every AWS API call made (CreateUser, PutRolePolicy, etc.)
+  - Error codes revealing permission attempts
+
+MITRE: T1530, T1078.004, T1552.005
+"""
+from __future__ import annotations
+import gzip
+import json
+import re
+import io
+from collections import defaultdict
+from typing import TYPE_CHECKING
+
+import requests
+from requests.packages.urllib3.exceptions import InsecureRequestWarning
+requests.packages.urllib3.disable_warnings(InsecureRequestWarning)
+
+from modules.base import BaseModule, ModuleResult
+
+if TYPE_CHECKING:
+    from core.session_manager import Session
+
+# API calls that indicate privilege escalation attempts
+PRIVESC_EVENTS = {
+    "CreateUser", "CreateAccessKey", "AttachUserPolicy", "AttachRolePolicy",
+    "PutUserPolicy", "PutRolePolicy", "CreatePolicy", "CreatePolicyVersion",
+    "SetDefaultPolicyVersion", "PassRole", "AssumeRole", "AssumeRoleWithWebIdentity",
+    "UpdateAssumeRolePolicy", "AddUserToGroup", "CreateGroup", "AttachGroupPolicy",
+    "PutGroupPolicy", "CreateLoginProfile", "UpdateLoginProfile",
+}
+
+# API calls that indicate data exfiltration
+EXFIL_EVENTS = {
+    "GetObject", "ListObjects", "ListBuckets", "GetBucketAcl",
+    "GetBucketPolicy", "ListObjectsV2", "GetSecretValue",
+    "GetParameter", "GetParameters", "DescribeSecret",
+}
+
+# Reconnaissance events
+RECON_EVENTS = {
+    "DescribeInstances", "ListUsers", "ListRoles", "ListPolicies",
+    "GetAccountSummary", "ListBuckets", "DescribeSecurityGroups",
+    "GetCallerIdentity", "ListAttachedUserPolicies", "ListGroupsForUser",
+    "GetUserPolicy", "ListAccessKeys", "GetAccountAuthorizationDetails",
+}
+
+# Events that GuardDuty would flag
+NOISY_EVENTS = {
+    "GetCallerIdentity",      # Reconnaissance — always flagged
+    "ListUsers",              # IAM enumeration
+    "ListRoles",
+    "GetAccountAuthorizationDetails",  # Very noisy — full IAM dump
+    "CreateAccessKey",        # Credential creation
+    "DeleteTrail",            # Covering tracks
+    "StopLogging",            # Covering tracks
+}
+
+
+class CloudTrailAnalyzer(BaseModule):
+
+    NAME        = "cloudtrail_analyzer"
+    DESCRIPTION = "Parse AWS CloudTrail logs from downloaded .json.gz files — extract credentials, IAM activity, and attack indicators"
+    AUTHOR      = "ExploitGraph Team"
+    VERSION     = "1.1.0"
+    CATEGORY    = "cloud"
+    SEVERITY    = "CRITICAL"
+    MITRE       = ["T1530", "T1078.004", "T1552.005"]
+    AWS_PARALLEL = "aws cloudtrail lookup-events --lookup-attributes AttributeKey=Username,AttributeValue=<user>"
+
+    OPTIONS = {
+        "TARGET":         {"default": "",     "required": False, "description": "Target URL (optional, for fetching additional logs)"},
+        "MAX_EVENTS":     {"default": "1000", "required": False, "description": "Maximum events to parse per log file"},
+        "DOWNLOAD_DIR":   {"default": "downloads", "required": False, "description": "Directory for saving decompressed logs"},
+        "DETECT_PRIVESC": {"default": "true", "required": False, "description": "Flag privilege escalation API calls"},
+        "DETECT_EXFIL":   {"default": "true", "required": False, "description": "Flag data exfiltration API calls"},
+        "GUARDDUTY_MODE": {"default": "true", "required": False, "description": "Flag events that would trigger GuardDuty"},
+    }
+
+    def run(self, session: "Session") -> ModuleResult:
+        from core.logger import log
+        import os
+
+        self._timer_start()
+        log.section("CloudTrail Log Analyzer")
+        log.info("MITRE: T1530 — Data from Cloud Storage / T1078.004 — Valid Accounts")
+        log.info("Parsing downloaded CloudTrail .json.gz files from s3_enum")
+
+        # Find all CloudTrail log files from session
+        log_files = self._find_cloudtrail_files(session)
+
+        if not log_files:
+            log.warning("No CloudTrail log files found in session.")
+            log.step("Run cloud/s3_enum first to download logs from exposed buckets.")
+            return ModuleResult(True, {"events_parsed": 0,
+                                        "skipped_reason": "No CloudTrail files in session"})
+
+        log.info(f"Found {len(log_files)} CloudTrail log files to analyze")
+
+        # Aggregated findings across all log files
+        all_events         = []
+        credentials_found  = []
+        principals         = defaultdict(list)   # ARN → [events]
+        ips                = defaultdict(int)     # IP → count
+        privesc_events     = []
+        exfil_events       = []
+        noisy_events       = []
+        error_events       = []
+
+        for file_info in log_files:
+            log.step(f"Parsing: {file_info['path']}")
+            events = self._parse_log_file(file_info, session)
+            if events:
+                log.success(f"  Parsed {len(events)} events")
+                all_events.extend(events)
+
+                # Analyze events
+                for event in events:
+                    self._analyze_event(event, credentials_found, principals,
+                                        ips, privesc_events, exfil_events,
+                                        noisy_events, error_events)
+
+        # Generate findings from analysis
+        self._generate_findings(
+            all_events, credentials_found, principals, ips,
+            privesc_events, exfil_events, noisy_events, error_events, session
+        )
+
+        # Add to attack graph
+        if all_events or credentials_found:
+            session.add_graph_node(
+                "cloudtrail", f"CloudTrail Logs\n{len(all_events)} events",
+                "asset", "HIGH",
+                f"{len(credentials_found)} credentials, {len(privesc_events)} priv-esc events"
+            )
+            session.add_graph_edge("s3_exposure", "cloudtrail",
+                                   "log analysis", "T1530")
+
+            if credentials_found:
+                session.add_graph_node(
+                    "cloudtrail_creds",
+                    f"IAM Creds in Logs\n{len(credentials_found)} found",
+                    "credential", "CRITICAL"
+                )
+                session.add_graph_edge("cloudtrail", "cloudtrail_creds",
+                                       "extract credentials", "T1078.004")
+
+        # Print summary
+        elapsed = self._timer_stop()
+        log.newline()
+        log.banner(f"CLOUDTRAIL ANALYSIS COMPLETE")
+        log.kv("Log files analyzed",   str(len(log_files)))
+        log.kv("Total events",         str(len(all_events)))
+        log.kv("Unique principals",    str(len(principals)))
+        log.kv("Credentials found",    str(len(credentials_found)))
+        log.kv("Priv-esc events",      str(len(privesc_events)))
+        log.kv("Exfiltration events",  str(len(exfil_events)))
+        log.kv("GuardDuty-noisy",      str(len(noisy_events)))
+
+        if credentials_found:
+            log.newline()
+            log.critical("CREDENTIALS EXTRACTED FROM CLOUDTRAIL LOGS:")
+            for cred in credentials_found:
+                log.secret(cred["type"], cred["value"])
+                log.step(f"Used by: {cred.get('principal', 'unknown')}")
+                log.step(f"Source IP: {cred.get('ip', 'unknown')}")
+
+        return ModuleResult(True, {
+            "log_files":       len(log_files),
+            "events_parsed":   len(all_events),
+            "credentials":     len(credentials_found),
+            "principals":      len(principals),
+            "privesc_events":  len(privesc_events),
+            "exfil_events":    len(exfil_events),
+        })
+
+    # ── File discovery ─────────────────────────────────────────────────────
+
+    def _find_cloudtrail_files(self, session: "Session") -> list[dict]:
+        """Find CloudTrail log files from session's downloaded content."""
+        files = []
+        for ef in session.exposed_files:
+            path = ef.get("path", "") or ef.get("url", "")
+            # Match CloudTrail patterns: AWSLogs/*/CloudTrail/*.json.gz
+            if (("CloudTrail" in path or "AWSLogs" in path) and
+                    (path.endswith(".json.gz") or path.endswith(".json"))):
+                files.append(ef)
+            # Also match any .json.gz we downloaded
+            elif path.endswith(".json.gz"):
+                files.append(ef)
+        return files
+
+    # ── Log parsing ────────────────────────────────────────────────────────
+
+    def _parse_log_file(self, file_info: dict, session: "Session") -> list[dict]:
+        """
+        Decompress and parse a CloudTrail log file.
+        Handles: in-memory content (bytes), URLs for re-fetching.
+        """
+        from core.logger import log
+        max_events = int(self.get_option("MAX_EVENTS", "1000"))
+        events = []
+
+        # Try to get raw bytes content
+        raw_bytes = file_info.get("raw_bytes")
+        content   = file_info.get("content")
+        url       = file_info.get("url", "")
+
+        # If we only have the URL, re-fetch it
+        if not raw_bytes and not content and url.startswith("http"):
+            try:
+                r = requests.get(url, timeout=15, verify=False)
+                if r.status_code == 200:
+                    raw_bytes = r.content
+                    log.step(f"  Re-fetched: {len(raw_bytes)} bytes")
+            except Exception as e:
+                log.warning(f"  Could not fetch: {url}: {e}")
+                return []
+
+        # Decompress if gzipped
+        if raw_bytes:
+            try:
+                if raw_bytes[:2] == b'\x1f\x8b':  # gzip magic bytes
+                    with gzip.open(io.BytesIO(raw_bytes)) as gz:
+                        content = gz.read().decode("utf-8", errors="ignore")
+                    log.step(f"  Decompressed: {len(content)} chars")
+                else:
+                    content = raw_bytes.decode("utf-8", errors="ignore")
+            except Exception as e:
+                log.warning(f"  Decompression failed: {e}")
+                return []
+
+        if not content:
+            return []
+
+        # Parse JSON
+        try:
+            data = json.loads(content)
+            records = data.get("Records", [])
+            log.step(f"  Records: {len(records)}")
+
+            for record in records[:max_events]:
+                events.append(self._normalize_event(record))
+
+        except json.JSONDecodeError as e:
+            log.warning(f"  JSON parse error: {e}")
+            # Try to extract partial events with regex
+            for match in re.finditer(r'\{[^{}]+\}', content):
+                try:
+                    events.append(self._normalize_event(json.loads(match.group(0))))
+                except Exception:
+                    pass
+
+        return events
+
+    def _normalize_event(self, record: dict) -> dict:
+        """Extract the key fields from a CloudTrail record."""
+        identity = record.get("userIdentity", {})
+        return {
+            "event_time":        record.get("eventTime", ""),
+            "event_name":        record.get("eventName", ""),
+            "event_source":      record.get("eventSource", ""),
+            "source_ip":         record.get("sourceIPAddress", ""),
+            "user_agent":        record.get("userAgent", ""),
+            "region":            record.get("awsRegion", ""),
+            "request_params":    record.get("requestParameters") or {},
+            "response_elements": record.get("responseElements") or {},
+            "error_code":        record.get("errorCode", ""),
+            "error_message":     record.get("errorMessage", ""),
+            # Identity
+            "principal_type":    identity.get("type", ""),
+            "principal_arn":     identity.get("arn", ""),
+            "principal_account": identity.get("accountId", ""),
+            "access_key_id":     identity.get("accessKeyId", ""),
+            "username":          identity.get("userName", ""),
+            # Assumed role session
+            "session_issuer_arn": (identity.get("sessionContext", {})
+                                   .get("sessionIssuer", {}).get("arn", "")),
+        }
+
+    # ── Analysis ───────────────────────────────────────────────────────────
+
+    def _analyze_event(self, event: dict, credentials_found: list,
+                        principals: dict, ips: dict,
+                        privesc_events: list, exfil_events: list,
+                        noisy_events: list, error_events: list) -> None:
+        """Analyse a single normalised event and categorise it."""
+        event_name = event["event_name"]
+        source_ip  = event["source_ip"]
+        arn        = event["principal_arn"] or event.get("session_issuer_arn", "")
+        access_key = event["access_key_id"]
+
+        # Track principals
+        if arn:
+            principals[arn].append(event_name)
+
+        # Track IPs
+        if source_ip and source_ip not in ("AWS Internal",):
+            ips[source_ip] += 1
+
+        # Extract access key IDs (AKIA...)
+        if access_key and re.match(r'AKIA[A-Z0-9]{16}', access_key):
+            if not any(c["value"] == access_key for c in credentials_found):
+                credentials_found.append({
+                    "type":      "AWS_ACCESS_KEY",
+                    "value":     access_key,
+                    "principal": arn or event.get("username", "unknown"),
+                    "ip":        source_ip,
+                    "source":    "CloudTrail log",
+                })
+
+        # Extract access keys from response elements (CreateAccessKey response)
+        if event_name == "CreateAccessKey":
+            resp = event.get("response_elements", {}) or {}
+            new_key = (resp.get("accessKey", {}) or {}).get("accessKeyId", "")
+            if new_key and re.match(r'AKIA[A-Z0-9]{16}', new_key):
+                credentials_found.append({
+                    "type":      "AWS_ACCESS_KEY",
+                    "value":     new_key,
+                    "principal": arn,
+                    "ip":        source_ip,
+                    "source":    "CloudTrail CreateAccessKey response",
+                    "note":      "Key was CREATED during the logged session",
+                })
+
+        # Categorise event
+        if event_name in PRIVESC_EVENTS:
+            privesc_events.append(event)
+        if event_name in EXFIL_EVENTS:
+            exfil_events.append(event)
+        if event_name in NOISY_EVENTS:
+            noisy_events.append(event)
+        if event.get("error_code"):
+            error_events.append(event)
+
+    # ── Finding generation ──────────────────────────────────────────────────
+
+    def _generate_findings(self, all_events: list, credentials_found: list,
+                            principals: dict, ips: dict,
+                            privesc_events: list, exfil_events: list,
+                            noisy_events: list, error_events: list,
+                            session: "Session") -> None:
+        from core.logger import log
+
+        # Finding 1: Credentials found in logs
+        for cred in credentials_found:
+            session.add_secret(
+                secret_type  = cred["type"],
+                value        = cred["value"],
+                source       = cred["source"],
+                severity     = "CRITICAL",
+                description  = f"AWS Access Key ID found in CloudTrail log. Used by: {cred['principal']}",
+                aws_parallel = "Leaked IAM access key — validate with: aws sts get-caller-identity",
+            )
+            session.add_finding(
+                module          = self.NAME,
+                title           = f"AWS Access Key Found in CloudTrail Logs",
+                severity        = "CRITICAL",
+                description     = (
+                    f"Access Key ID extracted from CloudTrail audit logs. "
+                    f"This key was actively used to make AWS API calls. "
+                    f"Principal: {cred['principal']}"
+                ),
+                evidence        = (
+                    f"Key: {cred['value']}\n"
+                    f"Principal: {cred['principal']}\n"
+                    f"Source IP: {cred['ip']}\n"
+                    f"Found in: {cred['source']}"
+                ),
+                recommendation  = (
+                    "Immediately check if this key is still active:\n"
+                    f"aws iam list-access-keys --user-name <user>\n"
+                    "Disable if active:\n"
+                    f"aws iam update-access-key --access-key-id {cred['value']} --status Inactive"
+                ),
+                cvss_score      = 9.8,
+                aws_parallel    = "Stolen IAM access key from CloudTrail — validate with STS GetCallerIdentity",
+                mitre_technique = "T1078.004",
+            )
+
+        # Finding 2: Privilege escalation events
+        if privesc_events:
+            event_names = list({e["event_name"] for e in privesc_events})
+            session.add_finding(
+                module          = self.NAME,
+                title           = f"Privilege Escalation Activity in CloudTrail ({len(privesc_events)} events)",
+                severity        = "CRITICAL",
+                description     = (
+                    f"CloudTrail logs contain {len(privesc_events)} events associated with "
+                    f"privilege escalation: {', '.join(event_names[:5])}"
+                ),
+                evidence        = self._format_events(privesc_events[:5]),
+                recommendation  = (
+                    "Review all IAM changes. Check for unauthorized policy attachments. "
+                    "Enable IAM Access Analyzer. Review CloudTrail for the full timeline."
+                ),
+                cvss_score      = 9.5,
+                aws_parallel    = "IAM privilege escalation via PutUserPolicy, AssumeRole chains",
+                mitre_technique = "T1078.004",
+            )
+
+        # Finding 3: Data exfiltration events
+        if exfil_events:
+            s3_gets = [e for e in exfil_events if e["event_name"] == "GetObject"]
+            session.add_finding(
+                module          = self.NAME,
+                title           = f"Data Access Events in CloudTrail ({len(exfil_events)} events)",
+                severity        = "HIGH",
+                description     = (
+                    f"{len(exfil_events)} data access events found. "
+                    f"{len(s3_gets)} S3 GetObject calls."
+                ),
+                evidence        = self._format_events(exfil_events[:5]),
+                recommendation  = (
+                    "Review S3 access logs. Enable S3 server access logging. "
+                    "Use Macie to detect sensitive data exposure."
+                ),
+                cvss_score      = 7.5,
+                aws_parallel    = "S3 GetObject calls — potential data exfiltration",
+                mitre_technique = "T1530",
+            )
+
+        # Finding 4: GuardDuty noisy events
+        if noisy_events and self.get_option("GUARDDUTY_MODE", "true").lower() == "true":
+            event_names = list({e["event_name"] for e in noisy_events})
+            log.warning(f"GuardDuty would flag these API calls: {', '.join(event_names)}")
+            session.add_finding(
+                module          = self.NAME,
+                title           = "GuardDuty Alert — High-Signal API Calls Detected",
+                severity        = "HIGH",
+                description     = (
+                    f"The following API calls would trigger GuardDuty findings: "
+                    f"{', '.join(event_names)}. "
+                    "These indicate reconnaissance or credential abuse."
+                ),
+                evidence        = self._format_events(noisy_events[:3]),
+                recommendation  = "Enable GuardDuty in all regions. Review and respond to findings.",
+                cvss_score      = 7.0,
+                aws_parallel    = "GuardDuty: UnauthorizedAccess:IAMUser/TorIPCaller or Recon:IAMUser/UserPermissions",
+                mitre_technique = "T1078.004",
+            )
+
+        # Finding 5: Unique external IPs
+        external_ips = {ip: cnt for ip, cnt in ips.items()
+                         if not ip.startswith(("10.", "172.", "192.168.", "AWS"))}
+        if external_ips:
+            top_ips = sorted(external_ips.items(), key=lambda x: x[1], reverse=True)[:5]
+            session.add_finding(
+                module          = self.NAME,
+                title           = f"External IP Addresses in CloudTrail ({len(external_ips)} unique)",
+                severity        = "MEDIUM",
+                description     = (
+                    f"CloudTrail shows API calls from {len(external_ips)} external IPs. "
+                    "Unexpected IPs may indicate compromised credentials."
+                ),
+                evidence        = "\n".join(f"{ip}: {cnt} calls" for ip, cnt in top_ips),
+                recommendation  = "Investigate unexpected source IPs. Use IAM condition keys to restrict by IP.",
+                cvss_score      = 6.0,
+                aws_parallel    = "GuardDuty: UnauthorizedAccess:IAMUser/ConsoleLoginSuccess.B",
+                mitre_technique = "T1078.004",
+            )
+
+        # Finding 6: Summary of who did what
+        if principals:
+            top_principals = sorted(principals.items(),
+                                     key=lambda x: len(x[1]), reverse=True)[:5]
+            for arn, events_list in top_principals:
+                log.step(f"Principal: {arn} → {len(events_list)} API calls")
+                event_summary = ", ".join(list(dict.fromkeys(events_list))[:8])
+                log.step(f"  Calls: {event_summary}")
+
+    def _format_events(self, events: list) -> str:
+        lines = []
+        for e in events:
+            lines.append(
+                f"{e['event_time'][:19]} | {e['event_name']:<35} | "
+                f"{e['principal_arn'][:40]} | {e['source_ip']}"
+            )
+        return "\n".join(lines)