dc-securex 2.29.7__py3-none-any.whl

securex/models.py

@@ -0,0 +1,156 @@
+"""
+Data models for SecureX SDK.
+These objects are returned to developers - no UI included.
+"""
+from dataclasses import dataclass, asdict, field
+from datetime import datetime, timezone
+from typing import Optional, List, Dict
+import json
+
+
+@dataclass
+class ThreatEvent:
+    """
+    Represents a detected security threat.
+    
+    Attributes:
+        type: Type of threat (e.g., "channel_delete", "role_create")
+        guild_id: ID of the guild where threat occurred
+        actor_id: ID of user who performed the action
+        target_id: ID of the affected resource
+        target_name: Name of the affected resource
+        prevented: Whether the action was prevented
+        restored: Whether restoration was successful
+        timestamp: When the threat was detected
+        details: Additional context about the threat
+    """
+    type: str
+    guild_id: int
+    actor_id: int
+    target_id: int
+    target_name: str
+    prevented: bool
+    restored: bool
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    details: Dict = field(default_factory=dict)
+    punishment_action: Optional[str] = None  
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary for serialization"""
+        data = asdict(self)
+        data['timestamp'] = self.timestamp.isoformat()
+        return data
+    
+    def to_json(self) -> str:
+        """Convert to JSON string"""
+        return json.dumps(self.to_dict())
+
+
+@dataclass
+class BackupInfo:
+    """
+    Information about a server backup.
+    
+    Attributes:
+        guild_id: ID of the backed up guild
+        timestamp: When backup was created
+        channel_count: Number of channels backed up
+        role_count: Number of roles backed up
+        backup_path: Path to backup file
+        success: Whether backup completed successfully
+    """
+    guild_id: int
+    timestamp: datetime
+    channel_count: int
+    role_count: int
+    backup_path: str
+    success: bool = True
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary"""
+        data = asdict(self)
+        data['timestamp'] = self.timestamp.isoformat()
+        return data
+
+
+@dataclass
+class RestoreResult:
+    """
+    Result of a restoration operation.
+    
+    Attributes:
+        success: Overall success status
+        items_restored: Number of items successfully restored
+        items_failed: Number of items that failed to restore
+        errors: List of error messages
+        duration: Time taken in seconds
+        details: Additional restoration details
+    """
+    success: bool
+    items_restored: int
+    items_failed: int
+    errors: List[str] = field(default_factory=list)
+    duration: float = 0.0
+    details: Dict = field(default_factory=dict)
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary"""
+        return asdict(self)
+
+
+@dataclass
+class WhitelistChange:
+    """
+    Represents a whitelist modification.
+    
+    Attributes:
+        guild_id: Guild where change occurred
+        user_id: User added/removed from whitelist
+        action: "added" or "removed"
+        timestamp: When the change occurred
+        moderator_id: Who made the change
+    """
+    guild_id: int
+    user_id: int
+    action: str  
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    moderator_id: Optional[int] = None
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary"""
+        data = asdict(self)
+        data['timestamp'] = self.timestamp.isoformat()
+        return data
+
+
+@dataclass
+class UserToken:
+    """
+    Represents a user token for guild-level API operations.
+    
+    Attributes:
+        guild_id: Guild this token is associated with
+        token: The user authentication token
+        set_by: User ID who set this token
+        timestamp: When the token was added/updated
+        last_used: When the token was last used (optional)
+        description: Optional description/note about the token
+    """
+    guild_id: int
+    token: str
+    set_by: Optional[int] = None
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+    last_used: Optional[datetime] = None
+    description: Optional[str] = None
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary"""
+        data = asdict(self)
+        data['timestamp'] = self.timestamp.isoformat()
+        if self.last_used:
+            data['last_used'] = self.last_used.isoformat()
+        return data
+    
+    def mark_used(self):
+        """Mark this token as used (updates last_used timestamp)"""
+        self.last_used = datetime.now(timezone.utc)

securex/utils/__init__.py

@@ -0,0 +1,5 @@
+"""Utils package"""
+
+from .whitelist import WhitelistManager
+
+__all__ = ['WhitelistManager']

securex/utils/punishment.py

@@ -0,0 +1,124 @@
+"""
+Punishment executor for anti-nuke violations.
+Handles kick, ban, timeout, and warn actions.
+"""
+import discord
+from datetime import timedelta
+from typing import Optional
+
+
+class PunishmentExecutor:
+    """Executes punishment actions on violators"""
+    
+    def __init__(self, bot):
+        """Initialize with bot instance"""
+        self.bot = bot
+    
+    async def punish(
+        self, 
+        guild: discord.Guild, 
+        user: discord.User,
+        violation_type: str,
+        details: str = None,
+        sdk = None
+    ) -> str:
+        """
+        Execute punishment on violator based on violation type.
+        
+        Args:
+            guild: The guild where violation occurred
+            user: The user who committed the violation
+            violation_type: Type of violation (e.g., "channel_delete")
+            details: Optional details about the violation
+            sdk: SDK instance for accessing punishment config
+            
+        Returns:
+            The punishment action that was applied ("none", "warn", "timeout", "kick", "ban")
+        """
+        if sdk is None:
+            return "none"
+            
+        
+        action = sdk.punishments.get(violation_type, "none")
+        
+        if action == "none":
+            return action
+        
+        member = guild.get_member(user.id)
+        if not member:
+            print(f"Cannot punish {user}: not a member")
+            return action
+        
+        
+        if member.id == guild.owner_id:
+            print(f"Cannot punish server owner {user}")
+            return action
+        
+        
+        
+        try:
+            if action == "warn":
+                
+                print(f"⚠️ Warned {user} for {violation_type}")
+                
+            elif action == "timeout":
+                duration = timedelta(seconds=sdk.timeout_duration)
+                await member.timeout(duration, reason=f"SecureX: {violation_type}")
+                print(f"⏱️ Timed out {user} for {sdk.timeout_duration}s ({violation_type})")
+                
+            elif action == "kick":
+                await member.kick(reason=f"SecureX: {violation_type}")
+                print(f"👢 Kicked {user} for {violation_type}")
+                
+            elif action == "ban":
+                await member.ban(reason=f"SecureX: {violation_type}", delete_message_days=0)
+                print(f"🔨 Banned {user} for {violation_type}")
+            
+            if sdk.notify_punished_user:
+                await self._notify_user(member, violation_type, action, details, sdk)
+        
+                
+        except discord.Forbidden:
+            print(f"❌ Missing permissions to {action} {user}")
+        except Exception as e:
+            print(f"Error punishing {user}: {e}")
+        
+        return action
+    
+    async def _notify_user(
+        self, 
+        member: discord.Member, 
+        violation_type: str, 
+        action: str, 
+        details: Optional[str],
+        sdk
+    ):
+        """Send DM notification to punished user"""
+        try:
+            
+            readable_type = violation_type.replace("_", " ").title()
+            
+            embed = discord.Embed(
+                title="🚨 Anti-Nuke Violation Detected",
+                description=f"You triggered anti-nuke protection in **{member.guild.name}**",
+                color=discord.Color.red()
+            )
+            embed.add_field(name="Violation Type", value=readable_type, inline=False)
+            if details:
+                embed.add_field(name="Details", value=details, inline=False)
+            embed.add_field(
+                name="Action Taken", 
+                value=f"**{action.title()}**", 
+                inline=False
+            )
+            
+            if action == "timeout":
+                mins = sdk.timeout_duration // 60
+                embed.add_field(name="Duration", value=f"{mins} minutes", inline=False)
+            
+            await member.send(embed=embed)
+            print(f"📨 Sent punishment notification to {member}")
+        except discord.Forbidden:
+            print(f"Cannot DM {member} (DMs disabled)")
+        except Exception as e:
+            print(f"Error notifying {member}: {e}")

securex/utils/whitelist.py

@@ -0,0 +1,129 @@
+"""
+Whitelist management for SecureX SDK.
+Strictly per-guild - no cross-server whitelisting.
+"""
+import json
+import aiofiles
+from pathlib import Path
+from typing import List, Set
+from ..models import WhitelistChange
+
+
+class WhitelistManager:
+    """Manages whitelisted users per guild (guild-specific only)"""
+    
+    def __init__(self, sdk):
+        self.sdk = sdk
+        self.data_dir = Path("./data/whitelists")
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        
+        
+        self._whitelists: dict[int, Set[int]] = {}
+        self._cache_loaded = False
+    
+    def _get_file_path(self, guild_id: int) -> Path:
+        """Get whitelist file path for guild"""
+        return self.data_dir / f"{guild_id}.json"
+    
+    async def preload_all(self):
+        """
+        Preload ALL whitelists into memory on startup.
+        Call this in enable() to warm the cache.
+        """
+        if self._cache_loaded:
+            return
+        
+        print("🔄 Preloading whitelists into cache...")
+        count = 0
+        
+        
+        for file_path in self.data_dir.glob("*.json"):
+            try:
+                guild_id = int(file_path.stem)
+                async with aiofiles.open(file_path, 'r') as f:
+                    content = await f.read()
+                    data = json.loads(content)
+                    self._whitelists[guild_id] = set(data.get('users', []))
+                count += 1
+            except Exception as e:
+                print(f"Error loading whitelist {file_path}: {e}")
+        
+        self._cache_loaded = True
+        print(f"✅ Cached {count} whitelists in memory")
+    
+    async def _load_whitelist(self, guild_id: int):
+        """Load whitelist from file (fallback if not preloaded)"""
+        file_path = self._get_file_path(guild_id)
+        if file_path.exists():
+            async with aiofiles.open(file_path, 'r') as f:
+                content = await f.read()
+                data = json.loads(content)
+                self._whitelists[guild_id] = set(data.get('users', []))
+    
+    async def _save_whitelist(self, guild_id: int):
+        """Save whitelist to file (async)"""
+        file_path = self._get_file_path(guild_id)
+        async with aiofiles.open(file_path, 'w') as f:
+            content = json.dumps({
+                'users': list(self._whitelists.get(guild_id, set()))
+            }, indent=2)
+            await f.write(content)
+    
+    async def add(self, guild_id: int, user_id: int, moderator_id: int = None):
+        """Add user to guild whitelist"""
+        if guild_id not in self._whitelists:
+            await self._load_whitelist(guild_id)
+            if guild_id not in self._whitelists:
+                self._whitelists[guild_id] = set()
+        
+        self._whitelists[guild_id].add(user_id)
+        await self._save_whitelist(guild_id)
+        
+        
+        change = WhitelistChange(
+            guild_id=guild_id,
+            user_id=user_id,
+            action="added",
+            moderator_id=moderator_id
+        )
+        await self.sdk._trigger_callbacks('whitelist_changed', change)
+    
+    async def remove(self, guild_id: int, user_id: int, moderator_id: int = None):
+        """Remove user from guild whitelist"""
+        if guild_id not in self._whitelists:
+            await self._load_whitelist(guild_id)
+        
+        if guild_id in self._whitelists:
+            self._whitelists[guild_id].discard(user_id)
+            await self._save_whitelist(guild_id)
+            
+            
+            change = WhitelistChange(
+                guild_id=guild_id,
+                user_id=user_id,
+                action="removed",
+                moderator_id=moderator_id
+            )
+            await self.sdk._trigger_callbacks('whitelist_changed', change)
+    
+    async def get_all(self, guild_id: int) -> List[int]:
+        """Get all whitelisted users for guild"""
+        if guild_id not in self._whitelists:
+            await self._load_whitelist(guild_id)
+        return list(self._whitelists.get(guild_id, set()))
+    
+    async def is_whitelisted(self, guild_id: int, user_id: int) -> bool:
+        """
+        Check if user is whitelisted in specific guild.
+        Uses cached data - instant response (no file I/O).
+        """
+        if guild_id not in self._whitelists:
+            await self._load_whitelist(guild_id)
+        
+        return user_id in self._whitelists.get(guild_id, set())
+    
+    async def clear(self, guild_id: int):
+        """Clear all whitelisted users for a guild"""
+        self._whitelists[guild_id] = set()
+        await self._save_whitelist(guild_id)
+

securex/workers/__init__.py

@@ -0,0 +1,8 @@
+"""Workers package - background processing workers"""
+
+from .action_worker import ActionWorker
+from .cleanup_worker import CleanupWorker
+from .log_worker import LogWorker
+from .guild_worker import GuildWorker
+
+__all__ = ['ActionWorker', 'CleanupWorker', 'LogWorker', 'GuildWorker']

securex/workers/action_worker.py

@@ -0,0 +1,115 @@
+"""
+Action Worker - Instant punishment for unauthorized actions
+"""
+import discord
+import asyncio
+
+
+class ActionWorker:
+    """Worker that bans/punishes violators instantly"""
+    
+    def __init__(self, sdk):
+        self.sdk = sdk
+        self.bot = sdk.bot
+        self.action_queue = asyncio.Queue()
+        self._worker_task = None
+        
+        self.action_map = {
+            discord.AuditLogAction.bot_add: "bot_add",
+            discord.AuditLogAction.channel_create: "channel_create",
+            discord.AuditLogAction.channel_delete: "channel_delete",
+            discord.AuditLogAction.channel_update: "channel_update",
+            discord.AuditLogAction.role_create: "role_create",
+            discord.AuditLogAction.role_delete: "role_delete",
+            discord.AuditLogAction.role_update: "role_update",
+            discord.AuditLogAction.kick: "member_kick",
+            discord.AuditLogAction.ban: "member_ban",
+            discord.AuditLogAction.unban: "member_unban",
+            discord.AuditLogAction.member_update: "member_update",
+            discord.AuditLogAction.webhook_create: "webhook_create",
+            discord.AuditLogAction.guild_update: "guild_update",
+        }
+    
+    async def start(self):
+        """Start the action worker"""
+        if self._worker_task is None or self._worker_task.done():
+            self._worker_task = asyncio.create_task(self._worker_loop())
+            print("⚡ Action Worker started")
+    
+    async def stop(self):
+        """Stop the worker"""
+        if self._worker_task:
+            self._worker_task.cancel()
+            self._worker_task = None
+    
+    async def _worker_loop(self):
+        """Main worker loop"""
+        while True:
+            try:
+                entry = await self.action_queue.get()
+                await self._process_entry(entry)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                print(f"Error in action worker: {e}")
+    
+    async def _process_entry(self, entry):
+        """Process audit log entry"""
+        print(f"🔍 [ActionWorker] Processing: {entry.action} by {entry.user.name}")
+        try:
+            guild = entry.guild
+            executor = entry.user
+            
+            if executor.id == self.bot.user.id:
+                return
+            
+            if executor.id == guild.owner_id:
+                return
+            
+            whitelist_set = self.sdk.whitelist_cache.get(guild.id, set())
+            if executor.id in whitelist_set:
+                return
+            
+            guild_punishments = self.sdk.punishment_cache.get(guild.id, self.sdk.punishments)
+            
+            violation_type = self.action_map.get(entry.action)
+            if not violation_type:
+                return
+            
+            punishment_action = guild_punishments.get(violation_type, "none")
+            punishment_result = "none"
+            
+            if violation_type == "bot_add":
+                try:
+                    bot_member = guild.get_member(entry.target.id)
+                    if bot_member:
+                        await bot_member.ban(reason="SecureX: Unauthorized bot addition")
+                        punishment_result = "banned_bot"
+                        print(f"🚀 INSTANT: Banned bot {entry.target.name} (added by {executor.name})")
+                except Exception as e:
+                    print(f"Error banning bot: {e}")
+            
+            if violation_type in ["member_kick", "member_ban", "member_unban", "webhook_create", "guild_update", "member_update"]:
+                try:
+                    await guild.ban(executor, reason=f"SecureX: Unauthorized {violation_type}")
+                    punishment_result = "banned_violator"
+                    print(f"🔨 INSTANT: Banned {executor.name} for {violation_type}")
+                except Exception as e:
+                    print(f"Error banning violator: {e}")
+                
+
+            if punishment_action != "none":
+                try:
+                    punishment_result = await self.sdk.punisher.punish(
+                        guild=guild,
+                        user=executor,
+                        violation_type=violation_type,
+                        details=f"{violation_type} on {getattr(entry.target, 'name', 'Unknown')}",
+                        sdk=self.sdk
+                    )
+                    print(f"👢 {punishment_result.title()} {executor.name} for {violation_type}")
+                except Exception as e:
+                    print(f"Cannot punish {executor.name}: {e}")
+            
+        except Exception as e:
+            print(f"Error processing action entry: {e}")

securex/workers/cleanup_worker.py

@@ -0,0 +1,94 @@
+"""
+Cleanup Worker - Deletes unauthorized creations instantly
+"""
+import discord
+import asyncio
+
+
+class CleanupWorker:
+    """Worker that deletes unauthorized creations (channels, roles, webhooks)"""
+    
+    def __init__(self, sdk):
+        self.sdk = sdk
+        self.bot = sdk.bot
+        self.cleanup_queue = asyncio.Queue()
+        self._worker_task = None
+    
+    async def start(self):
+        """Start the cleanup worker"""
+        if self._worker_task is None or self._worker_task.done():
+            self._worker_task = asyncio.create_task(self._worker_loop())
+            print("🧹 Cleanup Worker started")
+    
+    async def stop(self):
+        """Stop the worker"""
+        if self._worker_task:
+            self._worker_task.cancel()
+            self._worker_task = None
+    
+    async def _worker_loop(self):
+        """Main worker loop"""
+        while True:
+            try:
+                entry = await self.cleanup_queue.get()
+                await self._process_entry(entry)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                print(f"Error in cleanup worker: {e}")
+    
+    async def _process_entry(self, entry):
+        """Process deletion of unauthorized creations"""
+        try:
+            guild = entry.guild
+            executor = entry.user
+            
+            if executor.id == self.bot.user.id:
+                return
+            
+            if executor.id == guild.owner_id:
+                return
+            
+            whitelist_set = self.sdk.whitelist_cache.get(guild.id, set())
+            if executor.id in whitelist_set:
+                return
+            
+            if entry.action not in [
+                discord.AuditLogAction.channel_create,
+                discord.AuditLogAction.role_create,
+                discord.AuditLogAction.webhook_create
+            ]:
+                return
+
+            try:
+                target = entry.target
+                if not target:
+                    return
+
+                if entry.action == discord.AuditLogAction.role_create:
+                    role = guild.get_role(target.id)
+                    if role:
+                        await role.delete(reason="SecureX: Unauthorized role creation")
+                        print(f"🗑️ [Worker] Deleted unauthorized role: {role.name}")
+                
+                elif entry.action == discord.AuditLogAction.channel_create:
+                    channel = guild.get_channel(target.id)
+                    if channel:
+                        await channel.delete(reason="SecureX: Unauthorized channel creation")
+                        print(f"🗑️ [Worker] Deleted unauthorized channel: {channel.name}")
+                
+                elif entry.action == discord.AuditLogAction.webhook_create:
+                    webhooks = await guild.webhooks()
+                    for webhook in webhooks:
+                        if webhook.id == target.id:
+                            await webhook.delete(reason="SecureX: Unauthorized webhook creation")
+                            print(f"🗑️ [Worker] Deleted unauthorized webhook: {webhook.name}")
+                            break
+
+            except (discord.Forbidden, discord.NotFound):
+                pass
+            except Exception as e:
+                print(f"Cleanup error: {e}")
+
+        except Exception as e:
+            print(f"Error processing cleanup entry: {e}")