sica-fondt/knowledge/cyber-skills/skills/investigating-phishing-email-incident/scripts/agent.py

#!/usr/bin/env python3
"""
Phishing Email Investigation Agent
Analyzes reported phishing emails by parsing headers, checking URL/attachment
reputation via VirusTotal and URLScan.io, and identifying impacted recipients.
"""

import email
import email.policy
import hashlib
import json
import re
import sys
import time
from datetime import datetime, timezone

import requests


VT_API_KEY = ""  # Set via environment or config
URLSCAN_API_KEY = ""  # Set via environment or config


def parse_email_headers(eml_path: str) -> dict:
    """Parse an .eml file and extract investigation-relevant headers."""
    with open(eml_path, "rb") as f:
        msg = email.message_from_binary_file(f, policy=email.policy.default)

    auth_results = msg.get("Authentication-Results", "")
    spf_match = re.search(r"spf=(\w+)", auth_results)
    dkim_match = re.search(r"dkim=(\w+)", auth_results)
    dmarc_match = re.search(r"dmarc=(\w+)", auth_results)

    received_chain = []
    for hdr in reversed(msg.get_all("Received", [])):
        received_chain.append(hdr.strip()[:200])

    return {
        "from": msg["From"],
        "return_path": msg.get("Return-Path", ""),
        "reply_to": msg.get("Reply-To", ""),
        "subject": msg["Subject"],
        "message_id": msg["Message-ID"],
        "date": msg["Date"],
        "x_originating_ip": msg.get("X-Originating-IP", ""),
        "spf": spf_match.group(1) if spf_match else "not found",
        "dkim": dkim_match.group(1) if dkim_match else "not found",
        "dmarc": dmarc_match.group(1) if dmarc_match else "not found",
        "received_chain": received_chain,
    }


def extract_urls_from_email(eml_path: str) -> list[str]:
    """Extract all URLs from email body."""
    with open(eml_path, "rb") as f:
        msg = email.message_from_binary_file(f, policy=email.policy.default)

    body = ""
    if msg.is_multipart():
        for part in msg.walk():
            ctype = part.get_content_type()
            if ctype in ("text/plain", "text/html"):
                payload = part.get_payload(decode=True)
                if payload:
                    body += payload.decode("utf-8", errors="ignore")
    else:
        payload = msg.get_payload(decode=True)
        if payload:
            body = payload.decode("utf-8", errors="ignore")

    url_pattern = re.compile(r'https?://[^\s<>"\')\]]+')
    return list(set(url_pattern.findall(body)))


def check_url_urlscan(url: str, api_key: str) -> dict:
    """Submit URL to URLScan.io for analysis."""
    if not api_key:
        return {"error": "URLSCAN_API_KEY not set"}

    resp = requests.post(
        "https://urlscan.io/api/v1/scan/",
        headers={"API-Key": api_key, "Content-Type": "application/json"},
        json={"url": url, "visibility": "unlisted"},
        timeout=30,
    )
    if resp.status_code == 200:
        data = resp.json()
        return {"uuid": data.get("uuid", ""), "result_url": data.get("result", "")}
    return {"error": f"URLScan returned {resp.status_code}: {resp.text[:200]}"}


def check_url_virustotal(url: str, api_key: str) -> dict:
    """Check URL reputation on VirusTotal."""
    if not api_key:
        return {"error": "VT_API_KEY not set"}

    resp = requests.post(
        "https://www.virustotal.com/api/v3/urls",
        headers={"x-apikey": api_key},
        data={"url": url},
        timeout=30,
    )
    if resp.status_code == 200:
        analysis_id = resp.json().get("data", {}).get("id", "")
        time.sleep(15)
        result = requests.get(
            f"https://www.virustotal.com/api/v3/analyses/{analysis_id}",
            headers={"x-apikey": api_key},
            timeout=30,
        )
        if result.status_code == 200:
            stats = result.json().get("data", {}).get("attributes", {}).get("stats", {})
            return {"malicious": stats.get("malicious", 0), "suspicious": stats.get("suspicious", 0),
                    "harmless": stats.get("harmless", 0), "undetected": stats.get("undetected", 0)}
    return {"error": f"VT returned {resp.status_code}"}


def hash_attachment(filepath: str) -> dict:
    """Calculate MD5 and SHA-256 hashes for an attachment."""
    with open(filepath, "rb") as f:
        content = f.read()
    return {
        "filename": filepath,
        "size_bytes": len(content),
        "md5": hashlib.md5(content).hexdigest(),
        "sha256": hashlib.sha256(content).hexdigest(),
    }


def check_hash_virustotal(file_hash: str, api_key: str) -> dict:
    """Look up file hash on VirusTotal."""
    if not api_key:
        return {"error": "VT_API_KEY not set"}

    resp = requests.get(
        f"https://www.virustotal.com/api/v3/files/{file_hash}",
        headers={"x-apikey": api_key},
        timeout=30,
    )
    if resp.status_code == 200:
        attrs = resp.json().get("data", {}).get("attributes", {})
        stats = attrs.get("last_analysis_stats", {})
        return {
            "detection_name": attrs.get("popular_threat_classification", {}).get("suggested_threat_label", "unknown"),
            "malicious": stats.get("malicious", 0),
            "total_engines": sum(stats.values()),
        }
    return {"error": f"Hash not found or VT error: {resp.status_code}"}


def generate_ioc_list(headers: dict, urls: list[str], attachments: list[dict]) -> dict:
    """Compile indicators of compromise from the investigation."""
    iocs = {"domains": set(), "ips": set(), "urls": urls, "hashes": []}

    for url in urls:
        domain_match = re.search(r"https?://([^/]+)", url)
        if domain_match:
            iocs["domains"].add(domain_match.group(1))

    if headers.get("x_originating_ip"):
        iocs["ips"].add(headers["x_originating_ip"].strip("[]"))

    for att in attachments:
        iocs["hashes"].append({"md5": att["md5"], "sha256": att["sha256"]})

    iocs["domains"] = sorted(iocs["domains"])
    iocs["ips"] = sorted(iocs["ips"])
    return iocs


def generate_report(headers: dict, urls: list[str], iocs: dict) -> str:
    """Generate phishing investigation report."""
    lines = [
        f"PHISHING INCIDENT REPORT",
        "=" * 50,
        f"Report Generated: {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}",
        "",
        f"From: {headers['from']}",
        f"Return-Path: {headers['return_path']}",
        f"Subject: {headers['subject']}",
        f"SPF: {headers['spf']}  DKIM: {headers['dkim']}  DMARC: {headers['dmarc']}",
        "",
        f"URLs Found: {len(urls)}",
    ]
    for u in urls[:10]:
        lines.append(f"  - {u}")
    lines.extend(["", f"IOC Domains: {', '.join(iocs['domains'])}",
                   f"IOC IPs: {', '.join(iocs['ips'])}",
                   f"IOC Hashes: {len(iocs['hashes'])}"])
    return "\n".join(lines)


if __name__ == "__main__":
    import os
    VT_API_KEY = os.getenv("VT_API_KEY", VT_API_KEY)
    URLSCAN_API_KEY = os.getenv("URLSCAN_API_KEY", URLSCAN_API_KEY)

    eml_path = sys.argv[1] if len(sys.argv) > 1 else "phishing_sample.eml"

    print(f"[*] Analyzing phishing email: {eml_path}")
    headers = parse_email_headers(eml_path)
    urls = extract_urls_from_email(eml_path)

    print(f"[*] Found {len(urls)} URLs in email body")
    for url in urls[:5]:
        if URLSCAN_API_KEY:
            result = check_url_urlscan(url, URLSCAN_API_KEY)
            print(f"  URLScan: {result}")

    iocs = generate_ioc_list(headers, urls, [])
    report = generate_report(headers, urls, iocs)
    print(report)

    output = f"phishing_report_{datetime.now(timezone.utc).strftime('%Y%m%d_%H%M%S')}.json"
    with open(output, "w") as f:
        json.dump({"headers": headers, "urls": urls, "iocs": iocs}, f, indent=2)
    print(f"\n[*] Results saved to {output}")