commit, am too tired to add docs here
This commit is contained in:
292
README.md
292
README.md
@@ -141,6 +141,162 @@ GuardDen is a comprehensive Discord moderation bot designed to protect your comm
|
||||
|
||||
## Configuration
|
||||
|
||||
GuardDen now supports **file-based configuration** as the primary method for managing bot settings. This replaces Discord commands for configuration, providing better version control, easier management, and more reliable deployments.
|
||||
|
||||
### File-Based Configuration (Recommended)
|
||||
|
||||
#### Directory Structure
|
||||
```
|
||||
config/
|
||||
├── guilds/
|
||||
│ ├── guild-123456789.yml # Per-server configuration
|
||||
│ ├── guild-987654321.yml
|
||||
│ └── default-template.yml # Template for new servers
|
||||
├── wordlists/
|
||||
│ ├── banned-words.yml # Custom banned words
|
||||
│ ├── domain-allowlists.yml # Allowed domains whitelist
|
||||
│ └── external-sources.yml # Managed wordlist sources
|
||||
├── schemas/
|
||||
│ ├── guild-schema.yml # Configuration validation
|
||||
│ └── wordlists-schema.yml
|
||||
└── templates/
|
||||
└── guild-default.yml # Default configuration template
|
||||
```
|
||||
|
||||
#### Quick Start with File Configuration
|
||||
|
||||
1. **Create your first server configuration:**
|
||||
```bash
|
||||
python -m guardden.cli.config guild create 123456789012345678 "My Discord Server"
|
||||
```
|
||||
|
||||
2. **Edit the configuration file:**
|
||||
```bash
|
||||
nano config/guilds/guild-123456789012345678.yml
|
||||
```
|
||||
|
||||
3. **Customize settings (example):**
|
||||
```yaml
|
||||
# Basic server information
|
||||
guild_id: 123456789012345678
|
||||
name: "My Discord Server"
|
||||
|
||||
settings:
|
||||
# AI Moderation
|
||||
ai_moderation:
|
||||
enabled: true
|
||||
sensitivity: 80 # 0-100 (higher = stricter)
|
||||
nsfw_only_filtering: true # Only block sexual content, allow violence
|
||||
|
||||
# Automod settings
|
||||
automod:
|
||||
message_rate_limit: 5 # Max messages per 5 seconds
|
||||
scam_allowlist:
|
||||
- "discord.com"
|
||||
- "github.com"
|
||||
```
|
||||
|
||||
4. **Validate your configuration:**
|
||||
```bash
|
||||
python -m guardden.cli.config guild validate 123456789012345678
|
||||
```
|
||||
|
||||
5. **Start the bot** (configurations auto-reload):
|
||||
```bash
|
||||
python -m guardden
|
||||
```
|
||||
|
||||
#### Configuration Management CLI
|
||||
|
||||
**Guild Management:**
|
||||
```bash
|
||||
# List all configured servers
|
||||
python -m guardden.cli.config guild list
|
||||
|
||||
# Create new server configuration
|
||||
python -m guardden.cli.config guild create <guild_id> "Server Name"
|
||||
|
||||
# Edit specific settings
|
||||
python -m guardden.cli.config guild edit <guild_id> ai_moderation.sensitivity 75
|
||||
python -m guardden.cli.config guild edit <guild_id> ai_moderation.nsfw_only_filtering true
|
||||
|
||||
# Validate configurations
|
||||
python -m guardden.cli.config guild validate
|
||||
python -m guardden.cli.config guild validate <guild_id>
|
||||
|
||||
# Backup configuration
|
||||
python -m guardden.cli.config guild backup <guild_id>
|
||||
```
|
||||
|
||||
**Migration from Discord Commands:**
|
||||
```bash
|
||||
# Export existing Discord command settings to files
|
||||
python -m guardden.cli.config migrate from-database
|
||||
|
||||
# Verify migration was successful
|
||||
python -m guardden.cli.config migrate verify
|
||||
```
|
||||
|
||||
**Wordlist Management:**
|
||||
```bash
|
||||
# View wordlist status
|
||||
python -m guardden.cli.config wordlist info
|
||||
|
||||
# View available templates
|
||||
python -m guardden.cli.config template info
|
||||
```
|
||||
|
||||
#### Key Configuration Options
|
||||
|
||||
**AI Moderation Settings:**
|
||||
```yaml
|
||||
ai_moderation:
|
||||
enabled: true # Enable AI content analysis
|
||||
sensitivity: 80 # 0-100 scale (higher = stricter)
|
||||
confidence_threshold: 0.7 # 0.0-1.0 confidence required
|
||||
nsfw_only_filtering: false # true = only sexual content, false = all content
|
||||
log_only: false # true = log only, false = take action
|
||||
```
|
||||
|
||||
**NSFW-Only Filtering Guide:**
|
||||
- `false` = Block ALL inappropriate content (sexual, violence, harassment, hate speech)
|
||||
- `true` = Only block sexual/nude content, allow violence and other content types
|
||||
|
||||
**Automod Configuration:**
|
||||
```yaml
|
||||
automod:
|
||||
message_rate_limit: 5 # Max messages per time window
|
||||
message_rate_window: 5 # Time window in seconds
|
||||
duplicate_threshold: 3 # Duplicate messages to trigger
|
||||
scam_allowlist: # Domains that bypass scam detection
|
||||
- "discord.com"
|
||||
- "github.com"
|
||||
```
|
||||
|
||||
**Banned Words Management:**
|
||||
Edit `config/wordlists/banned-words.yml`:
|
||||
```yaml
|
||||
global_patterns:
|
||||
- pattern: "badword"
|
||||
action: delete
|
||||
is_regex: false
|
||||
category: profanity
|
||||
|
||||
guild_patterns:
|
||||
123456789: # Specific server overrides
|
||||
- pattern: "server-specific-rule"
|
||||
action: warn
|
||||
override_global: false
|
||||
```
|
||||
|
||||
#### Hot-Reloading
|
||||
|
||||
Configuration changes are automatically detected and applied without restarting the bot:
|
||||
- ✅ Edit YAML files directly
|
||||
- ✅ Changes apply within seconds
|
||||
- ✅ Invalid configs are rejected with error logs
|
||||
- ✅ Automatic rollback on errors
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Description | Default |
|
||||
@@ -170,19 +326,29 @@ GuardDen is a comprehensive Discord moderation bot designed to protect your comm
|
||||
|
||||
### Per-Guild Settings
|
||||
|
||||
Each server can configure:
|
||||
- Command prefix
|
||||
- Log channels (general and moderation)
|
||||
- Welcome channel
|
||||
- Mute role and verified role
|
||||
- Automod toggles (spam, links, banned words)
|
||||
- Automod thresholds and scam allowlist
|
||||
- Strike action thresholds
|
||||
- AI moderation settings (enabled, sensitivity, confidence threshold, log-only, NSFW detection, NSFW-only mode)
|
||||
- Verification settings (type, enabled)
|
||||
Each server can be configured via YAML files in `config/guilds/`:
|
||||
|
||||
**General Settings:**
|
||||
- Command prefix and locale
|
||||
- Channel IDs (log, moderation, welcome)
|
||||
- Role IDs (mute, verified, moderator)
|
||||
|
||||
**Content Moderation:**
|
||||
- AI moderation (enabled, sensitivity, NSFW-only mode)
|
||||
- Automod thresholds and rate limits
|
||||
- Banned words and domain allowlists
|
||||
- Strike system and escalation actions
|
||||
|
||||
**Member Verification:**
|
||||
- Verification challenges (button, captcha, math, emoji)
|
||||
- Auto-role assignment
|
||||
|
||||
**All settings support hot-reloading** - edit files and changes apply immediately!
|
||||
|
||||
## Commands
|
||||
|
||||
> **Note:** Configuration commands (`!config`, `!ai`, `!automod`, etc.) have been replaced with file-based configuration. See the [Configuration](#configuration) section above for managing settings via YAML files and the CLI tool.
|
||||
|
||||
### Moderation
|
||||
|
||||
| Command | Permission | Description |
|
||||
@@ -198,56 +364,49 @@ Each server can configure:
|
||||
| `!purge <amount>` | Manage Messages | Delete multiple messages (max 100) |
|
||||
| `!modlogs <user>` | Kick Members | View moderation history |
|
||||
|
||||
### Configuration (Admin only)
|
||||
### Configuration Management
|
||||
|
||||
Configuration is now managed via **YAML files** instead of Discord commands. Use the CLI tool:
|
||||
|
||||
```bash
|
||||
# Configuration Management CLI
|
||||
python -m guardden.cli.config guild create <guild_id> "Server Name"
|
||||
python -m guardden.cli.config guild list
|
||||
python -m guardden.cli.config guild edit <guild_id> <setting> <value>
|
||||
python -m guardden.cli.config guild validate [guild_id]
|
||||
|
||||
# Migration from old Discord commands
|
||||
python -m guardden.cli.config migrate from-database
|
||||
python -m guardden.cli.config migrate verify
|
||||
|
||||
# Wordlist management
|
||||
python -m guardden.cli.config wordlist info
|
||||
```
|
||||
|
||||
**Read-only Status Commands (Still Available):**
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `!config` | View current configuration |
|
||||
| `!config prefix <prefix>` | Set command prefix |
|
||||
| `!config logchannel [#channel]` | Set general log channel |
|
||||
| `!config modlogchannel [#channel]` | Set moderation log channel |
|
||||
| `!config welcomechannel [#channel]` | Set welcome channel |
|
||||
| `!config muterole [@role]` | Set mute role |
|
||||
| `!config automod <true/false>` | Toggle automod |
|
||||
| `!config antispam <true/false>` | Toggle anti-spam |
|
||||
| `!config linkfilter <true/false>` | Toggle link filtering |
|
||||
| `!config` | View current configuration (read-only) |
|
||||
| `!ai` | View AI moderation settings (read-only) |
|
||||
| `!automod` | View automod status (read-only) |
|
||||
| `!bannedwords` | List banned words (read-only) |
|
||||
|
||||
### Banned Words
|
||||
**Configuration Examples:**
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `!bannedwords` | List all banned words |
|
||||
| `!bannedwords add <word> [action] [is_regex]` | Add a banned word |
|
||||
| `!bannedwords remove <id>` | Remove a banned word by ID |
|
||||
```bash
|
||||
# Set AI sensitivity to 75 (0-100 scale)
|
||||
python -m guardden.cli.config guild edit 123456789 ai_moderation.sensitivity 75
|
||||
|
||||
Managed wordlists are synced weekly by default. You can override sources with
|
||||
`GUARDDEN_WORDLIST_SOURCES` (JSON array) or disable syncing entirely with
|
||||
`GUARDDEN_WORDLIST_ENABLED=false`.
|
||||
# Enable NSFW-only filtering (only block sexual content)
|
||||
python -m guardden.cli.config guild edit 123456789 ai_moderation.nsfw_only_filtering true
|
||||
|
||||
### Automod
|
||||
# Add domain to scam allowlist
|
||||
Edit config/wordlists/domain-allowlists.yml
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `!automod` | View automod status |
|
||||
| `!automod test <text>` | Test text against filters |
|
||||
| `!automod threshold <setting> <value>` | Update a single automod threshold |
|
||||
| `!automod allowlist` | List allowlisted domains |
|
||||
| `!automod allowlist add <domain>` | Add a domain to the allowlist |
|
||||
| `!automod allowlist remove <domain>` | Remove a domain from the allowlist |
|
||||
|
||||
### AI Moderation (Admin only)
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `!ai` | View AI moderation settings |
|
||||
| `!ai enable` | Enable AI moderation |
|
||||
| `!ai disable` | Disable AI moderation |
|
||||
| `!ai sensitivity <0-100>` | Set AI sensitivity level |
|
||||
| `!ai threshold <0.0-1.0>` | Set AI confidence threshold |
|
||||
| `!ai logonly <true/false>` | Toggle AI log-only mode |
|
||||
| `!ai nsfw <true/false>` | Toggle NSFW image detection |
|
||||
| `!ai nsfwonly <true/false>` | Toggle NSFW-only filtering mode |
|
||||
| `!ai analyze <text>` | Test AI analysis on text |
|
||||
# Add banned word pattern
|
||||
Edit config/wordlists/banned-words.yml
|
||||
```
|
||||
|
||||
### Diagnostics (Admin only)
|
||||
|
||||
@@ -295,7 +454,7 @@ guardden/
|
||||
│ ├── bot.py # Main bot class
|
||||
│ ├── config.py # Settings management
|
||||
│ ├── cogs/ # Discord command groups
|
||||
│ │ ├── admin.py # Configuration commands
|
||||
│ │ ├── admin.py # Configuration commands (read-only)
|
||||
│ │ ├── ai_moderation.py # AI-powered moderation
|
||||
│ │ ├── automod.py # Automatic moderation
|
||||
│ │ ├── events.py # Event logging
|
||||
@@ -304,18 +463,29 @@ guardden/
|
||||
│ ├── models/ # Database models
|
||||
│ │ ├── guild.py # Guild settings, banned words
|
||||
│ │ └── moderation.py # Logs, strikes, notes
|
||||
│ └── services/ # Business logic
|
||||
│ ├── ai/ # AI provider implementations
|
||||
│ ├── automod.py # Content filtering
|
||||
│ ├── database.py # DB connections
|
||||
│ ├── guild_config.py # Config caching
|
||||
│ ├── ratelimit.py # Rate limiting
|
||||
│ └── verification.py # Verification challenges
|
||||
│ ├── services/ # Business logic
|
||||
│ │ ├── ai/ # AI provider implementations
|
||||
│ │ ├── automod.py # Content filtering
|
||||
│ │ ├── database.py # DB connections
|
||||
│ │ ├── guild_config.py # Config caching
|
||||
│ │ ├── file_config.py # File-based configuration system
|
||||
│ │ ├── config_migration.py # Migration from DB to files
|
||||
│ │ ├── ratelimit.py # Rate limiting
|
||||
│ │ └── verification.py # Verification challenges
|
||||
│ └── cli/ # Command-line tools
|
||||
│ └── config.py # Configuration management CLI
|
||||
├── config/ # File-based configuration
|
||||
│ ├── guilds/ # Per-server configuration files
|
||||
│ ├── wordlists/ # Banned words and allowlists
|
||||
│ ├── schemas/ # Configuration validation schemas
|
||||
│ └── templates/ # Configuration templates
|
||||
├── tests/ # Test suite
|
||||
├── migrations/ # Database migrations
|
||||
├── dashboard/ # Web dashboard (FastAPI + React)
|
||||
├── docker-compose.yml # Docker deployment
|
||||
└── pyproject.toml # Dependencies
|
||||
├── pyproject.toml # Dependencies
|
||||
├── README.md # This file
|
||||
└── MIGRATION.md # Migration guide for file-based config
|
||||
```
|
||||
|
||||
## Verification System
|
||||
|
||||
Reference in New Issue
Block a user