shadowhunter_alerts.py

#!/usr/bin/env python3
"""
ShadowHunter - Dark Web Credential Intelligence Platform
Module: Unified Multi-Channel Alerting System
Author: Fevra
Version: 0.1.0

Consolidated from Darkweb Monitor research - provides:
- Multi-channel alert delivery (Email, Telegram, Discord, Webhook)
- Priority-based routing and rate limiting
- Alert aggregation and deduplication
- Customizable alert templates
- Delivery tracking and retry logic
- Integration with scheduler and verify modules

Extends the email module with additional channels and unified interface.

References:
- shadowhunter_email.py patterns
- Darkweb Monitor alerting concepts
"""

import asyncio
import json
import hashlib
import aiohttp
from datetime import datetime, timezone, timedelta
from typing import List, Dict, Optional, Any, Callable, Set, Tuple
from dataclasses import dataclass, field
from enum import Enum
from abc import ABC, abstractmethod
import threading

# Import ShadowHunter modules
try:
    from shadowhunter_logger import get_logger, LogLevel
    from shadowhunter_email import EmailSender, EmailConfig, EmailAlert, AlertType, AlertSeverity
except ImportError:
    import logging
    def get_logger(name, **kwargs):
        return logging.getLogger(name)
    EmailSender = None
    EmailConfig = None
    EmailAlert = None
    AlertType = None
    AlertSeverity = None

# Initialize module logger
logger = get_logger("Alerts", log_level=LogLevel.DEBUG)


# ============================================================================
# CONFIGURATION & ENUMS
# ============================================================================

class AlertChannel(str, Enum):
    """Available alert delivery channels."""
    EMAIL = "email"
    TELEGRAM = "telegram"
    DISCORD = "discord"
    SLACK = "slack"
    WEBHOOK = "webhook"
    CONSOLE = "console"


class AlertPriority(str, Enum):
    """Alert priority levels."""
    CRITICAL = "critical"   # Immediate delivery, all channels
    HIGH = "high"           # Fast delivery, primary channels
    MEDIUM = "medium"       # Standard delivery
    LOW = "low"             # Batched/digest delivery
    INFO = "info"           # Optional, log only


class DeliveryStatus(str, Enum):
    """Alert delivery status."""
    PENDING = "pending"
    SENDING = "sending"
    DELIVERED = "delivered"
    FAILED = "failed"
    RETRYING = "retrying"
    SUPPRESSED = "suppressed"


# ============================================================================
# DATA MODELS
# ============================================================================

@dataclass
class AlertConfig:
    """
    Configuration for the unified alerting system.
    
    Defines channels, rate limits, and routing rules.
    """
    # Channel configurations
    email_config: Optional[Dict[str, Any]] = None
    telegram_config: Optional[Dict[str, Any]] = None
    discord_config: Optional[Dict[str, Any]] = None
    slack_config: Optional[Dict[str, Any]] = None
    webhook_urls: List[str] = field(default_factory=list)
    
    # Rate limiting
    max_alerts_per_hour: int = 100
    max_alerts_per_day: int = 1000
    cooldown_seconds: int = 60  # Min time between same alert type
    
    # Retry settings
    max_retries: int = 3
    retry_delay_seconds: int = 60
    
    # Deduplication
    dedup_window_minutes: int = 30
    
    # Routing rules (priority -> channels)
    routing_rules: Dict[str, List[str]] = field(default_factory=lambda: {
        "critical": ["email", "telegram", "discord", "webhook"],
        "high": ["email", "telegram", "webhook"],
        "medium": ["email", "webhook"],
        "low": ["email"],
        "info": ["console"]
    })


@dataclass
class Alert:
    """
    Unified alert structure for all channels.
    
    Represents a single alert that can be delivered
    through multiple channels based on priority and routing.
    """
    id: str
    title: str
    message: str
    priority: AlertPriority
    source: str  # Module that generated the alert
    category: str  # credential_leak, ransomware, change_detected, etc.
    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
    metadata: Dict[str, Any] = field(default_factory=dict)
    affected_domains: List[str] = field(default_factory=list)
    actions: List[str] = field(default_factory=list)  # Recommended actions
    tags: List[str] = field(default_factory=list)
    
    def get_dedup_key(self) -> str:
        """Generate deduplication key for alert."""
        key_parts = [
            self.category,
            self.source,
            ','.join(sorted(self.affected_domains)),
            self.title
        ]
        return hashlib.sha256('|'.join(key_parts).encode()).hexdigest()[:16]
    
    def to_dict(self) -> Dict[str, Any]:
        """Convert to dictionary."""
        return {
            "id": self.id,
            "title": self.title,
            "message": self.message,
            "priority": self.priority.value,
            "source": self.source,
            "category": self.category,
            "timestamp": self.timestamp.isoformat(),
            "affected_domains": self.affected_domains,
            "actions": self.actions,
            "tags": self.tags,
            "metadata": self.metadata
        }
    
    def get_priority_emoji(self) -> str:
        """Get emoji for priority level."""
        emojis = {
            AlertPriority.CRITICAL: "🔴",
            AlertPriority.HIGH: "🟠",
            AlertPriority.MEDIUM: "🟡",
            AlertPriority.LOW: "🔵",
            AlertPriority.INFO: "ℹ️"
        }
        return emojis.get(self.priority, "⚪")


@dataclass
class DeliveryRecord:
    """
    Record of an alert delivery attempt.
    
    Tracks delivery status, timing, and errors for
    each channel the alert was sent to.
    """
    alert_id: str
    channel: AlertChannel
    status: DeliveryStatus
    attempt: int
    timestamp: datetime
    error: Optional[str] = None
    response: Optional[str] = None
    
    def to_dict(self) -> Dict[str, Any]:
        """Convert to dictionary."""
        return {
            "alert_id": self.alert_id,
            "channel": self.channel.value,
            "status": self.status.value,
            "attempt": self.attempt,
            "timestamp": self.timestamp.isoformat(),
            "error": self.error
        }


# ============================================================================
# CHANNEL HANDLERS
# ============================================================================

class ChannelHandler(ABC):
    """
    Abstract base class for alert channel handlers.
    
    Each channel (email, telegram, etc.) implements this interface
    to provide consistent delivery behavior.
    """
    
    @property
    @abstractmethod
    def channel_type(self) -> AlertChannel:
        """Return the channel type."""
        pass
    
    @abstractmethod
    async def send(self, alert: Alert) -> Tuple[bool, Optional[str]]:
        """
        Send alert through this channel.
        
        Args:
            alert: Alert to send
        
        Returns:
            Tuple of (success, error_message)
        """
        pass
    
    @abstractmethod
    def is_configured(self) -> bool:
        """Check if channel is properly configured."""
        pass
    
    def format_message(self, alert: Alert) -> str:
        """Format alert message for this channel."""
        return f"{alert.get_priority_emoji()} [{alert.priority.value.upper()}] {alert.title}\n\n{alert.message}"


class TelegramHandler(ChannelHandler):
    """
    Telegram bot alert handler.
    
    Sends alerts to configured Telegram chat(s) via Bot API.
    """
    
    def __init__(
        self,
        bot_token: str,
        chat_ids: List[str],
        parse_mode: str = "HTML"
    ):
        """
        Initialize Telegram handler.
        
        Args:
            bot_token: Telegram bot API token
            chat_ids: List of chat IDs to send alerts to
            parse_mode: Message parse mode (HTML or Markdown)
        """
        self.bot_token = bot_token
        self.chat_ids = chat_ids
        self.parse_mode = parse_mode
        self.api_base = f"https://api.telegram.org/bot{bot_token}"
    
    @property
    def channel_type(self) -> AlertChannel:
        return AlertChannel.TELEGRAM
    
    def is_configured(self) -> bool:
        return bool(self.bot_token and self.chat_ids)
    
    def format_message(self, alert: Alert) -> str:
        """Format message for Telegram HTML."""
        emoji = alert.get_priority_emoji()
        
        message = f"""
{emoji} <b>{alert.priority.value.upper()} ALERT</b>

<b>🔔 {alert.title}</b>

{alert.message}

<b>📋 Details:</b>
• Source: {alert.source}
• Category: {alert.category}
• Time: {alert.timestamp.strftime('%Y-%m-%d %H:%M:%S UTC')}
"""
        
        if alert.affected_domains:
            message += f"\n• Affected: {', '.join(alert.affected_domains[:5])}"
        
        if alert.actions:
            message += "\n\n<b>⚡ Recommended Actions:</b>\n"
            for i, action in enumerate(alert.actions[:5], 1):
                message += f"{i}. {action}\n"
        
        if alert.tags:
            message += f"\n🏷 {' '.join(f'#{tag}' for tag in alert.tags[:5])}"
        
        return message.strip()
    
    async def send(self, alert: Alert) -> Tuple[bool, Optional[str]]:
        """Send alert to Telegram."""
        if not self.is_configured():
            return False, "Telegram not configured"
        
        message = self.format_message(alert)
        success_count = 0
        errors = []
        
        async with aiohttp.ClientSession() as session:
            for chat_id in self.chat_ids:
                try:
                    async with session.post(
                        f"{self.api_base}/sendMessage",
                        json={
                            "chat_id": chat_id,
                            "text": message,
                            "parse_mode": self.parse_mode,
                            "disable_web_page_preview": True
                        },
                        timeout=aiohttp.ClientTimeout(total=10)
                    ) as response:
                        result = await response.json()
                        
                        if result.get("ok"):
                            success_count += 1
                            logger.info(f"Telegram alert sent to chat {chat_id}")
                        else:
                            error = result.get("description", "Unknown error")
                            errors.append(f"{chat_id}: {error}")
                            logger.warn(f"Telegram send failed: {error}")
                            
                except Exception as e:
                    errors.append(f"{chat_id}: {str(e)}")
                    logger.error(f"Telegram error: {e}")
        
        if success_count == len(self.chat_ids):
            return True, None
        elif success_count > 0:
            return True, f"Partial delivery: {'; '.join(errors)}"
        else:
            return False, '; '.join(errors)


class DiscordHandler(ChannelHandler):
    """
    Discord webhook alert handler.
    
    Sends alerts to Discord channels via webhooks with rich embeds.
    """
    
    def __init__(self, webhook_urls: List[str]):
        """
        Initialize Discord handler.
        
        Args:
            webhook_urls: List of Discord webhook URLs
        """
        self.webhook_urls = webhook_urls
    
    @property
    def channel_type(self) -> AlertChannel:
        return AlertChannel.DISCORD
    
    def is_configured(self) -> bool:
        return bool(self.webhook_urls)
    
    def _get_color(self, priority: AlertPriority) -> int:
        """Get embed color based on priority."""
        colors = {
            AlertPriority.CRITICAL: 0xDC2626,  # Red
            AlertPriority.HIGH: 0xEA580C,      # Orange
            AlertPriority.MEDIUM: 0xCA8A04,    # Yellow
            AlertPriority.LOW: 0x2563EB,       # Blue
            AlertPriority.INFO: 0x64748B       # Gray
        }
        return colors.get(priority, 0x6B7280)
    
    def format_embed(self, alert: Alert) -> Dict[str, Any]:
        """Format alert as Discord embed."""
        embed = {
            "title": f"{alert.get_priority_emoji()} {alert.title}",
            "description": alert.message[:2000],  # Discord limit
            "color": self._get_color(alert.priority),
            "timestamp": alert.timestamp.isoformat(),
            "footer": {
                "text": f"ShadowHunter | {alert.source}"
            },
            "fields": [
                {
                    "name": "Priority",
                    "value": alert.priority.value.upper(),
                    "inline": True
                },
                {
                    "name": "Category",
                    "value": alert.category,
                    "inline": True
                }
            ]
        }
        
        if alert.affected_domains:
            embed["fields"].append({
                "name": "Affected Domains",
                "value": ', '.join(alert.affected_domains[:10]),
                "inline": False
            })
        
        if alert.actions:
            embed["fields"].append({
                "name": "⚡ Recommended Actions",
                "value": '\n'.join(f"• {a}" for a in alert.actions[:5]),
                "inline": False
            })
        
        return embed
    
    async def send(self, alert: Alert) -> Tuple[bool, Optional[str]]:
        """Send alert to Discord."""
        if not self.is_configured():
            return False, "Discord not configured"
        
        embed = self.format_embed(alert)
        payload = {
            "username": "ShadowHunter",
            "embeds": [embed]
        }
        
        success_count = 0
        errors = []
        
        async with aiohttp.ClientSession() as session:
            for webhook_url in self.webhook_urls:
                try:
                    async with session.post(
                        webhook_url,
                        json=payload,
                        timeout=aiohttp.ClientTimeout(total=10)
                    ) as response:
                        if response.status in [200, 204]:
                            success_count += 1
                            logger.info("Discord alert sent")
                        else:
                            error = await response.text()
                            errors.append(error[:100])
                            logger.warn(f"Discord send failed: {response.status}")
                            
                except Exception as e:
                    errors.append(str(e))
                    logger.error(f"Discord error: {e}")
        
        if success_count == len(self.webhook_urls):
            return True, None
        elif success_count > 0:
            return True, f"Partial delivery: {'; '.join(errors)}"
        else:
            return False, '; '.join(errors)


class SlackHandler(ChannelHandler):
    """
    Slack webhook alert handler.
    
    Sends alerts to Slack channels via incoming webhooks.
    """
    
    def __init__(self, webhook_url: str):
        """
        Initialize Slack handler.
        
        Args:
            webhook_url: Slack incoming webhook URL
        """
        self.webhook_url = webhook_url
    
    @property
    def channel_type(self) -> AlertChannel:
        return AlertChannel.SLACK
    
    def is_configured(self) -> bool:
        return bool(self.webhook_url)
    
    def _get_color(self, priority: AlertPriority) -> str:
        """Get attachment color based on priority."""
        colors = {
            AlertPriority.CRITICAL: "danger",
            AlertPriority.HIGH: "warning",
            AlertPriority.MEDIUM: "#CA8A04",
            AlertPriority.LOW: "good",
            AlertPriority.INFO: "#64748B"
        }
        return colors.get(priority, "#6B7280")
    
    def format_blocks(self, alert: Alert) -> Dict[str, Any]:
        """Format alert as Slack blocks."""
        blocks = [
            {
                "type": "header",
                "text": {
                    "type": "plain_text",
                    "text": f"{alert.get_priority_emoji()} {alert.title}"
                }
            },
            {
                "type": "section",
                "text": {
                    "type": "mrkdwn",
                    "text": alert.message[:2900]  # Slack limit
                }
            },
            {
                "type": "context",
                "elements": [
                    {
                        "type": "mrkdwn",
                        "text": f"*Priority:* {alert.priority.value.upper()} | *Source:* {alert.source} | *Category:* {alert.category}"
                    }
                ]
            }
        ]
        
        if alert.actions:
            actions_text = '\n'.join(f"• {a}" for a in alert.actions[:5])
            blocks.append({
                "type": "section",
                "text": {
                    "type": "mrkdwn",
                    "text": f"*⚡ Recommended Actions:*\n{actions_text}"
                }
            })
        
        blocks.append({"type": "divider"})
        
        return {
            "attachments": [{
                "color": self._get_color(alert.priority),
                "blocks": blocks
            }]
        }
    
    async def send(self, alert: Alert) -> Tuple[bool, Optional[str]]:
        """Send alert to Slack."""
        if not self.is_configured():
            return False, "Slack not configured"
        
        payload = self.format_blocks(alert)
        
        try:
            async with aiohttp.ClientSession() as session:
                async with session.post(
                    self.webhook_url,
                    json=payload,
                    timeout=aiohttp.ClientTimeout(total=10)
                ) as response:
                    if response.status == 200:
                        logger.info("Slack alert sent")
                        return True, None
                    else:
                        error = await response.text()
                        logger.warn(f"Slack send failed: {response.status}")
                        return False, error
                        
        except Exception as e:
            logger.error(f"Slack error: {e}")
            return False, str(e)


class WebhookHandler(ChannelHandler):
    """
    Generic webhook alert handler.
    
    Sends alerts as JSON to configured webhook endpoints.
    """
    
    def __init__(
        self,
        webhook_urls: List[str],
        headers: Optional[Dict[str, str]] = None
    ):
        """
        Initialize webhook handler.
        
        Args:
            webhook_urls: List of webhook URLs
            headers: Optional custom headers
        """
        self.webhook_urls = webhook_urls
        self.headers = headers or {"Content-Type": "application/json"}
    
    @property
    def channel_type(self) -> AlertChannel:
        return AlertChannel.WEBHOOK
    
    def is_configured(self) -> bool:
        return bool(self.webhook_urls)
    
    async def send(self, alert: Alert) -> Tuple[bool, Optional[str]]:
        """Send alert to webhooks."""
        if not self.is_configured():
            return False, "Webhooks not configured"
        
        payload = {
            "event": "shadowhunter_alert",
            "alert": alert.to_dict()
        }
        
        success_count = 0
        errors = []
        
        async with aiohttp.ClientSession() as session:
            for webhook_url in self.webhook_urls:
                try:
                    async with session.post(
                        webhook_url,
                        json=payload,
                        headers=self.headers,
                        timeout=aiohttp.ClientTimeout(total=10)
                    ) as response:
                        if response.status in range(200, 300):
                            success_count += 1
                            logger.info(f"Webhook alert sent to {webhook_url[:50]}")
                        else:
                            errors.append(f"HTTP {response.status}")
                            logger.warn(f"Webhook failed: {response.status}")
                            
                except Exception as e:
                    errors.append(str(e))
                    logger.error(f"Webhook error: {e}")
        
        if success_count == len(self.webhook_urls):
            return True, None
        elif success_count > 0:
            return True, f"Partial: {len(errors)} failed"
        else:
            return False, '; '.join(errors)


class ConsoleHandler(ChannelHandler):
    """
    Console output alert handler for development/testing.
    """
    
    @property
    def channel_type(self) -> AlertChannel:
        return AlertChannel.CONSOLE
    
    def is_configured(self) -> bool:
        return True
    
    async def send(self, alert: Alert) -> Tuple[bool, Optional[str]]:
        """Print alert to console."""
        print("\n" + "=" * 60)
        print(f"{alert.get_priority_emoji()} [{alert.priority.value.upper()}] ALERT")
        print("=" * 60)
        print(f"📋 {alert.title}")
        print(f"\n{alert.message}")
        print(f"\n• Source: {alert.source}")
        print(f"• Category: {alert.category}")
        print(f"• Time: {alert.timestamp.strftime('%Y-%m-%d %H:%M:%S UTC')}")
        
        if alert.affected_domains:
            print(f"• Affected: {', '.join(alert.affected_domains)}")
        
        if alert.actions:
            print("\n⚡ Recommended Actions:")
            for i, action in enumerate(alert.actions, 1):
                print(f"   {i}. {action}")
        
        print("=" * 60 + "\n")
        
        return True, None


# ============================================================================
# ALERT MANAGER
# ============================================================================

class AlertManager:
    """
    Unified alert management system.
    
    Provides:
    - Multi-channel alert routing
    - Rate limiting and deduplication
    - Delivery tracking and retries
    - Alert aggregation for digests
    
    Usage:
        manager = AlertManager(config)
        manager.register_channel(TelegramHandler(...))
        await manager.send_alert(alert)
    """
    
    def __init__(self, config: AlertConfig):
        """
        Initialize alert manager.
        
        Args:
            config: Alert configuration
        """
        self.config = config
        self.handlers: Dict[AlertChannel, ChannelHandler] = {}
        self.delivery_history: List[DeliveryRecord] = []
        self.alert_hashes: Dict[str, datetime] = {}  # For deduplication
        self.rate_tracker = {"hour": 0, "day": 0}
        self.last_reset = {"hour": datetime.now(), "day": datetime.now()}
        self._lock = threading.Lock()
        
        # Register console handler by default
        self.register_channel(ConsoleHandler())
        
        logger.info("Alert manager initialized", {
            "max_per_hour": config.max_alerts_per_hour,
            "max_per_day": config.max_alerts_per_day
        })
    
    def register_channel(self, handler: ChannelHandler):
        """
        Register a channel handler.
        
        Args:
            handler: Channel handler to register
        """
        self.handlers[handler.channel_type] = handler
        logger.info(f"Registered channel: {handler.channel_type.value}", {
            "configured": handler.is_configured()
        })
    
    def _check_rate_limit(self) -> bool:
        """Check if rate limit allows sending."""
        now = datetime.now()
        
        with self._lock:
            # Reset hourly counter
            if (now - self.last_reset["hour"]).total_seconds() > 3600:
                self.rate_tracker["hour"] = 0
                self.last_reset["hour"] = now
            
            # Reset daily counter
            if (now - self.last_reset["day"]).total_seconds() > 86400:
                self.rate_tracker["day"] = 0
                self.last_reset["day"] = now
            
            # Check limits
            if self.rate_tracker["hour"] >= self.config.max_alerts_per_hour:
                return False
            if self.rate_tracker["day"] >= self.config.max_alerts_per_day:
                return False
            
            return True
    
    def _is_duplicate(self, alert: Alert) -> bool:
        """Check if alert is a duplicate within dedup window."""
        dedup_key = alert.get_dedup_key()
        
        with self._lock:
            if dedup_key in self.alert_hashes:
                last_sent = self.alert_hashes[dedup_key]
                window = timedelta(minutes=self.config.dedup_window_minutes)
                
                if datetime.now(timezone.utc) - last_sent < window:
                    return True
            
            return False
    
    def _record_alert(self, alert: Alert):
        """Record alert for deduplication."""
        dedup_key = alert.get_dedup_key()
        
        with self._lock:
            self.alert_hashes[dedup_key] = alert.timestamp
            self.rate_tracker["hour"] += 1
            self.rate_tracker["day"] += 1
    
    def _get_channels_for_priority(self, priority: AlertPriority) -> List[AlertChannel]:
        """Get channels to use for priority level."""
        channel_names = self.config.routing_rules.get(priority.value, ["console"])
        
        channels = []
        for name in channel_names:
            try:
                channel = AlertChannel(name)
                if channel in self.handlers and self.handlers[channel].is_configured():
                    channels.append(channel)
            except ValueError:
                pass
        
        return channels
    
    async def send_alert(
        self,
        alert: Alert,
        force: bool = False,
        channels: Optional[List[AlertChannel]] = None
    ) -> Dict[AlertChannel, DeliveryRecord]:
        """
        Send alert through configured channels.
        
        Args:
            alert: Alert to send
            force: Force send even if duplicate/rate limited
            channels: Override channel selection
        
        Returns:
            Dictionary of channel -> delivery record
        """
        results = {}
        
        # Check rate limit
        if not force and not self._check_rate_limit():
            logger.warn("Alert rate limit exceeded", {
                "alert_id": alert.id,
                "hour_count": self.rate_tracker["hour"],
                "day_count": self.rate_tracker["day"]
            })
            return results
        
        # Check deduplication
        if not force and self._is_duplicate(alert):
            logger.info("Duplicate alert suppressed", {
                "alert_id": alert.id,
                "dedup_key": alert.get_dedup_key()
            })
            
            # Return suppressed record
            for channel in self._get_channels_for_priority(alert.priority):
                results[channel] = DeliveryRecord(
                    alert_id=alert.id,
                    channel=channel,
                    status=DeliveryStatus.SUPPRESSED,
                    attempt=0,
                    timestamp=datetime.now(timezone.utc)
                )
            
            return results
        
        # Determine channels
        target_channels = channels or self._get_channels_for_priority(alert.priority)
        
        if not target_channels:
            logger.warn("No channels configured for priority", {
                "priority": alert.priority.value
            })
            return results
        
        logger.info(f"Sending alert: {alert.title}", {
            "alert_id": alert.id,
            "priority": alert.priority.value,
            "channels": [c.value for c in target_channels]
        })
        
        # Send to each channel
        for channel in target_channels:
            handler = self.handlers.get(channel)
            
            if not handler:
                continue
            
            attempt = 1
            success = False
            error = None
            
            while attempt <= self.config.max_retries and not success:
                try:
                    success, error = await handler.send(alert)
                    
                    if not success and attempt < self.config.max_retries:
                        logger.warn(f"Retry {attempt}/{self.config.max_retries} for {channel.value}")
                        await asyncio.sleep(self.config.retry_delay_seconds)
                    
                except Exception as e:
                    error = str(e)
                    logger.error(f"Channel error: {channel.value} - {e}")
                
                attempt += 1
            
            # Record delivery
            record = DeliveryRecord(
                alert_id=alert.id,
                channel=channel,
                status=DeliveryStatus.DELIVERED if success else DeliveryStatus.FAILED,
                attempt=attempt - 1,
                timestamp=datetime.now(timezone.utc),
                error=error
            )
            
            results[channel] = record
            self.delivery_history.append(record)
        
        # Record alert for deduplication
        self._record_alert(alert)
        
        return results
    
    async def send_batch(
        self,
        alerts: List[Alert],
        parallel: bool = True
    ) -> Dict[str, Dict[AlertChannel, DeliveryRecord]]:
        """
        Send multiple alerts.
        
        Args:
            alerts: List of alerts to send
            parallel: Send alerts in parallel
        
        Returns:
            Dictionary of alert_id -> delivery results
        """
        results = {}
        
        if parallel:
            tasks = [self.send_alert(alert) for alert in alerts]
            delivery_results = await asyncio.gather(*tasks)
            
            for alert, result in zip(alerts, delivery_results):
                results[alert.id] = result
        else:
            for alert in alerts:
                results[alert.id] = await self.send_alert(alert)
        
        return results
    
    def get_statistics(self) -> Dict[str, Any]:
        """Get alerting statistics."""
        with self._lock:
            # Count by status
            status_counts = {}
            channel_counts = {}
            
            for record in self.delivery_history[-1000:]:  # Last 1000
                status = record.status.value
                channel = record.channel.value
                
                status_counts[status] = status_counts.get(status, 0) + 1
                channel_counts[channel] = channel_counts.get(channel, 0) + 1
            
            return {
                "alerts_this_hour": self.rate_tracker["hour"],
                "alerts_today": self.rate_tracker["day"],
                "hourly_limit": self.config.max_alerts_per_hour,
                "daily_limit": self.config.max_alerts_per_day,
                "registered_channels": [c.value for c in self.handlers.keys()],
                "configured_channels": [
                    c.value for c, h in self.handlers.items() 
                    if h.is_configured()
                ],
                "delivery_status_counts": status_counts,
                "channel_counts": channel_counts,
                "total_deliveries": len(self.delivery_history)
            }
    
    def get_recent_alerts(self, limit: int = 50) -> List[DeliveryRecord]:
        """Get recent delivery records."""
        return self.delivery_history[-limit:]


# ============================================================================
# FACTORY FUNCTION
# ============================================================================

def create_alert_manager(
    telegram_token: Optional[str] = None,
    telegram_chat_ids: Optional[List[str]] = None,
    discord_webhooks: Optional[List[str]] = None,
    slack_webhook: Optional[str] = None,
    custom_webhooks: Optional[List[str]] = None,
    config: Optional[AlertConfig] = None
) -> AlertManager:
    """
    Create and configure an alert manager.
    
    Args:
        telegram_token: Telegram bot token
        telegram_chat_ids: Telegram chat IDs
        discord_webhooks: Discord webhook URLs
        slack_webhook: Slack webhook URL
        custom_webhooks: Custom webhook URLs
        config: Alert configuration
    
    Returns:
        Configured AlertManager
    """
    config = config or AlertConfig()
    manager = AlertManager(config)
    
    # Register Telegram
    if telegram_token and telegram_chat_ids:
        manager.register_channel(TelegramHandler(
            bot_token=telegram_token,
            chat_ids=telegram_chat_ids
        ))
    
    # Register Discord
    if discord_webhooks:
        manager.register_channel(DiscordHandler(discord_webhooks))
    
    # Register Slack
    if slack_webhook:
        manager.register_channel(SlackHandler(slack_webhook))
    
    # Register custom webhooks
    if custom_webhooks:
        manager.register_channel(WebhookHandler(custom_webhooks))
    
    return manager


# ============================================================================
# INTEGRATION HELPERS
# ============================================================================

def create_credential_leak_alert(
    domain: str,
    count: int,
    source: str,
    has_passwords: bool = False,
    metadata: Optional[Dict[str, Any]] = None
) -> Alert:
    """Create a credential leak alert."""
    priority = AlertPriority.CRITICAL if has_passwords else AlertPriority.HIGH
    
    return Alert(
        id=f"cred_{hashlib.sha256(f'{domain}{datetime.now()}'.encode()).hexdigest()[:12]}",
        title=f"Credential Leak Detected: {domain}",
        message=f"{count} credentials for {domain} found in {source}.\n" +
                ("⚠️ Passwords included!" if has_passwords else "Emails/usernames only."),
        priority=priority,
        source="CredentialMonitor",
        category="credential_leak",
        affected_domains=[domain],
        actions=[
            "Reset passwords for affected accounts immediately",
            "Enable MFA on all affected accounts",
            "Review account activity for suspicious logins",
            "Notify affected users"
        ],
        tags=["credentials", source.lower().replace(" ", "_")],
        metadata={"credential_count": count, "has_passwords": has_passwords, **(metadata or {})}
    )


def create_change_detection_alert(
    site_name: str,
    site_url: str,
    change_type: str,
    change_description: str,
    metadata: Optional[Dict[str, Any]] = None
) -> Alert:
    """Create a site change detection alert."""
    return Alert(
        id=f"change_{hashlib.sha256(f'{site_url}{datetime.now()}'.encode()).hexdigest()[:12]}",
        title=f"Content Change: {site_name}",
        message=f"Change detected on monitored site.\n\n{change_description}",
        priority=AlertPriority.MEDIUM,
        source="Scheduler",
        category="site_change",
        affected_domains=[site_url],
        actions=[
            "Review the content changes",
            "Check for new threat intelligence",
            "Update monitoring keywords if needed"
        ],
        tags=["monitoring", change_type],
        metadata=metadata or {}
    )


def create_keyword_match_alert(
    site_name: str,
    keyword: str,
    context: str,
    metadata: Optional[Dict[str, Any]] = None
) -> Alert:
    """Create a keyword match alert."""
    return Alert(
        id=f"keyword_{hashlib.sha256(f'{keyword}{datetime.now()}'.encode()).hexdigest()[:12]}",
        title=f"Keyword Match: '{keyword}' on {site_name}",
        message=f"Monitored keyword detected.\n\nContext: ...{context}...",
        priority=AlertPriority.HIGH,
        source="Scheduler",
        category="keyword_match",
        affected_domains=[site_name],
        actions=[
            "Investigate the match context",
            "Determine if further action is needed",
            "Consider adjusting keyword sensitivity"
        ],
        tags=["keyword", keyword.lower().replace(" ", "_")],
        metadata=metadata or {}
    )


# ============================================================================
# DEMO & TESTING
# ============================================================================

async def demo_alerts():
    """Demonstrate unified alerting system."""
    print("=" * 80)
    print("ShadowHunter Unified Alerting Demo")
    print("=" * 80)
    
    # Create manager with console-only output for demo
    config = AlertConfig(
        max_alerts_per_hour=10,
        max_alerts_per_day=50,
        dedup_window_minutes=5
    )
    
    manager = AlertManager(config)
    
    # Demo 1: Critical credential alert
    print("\n📧 Test 1: Critical Credential Alert")
    alert1 = create_credential_leak_alert(
        domain="acmecorp.com",
        count=500,
        source="Telegram Stealer Channel",
        has_passwords=True
    )
    await manager.send_alert(alert1)
    
    # Demo 2: Site change alert
    print("\n📧 Test 2: Site Change Alert")
    alert2 = create_change_detection_alert(
        site_name="Ransomware Leak Site",
        site_url="http://example.onion",
        change_type="content",
        change_description="New victim listing added (+1500 words)"
    )
    await manager.send_alert(alert2)
    
    # Demo 3: Keyword match alert
    print("\n📧 Test 3: Keyword Match Alert")
    alert3 = create_keyword_match_alert(
        site_name="Underground Forum",
        keyword="acmecorp",
        context="selling access to acmecorp.com VPN for $5000"
    )
    await manager.send_alert(alert3)
    
    # Demo 4: Duplicate suppression
    print("\n📧 Test 4: Duplicate Suppression")
    duplicate = create_credential_leak_alert(
        domain="acmecorp.com",  # Same domain
        count=500,
        source="Telegram Stealer Channel",
        has_passwords=True
    )
    await manager.send_alert(duplicate)
    
    # Show statistics
    print("\n📊 Alert Statistics:")
    stats = manager.get_statistics()
    print(json.dumps(stats, indent=2))
    
    print("\n" + "=" * 80)
    print("✅ Demo complete!")
    print("=" * 80)


if __name__ == "__main__":
    asyncio.run(demo_alerts())