From 59e738c0d4fb88eabc0fb325ccb60e1f10fdaaf0 Mon Sep 17 00:00:00 2001 From: Mathis Date: Thu, 1 Jan 2026 20:19:45 +0100 Subject: [PATCH] =?UTF-8?q?Mise=20=C3=A0=20jour=20de=20la=20documentation?= =?UTF-8?q?=20de=20Kuby=20(README.md)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 653 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 402 insertions(+), 251 deletions(-) diff --git a/README.md b/README.md index 290c244..a7084a0 100755 --- a/README.md +++ b/README.md @@ -1,256 +1,407 @@ -# 🤖 Kuby Discord Bot +# 🤖 Kuby - Bot Discord Multi-Fonctions -Un bot Discord avancé et sécurisé développé en Python avec discord.py, conçu pour la gestion de serveurs et l'automatisation. - -## 📋 Table des matières - -- [🤖 Kuby Discord Bot](#-kuby-discord-bot) - - [📋 Table des matières](#-table-des-matières) - - [🚀 Fonctionnalités](#-fonctionnalités) - - [⚙️ Installation](#️-installation) - - [🔧 Configuration](#-configuration) - - [📁 Structure du projet](#-structure-du-projet) - - [🎯 Utilisation](#-utilisation) - - [🛡️ Sécurité](#️-sécurité) - - [🔍 Logging](#-logging) - - [🐛 Dépannage](#-dépannage) - - [🤝 Contribution](#-contribution) - - [📄 Licence](#-licence) - -## 🚀 Fonctionnalités - -### ✅ Fonctionnalités principales -- **Système de whitelist** : Contrôle d'accès basé sur une liste blanche -- **Logs avancés** : Suivi détaillé de toutes les activités du serveur -- **Système de bienvenue/au revoir** : Messages personnalisés pour les arrivées/départs -- **Sécurité renforcée** : Protection contre les raids et les utilisateurs malveillants -- **Commandes de modération** : Outils complets pour les modérateurs -- **Sauvegardes automatiques** : Backup régulier des données importantes - -### 🎮 Commandes disponibles -| Commande | Description | Usage | -|----------|-------------|--------| -| `!whitelist add @user` | Ajoute un utilisateur à la whitelist | `!whitelist add @Kuby` | -| `!whitelist remove @user` | Retire un utilisateur de la whitelist | `!whitelist remove @Kuby` | -| `!whitelist list` | Liste tous les utilisateurs whitelistés | `!whitelist list` | -| `!setwelcome #channel` | Définit le canal de bienvenue | `!setwelcome #bienvenue` | -| `!setgoodbye #channel` | Définit le canal d'au revoir | `!setgoodbye #depart` | -| `!security settings` | Affiche les paramètres de sécurité | `!security settings` | -| `!snipe` | Récupère le dernier message supprimé | `!snipe` | -| `!fun meme` | Envoie un meme aléatoire | `!fun meme` | - -## ⚙️ Installation - -### Prérequis -- Python 3.8 ou supérieur -- Un compte Discord avec des permissions d'administrateur -- Un serveur Discord pour tester le bot - -### Étapes d'installation - -1. **Cloner le repository** - ```bash - git clone [URL_DU_REPO] - cd kuby-bot - ``` - -2. **Créer un environnement virtuel** - ```bash - python -m venv venv - - # Windows - venv\Scripts\activate - - # Linux/Mac - source venv/bin/activate - ``` - -3. **Installer les dépendances** - ```bash - pip install -r requirements.txt - ``` - -4. **Créer le fichier .env** - ```bash - cp .env.example .env - ``` - -5. **Configurer les variables d'environnement** - Éditer le fichier `.env` avec vos informations : - ``` - DISCORD_TOKEN=VOTRE_TOKEN_BOT - APPLICATION_ID=VOTRE_APPLICATION_ID - ``` - -6. **Lancer le bot** - ```bash - python bot.py - ``` - -## 🔧 Configuration - -### Fichier .env -```env -# Token du bot Discord (obligatoire) -DISCORD_TOKEN=your_bot_token_here - -# ID de l'application Discord (optionnel mais recommandé) -APPLICATION_ID=your_application_id_here - -# Configuration du logging -LOG_LEVEL=INFO -LOG_FILE_MAX_SIZE=10MB -LOG_BACKUP_COUNT=5 -``` - -### Permissions Discord requises -- **Administrator** : Pour une gestion complète du serveur -- **Manage Server** : Pour modifier les paramètres du serveur -- **Manage Channels** : Pour créer/modifier les canaux -- **Manage Roles** : Pour gérer les rôles -- **Kick Members** : Pour expulser des membres -- **Ban Members** : Pour bannir des membres -- **Read Messages** : Pour lire les messages -- **Send Messages** : Pour envoyer des messages -- **Embed Links** : Pour envoyer des embeds -- **Attach Files** : Pour envoyer des fichiers -- **Add Reactions** : Pour ajouter des réactions - -## 📁 Structure du projet - -``` -kuby-bot/ -├── bot.py # Point d'entrée principal du bot -├── kuby.py # Classe principale MyBot avec événements -├── requirements.txt # Dépendances Python -├── .env # Variables d'environnement (non versionné) -├── .gitignore # Fichiers à ignorer par Git -├── README.md # Ce fichier -├── data/ # Dossier pour les données -│ ├── security_settings.json # Paramètres de sécurité -│ ├── logs/ # Fichiers de logs -│ └── member_logs/ # Logs des membres -├── commandes/ # Extensions (cogs) du bot -│ ├── __init__.py -│ ├── whitelist.py # Gestion de la whitelist -│ ├── whitelist_monitor.py # Surveillance de la whitelist -│ ├── security.py # Commandes de sécurité -│ ├── fun.py # Commandes amusantes -│ ├── snipe.py # Récupération de messages -│ ├── sendbotmessages.py # Envoi de messages via le bot -│ ├── setwelcomechannel.py # Configuration canal bienvenue -│ ├── setgoodbyechannel.py # Configuration canal au revoir -│ └── whitelist_monitor.py # Monitoring de la whitelist -├── src/ # Code source utilitaire -│ ├── logger.py # Configuration du logging -│ └── advanced_logger.py # Logger avancé avec fonctionnalités -└── utils/ # Utilitaires divers -``` - -## 🎯 Utilisation - -### Premier démarrage -1. Invitez le bot sur votre serveur avec les permissions appropriées -2. Configurez le canal de bienvenue avec `!setwelcome #channel` -3. Configurez le canal d'au revoir avec `!setgoodbye #channel` -4. Ajoutez les modérateurs à la whitelist avec `!whitelist add @modérateur` - -### Configuration de la sécurité -```bash -# Activer la surveillance de la whitelist -!security enable - -# Voir les paramètres actuels -!security settings - -# Configurer les notifications -!security notifications #channel -``` - -## 🛡️ Sécurité - -### Système de whitelist -Le bot utilise un système de liste blanche pour contrôler l'accès aux commandes : -- Seuls les utilisateurs whitelistés peuvent utiliser les commandes -- Les administrateurs du serveur sont automatiquement whitelistés -- Les modifications de la whitelist sont loguées - -### Protection contre les raids -- Détection automatique des arrivées massives -- Notifications aux administrateurs -- Actions automatiques possibles (kick, ban) - -### Logs de sécurité -Toutes les actions importantes sont enregistrées : -- Connexions/déconnexions -- Modifications de la whitelist -- Arrivées/départs de membres -- Suppressions de messages -- Modifications de rôles - -## 🔍 Logging - -### Niveaux de logs -- **DEBUG** : Informations détaillées pour le développement -- **INFO** : Informations générales sur le fonctionnement -- **WARNING** : Avertissements sur des comportements potentiellement problématiques -- **ERROR** : Erreurs qui n'empêchent pas le fonctionnement -- **CRITICAL** : Erreurs graves qui nécessitent une intervention - -### Fichiers de logs -Les logs sont stockés dans `data/logs/` avec rotation automatique : -- `kuby.log` : Logs principaux -- `security.log` : Logs de sécurité -- `commands.log` : Logs des commandes - -## 🐛 Dépannage - -### Problèmes courants - -#### "Bot ne se connecte pas" -1. Vérifiez le token dans `.env` -2. Assurez-vous que le bot a les bonnes permissions -3. Vérifiez la connexion Internet - -#### "Commandes ne fonctionnent pas" -1. Vérifiez que l'utilisateur est whitelisté -2. Vérifiez les permissions du bot -3. Consultez les logs pour les erreurs - -#### "Erreur de permissions" -1. Vérifiez que le bot a le rôle approprié -2. Vérifiez la hiérarchie des rôles -3. Assurez-vous que le bot est au-dessus des rôles à gérer - -### Commandes de debug -```bash -# Vérifier l'état du bot -!ping - -# Voir les logs récents -!logs recent - -# Vérifier la configuration -!config check -``` - -## 🤝 Contribution - -### Rapport de bugs -Pour signaler un bug : -1. Vérifiez les issues existantes -2. Créez une nouvelle issue avec : - - Description détaillée - - Étapes pour reproduire - - Logs pertinents - - Environnement (Python version, discord.py version) - -## 📄 Licence - -Ce projet est sous licence MIT. Voir le fichier `LICENSE` pour plus de détails. +Kuby est un bot Discord complet développé en Python avec `discord.py`. Il offre une suite complète d'outils de modération, de sécurité, de sauvegarde et de gestion communautaire. --- -**Développé avec Lowei et Gameur ❤️ par l'équipe Omega Kube** +## 📋 Table des Matières + +1. [✨ Fonctionnalités](#-fonctionnalités) +2. [🛠️ Installation](#️-installation) +3. [⚙️ Configuration](#️-configuration) +4. [📖 Commandes](#-commandes) +5. [🏗️ Architecture](#️-architecture) +6. [🔐 Système de Permissions](#-système-de-permissions) +7. [📊 Système de Logs](#-système-de-logs) +8. [🧪 Tests](#-tests) + +--- + +## ✨ Fonctionnalités + +### 🛡️ Sécurité +- **Anti-Raid** : Protection contre les attaques de raid +- **Anti-Spam** : Détection et sanction du spam (5 msgs/5s par défaut) +- **Anti-Link** : Blocage des liens non autorisés (discord.gg, http, https, www) +- **Anti-Mention** : Protection contre les mentions abusives +- **Anti-Nuke** : Protection contre la suppression massive de salons/ rôles + +### 💾 Sauvegardes +- **Backup Complet** : Sauvegarde rôles, catégories, salons, membres +- **Export des Messages** : Option pour inclure l'historique des messages +- **Archives ZIP** : Fichiers compressés pour faciliter le stockage + +### 🎫 Système de Tickets +- Création de tickets via bouton interactif +- Gestion des permissions par rôle staff +- Logs des actions +- Réouverture et suppression + +### 👋 Bienvenue / Au Revoir +- Images de bienvenue personnalisées avec avatar +- Messages DM automatisés +- Images d'au revoir avec temps de présence + +### 📝 Logs & Monitoring +- Logs des événements membres (join/leave) +- Logs des messages (édit/ suppression) +- Logs vocaux (connexion/ déconnection) +- Restauration des rôles à la reconnexion + +### 🔒 Gestion des Utilisateurs +- **Whitelist** : Liste d'utilisateurs autorisés à utiliser les commandes sensibles +- **Blacklist Réseau** : Système de blacklist global pour tous les serveurs partenaires + +### 🎮 Commandes Fun +- Commandes variées pour animer le serveur + +--- + +## 🛠️ Installation + +### Prérequis + +- Python 3.10 ou supérieur +- pip (gestionnaire de paquets Python) + +### 1. Cloner le Repository + +```bash +git clone +cd backup_kuby +``` + +### 2. Créer un Environnement Virtuel (Recommandé) + +```bash +python -m venv venv +source venv/bin/activate # Linux/Mac +# ou +.\venv\Scripts\activate # Windows +``` + +### 3. Installer les Dépendances + +```bash +pip install -r requirements.txt +``` + +Les dépendances incluent : +- `discord.py>=2.3.0` - Framework Discord +- `python-dotenv>=1.0.0` - Variables d'environnement +- `PIL` - Traitement d'images (pour les images de bienvenue) +- `aiohttp` - Requêtes HTTP asynchrones + +--- + +## ⚙️ Configuration + +### 1. Créer un Fichier `.env` + +Créez un fichier `.env` à la racine du projet avec le contenu suivant : + +```env +# Token de votre bot Discord +DISCORD_TOKEN=your_bot_token_here + +# ID de l'application Discord (optionnel) +APPLICATION_ID=your_application_id_here +``` + +### 2. Obtenir le Token du Bot + +1. Allez sur le [Discord Developer Portal](https://discord.com/developers/applications) +2. Créez une nouvelle application +3. Allez dans l'onglet "Bot" +4. Créez un bot et copiez le token +5. Activez les intents nécessaires : + - `SERVER MEMBERS INTENT` + - `MESSAGE CONTENT INTENT` + - `VOICE STATES` + +### 3. Inviter le Bot sur votre Serveur + +Générez un lien d'invitation avec les permissions suivantes : +- `Administrator` (recommandé pour toutes les fonctionnalités) + +--- + +## 📖 Commandes + +### 🔐 Sécurité + +| Commande | Description | +|----------|-------------| +| `/security` | Ouvrir le panneau de configuration de sécurité | + +Le panneau de sécurité permet de configurer : +- **Anti-Raid** : Protection contre les raids +- **Anti-Spam** : Bloque le spam excessif +- **Anti-Link** : Interdit les liens non autorisés +- **Anti-Mention** : Protection contre les mentions de masse +- **Anti-Nuke** : Protection contre la suppression de salons/rôles +- **Logs** : Activer/désactiver les logs + +### 💾 Sauvegardes + +| Commande | Description | +|----------|-------------| +| `/backup create` | Créer une sauvegarde complète du serveur | +| `/backup list` | Lister les sauvegardes disponibles | + +Options pour `/backup create` : +- `save_messages` : Inclure les messages (défaut: True) +- `privacy_notice` : Afficher un avertissement public (défaut: True) +- `message_limit_per_channel` : Limite de messages par salon (défaut: 10000) + +### 🎫 Tickets + +| Commande | Description | +|----------|-------------| +| `/ticket setup` | Configurer le système de tickets | +| `/ticket panel [channel]` | Créer un panneau de création de tickets | + +**Fonctionnement :** +1. Les utilisateurs cliquent sur "Créer un ticket" +2. Un salon privé est créé automatiquement +3. Les membres staff peuvent fermer/rouvrir + +### 👋 Bienvenue / Au Revoir + +| Commande | Description | +|----------|-------------| +| `/setwelcome [message_dm]` | Configurer le salon de bienvenue et message DM | +| `/setgoodbye ` | Configurer le salon d'au revoir | + +**Variables pour les messages DM :** +- `{username}` - Nom d'utilisateur +- `{servername}` - Nom du serveur +- `{member_count}` - Nombre de membres + +### 👥 Whitelist + +| Commande | Description | +|----------|-------------| +| `/whitelist ajouter ` | Ajouter un utilisateur à la whitelist | +| `/whitelist retirer ` | Retirer un utilisateur de la whitelist | +| `/whitelist liste` | Lister les utilisateurs whitelistés | + +### 🔒 Blacklist (Agents uniquement) + +| Commande | Description | +|----------|-------------| +| `/blacklist [raison]` | Blacklister un utilisateur du réseau | +| `/unblacklist ` | Retirer de la blacklist | + +--- + +## 🏗️ Architecture + +``` +backup_kuby/ +├── bot.py # Point d'entrée principal du bot +├── kuby.py # Script de lancement alternatif +├── requirements.txt # Dépendances Python +├── .env # Variables d'environnement (à créer) +├── README.md # Documentation +│ +├── commandes/ # Cog Discord (modules de commandes) +│ ├── whitelist.py # Gestion de la whitelist +│ ├── whitelist_monitor.py # Monitoring whitelist +│ ├── security.py # Panneau de sécurité +│ ├── ticket.py # Système de tickets +│ ├── backup.py # Sauvegardes serveur +│ ├── blacklist.py # Blacklist réseau +│ ├── welcome.py # Messages de bienvenue +│ ├── goodbye.py # Messages d'au revoir +│ ├── fun.py # Commandes fun +│ ├── snipe.py # Commande snipe +│ ├── scan.py # Scan de sécurité +│ ├── no_link.py # Anti-liens basique +│ │ +│ └── modules_security/ # Modules de sécurité avancés +│ ├── antispam.py # Anti-spam & Anti-liens +│ ├── antiraid.py # Anti-raid +│ └── logs_manager.py # Gestion des logs +│ +├── data/ # Données et configurations +│ ├── config.db # Base SQLite (welcome/goodbye) +│ ├── whitelist.json # Utilisateurs whitelistés +│ ├── blacklist.json # Utilisateurs blacklistés +│ ├── security_settings.json # Paramètres de sécurité +│ ├── agents.json # Agents de la blacklist +│ ├── tickets_blacklist.json # Tickets blacklist +│ │ +│ ├── logs/ # Logs d'événements +│ │ ├── member_events_*.json +│ │ ├── messages_*.json +│ │ └── voice_*.json +│ │ +│ ├── security_backups/ # Sauvegardes serveur +│ └── member_logs/ # Historique des rôles membres +│ +├── ressources/ # Ressources statiques +│ └── assets/ +│ +└── src/ # Code source utilitaire + ├── logger.py # Système de logging + └── advanced_logger.py # Logging avancé & historique +``` + +--- + +## 🔐 Système de Permissions + +### Whitelist + +La whitelist est un système de permissions qui contrôle l'accès aux commandes sensibles. Seuls les utilisateurs whitelistés peuvent utiliser certaines commandes administratives. + +**Fichiers :** +- `data/whitelist.json` - Stockage des utilisateurs whitelistés + +**Gestion :** +- Les propriétaires de serveur sont automatiquement whitelistés +- Gestion via `/whitelist ajouter/retirer/liste` + +### Rôles de Staff + +Pour le système de tickets, les rôles staff sont définis lors de la configuration. Ces rôles ont accès aux tickets des utilisateurs. + +### Permissions Requises + +Le bot nécessite les permissions suivantes sur le serveur : +- `Administrator` (recommandé) OU +- `Manage Roles` - Pour la modération +- `Manage Channels` - Pour les tickets +- `Ban Members` - Pour la sécurité +- `Manage Messages` - Pour l'anti-spam +- `View Audit Log` - Pour les logs + +--- + +## 📊 Système de Logs + +### Types d'Événements Trackés + +#### Événements Membres +- **Join** : Arrivée d'un nouveau membre +- **Leave** : Départ d'un membre +- **Restauration de rôles** : Les rôles sont restaurés si le membre revient + +#### Événements Messages +- **Suppression** : Message supprimé (contenu, auteur, salon) +- **Édition** : Message modifié (avant/après) + +#### Événements Vocaux +- **Connexion** : Arrivée dans un salon vocal +- **Déconnexion** : Départ d'un salon vocal +- **Déplacement** : Changement de salon vocal + +### Fichiers de Logs + +Les logs sont stockés dans `data/logs/` avec la structure suivante : +- `member_events_YYYY-MM-DD.json` - Événements membres +- `messages_YYYY-MM-DD.json` - Événements messages +- `voice_YYYY-MM-DD.json` - Événements vocaux + +### Restauration des Rôles + +Le système `advanced_logger.py` сохраняе l'historique des rôles des membres dans `data/member_logs/{user_id}.json`. Lorsqu'un membre rejoint à nouveau, ses rôles précédents sont automatiquement restaurés. + +--- + +## 🧪 Tests + +### Lancer le Bot + +```bash +# Méthode 1 : Via kuby.py +python kuby.py + +# Méthode 2 : Via bot.py (avec gestion d'erreur) +python bot.py +``` + +### Vérifier le Fonctionnement + +1. Le bot doit apparaître en ligne sur Discord +2. Vérifiez les logs dans la console +3. Testez les commandes : + - `/whitelist liste` - Doit fonctionner + - `/security` - Doit ouvrir le panneau + - `/backup create` - Doit créer une sauvegarde + +### Dépannage + +**Problèmes Courants :** + +1. **Token manquant** + ``` + Erreur: Token Discord non trouvé dans les variables d'environnement! + ``` + ➡️ Vérifiez le fichier `.env` + +2. **Intentions manquantes** + ``` + discord.IntentsRequired: ... + ``` + ➡️ Activez les intents sur le portail développeur + +3. **Permissions insuffisantes** + ``` + Je n'ai pas la permission d'exclure ce membre + ``` + ➡️ Vérifiez la position du bot dans la hiérarchie des rôles + +--- + +## 📝 Notes de Développement + +### Structure des Cogs + +Chaque module est un "Cog" Discord.py qui permet une organisation modulaire du code : + +```python +class NomDuModule(commands.Cog): + def __init__(self, bot): + self.bot = bot + + # Commandes slash + @app_commands.command(name="commande", description="Description") + async def ma_commande(self, interaction: discord.Interaction): + # Logique + pass + +async def setup(bot): + await bot.add_cog(NomDuModule(bot)) +``` + +### Système de Logging + +Le bot utilise un système de logging personnalisé via `src/logger.py` : +- `kuby_logger.info()` - Informations générales +- `kuby_logger.debug()` - Messages de débogage +- `kuby_logger.error()` - Erreurs +- `kuby_logger.audit()` - Audits de sécurité + +--- + +## 📄 Licence + +Ce projet est développé pour le réseau **Omega Kube**. Toute utilisation est soumise aux conditions du projet. + +--- + +## 🤝 Contribution + +Pour contribuer au projet : +1. Forkez le repository +2. Créez une branche (`git checkout -b feature/ma-fonctionnalite`) +3. Commitez vos changements (`git commit -m 'Ajout de...'`) +4. Push sur la branche (`git push origin feature/ma-fonctionnalite`) +5. Ouvrez une Pull Request + +--- + +Développé avec ❤️ pour Omega Kube -Pour toute question ou support, rejoignez notre serveur Discord ou créez une issue sur GitHub.