Gameur/Kuby
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions
Kuby/README.md

407 lines
12 KiB
Markdown
Executable file
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 🤖 Kuby - Bot Discord Multi-Fonctions
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.
---
## 📋 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 <url-du-repo>
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 <channel> [message_dm]` | Configurer le salon de bienvenue et message DM |
| `/setgoodbye <channel>` | 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 <utilisateur>` | Ajouter un utilisateur à la whitelist |
| `/whitelist retirer <utilisateur>` | Retirer un utilisateur de la whitelist |
| `/whitelist liste` | Lister les utilisateurs whitelistés |
### 🔒 Blacklist (Agents uniquement)
| Commande | Description |
|----------|-------------|
| `/blacklist <utilisateur> [raison]` | Blacklister un utilisateur du réseau |
| `/unblacklist <utilisateur>` | 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
Reference in a new issue View git blame Copy permalink