diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..03f9124 --- /dev/null +++ b/.env.example @@ -0,0 +1,9 @@ +# Discord Configuration +DISCORD_TOKEN=votre_token_discord +APPLICATION_ID=votre_id_application + +# API Configuration +API_HOST=127.0.0.1 +API_PORT=5000 +API_DEBUG=False +API_SECRET_KEY=votre-cle-secrete-api diff --git a/.gitignore b/.gitignore index 813ff0f..4cd1530 100755 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,6 @@ env/ # Logs *.Logs .data + +# Documentation +# BOT_DOCUMENTATION.md diff --git a/BOT_DOCUMENTATION.md b/BOT_DOCUMENTATION.md new file mode 100644 index 0000000..c3856c0 --- /dev/null +++ b/BOT_DOCUMENTATION.md @@ -0,0 +1,412 @@ +# Documentation du Bot Kuby + +## Table des matières +1. [Présentation générale](#présentation-générale) +2. [Architecture du bot](#architecture-du-bot) +3. [Installation et configuration](#installation-et-configuration) +4. [Modules et fonctionnalités](#modules-et-fonctionnalités) +5. [Système de sécurité](#système-de-sécurité) +6. [Gestion des tickets](#gestion-des-tickets) +7. [Système de logs](#système-de-logs) +8. [API REST](#api-rest) +9. [Commandes disponibles](#commandes-disponibles) +10. [Base de données](#base-de-données) +11. [Dépannage](#dépannage) + +--- + +## Présentation générale + +Kuby est un bot Discord multifonctionnel développé en Python utilisant la bibliothèque `discord.py`. Il est conçu pour offrir une gestion complète de serveur Discord avec des fonctionnalités de modération, sécurité, gestion de tickets, et bien plus encore. + +### Caractéristiques principales +- **Système de whitelist** pour contrôler l'accès aux commandes +- **Gestion de tickets** avancée avec permissions configurables +- **Système de sécurité** anti-spam et anti-raid +- **Logs détaillés** des activités du serveur +- **Messages de bienvenue/départ** personnalisables +- **Modération** avec blacklist et scan de sécurité +- **Système de rôles automatique** pour les membres rejoignant +- **API REST** pour intégration externe et monitoring + +--- + +## Architecture du bot + +### Fichiers principaux + +#### `kuby.py` - Point d'entrée +- Charge les variables d'environnement +- Initialise et démarre le bot +- Gère les erreurs critiques de démarrage + +#### `bot.py` - Classe principale du bot +- Définit la classe `MyBot` héritant de `commands.Bot` +- Configure les intents Discord +- Charge toutes les extensions/modules +- Implémente les événements Discord principaux + +### Structure des dossiers + +``` +kuby/ +├── bot.py # Classe principale du bot +├── kuby.py # Point d'entrée +├── commandes/ # Modules de commandes +│ ├── ticket/ # Système de tickets +│ ├── modules_security/ # Modules de sécurité +│ ├── whitelist.py # Gestion whitelist +│ ├── blacklist.py # Gestion blacklist +│ └── ... +├── src/ # Utilitaires et core +│ ├── api/ # API REST module +│ │ ├── app.py # Application Flask +│ │ ├── routes.py # Routes API +│ │ └── config.py # Configuration API +│ ├── logger.py # Système de logging +│ └── advanced_logger.py # Logs avancés +├── data/ # Données de configuration +├── utils/ # Fonctions utilitaires +└── requirements.txt # Dépendances Python +``` + +--- + +## Installation et configuration + +### Prérequis +- Python 3.8+ +- Un token de bot Discord + +### Installation +1. Cloner le repository +2. Installer les dépendances : + ```bash + pip install -r requirements.txt + ``` + +### Configuration +Créer un fichier `.env` avec les variables suivantes : +```env +# Discord Configuration +DISCORD_TOKEN=votre_token_discord +APPLICATION_ID=votre_id_application + +# API Configuration +API_HOST=127.0.0.1 +API_PORT=5000 +API_DEBUG=False +API_SECRET_KEY=votre-cle-secrete-api + +# Partner Server IDs (for API) +PARTNER_IDS=111111111111111111,222222222222222222,333333333333333333 +``` + +### Dépendances principales +- `discord.py>=2.3.0` - API Discord +- `python-dotenv>=1.0.0` - Gestion variables d'environnement +- `Pillow>=10.0.0` - Traitement d'images +- `aiohttp>=3.8.0` - Requêtes HTTP asynchrones +- `flask>=2.3.0` - Framework API REST +- `flask-cors>=4.0.0` - Support CORS pour l'API + +--- + +## Modules et fonctionnalités + +### 1. Système de Whitelist (`whitelist.py`, `whitelist_monitor.py`) +- **Fonction** : Contrôle l'accès aux commandes du bot +- **Mécanisme** : Vérification globale avant l'exécution de toute commande +- **Exceptions** : + - Propriétaire du bot (bypass automatique) + - Utilisateurs avec permissions tickets pour commandes spécifiques + +### 2. Messages de bienvenue/départ (`welcome.py`, `goodbye.py`) +- **Fonctionnalités** : + - Messages personnalisables avec images + - Templates de bannières + - Support de polices personnalisées + - Restauration automatique des rôles + +### 3. Système de sécurité (`security.py`) +- **Scan de sécurité** : Analyse des comptes suspects +- **Gestion des menaces** : Actions automatiques configurables +- **Logs de sécurité** : Traçabilité des incidents + +### 4. Modules de sécurité avancés (`modules_security/`) +- **Anti-spam** : Détection et blocage des spams +- **Anti-raid** : Protection contre les raids massifs +- **Logs manager** : Gestion centralisée des logs +- **Rules** : Gestion des règles du serveur + +### 5. Gestion des tickets (`ticket/`) +- **Création de tickets** : Interface complète pour les utilisateurs +- **Permissions** : Système granulaire d'accès +- **Configuration** : Paramètres par serveur +- **Support** : Outils de modération intégrés + +--- + +## Système de sécurité + +### Niveaux de protection +1. **Whitelist globale** : Contrôle d'accès aux commandes +2. **Anti-spam** : Détection de messages répétitifs +3. **Anti-raid** : Protection contre les arrivées massives +4. **Scan de sécurité** : Analyse des comptes suspects +5. **Blacklist** : Bannissement automatique + +### Configuration de sécurité +- Paramètres stockés par serveur +- Actions configurables (kick, ban, avertissement) +- Logs détaillés pour audit + +--- + +## Gestion des tickets + +### Fonctionnalités +- **Création** : Interface utilisateur simple +- **Catégories** : Organisation par type de demande +- **Permissions** : Accès contrôlé par rôles +- **Transcription** : Sauvegarde des conversations +- **Statistiques** : Suivi des tickets + +### Configuration +```python +# Exemple de configuration ticket +config = { + "category_id": 123456789, + "support_role_id": 987654321, + "log_channel_id": 555666777, + "transcript_channel_id": 888999000 +} +``` + +--- + +## API REST + +Le bot Kuby inclut une API REST basée sur Flask qui permet d'accéder à certaines fonctionnalités du bot via des requêtes HTTP. + +### Configuration de l'API + +L'API se configure via les variables d'environnement : +- `API_HOST` : Adresse d'écoute (défaut: 127.0.0.1) +- `API_PORT` : Port d'écoute (défaut: 5000) +- `API_DEBUG` : Mode debug (défaut: False) +- `API_SECRET_KEY` : Clé secrète pour la sécurité + +### Endpoints disponibles + +#### `GET /api/user/` +Retourne les informations d'un utilisateur Discord. + +**Réponse :** +```json +{ + "username": "Nom d'utilisateur", + "avatar_url": "https://cdn.discordapp.com/avatars/user_id/avatar.png" +} +``` + +#### `GET /api/partners` +Retourne la liste des serveurs partenaires configurés. + +**Réponse :** +```json +[ + { + "name": "Nom du serveur", + "icon_url": "https://cdn.discordapp.com/icons/guild_id/icon.png", + "member_count": 150 + } +] +``` + +#### `GET /api/status` +Retourne le statut actuel du bot. + +**Réponse :** +```json +{ + "status": "online", + "username": "Kuby", + "guild_count": 5, + "total_members": 1250 +} +``` + +#### `GET /api/guilds` +Retourne la liste des serveurs où le bot est présent. + +**Réponse :** +```json +[ + { + "id": 123456789, + "name": "Serveur Discord", + "icon_url": "https://cdn.discordapp.com/icons/guild_id/icon.png", + "member_count": 250, + "owner_id": 987654321 + } +] +``` + +### Utilisation + +L'API démarre automatiquement avec le bot et est accessible sur `http://127.0.0.1:5000` par défaut. + +**Exemple d'utilisation :** +```bash +# Obtenir les infos d'un utilisateur +curl http://127.0.0.1:5000/api/user/123456789 + +# Obtenir le statut du bot +curl http://127.0.0.1:5000/api/status +``` + +### Sécurité + +- L'API utilise CORS pour permettre les requêtes cross-origin +- Les logs d'accès sont enregistrés via le système de logging du bot +- L'API s'exécute dans un thread séparé pour ne pas bloquer le bot Discord + +--- + +## Système de logs + +### Types de logs +1. **Logs standards** (`kuby_logs.log`) : Activités générales +2. **Audit logs** (`kuby_audit.log`) : Actions de modération +3. **Error logs** (`kuby_errors.log`) : Erreurs et exceptions +4. **Performance logs** : Métriques de performance + +### Fonctionnalités avancées +- **Advanced Logger** : Suivi détaillé des événements +- **Restauration de rôles** : Mémorisation des rôles des membres +- **Notifications** : Messages de départ/arrivée +- **Voice tracking** : Suivi des salons vocaux + +--- + +## Commandes disponibles + +### Commandes de modération +- `!whitelist` : Gestion de la whitelist +- `!blacklist` : Gestion de la blacklist +- `!scan` : Analyse de sécurité +- `!security` : Configuration sécurité + +### Commandes de tickets +- `!ticket` : Gestion des tickets +- `!ticketconfig` : Configuration du système +- `!ticketsetup` : Initialisation rapide + +### Commandes utilitaires +- `!snipe` : Récupération de messages supprimés +- `!bug_report` : Rapport de bugs +- `!sendbotmessages` : Messages automatisés + +### Commandes de configuration +- `!welcome` : Messages de bienvenue +- `!goodbye` : Messages de départ +- `!nolink` : Filtrage des liens + +--- + +## Base de données + +### Fichiers de données +- `config.db` : Configuration principale (SQLite) +- `whitelist.json` : Liste des utilisateurs autorisés +- Données par serveur dans le dossier `data/` + +### Structure de la base de données +```sql +-- Tables principales +- guilds : Configuration par serveur +- users : Données utilisateurs +- tickets : Historique des tickets +- audit_logs : Logs de modération +``` + +--- + +## Dépannage + +### Problèmes courants + +#### Token Discord invalide +``` +❌ Erreur: Token Discord non trouvé +``` +**Solution** : Vérifier le fichier `.env` et le token Discord + +#### Extensions non chargées +``` +❌ Erreur lors du chargement de l'extension +``` +**Solution** : Vérifier les imports et la syntaxe dans les modules + +#### Permissions manquantes +``` +❌ Vous n'êtes pas autorisé à utiliser cette commande +``` +**Solution** : Ajouter l'utilisateur à la whitelist ou vérifier les permissions + +### Logs utiles pour le dépannage +- `kuby_errors.log` : Erreurs détaillées avec stack traces +- `debug.log` : Informations de débogage +- Console output : Logs en temps réel + +### Commandes de maintenance +```python +# Redémarrage du bot +!restart + +# Vérification du statut +!status + +# Rechargement des modules +!reload +``` + +--- + +## Bonnes pratiques + +### Sécurité +- Garder le token Discord secret +- Utiliser la whitelist pour limiter l'accès +- Configurer correctement les permissions +- Surveiller régulièrement les logs + +### Performance +- Limiter le nombre de commandes simultanées +- Optimiser les requêtes base de données +- Utiliser le cache pour les données fréquemment accédées +- Surveiller l'utilisation mémoire + +### Maintenance +- Sauvegarder régulièrement la base de données +- Mettre à jour les dépendances +- Nettoyer les anciens logs +- Documenter les modifications + +--- + +## Support et développement + +### Pour obtenir de l'aide +1. Consulter les logs d'erreurs +2. Vérifier la configuration +3. Tester avec des commandes simples +4. Contacter le développeur si nécessaire + +### Contributeurs +Le bot Kuby est développé avec une architecture modulaire pour faciliter l'ajout de nouvelles fonctionnalités. Chaque module est indépendant et peut être maintenu séparément. + +--- + +*Document généré automatiquement - Dernière mise à jour : 2025* diff --git a/bot.py b/bot.py index fde07e6..b6936c6 100755 --- a/bot.py +++ b/bot.py @@ -47,6 +47,19 @@ class MyBot(commands.Bot): self.advanced_logger = AdvancedLogger(self) kuby_logger.info("✅ Advanced logger initialized") + # Initialize API Manager + from src.api.app import APIManager + self.api_manager = APIManager(self) + kuby_logger.info("✅ API Manager initialized") + + # Start API server + try: + self.api_manager.run_async() + kuby_logger.info(f"🌐 API server started on http://{self.api_manager.config.HOST}:{self.api_manager.config.PORT}") + except Exception as e: + kuby_logger.error(f"❌ Erreur lors du démarrage de l'API : {e}", exc_info=True) + + # Charger les extensions extensions = [ "commandes.whitelist", diff --git a/requirements.txt b/requirements.txt index d4e9a44..d78758c 100755 --- a/requirements.txt +++ b/requirements.txt @@ -2,3 +2,5 @@ discord.py>=2.3.0 python-dotenv>=1.0.0 Pillow>=10.0.0 aiohttp>=3.8.0 +flask>=2.3.0 +flask-cors>=4.0.0 diff --git a/src/api/__init__.py b/src/api/__init__.py new file mode 100644 index 0000000..2c3a71d --- /dev/null +++ b/src/api/__init__.py @@ -0,0 +1,9 @@ +""" +API module for Kuby Discord bot +Provides REST API endpoints for bot functionality +""" + +from .app import APIManager +from .config import APIConfig + +__all__ = ['APIManager', 'APIConfig'] diff --git a/src/api/app.py b/src/api/app.py new file mode 100644 index 0000000..6b770ac --- /dev/null +++ b/src/api/app.py @@ -0,0 +1,56 @@ +""" +Flask application for Kuby Discord bot API +""" + +from flask import Flask +from flask_cors import CORS +import threading +from .routes import setup_routes +from .config import APIConfig +from src.logger import kuby_logger + + +class APIManager: + """Manages the Flask API server for the bot""" + + def __init__(self, bot_instance): + """Initialize the API manager + + Args: + bot_instance: The Discord bot instance + """ + self.bot = bot_instance + self.app = Flask(__name__) + CORS(self.app) + self.config = APIConfig() + + # Configuration Flask + self.app.config['SECRET_KEY'] = self.config.SECRET_KEY + self.app.config['JSON_SORT_KEYS'] = False + + # Setup routes + setup_routes(self.app, self.bot) + + kuby_logger.info("✅ API Manager initialized") + + def run_async(self): + """Start the API server in a separate thread""" + try: + kuby_logger.info(f"🌐 Starting API server on {self.config.HOST}:{self.config.PORT}") + threading.Thread( + target=lambda: self.app.run( + host=self.config.HOST, + port=self.config.PORT, + debug=self.config.DEBUG, + use_reloader=False # Important: disable reloader in thread + ), + daemon=True + ).start() + kuby_logger.info(f"✅ API server started successfully") + except Exception as e: + kuby_logger.error(f"❌ Failed to start API server: {e}") + raise + + def get_app(self): + """Get the Flask app instance (for testing purposes)""" + return self.app diff --git a/src/api/config.py b/src/api/config.py new file mode 100644 index 0000000..df42c5a --- /dev/null +++ b/src/api/config.py @@ -0,0 +1,15 @@ +""" +Configuration for the API module +""" + +import os +from dotenv import load_dotenv + +load_dotenv() + +class APIConfig: + """API configuration class""" + HOST = os.getenv("API_HOST", "127.0.0.1") + PORT = int(os.getenv("API_PORT", 5000)) + DEBUG = os.getenv("API_DEBUG", "False").lower() == "true" + SECRET_KEY = os.getenv("API_SECRET_KEY", "votre-cle-secrete-api") diff --git a/src/api/routes.py b/src/api/routes.py new file mode 100644 index 0000000..64755fe --- /dev/null +++ b/src/api/routes.py @@ -0,0 +1,97 @@ +""" +API routes for Kuby Discord bot +""" + +from flask import jsonify + + +def setup_routes(app, bot): + """Setup all API routes""" + + @app.route("/api/user/") + def get_user(user_id): + """Get user information by ID""" + user = bot.get_user(user_id) + if not user: + return jsonify({ + "username": "Utilisateur inconnu", + "avatar_url": "https://cdn.discordapp.com/embed/avatars/0.png", + }) + return jsonify({ + "username": user.display_name, + "avatar_url": str(user.display_avatar.url) if user.display_avatar else "https://cdn.discordapp.com/embed/avatars/0.png", + }) + + @app.route("/api/guilds") + def get_guilds(): + """Get all guilds where the bot is present""" + guilds_info = [] + for guild in bot.guilds: + guilds_info.append({ + "id": guild.id, + "name": guild.name, + "icon_url": guild.icon.url if guild.icon else None, + "member_count": guild.member_count, + "owner_id": guild.owner_id, + "description": guild.description if guild.description else None, + "features": list(guild.features) if guild.features else [], + "created_at": guild.created_at.isoformat() if guild.created_at else None + }) + return jsonify(guilds_info) + + @app.route("/api/guild/") + def get_guild(guild_id): + """Get specific guild information by ID""" + guild = bot.get_guild(guild_id) + if not guild: + return jsonify({"error": "Serveur non trouvé"}), 404 + + return jsonify({ + "id": guild.id, + "name": guild.name, + "icon_url": guild.icon.url if guild.icon else None, + "member_count": guild.member_count, + "owner_id": guild.owner_id, + "description": guild.description if guild.description else None, + "features": list(guild.features) if guild.features else [], + "created_at": guild.created_at.isoformat() if guild.created_at else None, + # "channels": [ + # { + # "id": channel.id, + # "name": channel.name, + # "type": str(channel.type), + # "category": channel.category.name if channel.category else None + # } + # for channel in guild.channels + # ], + # "roles": [ + # { + # "id": role.id, + # "name": role.name, + # "color": role.color, + # "position": role.position, + # "member_count": len(role.members) + # } + # for role in guild.roles + # ] + }) + + @app.route("/api/status") + def get_status(): + """Get bot status and basic information""" + return jsonify({ + "status": "online" if bot.is_ready() else "connecting", + "username": bot.user.name if bot.user else "Unknown", + "user_id": bot.user.id if bot.user else None, + "guild_count": len(bot.guilds), + "total_members": sum(guild.member_count for guild in bot.guilds) if bot.guilds else 0, + # "total_channels": sum(len(guild.channels) for guild in bot.guilds) if bot.guilds else 0, + "uptime": "N/A", # TODO: Implement uptime tracking + "version": "2.0.0", + "api_endpoints": [ + "/api/user/", + "/api/guilds", + "/api/guild/", + "/api/status" + ] + })