threatpulse-cli 1.0.0__py3-none-any.whl

threat_pulse/enrichers/malware.py

@@ -0,0 +1,80 @@
+"""Malware hash intelligence enricher with offline threat signature database."""
+
+from typing import Dict, Any, Optional
+from threat_pulse.enrichers.base import BaseEnricher
+from threat_pulse.models import IOCType
+
+# Curated offline database of critical malware hashes (Ransomware, Mimikatz, C2 Beacons, WebShells)
+KNOWN_MALWARE_HASHES: Dict[str, Dict[str, str]] = {
+    # WannaCry Ransomware
+    "ed01ebf83334a19373140c0df0ddb638ec6d7e99f8788f5b8978cb8c4cb5ffce": {
+        "family": "WannaCry Ransomware",
+        "type": "Ransomware / Cryptoworm",
+        "severity": "CRITICAL",
+        "description": "EternalBlue-based ransomware targeting SMBv1 (MS17-010)"
+    },
+    "84c82835a5d21bbcf75a61706d8ab549": {
+        "family": "WannaCry Dropper",
+        "type": "Dropper",
+        "severity": "CRITICAL",
+        "description": "WannaCry primary dropper binary"
+    },
+    # Mimikatz (Credential Dumping)
+    "a60c52bb53a5c0b89cf53dc5bb7c2c129219b16e4ee7d9c6e3b5e43a9b1c9d2f": {
+        "family": "Mimikatz",
+        "type": "Credential Dumper",
+        "severity": "CRITICAL",
+        "description": "LSASS memory credential extraction utility (T1003.001)"
+    },
+    # Cobalt Strike Beacon
+    "4d01b1bcf03ebdd8cb0667b9381665a58d6ff8cb194fa8cbdf24dd3ee3228a9b": {
+        "family": "Cobalt Strike",
+        "type": "Adversary Simulation / C2 Beacon",
+        "severity": "CRITICAL",
+        "description": "Malleable C2 Beacon executable (T1071)"
+    },
+    # Emotet Trojan
+    "49b788647055a40bbd21b79313ea5fa2e6ff3f1b": {
+        "family": "Emotet",
+        "type": "Banking Trojan / Botnet",
+        "severity": "HIGH",
+        "description": "Polymorphic modular botnet loader"
+    },
+    # China Chopper / Classic WebShell
+    "8bc6e6f96602330a6c0c2bb01c56ad44": {
+        "family": "China Chopper WebShell",
+        "type": "Web Shell",
+        "severity": "HIGH",
+        "description": "Minimalist server-side web backdoor (T1505.003)"
+    }
+}
+
+
+class MalwareHashEnricher(BaseEnricher):
+    """Enriches file hashes against known malware signatures and IOC threat feeds."""
+
+    def __init__(self):
+        super().__init__(name="malware_hash_enricher")
+
+    def can_enrich(self, ioc_type: IOCType) -> bool:
+        return ioc_type in (IOCType.MD5, IOCType.SHA1, IOCType.SHA256)
+
+    def enrich(self, ioc: str, ioc_type: IOCType) -> Dict[str, Any]:
+        normalized_hash = ioc.lower().strip()
+        data: Dict[str, Any] = {
+            "is_known_malware": False,
+            "family": None,
+            "type": None,
+            "severity": None,
+            "description": None,
+        }
+
+        if normalized_hash in KNOWN_MALWARE_HASHES:
+            intel = KNOWN_MALWARE_HASHES[normalized_hash]
+            data["is_known_malware"] = True
+            data["family"] = intel["family"]
+            data["type"] = intel["type"]
+            data["severity"] = intel["severity"]
+            data["description"] = intel["description"]
+
+        return data

threat_pulse/enrichers/network.py

@@ -0,0 +1,81 @@
+"""Network enricher: DNS PTR resolution, Tor exit node detection, and scanner identification."""
+
+import socket
+from typing import Dict, Any, Set
+from threat_pulse.enrichers.base import BaseEnricher
+from threat_pulse.models import IOCType
+
+# Known active Tor exit nodes (sample curated offline seed list for instant high-confidence matching)
+KNOWN_TOR_EXIT_NODES: Set[str] = {
+    "185.220.101.5", "185.220.101.6", "185.220.101.7",
+    "185.220.100.241", "185.220.100.242", "185.220.100.252",
+    "195.176.3.23", "51.15.43.205", "185.107.56.210",
+    "109.70.100.25", "185.14.29.178", "198.96.155.3"
+}
+
+# Known security research / port scanner subnets & IPs
+KNOWN_SCANNERS: Dict[str, str] = {
+    "198.20.69.74": "Shadowserver Foundation Scanner",
+    "198.20.69.98": "Shadowserver Foundation Scanner",
+    "162.142.125.0": "Censys Research Scanner",
+    "167.248.133.0": "Censys Research Scanner",
+    "71.6.232.0": "Shodan Internet Scanner",
+    "71.6.165.200": "Shodan Internet Scanner",
+    "185.180.143.0": "LeakIX Security Scanner",
+}
+
+
+class NetworkEnricher(BaseEnricher):
+    """Enriches network indicators with reverse DNS, Tor status, and scanner attribution."""
+
+    def __init__(self, timeout: float = 2.0):
+        super().__init__(name="network_enricher")
+        self.timeout = timeout
+
+    def can_enrich(self, ioc_type: IOCType) -> bool:
+        return ioc_type in (IOCType.IPV4, IOCType.IPV6, IOCType.DOMAIN)
+
+    def enrich(self, ioc: str, ioc_type: IOCType) -> Dict[str, Any]:
+        data: Dict[str, Any] = {
+            "ptr": None,
+            "resolved_ips": [],
+            "is_tor_exit": False,
+            "is_known_scanner": False,
+            "scanner_name": None,
+        }
+
+        # IP Specific Network Checks
+        if ioc_type in (IOCType.IPV4, IOCType.IPV6):
+            # Check Tor
+            if ioc in KNOWN_TOR_EXIT_NODES:
+                data["is_tor_exit"] = True
+
+            # Check Known Scanners
+            for scanner_ip, scanner_name in KNOWN_SCANNERS.items():
+                if ioc == scanner_ip or ioc.startswith(scanner_ip.rsplit(".", 1)[0]):
+                    data["is_known_scanner"] = True
+                    data["scanner_name"] = scanner_name
+                    break
+
+            # Reverse DNS (PTR)
+            try:
+                socket.setdefaulttimeout(self.timeout)
+                host_info = socket.gethostbyaddr(ioc)
+                data["ptr"] = host_info[0]
+            except (socket.herror, socket.gaierror, socket.timeout, OSError):
+                data["ptr"] = None
+
+        # Domain Specific Network Checks
+        elif ioc_type == IOCType.DOMAIN:
+            try:
+                socket.setdefaulttimeout(self.timeout)
+                _, _, ip_list = socket.gethostbyname_ex(ioc)
+                data["resolved_ips"] = ip_list
+                # Check if domain resolves to a Tor node or scanner
+                for ip in ip_list:
+                    if ip in KNOWN_TOR_EXIT_NODES:
+                        data["is_tor_exit"] = True
+            except (socket.gaierror, socket.timeout, OSError):
+                data["resolved_ips"] = []
+
+        return data

threat_pulse/formatters.py

@@ -0,0 +1,140 @@
+"""Terminal card, table, JSON, Markdown, and Wazuh CDB list output formatters."""
+
+import json
+from typing import List
+from threat_pulse.models import EnrichmentResult, RiskLevel
+
+# ANSI Color codes for clean, zero-dependency colored terminal rendering
+RESET = "\033[0m"
+BOLD = "\033[1m"
+DIM = "\033[2m"
+RED = "\033[91m"
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+BLUE = "\033[94m"
+MAGENTA = "\033[95m"
+CYAN = "\033[96m"
+WHITE = "\033[97m"
+BG_RED = "\033[41m"
+BG_YELLOW = "\033[43m"
+BG_GREEN = "\033[42m"
+
+
+def _risk_color(level: RiskLevel) -> str:
+    if level == RiskLevel.CRITICAL:
+        return f"{BG_RED}{WHITE}{BOLD}"
+    elif level == RiskLevel.HIGH:
+        return f"{RED}{BOLD}"
+    elif level == RiskLevel.MEDIUM:
+        return f"{YELLOW}{BOLD}"
+    elif level == RiskLevel.LOW:
+        return f"{BLUE}"
+    else:
+        return f"{GREEN}{BOLD}"
+
+
+def render_terminal_card(res: EnrichmentResult) -> str:
+    """Render a standalone, highly detailed threat intelligence card for a single IOC."""
+    color = _risk_color(res.risk_level)
+    lines = []
+    lines.append(f"{CYAN}┌────────────────────────────────────────────────────────────────────────┐{RESET}")
+    lines.append(f"{CYAN}│{RESET} {BOLD}ThreatPulse IOC Report{RESET}  {DIM}[{res.ioc_type.value.upper()}]{RESET}")
+    lines.append(f"{CYAN}├────────────────────────────────────────────────────────────────────────┤{RESET}")
+    lines.append(f"{CYAN}│{RESET} {BOLD}Indicator:{RESET}    {res.defanged} {DIM}(raw: {res.ioc}){RESET}")
+    lines.append(f"{CYAN}│{RESET} {BOLD}Risk Level:{RESET}   {color} {res.risk_level.value} ({res.risk_score}/100) {RESET}")
+    lines.append(f"{CYAN}│{RESET} {BOLD}Verdict:{RESET}      {res.verdict}")
+
+    if res.tags:
+        tag_str = " ".join([f"{MAGENTA}#{t}{RESET}" for t in res.tags])
+        lines.append(f"{CYAN}│{RESET} {BOLD}Tags:{RESET}         {tag_str}")
+
+    if res.mitre_attack:
+        lines.append(f"{CYAN}│{RESET} {BOLD}MITRE ATT&CK:{RESET}")
+        for m in res.mitre_attack:
+            lines.append(f"{CYAN}│{RESET}   • {YELLOW}{m}{RESET}")
+
+    # Specific details section
+    details = res.details
+    if details:
+        lines.append(f"{CYAN}│{RESET} {BOLD}Intelligence Details:{RESET}")
+        if "ptr" in details and details["ptr"]:
+            lines.append(f"{CYAN}│{RESET}   • Reverse DNS: {details['ptr']}")
+        if "country_code" in details and details["country_code"] != "UNKNOWN":
+            lines.append(f"{CYAN}│{RESET}   • Country / ISP: {details['country_code']} ({details.get('isp', 'N/A')})")
+        if "abuse_score" in details and details["abuse_score"] > 0:
+            lines.append(f"{CYAN}│{RESET}   • AbuseIPDB Score: {details['abuse_score']}% ({details.get('total_reports', 0)} reports)")
+        if "family" in details and details["family"]:
+            lines.append(f"{CYAN}│{RESET}   • Malware Family: {details['family']} ({details.get('description', '')})")
+        if "sld_entropy" in details:
+            lines.append(f"{CYAN}│{RESET}   • Domain Entropy: {details['sld_entropy']} (DGA Candidate: {details.get('is_dga_candidate')})")
+        if "is_known_scanner" in details and details["is_known_scanner"]:
+            lines.append(f"{CYAN}│{RESET}   • Scanner: {details.get('scanner_name')}")
+
+    lines.append(f"{CYAN}│{RESET} {BOLD}SOC Action:{RESET}   {WHITE}{res.recommendation}{RESET}")
+    cache_badge = f"{DIM}(from local cache){RESET}" if res.cached else f"{DIM}(live analysis){RESET}"
+    lines.append(f"{CYAN}│{RESET} {DIM}Timestamp: {res.timestamp} {cache_badge}{RESET}")
+    lines.append(f"{CYAN}└────────────────────────────────────────────────────────────────────────┘{RESET}")
+    return "\n".join(lines)
+
+
+def render_terminal_summary_table(results: List[EnrichmentResult]) -> str:
+    """Render a clean summary table for batch IOC enrichment."""
+    if not results:
+        return "No IOCs analyzed."
+
+    headers = f"{'INDICATOR':<35} {'TYPE':<8} {'RISK':<12} {'SCORE':<7} {'VERDICT':<30}"
+    separator = "-" * 95
+    lines = [f"{BOLD}{headers}{RESET}", separator]
+
+    for r in results:
+        color = _risk_color(r.risk_level)
+        short_verdict = (r.verdict[:27] + "...") if len(r.verdict) > 30 else r.verdict
+        line = (
+            f"{r.defanged[:33]:<35} "
+            f"{r.ioc_type.value:<8} "
+            f"{color}{r.risk_level.value:<12}{RESET} "
+            f"{r.risk_score:<7} "
+            f"{short_verdict:<30}"
+        )
+        lines.append(line)
+
+    return "\n".join(lines)
+
+
+def render_json(results: List[EnrichmentResult], pretty: bool = True) -> str:
+    """Serialize results list to JSON."""
+    data = [r.to_dict() for r in results]
+    indent = 2 if pretty else None
+    return json.dumps({"count": len(results), "indicators": data}, indent=indent)
+
+
+def render_markdown(results: List[EnrichmentResult]) -> str:
+    """Format results into a Markdown table for ticketing / GitHub / reporting."""
+    lines = [
+        "# ThreatPulse Threat Intelligence Report",
+        "",
+        f"**Total Indicators Analyzed:** {len(results)}",
+        "",
+        "| Indicator (Defanged) | Type | Risk Level | Score | Verdict | Tags |",
+        "| --------------------- | ---- | ---------- | ----- | ------- | ---- |"
+    ]
+    for r in results:
+        tags_str = ", ".join(r.tags) if r.tags else "-"
+        lines.append(
+            f"| `{r.defanged}` | {r.ioc_type.value} | **{r.risk_level.value}** | {r.risk_score}/100 | {r.verdict} | {tags_str} |"
+        )
+    return "\n".join(lines)
+
+
+def render_wazuh_cdb_list(results: List[EnrichmentResult]) -> str:
+    """
+    Format malicious/suspicious indicators into Wazuh CDB list syntax.
+    Syntax: <key>:<value>
+    Usage: save to /var/ossec/etc/lists/threat_pulse.cdb
+    """
+    lines = ["# ThreatPulse exported CDB List for Wazuh SIEM"]
+    for r in results:
+        if r.risk_score >= 40:  # Medium, High, or Critical
+            tag_summary = ",".join(r.tags[:2]) if r.tags else "malicious"
+            lines.append(f"{r.ioc}:{r.risk_level.value}_{r.risk_score}:{tag_summary}")
+    return "\n".join(lines)

threat_pulse/heuristics.py

@@ -0,0 +1,167 @@
+"""Offline heuristic analyzers for IP addresses, domains, and URLs."""
+
+import ipaddress
+import math
+import re
+from typing import Dict, Any, Optional, Tuple
+from urllib.parse import urlparse
+
+# Suspicious TLDs frequently abused in malware campaigns / phishing
+HIGH_ABUSE_TLDS = {
+    "top", "xyz", "tk", "ml", "ga", "cf", "gq", "buzz", "icu", "work",
+    "click", "link", "rest", "surf", "monster", "casa", "country", "kim"
+}
+
+# Bogon / Reserved network ranges (IPv4)
+BOGON_NETWORKS = [
+    ipaddress.ip_network("0.0.0.0/8"),
+    ipaddress.ip_network("10.0.0.0/8"),         # RFC 1918
+    ipaddress.ip_network("100.64.0.0/10"),     # Carrier-grade NAT
+    ipaddress.ip_network("127.0.0.0/8"),       # Loopback
+    ipaddress.ip_network("169.254.0.0/16"),    # Link-local / APIPA
+    ipaddress.ip_network("172.16.0.0/12"),     # RFC 1918
+    ipaddress.ip_network("192.0.0.0/24"),      # IETF Protocol
+    ipaddress.ip_network("192.0.2.0/24"),      # TEST-NET-1
+    ipaddress.ip_network("192.168.0.0/16"),    # RFC 1918
+    ipaddress.ip_network("198.18.0.0/15"),     # Network Interconnect Benchmarking
+    ipaddress.ip_network("198.51.100.0/24"),   # TEST-NET-2
+    ipaddress.ip_network("203.0.113.0/24"),    # TEST-NET-3
+    ipaddress.ip_network("224.0.0.0/4"),       # Multicast
+    ipaddress.ip_network("240.0.0.0/4"),       # Reserved / Future use
+    ipaddress.ip_network("255.255.255.255/32"),# Broadcast
+]
+
+
+def calculate_shannon_entropy(text: str) -> float:
+    """Calculate Shannon entropy of a string to evaluate randomness (DGA detection)."""
+    if not text:
+        return 0.0
+    entropy = 0.0
+    text_len = len(text)
+    freq: Dict[str, int] = {}
+    for char in text:
+        freq[char] = freq.get(char, 0) + 1
+    for count in freq.values():
+        p = count / text_len
+        entropy -= p * math.log2(p)
+    return round(entropy, 3)
+
+
+def analyze_ip_heuristics(ip_str: str) -> Dict[str, Any]:
+    """Inspect IP against RFC1918, Bogon, Loopback, and Reserved spaces."""
+    try:
+        ip = ipaddress.ip_address(ip_str)
+    except ValueError:
+        return {"valid": False}
+
+    is_private = ip.is_private
+    is_loopback = ip.is_loopback
+    is_link_local = ip.is_link_local
+    is_multicast = ip.is_multicast
+    is_reserved = ip.is_reserved
+
+    is_bogon = False
+    bogon_reason = ""
+    if ip.version == 4:
+        for net in BOGON_NETWORKS:
+            if ip in net:
+                is_bogon = True
+                bogon_reason = str(net)
+                break
+
+    rfc1918 = False
+    if ip.version == 4:
+        rfc_nets = [
+            ipaddress.ip_network("10.0.0.0/8"),
+            ipaddress.ip_network("172.16.0.0/12"),
+            ipaddress.ip_network("192.168.0.0/16"),
+        ]
+        rfc1918 = any(ip in net for net in rfc_nets)
+
+    return {
+        "valid": True,
+        "version": ip.version,
+        "is_private": is_private,
+        "is_rfc1918": rfc1918,
+        "is_bogon": is_bogon,
+        "bogon_network": bogon_reason,
+        "is_loopback": is_loopback,
+        "is_link_local": is_link_local,
+        "is_multicast": is_multicast,
+        "is_reserved": is_reserved,
+    }
+
+
+def analyze_domain_heuristics(domain: str) -> Dict[str, Any]:
+    """Inspect domain for DGA entropy, suspicious TLDs, and IDN homograph punycode."""
+    clean_domain = domain.lower().strip()
+    parts = clean_domain.split(".")
+
+    tld = parts[-1] if len(parts) > 1 else ""
+    sld = parts[-2] if len(parts) > 1 else parts[0]
+
+    # Calculate entropy on Second-Level Domain (the main name)
+    sld_entropy = calculate_shannon_entropy(sld)
+
+    is_high_entropy = (sld_entropy >= 3.6 and len(sld) >= 8) or (sld_entropy >= 3.3 and len(sld) >= 14)
+    has_suspicious_tld = tld in HIGH_ABUSE_TLDS
+    is_punycode = "xn--" in clean_domain
+    has_subdomain_abuse = len(parts) >= 4
+
+    # Count digits in main domain name (common in botnets / DGA)
+    digit_count = sum(c.isdigit() for c in sld)
+    digit_ratio = digit_count / len(sld) if sld else 0.0
+
+    return {
+        "domain": clean_domain,
+        "sld": sld,
+        "tld": tld,
+        "sld_entropy": sld_entropy,
+        "is_dga_candidate": is_high_entropy or (digit_ratio >= 0.4 and len(sld) >= 8),
+        "suspicious_tld": has_suspicious_tld,
+        "is_punycode": is_punycode,
+        "subdomain_depth": len(parts),
+        "excessive_subdomains": has_subdomain_abuse,
+        "digit_ratio": round(digit_ratio, 2),
+    }
+
+
+def analyze_url_heuristics(url_str: str) -> Dict[str, Any]:
+    """Inspect URL structure for raw IP hosts, suspicious paths, or credentials in URI."""
+    try:
+        parsed = urlparse(url_str)
+    except Exception:
+        return {"valid": False}
+
+    hostname = parsed.hostname or ""
+    path = parsed.path or ""
+    query = parsed.query or ""
+
+    is_raw_ip = False
+    try:
+        if hostname:
+            ipaddress.ip_address(hostname)
+            is_raw_ip = True
+    except ValueError:
+        is_raw_ip = False
+
+    has_credentials = bool(parsed.username or parsed.password)
+    has_executable_extension = any(
+        path.lower().endswith(ext)
+        for ext in [".exe", ".dll", ".ps1", ".vbs", ".bat", ".scr", ".iso", ".hta", ".apk"]
+    )
+    uncommon_port = parsed.port not in [None, 80, 443, 8080]
+
+    domain_data = analyze_domain_heuristics(hostname) if not is_raw_ip else {}
+
+    return {
+        "valid": True,
+        "scheme": parsed.scheme,
+        "hostname": hostname,
+        "port": parsed.port,
+        "uncommon_port": uncommon_port,
+        "is_raw_ip_host": is_raw_ip,
+        "has_credentials": has_credentials,
+        "has_executable_extension": has_executable_extension,
+        "domain_heuristics": domain_data,
+    }

threat_pulse/models.py

@@ -0,0 +1,67 @@
+"""Data models and enums for ThreatPulse."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+import datetime
+
+
+class IOCType(str, Enum):
+    """Supported indicator of compromise types."""
+    IPV4 = "ipv4"
+    IPV6 = "ipv6"
+    DOMAIN = "domain"
+    URL = "url"
+    MD5 = "md5"
+    SHA1 = "sha1"
+    SHA256 = "sha256"
+    UNKNOWN = "unknown"
+
+
+class RiskLevel(str, Enum):
+    """Categorized threat risk level based on aggregated score."""
+    CLEAN = "CLEAN"          # 0 - 15
+    LOW = "LOW"              # 16 - 39
+    MEDIUM = "MEDIUM"        # 40 - 69
+    HIGH = "HIGH"            # 70 - 89
+    CRITICAL = "CRITICAL"    # 90 - 100
+
+
+@dataclass
+class EnrichmentResult:
+    """Consolidated threat intelligence report for a single IOC."""
+    ioc: str
+    ioc_type: IOCType
+    defanged: str
+    risk_score: int
+    risk_level: RiskLevel
+    verdict: str
+    is_private: bool = False
+    is_bogon: bool = False
+    tags: List[str] = field(default_factory=list)
+    mitre_attack: List[str] = field(default_factory=list)
+    details: Dict[str, Any] = field(default_factory=dict)
+    recommendation: str = ""
+    cached: bool = False
+    timestamp: str = field(
+        default_factory=lambda: datetime.datetime.now(datetime.timezone.utc).isoformat()
+    )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert result to a serializable dictionary."""
+        return {
+            "ioc": self.ioc,
+            "ioc_type": self.ioc_type.value,
+            "defanged": self.defanged,
+            "risk_score": self.risk_score,
+            "risk_level": self.risk_level.value,
+            "verdict": self.verdict,
+            "is_private": self.is_private,
+            "is_bogon": self.is_bogon,
+            "tags": self.tags,
+            "mitre_attack": self.mitre_attack,
+            "details": self.details,
+            "recommendation": self.recommendation,
+            "cached": self.cached,
+            "timestamp": self.timestamp,
+        }