threatpulse-cli 1.0.0__py3-none-any.whl

threat_pulse/__init__.py

@@ -0,0 +1,17 @@
+"""ThreatPulse - Fast, modular Threat Intelligence & IOC enrichment engine for SOC Analysts."""
+
+__version__ = "1.0.0"
+__author__ = "Aleksei Zharkou"
+__license__ = "MIT"
+
+from threat_pulse.models import IOCType, RiskLevel, EnrichmentResult
+from threat_pulse.detector import detect_ioc_type
+from threat_pulse.scorer import calculate_risk_score
+
+__all__ = [
+    "IOCType",
+    "RiskLevel",
+    "EnrichmentResult",
+    "detect_ioc_type",
+    "calculate_risk_score",
+]

threat_pulse/__main__.py

@@ -0,0 +1,7 @@
+"""Execution wrapper for python -m threat_pulse."""
+
+import sys
+from threat_pulse.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

threat_pulse/cache.py

@@ -0,0 +1,119 @@
+"""Local SQLite caching layer for threat intelligence queries."""
+
+import json
+import sqlite3
+import time
+from pathlib import Path
+from typing import Optional, Dict, Any
+from threat_pulse.models import EnrichmentResult, IOCType, RiskLevel
+
+
+class ThreatCache:
+    """Persistent local cache for IOC enrichment results to respect API rate limits."""
+
+    def __init__(self, db_path: Optional[str] = None, ttl_seconds: int = 86400):
+        if db_path:
+            self.db_path = Path(db_path)
+        else:
+            self.db_path = Path.home() / ".threatpulse_cache.db"
+        self.ttl = ttl_seconds
+        self._init_db()
+
+    def _init_db(self) -> None:
+        """Create cache table if not already existing."""
+        try:
+            conn = sqlite3.connect(self.db_path)
+            try:
+                cursor = conn.cursor()
+                cursor.execute(
+                    """
+                    CREATE TABLE IF NOT EXISTS ioc_cache (
+                        ioc TEXT PRIMARY KEY,
+                        ioc_type TEXT,
+                        data_json TEXT,
+                        cached_at INTEGER
+                    )
+                    """
+                )
+                conn.commit()
+            finally:
+                conn.close()
+        except Exception:
+            pass
+
+    def get(self, ioc: str) -> Optional[EnrichmentResult]:
+        """Retrieve cached result if within TTL."""
+        try:
+            conn = sqlite3.connect(self.db_path)
+            try:
+                cursor = conn.cursor()
+                cursor.execute(
+                    "SELECT ioc_type, data_json, cached_at FROM ioc_cache WHERE ioc = ?",
+                    (ioc.lower().strip(),)
+                )
+                row = cursor.fetchone()
+                if not row:
+                    return None
+
+                ioc_type_str, data_json, cached_at = row
+                if time.time() - cached_at > self.ttl:
+                    return None  # Expired
+
+                payload = json.loads(data_json)
+                payload["cached"] = True
+                return EnrichmentResult(
+                    ioc=payload["ioc"],
+                    ioc_type=IOCType(payload["ioc_type"]),
+                    defanged=payload["defanged"],
+                    risk_score=payload["risk_score"],
+                    risk_level=RiskLevel(payload["risk_level"]),
+                    verdict=payload["verdict"],
+                    is_private=payload.get("is_private", False),
+                    is_bogon=payload.get("is_bogon", False),
+                    tags=payload.get("tags", []),
+                    mitre_attack=payload.get("mitre_attack", []),
+                    details=payload.get("details", {}),
+                    recommendation=payload.get("recommendation", ""),
+                    cached=True,
+                    timestamp=payload.get("timestamp", "")
+                )
+            finally:
+                conn.close()
+        except Exception:
+            return None
+
+    def set(self, result: EnrichmentResult) -> None:
+        """Save enrichment result into local SQLite cache."""
+        try:
+            payload_json = json.dumps(result.to_dict())
+            conn = sqlite3.connect(self.db_path)
+            try:
+                cursor = conn.cursor()
+                cursor.execute(
+                    """
+                    INSERT OR REPLACE INTO ioc_cache (ioc, ioc_type, data_json, cached_at)
+                    VALUES (?, ?, ?, ?)
+                    """,
+                    (result.ioc.lower().strip(), result.ioc_type.value, payload_json, int(time.time()))
+                )
+                conn.commit()
+            finally:
+                conn.close()
+        except Exception:
+            pass
+
+    def clear(self) -> int:
+        """Clear all entries from cache and return count of deleted records."""
+        try:
+            conn = sqlite3.connect(self.db_path)
+            try:
+                cursor = conn.cursor()
+                cursor.execute("SELECT count(*) FROM ioc_cache")
+                count = cursor.fetchone()[0]
+                cursor.execute("DELETE FROM ioc_cache")
+                conn.commit()
+                return count
+            finally:
+                conn.close()
+        except Exception:
+            return 0

threat_pulse/cli.py

@@ -0,0 +1,282 @@
+"""Command Line Interface (CLI) entry point for ThreatPulse."""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from threat_pulse import __version__
+from threat_pulse.cache import ThreatCache
+from threat_pulse.detector import detect_ioc_type, defang, refang, extract_iocs_from_text
+from threat_pulse.enrichers.abuseipdb import AbuseIPDBEnricher
+from threat_pulse.enrichers.malware import MalwareHashEnricher
+from threat_pulse.enrichers.network import NetworkEnricher
+from threat_pulse.formatters import (
+    render_terminal_card,
+    render_terminal_summary_table,
+    render_json,
+    render_markdown,
+    render_wazuh_cdb_list,
+)
+from threat_pulse.heuristics import (
+    analyze_ip_heuristics,
+    analyze_domain_heuristics,
+    analyze_url_heuristics,
+)
+from threat_pulse.models import EnrichmentResult, IOCType, RiskLevel
+from threat_pulse.scorer import calculate_risk_score
+
+
+def enrich_single_ioc(
+    raw_ioc: str,
+    cache: Optional[ThreatCache] = None,
+    abuse_api_key: Optional[str] = None,
+    use_cache: bool = True
+) -> EnrichmentResult:
+    """Enrich a single IOC across all heuristic, network, and intelligence engines."""
+    clean_target = refang(raw_ioc).strip()
+    ioc_type = detect_ioc_type(clean_target)
+
+    # 1. Check Cache
+    if use_cache and cache:
+        cached_result = cache.get(clean_target)
+        if cached_result:
+            return cached_result
+
+    # 2. Run Heuristics
+    heuristics = {}
+    if ioc_type in (IOCType.IPV4, IOCType.IPV6):
+        heuristics = analyze_ip_heuristics(clean_target)
+    elif ioc_type == IOCType.DOMAIN:
+        heuristics = analyze_domain_heuristics(clean_target)
+    elif ioc_type == IOCType.URL:
+        heuristics = analyze_url_heuristics(clean_target)
+
+    # 3. Run Enrichers
+    network_enricher = NetworkEnricher()
+    abuse_enricher = AbuseIPDBEnricher(api_key=abuse_api_key)
+    malware_enricher = MalwareHashEnricher()
+
+    net_data = network_enricher.enrich(clean_target, ioc_type) if network_enricher.can_enrich(ioc_type) else {}
+    abuse_data = abuse_enricher.enrich(clean_target, ioc_type) if abuse_enricher.can_enrich(ioc_type) else {}
+    malware_data = malware_enricher.enrich(clean_target, ioc_type) if malware_enricher.can_enrich(ioc_type) else {}
+
+    # 4. Score and Classify
+    score, level, verdict, tags, mitre, recom = calculate_risk_score(
+        clean_target, ioc_type, heuristics, net_data, abuse_data, malware_data
+    )
+
+    # Combine all details
+    combined_details = {**heuristics, **net_data, **abuse_data, **malware_data}
+
+    result = EnrichmentResult(
+        ioc=clean_target,
+        ioc_type=ioc_type,
+        defanged=defang(clean_target),
+        risk_score=score,
+        risk_level=level,
+        verdict=verdict,
+        is_private=heuristics.get("is_rfc1918", False),
+        is_bogon=heuristics.get("is_bogon", False),
+        tags=tags,
+        mitre_attack=mitre,
+        details=combined_details,
+        recommendation=recom,
+        cached=False,
+    )
+
+    # Save to Cache
+    if use_cache and cache:
+        cache.set(result)
+
+    return result
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the CLI argument parser with comprehensive options."""
+    parser = argparse.ArgumentParser(
+        prog="threat-pulse",
+        description="ThreatPulse - Fast Threat Intelligence & IOC Enrichment CLI for SOC Analysts.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  threat-pulse 185.220.101.5
+  threat-pulse 84c82835a5d21bbcf75a61706d8ab549
+  threat-pulse evil-dga-domain192837.top --format json
+  threat-pulse --file access.log --format table
+  threat-pulse --file suspicious_iocs.txt --format wazuh-cdb --out threat_pulse.cdb
+  threat-pulse --defang http://malicious.com/payload.exe
+        """
+    )
+    parser.add_argument(
+        "ioc",
+        nargs="?",
+        help="Target IOC to inspect (IPv4, IPv6, Domain, URL, MD5, SHA1, SHA256)"
+    )
+    parser.add_argument(
+        "-f", "--file",
+        help="Path to file (log, alert export, text) containing IOCs to extract and analyze"
+    )
+    parser.add_argument(
+        "--format",
+        choices=["card", "table", "json", "markdown", "wazuh-cdb"],
+        default="card",
+        help="Output visualization format (default: card for single, table for batch)"
+    )
+    parser.add_argument(
+        "-o", "--out",
+        help="Write report to an output file instead of stdout"
+    )
+    parser.add_argument(
+        "--api-key",
+        help="AbuseIPDB API key (defaults to ABUSEIPDB_API_KEY environment variable)"
+    )
+    parser.add_argument(
+        "--no-cache",
+        action="store_true",
+        help="Bypass local SQLite cache and force fresh enrichment"
+    )
+    parser.add_argument(
+        "--clear-cache",
+        action="store_true",
+        help="Wipe the local ThreatPulse SQLite cache and exit"
+    )
+    parser.add_argument(
+        "--defang",
+        help="Quickly defang an indicator and print the result"
+    )
+    parser.add_argument(
+        "--refang",
+        help="Quickly refang an indicator and print the canonical form"
+    )
+    parser.add_argument(
+        "-v", "--version",
+        action="version",
+        version=f"ThreatPulse v{__version__}"
+    )
+    return parser
+
+
+def main() -> int:
+    # Ensure Windows console supports UTF-8 Unicode characters (borders, bullets, emoji)
+    if sys.platform == "win32":
+        try:
+            sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+            sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+        except Exception:
+            pass
+
+    parser = build_parser()
+    args = parser.parse_args()
+
+    cache = ThreatCache()
+
+    # Clear cache action
+    if args.clear_cache:
+        deleted = cache.clear()
+        print(f"[*] ThreatPulse cache cleared successfully ({deleted} entries removed).")
+        return 0
+
+    # Quick defang / refang helpers
+    if args.defang:
+        print(defang(args.defang))
+        return 0
+
+    if args.refang:
+        print(refang(args.refang))
+        return 0
+
+    use_cache = not args.no_cache
+    iocs_to_check: List[str] = []
+
+    # Single IOC from positional argument
+    if args.ioc:
+        iocs_to_check.append(args.ioc)
+
+    # Batch IOCs from file
+    if args.file:
+        file_path = Path(args.file)
+        if not file_path.is_file():
+            print(f"[!] Error: File '{args.file}' not found.", file=sys.stderr)
+            return 1
+        try:
+            content = file_path.read_text(encoding="utf-8", errors="ignore")
+            extracted = extract_iocs_from_text(content)
+            for val, _ in extracted:
+                if val not in iocs_to_check:
+                    iocs_to_check.append(val)
+        except Exception as e:
+            print(f"[!] Error reading file: {e}", file=sys.stderr)
+            return 1
+
+    if not iocs_to_check:
+        parser.print_help()
+        return 1
+
+    # Enrich all targets (parallelized for batch files)
+    results: List[EnrichmentResult] = []
+    if len(iocs_to_check) > 1:
+        import concurrent.futures
+        future_map = {}
+        with concurrent.futures.ThreadPoolExecutor(max_workers=10) as executor:
+            for target in iocs_to_check:
+                fut = executor.submit(
+                    enrich_single_ioc,
+                    target,
+                    cache=cache,
+                    abuse_api_key=args.api_key,
+                    use_cache=use_cache
+                )
+                future_map[fut] = target
+
+            completed_map = {}
+            for fut in concurrent.futures.as_completed(future_map):
+                t = future_map[fut]
+                completed_map[t] = fut.result()
+
+            # Maintain original order of inputs
+            results = [completed_map[t] for t in iocs_to_check if t in completed_map]
+    else:
+        results = [
+            enrich_single_ioc(
+                iocs_to_check[0],
+                cache=cache,
+                abuse_api_key=args.api_key,
+                use_cache=use_cache
+            )
+        ]
+
+    # Determine default format
+    selected_format = args.format
+    if len(results) > 1 and selected_format == "card" and not args.out:
+        selected_format = "table"
+
+    output_text = ""
+    if selected_format == "card":
+        output_text = "\n\n".join(render_terminal_card(r) for r in results)
+    elif selected_format == "table":
+        output_text = render_terminal_summary_table(results)
+    elif selected_format == "json":
+        output_text = render_json(results, pretty=True)
+    elif selected_format == "markdown":
+        output_text = render_markdown(results)
+    elif selected_format == "wazuh-cdb":
+        output_text = render_wazuh_cdb_list(results)
+
+    # Write output or print to console
+    if args.out:
+        try:
+            Path(args.out).write_text(output_text, encoding="utf-8")
+            print(f"[+] Threat report successfully written to {args.out}")
+        except Exception as e:
+            print(f"[!] Error writing to {args.out}: {e}", file=sys.stderr)
+            return 1
+    else:
+        print(output_text)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

threat_pulse/detector.py

@@ -0,0 +1,136 @@
+"""Indicator of Compromise (IOC) type detection and extraction engine."""
+
+import ipaddress
+import re
+from typing import List, Tuple
+from threat_pulse.models import IOCType
+
+# Regular expressions for IOC detection
+IPV4_REGEX = re.compile(
+    r"\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}"
+    r"(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\b"
+)
+
+MD5_REGEX = re.compile(r"\b[a-fA-F0-9]{32}\b")
+SHA1_REGEX = re.compile(r"\b[a-fA-F0-9]{40}\b")
+SHA256_REGEX = re.compile(r"\b[a-fA-F0-9]{64}\b")
+
+# Matches standard domains (2+ labels, valid TLD length)
+DOMAIN_REGEX = re.compile(
+    r"\b(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,24}\b"
+)
+
+# Matches URLs (http, https, ftp, or defanged hxxp/hxxps)
+URL_REGEX = re.compile(
+    r"\b(?:https?|hxxps?|ftp)://[^\s/$.?#].[^\s]*", re.IGNORECASE
+)
+
+
+def refang(ioc: str) -> str:
+    """Normalize defanged indicators back into canonical format."""
+    cleaned = ioc.strip()
+    # Replace bracketed dots: [.] or (.) or {.} -> .
+    cleaned = re.sub(r"[\[\(\{]\.[\]\)\}]", ".", cleaned)
+    # Replace hxxp/hxxps -> http/https
+    cleaned = re.sub(r"^hxxp(s?):", r"http\1:", cleaned, flags=re.IGNORECASE)
+    # Replace [:] -> :
+    cleaned = re.sub(r"\[:\]", ":", cleaned)
+    return cleaned
+
+
+def defang(ioc: str) -> str:
+    """Defang an indicator to prevent accidental clicks or resolutions."""
+    cleaned = ioc.strip()
+    # Defang http/https
+    cleaned = re.sub(r"^http:", "hxxp:", cleaned, flags=re.IGNORECASE)
+    cleaned = re.sub(r"^https:", "hxxps:", cleaned, flags=re.IGNORECASE)
+    # Defang dots
+    return cleaned.replace(".", "[.]")
+
+
+def detect_ioc_type(raw_ioc: str) -> IOCType:
+    """Classify an IOC string into a specific IOCType."""
+    target = refang(raw_ioc).strip()
+
+    # 1. URL Check
+    if URL_REGEX.match(target) or target.startswith(("http://", "https://", "ftp://")):
+        return IOCType.URL
+
+    # 2. IP Checks
+    try:
+        ip = ipaddress.ip_address(target)
+        if ip.version == 4:
+            return IOCType.IPV4
+        elif ip.version == 6:
+            return IOCType.IPV6
+    except ValueError:
+        pass
+
+    # 3. Hash Checks
+    if SHA256_REGEX.fullmatch(target):
+        return IOCType.SHA256
+    if SHA1_REGEX.fullmatch(target):
+        return IOCType.SHA1
+    if MD5_REGEX.fullmatch(target):
+        return IOCType.MD5
+
+    # 4. Domain Check
+    if DOMAIN_REGEX.fullmatch(target):
+        # Exclude common file extensions that match domain regex by accident (e.g. script.sh, tool.py)
+        excluded_suffixes = {
+            "py", "sh", "exe", "dll", "bat", "ps1", "json", "xml", "csv", "log",
+            "txt", "md", "yml", "yaml", "tar", "gz", "zip", "rar", "7z", "conf"
+        }
+        parts = target.lower().split(".")
+        if len(parts) == 2 and parts[-1] in excluded_suffixes:
+            return IOCType.UNKNOWN
+        return IOCType.DOMAIN
+
+    return IOCType.UNKNOWN
+
+
+def extract_iocs_from_text(text: str) -> List[Tuple[str, IOCType]]:
+    """Scan raw text/logs and extract all recognized indicators."""
+    results: List[Tuple[str, IOCType]] = []
+    seen = set()
+
+    # 1. URLs
+    for match in URL_REGEX.finditer(text):
+        val = refang(match.group(0))
+        if val not in seen:
+            seen.add(val)
+            results.append((val, IOCType.URL))
+
+    # 2. IP Addresses (v4)
+    for match in IPV4_REGEX.finditer(text):
+        val = match.group(0)
+        try:
+            ipaddress.IPv4Address(val)
+            if val not in seen:
+                seen.add(val)
+                results.append((val, IOCType.IPV4))
+        except ValueError:
+            continue
+
+    # 3. Hashes
+    for match in SHA256_REGEX.finditer(text):
+        val = match.group(0)
+        if val not in seen:
+            seen.add(val)
+            results.append((val, IOCType.SHA256))
+
+    for match in MD5_REGEX.finditer(text):
+        val = match.group(0)
+        if val not in seen:
+            seen.add(val)
+            results.append((val, IOCType.MD5))
+
+    # 4. Domains (avoid matching substrings of already extracted URLs or IPs)
+    for match in DOMAIN_REGEX.finditer(text):
+        val = match.group(0)
+        if detect_ioc_type(val) == IOCType.DOMAIN:
+            if val not in seen:
+                seen.add(val)
+                results.append((val, IOCType.DOMAIN))
+
+    return results

threat_pulse/enrichers/__init__.py

@@ -0,0 +1,13 @@
+"""Enrichers package initialization."""
+
+from threat_pulse.enrichers.base import BaseEnricher
+from threat_pulse.enrichers.network import NetworkEnricher
+from threat_pulse.enrichers.abuseipdb import AbuseIPDBEnricher
+from threat_pulse.enrichers.malware import MalwareHashEnricher
+
+__all__ = [
+    "BaseEnricher",
+    "NetworkEnricher",
+    "AbuseIPDBEnricher",
+    "MalwareHashEnricher",
+]

threat_pulse/enrichers/abuseipdb.py

@@ -0,0 +1,69 @@
+"""AbuseIPDB Threat Intelligence API client with graceful offline fallback."""
+
+import json
+import os
+import urllib.request
+import urllib.error
+from typing import Dict, Any, Optional
+from threat_pulse.enrichers.base import BaseEnricher
+from threat_pulse.models import IOCType
+
+
+class AbuseIPDBEnricher(BaseEnricher):
+    """Enriches IP addresses using AbuseIPDB APIv2 or fallback heuristics."""
+
+    def __init__(self, api_key: Optional[str] = None, timeout: float = 3.0):
+        super().__init__(name="abuseipdb")
+        self.api_key = api_key or os.getenv("ABUSEIPDB_API_KEY")
+        self.timeout = timeout
+
+    def can_enrich(self, ioc_type: IOCType) -> bool:
+        return ioc_type in (IOCType.IPV4, IOCType.IPV6)
+
+    def enrich(self, ioc: str, ioc_type: IOCType) -> Dict[str, Any]:
+        data: Dict[str, Any] = {
+            "queried": False,
+            "abuse_score": 0,
+            "total_reports": 0,
+            "country_code": "UNKNOWN",
+            "usage_type": "Unknown",
+            "isp": "Unknown",
+            "is_whitelisted": False,
+            "last_reported_at": None,
+            "categories": [],
+            "error": None,
+        }
+
+        if not self.api_key:
+            data["error"] = "No API key configured (using local heuristics). Set ABUSEIPDB_API_KEY to enable live checks."
+            return data
+
+        url = f"https://api.abuseipdb.com/api/v2/check?ipAddress={ioc}&maxAgeInDays=90&verbose"
+        headers = {
+            "Key": self.api_key,
+            "Accept": "application/json",
+            "User-Agent": "ThreatPulse-SOC-CLI/1.0"
+        }
+
+        try:
+            req = urllib.request.Request(url, headers=headers, method="GET")
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                if resp.status == 200:
+                    payload = json.loads(resp.read().decode("utf-8"))
+                    report = payload.get("data", {})
+                    data["queried"] = True
+                    data["abuse_score"] = report.get("abuseConfidenceScore", 0)
+                    data["total_reports"] = report.get("totalReports", 0)
+                    data["country_code"] = report.get("countryCode", "UNKNOWN")
+                    data["usage_type"] = report.get("usageType", "Unknown")
+                    data["isp"] = report.get("isp", "Unknown")
+                    data["is_whitelisted"] = report.get("isWhitelisted", False)
+                    data["last_reported_at"] = report.get("lastReportedAt")
+        except urllib.error.HTTPError as e:
+            data["error"] = f"HTTP {e.code}: {e.reason}"
+        except urllib.error.URLError as e:
+            data["error"] = f"Network error: {e.reason}"
+        except Exception as e:
+            data["error"] = str(e)
+
+        return data

threat_pulse/enrichers/base.py

@@ -0,0 +1,23 @@
+"""Base classes for threat intelligence enrichers."""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+from threat_pulse.models import IOCType
+
+
+class BaseEnricher(ABC):
+    """Abstract interface for all threat intelligence and metadata enrichers."""
+
+    def __init__(self, name: str, enabled: bool = True):
+        self.name = name
+        self.enabled = enabled
+
+    @abstractmethod
+    def can_enrich(self, ioc_type: IOCType) -> bool:
+        """Determine if this enricher supports the given IOC type."""
+        pass
+
+    @abstractmethod
+    def enrich(self, ioc: str, ioc_type: IOCType) -> Dict[str, Any]:
+        """Perform enrichment and return structured metadata dictionary."""
+        pass