sica-fondt/knowledge/cyber-skills/skills/detecting-aws-cloudtrail-anomalies/scripts/agent.py

#!/usr/bin/env python3
"""Agent for detecting anomalies in AWS CloudTrail logs.

Queries CloudTrail events via boto3, builds behavioral baselines,
and detects unusual API patterns indicating credential compromise,
privilege escalation, or unauthorized access.
"""

import argparse
import json
import os
from collections import Counter, defaultdict
from datetime import datetime, timedelta
from pathlib import Path

try:
    import boto3
except ImportError:
    boto3 = None

SENSITIVE_EVENTS = {
    "CreateUser", "CreateAccessKey", "AttachUserPolicy", "AttachRolePolicy",
    "PutUserPolicy", "PutRolePolicy", "CreateRole", "AssumeRole",
    "ConsoleLogin", "PutBucketPolicy", "PutBucketAcl",
    "CreateKeyPair", "RunInstances", "StopLogging", "DeleteTrail",
    "DisableKey", "ScheduleKeyDeletion", "CreateGrante",
    "AuthorizeSecurityGroupIngress", "ModifyInstanceAttribute",
}

ERROR_INDICATORS = {"AccessDenied", "UnauthorizedAccess", "Client.UnauthorizedAccess"}


class CloudTrailAnomalyDetector:
    """Detects anomalies in AWS CloudTrail API activity."""

    def __init__(self, profile=None, region=None, lookback_hours=24,
                 output_dir="./cloudtrail_anomalies"):
        self.output_dir = Path(output_dir)
        self.output_dir.mkdir(parents=True, exist_ok=True)
        self.lookback_hours = lookback_hours
        self.findings = []
        self.client = None
        if boto3:
            session = boto3.Session(profile_name=profile, region_name=region or "us-east-1")
            self.client = session.client("cloudtrail")

    def fetch_events(self, max_results=1000):
        """Fetch CloudTrail events using lookup_events with pagination."""
        if not self.client:
            return []
        start_time = datetime.utcnow() - timedelta(hours=self.lookback_hours)
        events = []
        paginator = self.client.get_paginator("lookup_events")
        page_iter = paginator.paginate(
            StartTime=start_time,
            EndTime=datetime.utcnow(),
            PaginationConfig={"MaxItems": max_results, "PageSize": 50},
        )
        for page in page_iter:
            for event in page.get("Events", []):
                ct_event = json.loads(event.get("CloudTrailEvent", "{}"))
                events.append({
                    "event_name": event.get("EventName", ""),
                    "event_source": event.get("EventSource", ""),
                    "event_time": event.get("EventTime", "").isoformat()
                        if hasattr(event.get("EventTime", ""), "isoformat")
                        else str(event.get("EventTime", "")),
                    "username": event.get("Username", ""),
                    "source_ip": ct_event.get("sourceIPAddress", ""),
                    "user_agent": ct_event.get("userAgent", ""),
                    "error_code": ct_event.get("errorCode", ""),
                    "error_message": ct_event.get("errorMessage", ""),
                    "aws_region": ct_event.get("awsRegion", ""),
                    "read_only": event.get("ReadOnly", ""),
                })
        return events

    def build_baseline(self, events):
        """Build behavioral baseline from events."""
        user_events = defaultdict(list)
        user_ips = defaultdict(set)
        user_sources = defaultdict(set)
        for e in events:
            user = e["username"]
            user_events[user].append(e["event_name"])
            user_ips[user].add(e["source_ip"])
            user_sources[user].add(e["event_source"])
        return {
            "user_event_counts": {u: len(evts) for u, evts in user_events.items()},
            "user_unique_ips": {u: len(ips) for u, ips in user_ips.items()},
            "user_unique_sources": {u: len(srcs) for u, srcs in user_sources.items()},
        }

    def detect_anomalies(self, events):
        """Detect anomalous patterns in CloudTrail events."""
        user_events = defaultdict(list)
        for e in events:
            user_events[e["username"]].append(e)

        sensitive_calls = [e for e in events if e["event_name"] in SENSITIVE_EVENTS]
        for e in sensitive_calls:
            self.findings.append({
                "severity": "high", "type": "Sensitive API Call",
                "detail": f"{e['username']} called {e['event_name']} from {e['source_ip']}",
            })

        error_events = [e for e in events if e["error_code"] in ERROR_INDICATORS]
        error_by_user = Counter(e["username"] for e in error_events)
        for user, count in error_by_user.items():
            if count >= 5:
                self.findings.append({
                    "severity": "high", "type": "High Access Denied Rate",
                    "detail": f"{user} received {count} AccessDenied errors",
                })

        for user, evts in user_events.items():
            ips = {e["source_ip"] for e in evts}
            if len(ips) >= 5:
                self.findings.append({
                    "severity": "medium", "type": "Multiple Source IPs",
                    "detail": f"{user} accessed from {len(ips)} distinct IPs",
                })

        trail_tampering = [e for e in events
                           if e["event_name"] in ("StopLogging", "DeleteTrail", "UpdateTrail")]
        for e in trail_tampering:
            self.findings.append({
                "severity": "critical", "type": "CloudTrail Tampering",
                "detail": f"{e['username']} called {e['event_name']}",
            })

        return {
            "sensitive_api_calls": len(sensitive_calls),
            "access_denied_events": len(error_events),
            "trail_tampering_events": len(trail_tampering),
        }

    def generate_report(self):
        events = self.fetch_events()
        baseline = self.build_baseline(events)
        anomalies = self.detect_anomalies(events)

        event_name_counts = Counter(e["event_name"] for e in events).most_common(20)
        source_counts = Counter(e["event_source"] for e in events).most_common(10)

        report = {
            "report_date": datetime.utcnow().isoformat(),
            "lookback_hours": self.lookback_hours,
            "total_events": len(events),
            "top_event_names": event_name_counts,
            "top_event_sources": source_counts,
            "baseline": baseline,
            "anomaly_summary": anomalies,
            "findings": self.findings,
            "total_findings": len(self.findings),
        }
        out = self.output_dir / "cloudtrail_anomaly_report.json"
        with open(out, "w") as f:
            json.dump(report, f, indent=2, default=str)
        print(json.dumps(report, indent=2, default=str))
        return report


def main():
    parser = argparse.ArgumentParser(
        description="Detect anomalies in AWS CloudTrail API activity"
    )
    parser.add_argument("--profile", default=None, help="AWS CLI profile name")
    parser.add_argument("--region", default="us-east-1", help="AWS region")
    parser.add_argument("--hours", type=int, default=24, help="Lookback window in hours")
    parser.add_argument("--output-dir", default="./cloudtrail_anomalies")
    args = parser.parse_args()

    os.makedirs(args.output_dir, exist_ok=True)
    detector = CloudTrailAnomalyDetector(
        profile=args.profile, region=args.region,
        lookback_hours=args.hours, output_dir=args.output_dir,
    )
    detector.generate_report()


if __name__ == "__main__":
    main()