dc-securex 2.15.3__py3-none-any.whl

securex/handlers/member.py

@@ -0,0 +1,110 @@
+"""
+Member protection handler (bot/ban/kick protection).
+"""
+import discord
+import asyncio
+
+
+class MemberHandler:
+    """Handles member-related protection"""
+    
+    
+    DANGEROUS_PERMISSIONS = frozenset([
+        'administrator',
+        'kick_members',
+        'ban_members',
+        'manage_guild',
+        'manage_roles',
+        'manage_channels',
+        'manage_webhooks',
+        'manage_emojis',
+        'mention_everyone',
+        'manage_expressions'
+    ])
+    
+    def __init__(self, sdk):
+        self.sdk = sdk
+        self.bot = sdk.bot
+        self.whitelist = sdk.whitelist
+    
+    async def _is_authorized(self, guild: discord.Guild, user_id: int) -> bool:
+        """Check if user is authorized"""
+        if guild.owner_id == user_id:
+            return True
+        if user_id == self.bot.user.id:
+            return True
+        return await self.whitelist.is_whitelisted(guild.id, user_id)
+    
+    async def on_member_ban(self, guild: discord.Guild, user: discord.User):
+        """Restore banned victims (punishment handled by action worker)"""
+        try:
+            await asyncio.sleep(0.5)
+            
+            
+            from datetime import datetime, timezone, timedelta
+            cutoff_time = datetime.now(timezone.utc) - timedelta(seconds=30)
+            
+            async for entry in guild.audit_logs(limit=50, action=discord.AuditLogAction.ban):
+                if entry.created_at < cutoff_time:
+                    break
+                    
+                if entry.target.id == user.id:
+                    if not await self._is_authorized(guild, entry.user.id):
+                        
+                        try:
+                            await guild.unban(user, reason="SecureX: Restoring banned member")
+                            print(f"🔄 Unbanned unauthorized member ban: {user.name}")
+                        except (discord.errors.Forbidden, discord.errors.HTTPException):
+                            pass
+                    break
+        except Exception as e:
+            print(f"Error in on_member_ban: {e}")
+
+    async def on_member_update(self, before: discord.Member, after: discord.Member):
+        """Check for dangerous permissions and remove unauthorized roles"""
+        try:
+            
+            if before.roles == after.roles:
+                return
+            
+            guild = after.guild
+            await asyncio.sleep(0.5)
+            
+            
+            from datetime import datetime, timezone, timedelta
+            cutoff_time = datetime.now(timezone.utc) - timedelta(seconds=30)
+            
+            async for entry in guild.audit_logs(limit=50, action=discord.AuditLogAction.member_role_update):
+                if entry.created_at < cutoff_time:
+                    break
+                if entry.target.id == after.id:
+                    
+                    is_authorized = await self._is_authorized(guild, entry.user.id)
+                    
+                    if not is_authorized:
+                        
+                        dangerous_roles = []
+                        
+                        for role in after.roles:
+                            if role.is_default():  
+                                continue
+                            
+                            
+                            permissions = role.permissions
+                            for perm_name in self.DANGEROUS_PERMISSIONS:
+                                if getattr(permissions, perm_name, False):
+                                    dangerous_roles.append(role)
+                                    break  
+                        
+                        
+                        if dangerous_roles:
+                            try:
+                                await after.remove_roles(*dangerous_roles, reason="SecureX: Removed dangerous roles (unauthorized update)")
+                                role_names = ", ".join([r.name for r in dangerous_roles])
+                                print(f"🛡️ Bulk removed {len(dangerous_roles)} dangerous role(s) from {after.name}: {role_names}")
+                            except (discord.errors.Forbidden, discord.errors.HTTPException) as e:
+                                print(f"⚠️ Failed to remove roles: {e}")
+                    
+                    break
+        except Exception as e:
+            print(f"Error in on_member_update: {e}")

securex/handlers/role.py

@@ -0,0 +1,74 @@
+"""
+Role protection handler for SecureX SDK.
+"""
+import discord
+import asyncio
+from datetime import datetime, timedelta
+
+
+class RoleHandler:
+    """Handles role protection logic"""
+    
+    def __init__(self, sdk):
+        self.sdk = sdk
+        self.bot = sdk.bot
+        self.backup_manager = sdk.backup_manager
+        self.whitelist = sdk.whitelist
+    
+    async def _is_authorized(self, guild: discord.Guild, user_id: int) -> bool:
+        """Check if user is authorized"""
+        if guild.owner_id == user_id:
+            return True
+        if user_id == self.bot.user.id:
+            return True
+        return await self.whitelist.is_whitelisted(guild.id, user_id)
+    
+
+    async def on_role_delete(self, role: discord.Role):
+        """Restore unauthorized role deletions"""
+        try:
+            guild = role.guild
+            await asyncio.sleep(1)
+            
+            
+            from datetime import timezone
+            cutoff_time = datetime.now(timezone.utc) - timedelta(seconds=30)
+            
+            async for entry in guild.audit_logs(limit=50, action=discord.AuditLogAction.role_delete):
+                if entry.created_at < cutoff_time:
+                    break
+                    
+                if entry.target.id == role.id:
+                    if not await self._is_authorized(guild, entry.user.id):
+                        if await self.backup_manager.restore_role(guild, role.id):
+                            print(f"🔄 Restored unauthorized role deletion: {role.name}")
+                    break
+        except Exception:
+            pass
+    
+    async def on_role_update(self, before: discord.Role, after: discord.Role):
+        """Restore unauthorized role permission changes"""
+        try:
+            
+            if before.position == after.position and before.permissions == after.permissions:
+                return
+            
+            guild = after.guild
+            await asyncio.sleep(0.3)
+            
+            
+            from datetime import timezone
+            cutoff_time = datetime.now(timezone.utc) - timedelta(seconds=30)
+            
+            async for entry in guild.audit_logs(limit=50, oldest_first=False):
+                if entry.created_at < cutoff_time:
+                    break
+                    
+                if entry.action == discord.AuditLogAction.role_update:
+                    if entry.target.id == after.id:
+                        if not await self._is_authorized(guild, entry.user.id):
+                            if await self.backup_manager.restore_role_permissions(guild, after.id):
+                                print(f"🔄 Restored unauthorized role update: {after.name}")
+                        break
+        except Exception:
+            pass

securex/models.py

@@ -0,0 +1,123 @@
+"""
+Data models for SecureX SDK.
+These objects are returned to developers - no UI included.
+"""
+from dataclasses import dataclass, asdict, field
+from datetime import datetime
+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=datetime.utcnow)
+    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=datetime.utcnow)
+    moderator_id: Optional[int] = None
+    
+    def to_dict(self) -> dict:
+        """Convert to dictionary"""
+        data = asdict(self)
+        data['timestamp'] = self.timestamp.isoformat()
+        return data

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)
+