Hiddenden/GuardDen
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7612770625016a2f88828bb4c219b200a8cef326
GuardDen/README.md

20 KiB
Raw Blame History

GuardDen

GuardDen is a comprehensive Discord moderation bot designed to protect your community while maintaining a warm, welcoming environment. Built with privacy and self-hosting in mind, GuardDen combines AI-powered content filtering with traditional moderation tools to create a safe space for your members.

Features

Core Moderation

  • Warn, Kick, Ban, Timeout - Standard moderation commands with logging
  • Strike System - Configurable point-based system with automatic escalation
  • Moderation History - Track all actions taken against users
  • Bulk Message Deletion - Purge up to 100 messages at once

Automod

  • Banned Words Filter - Block words/phrases with regex support
  • Scam Detection - Automatic detection of phishing/scam links
  • Anti-Spam - Rate limiting, duplicate detection, mass mention protection
  • Link Filtering - Block Discord invites and suspicious URLs

AI Moderation

  • Text Analysis - AI-powered content moderation using Claude or GPT
  • NSFW Image Detection - Automatic flagging of inappropriate images
  • NSFW-Only Filtering - Option to only filter sexual content, allowing violence/harassment
  • Phishing Analysis - AI-enhanced detection of scam URLs
  • Configurable Sensitivity - Adjust strictness per server (0-100)

Verification System

  • Multiple Challenge Types - Button, captcha, math problems, emoji selection
  • Automatic New Member Verification - Challenge users on join
  • Configurable Verified Role - Auto-assign role on successful verification
  • Rate Limited - Prevents verification spam

Logging

  • Member joins/leaves
  • Message edits and deletions
  • Voice channel activity
  • Ban/unban events
  • All moderation actions

Web Dashboard

  • Servers overview with plan status and quick config links
  • Users view with cross-guild search and strike totals
  • Chats view for moderated message logs with filters
  • Moderation logs, analytics, and configuration updates
  • Config export for backups

Quick Start

Prerequisites

  • Python 3.11+
  • PostgreSQL 15+
  • Discord Bot Token (see setup below)
  • (Optional) Anthropic or OpenAI API key for AI features

Discord Bot Setup

  1. Go to the Discord Developer Portal

  2. Click New Application and give it a name (e.g., "GuardDen")

  3. Go to the Bot tab and click Add Bot

  4. Configure Bot Settings:

    • Disable Public Bot if you only want yourself to add it
    • Copy the Token (click "Reset Token") - this is your GUARDDEN_DISCORD_TOKEN

  5. Enable Privileged Gateway Intents (all three required):

    • Presence Intent - for user status tracking
    • Server Members Intent - for member join/leave events, verification
    • Message Content Intent - for reading messages (automod, AI moderation)

  6. Generate Invite URL - Go to OAuth2 > URL Generator:

    Scopes:

    • bot
    • applications.commands

    Bot Permissions:

    • Manage Roles
    • Kick Members
    • Ban Members
    • Moderate Members (timeout)
    • Manage Channels
    • View Channels
    • Send Messages
    • Manage Messages
    • Embed Links
    • Attach Files
    • Read Message History
    • Add Reactions

    Or use permission integer: 1239943348294

  7. Use the generated URL to invite the bot to your server

Docker Deployment (Recommended)

  1. Clone the repository:

    git clone https://git.hiddenden.cafe/Hiddenden/GuardDen.git
cd guardden

  2. Create your environment file:

    cp .env.example .env
# Edit .env and add your Discord token

  3. Start with Docker Compose:

    docker compose up -d

  4. Open the dashboard (if configured): http://localhost:8080

Local Development

  1. Create a virtual environment:

    python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  2. Install dependencies:

    pip install -e ".[dev,ai]"

  3. Set up environment variables:

    cp .env.example .env
# Edit .env with your configuration

  4. Start PostgreSQL (or use Docker):

    docker compose up db -d

  5. Run the bot:

    python -m guardden

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:

    python -m guardden.cli.config guild create 123456789012345678 "My Discord Server"

  2. Edit the configuration file:

    nano config/guilds/guild-123456789012345678.yml

  3. Customize settings (example):

    # 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:

    python -m guardden.cli.config guild validate 123456789012345678

  5. Start the bot (configurations auto-reload):

    python -m guardden

Configuration Management CLI

Guild Management:

# 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:

# 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:

# 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:

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:

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:

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
GUARDDEN_DISCORD_TOKEN Your Discord bot token Required
GUARDDEN_DISCORD_PREFIX Default command prefix !
GUARDDEN_ALLOWED_GUILDS Comma-separated guild allowlist (empty = all)
GUARDDEN_OWNER_IDS Comma-separated owner user IDs (empty = admins)
GUARDDEN_DATABASE_URL PostgreSQL connection URL postgresql://guardden:guardden@localhost:5432/guardden
GUARDDEN_LOG_LEVEL Logging level INFO
GUARDDEN_AI_PROVIDER AI provider (anthropic/openai/none) none
GUARDDEN_ANTHROPIC_API_KEY Anthropic API key (if using Claude) -
GUARDDEN_OPENAI_API_KEY OpenAI API key (if using GPT) -
GUARDDEN_DASHBOARD_BASE_URL Dashboard base URL for OAuth callbacks http://localhost:8080
GUARDDEN_DASHBOARD_SECRET_KEY Session secret for dashboard Required
GUARDDEN_DASHBOARD_ENTRA_TENANT_ID Entra tenant ID Required
GUARDDEN_DASHBOARD_ENTRA_CLIENT_ID Entra client ID Required
GUARDDEN_DASHBOARD_ENTRA_CLIENT_SECRET Entra client secret Required
GUARDDEN_DASHBOARD_DISCORD_CLIENT_ID Discord OAuth client ID Required
GUARDDEN_DASHBOARD_DISCORD_CLIENT_SECRET Discord OAuth client secret Required
GUARDDEN_DASHBOARD_OWNER_DISCORD_ID Discord user ID allowed Required
GUARDDEN_DASHBOARD_OWNER_ENTRA_OBJECT_ID Entra object ID allowed Required
GUARDDEN_DASHBOARD_CORS_ORIGINS Dashboard CORS origins (empty = none)
GUARDDEN_WORDLIST_ENABLED Enable managed wordlist sync true
GUARDDEN_WORDLIST_UPDATE_HOURS Managed wordlist sync interval 168
GUARDDEN_WORDLIST_SOURCES JSON array of wordlist sources (empty = defaults)

Per-Guild Settings

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 section above for managing settings via YAML files and the CLI tool.

Moderation

Command Permission Description
!warn <user> [reason] Kick Members Warn a user
!strike <user> [points] [reason] Kick Members Add strikes to a user
!strikes <user> Kick Members View user's strikes
!timeout <user> <duration> [reason] Moderate Members Timeout a user (e.g., 1h, 30m, 7d)
!untimeout <user> Moderate Members Remove timeout
!kick <user> [reason] Kick Members Kick a user
!ban <user> [reason] Ban Members Ban a user
!unban <user_id> [reason] Ban Members Unban a user by ID
!purge <amount> Manage Messages Delete multiple messages (max 100)
!modlogs <user> Kick Members View moderation history

Configuration Management

Configuration is now managed via YAML files instead of Discord commands. Use the CLI tool:

# 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 (read-only)
!ai View AI moderation settings (read-only)
!automod View automod status (read-only)
!bannedwords List banned words (read-only)

Configuration Examples:

# Set AI sensitivity to 75 (0-100 scale)
python -m guardden.cli.config guild edit 123456789 ai_moderation.sensitivity 75

# Enable NSFW-only filtering (only block sexual content)
python -m guardden.cli.config guild edit 123456789 ai_moderation.nsfw_only_filtering true

# Add domain to scam allowlist
Edit config/wordlists/domain-allowlists.yml

# Add banned word pattern
Edit config/wordlists/banned-words.yml

Diagnostics (Admin only)

Command Description
!health Check database and AI provider status

Verification (Admin only)

Command Description
!verify Request verification (for users)
!verify setup View verification setup status
!verify enable Enable verification for new members
!verify disable Disable verification
!verify role @role Set the verified role
!verify type <type> Set verification type (button/captcha/math/emoji)
!verify test [type] Test a verification challenge
!verify reset @user Reset verification for a user

Dashboard

The dashboard provides owner-only visibility and configuration across all servers, including servers, users, chats, moderation logs, analytics, and settings.

  1. Configure Entra + Discord OAuth credentials in .env.
  2. Run with Docker: docker compose up -d dashboard (builds the dashboard UI).
  3. For local development without Docker, build the frontend: cd dashboard/frontend && npm install && npm run build
  4. Start the dashboard: python -m guardden.dashboard
  5. OAuth callbacks:
    • Entra: http://localhost:8080/auth/entra/callback
    • Discord: http://localhost:8080/auth/discord/callback

CI (Gitea Actions)

Workflows live under .gitea/workflows/ and mirror the previous GitHub Actions pipeline for linting, tests, and Docker builds.

Project Structure

guardden/
├── src/guardden/
│   ├── bot.py              # Main bot class
│   ├── config.py           # Settings management
│   ├── cogs/               # Discord command groups
│   │   ├── admin.py        # Configuration commands (read-only)
│   │   ├── ai_moderation.py # AI-powered moderation
│   │   ├── automod.py      # Automatic moderation
│   │   ├── events.py       # Event logging
│   │   ├── moderation.py   # Moderation commands
│   │   └── verification.py # Member verification
│   ├── 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
│   │   ├── 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
├── README.md               # This file
└── MIGRATION.md            # Migration guide for file-based config

Verification System

GuardDen includes a verification system to protect your server from bots and raids.

Challenge Types

Type Description
button Simple button click (default, easiest)
captcha Text-based captcha code entry
math Solve a simple math problem
emoji Select the correct emoji from options

Setup

  1. Create a verified role in your server
  2. Configure the role permissions (verified members get full access)
  3. Set up verification: 
    !verify role @Verified
!verify type captcha
!verify enable

How It Works

  1. New member joins the server
  2. Bot sends verification challenge via DM (or channel if DMs disabled)
  3. Member completes the challenge
  4. Bot assigns the verified role
  5. Member gains access to the server

AI Moderation

GuardDen supports AI-powered content moderation using either Anthropic's Claude or OpenAI's GPT models.

Setup

  1. Set the AI provider in your environment:

    GUARDDEN_AI_PROVIDER=anthropic  # or "openai"
GUARDDEN_ANTHROPIC_API_KEY=sk-ant-...  # if using Claude
GUARDDEN_OPENAI_API_KEY=sk-...  # if using OpenAI

  2. Enable AI moderation per server:

    !ai enable
!ai sensitivity 50  # 0=lenient, 100=strict
!ai nsfw true       # Enable NSFW image detection

Content Categories

The AI analyzes content for:

  • Harassment - Personal attacks, bullying
  • Hate Speech - Discrimination, slurs
  • Sexual Content - Explicit material
  • Violence - Threats, graphic content
  • Self-Harm - Suicide/self-injury content
  • Scams - Phishing, fraud attempts
  • Spam - Promotional, low-quality content

How It Works

  1. Messages are analyzed by the AI provider
  2. Results include confidence scores and severity ratings
  3. Actions are taken based on guild sensitivity settings
  4. All AI actions are logged to the mod log channel

NSFW-Only Filtering Mode

For communities that only want to filter sexual content while allowing other content types:

!ai nsfwonly true

When enabled:

  • ✅ Blocked: Sexual content, nude images, explicit material
  • ❌ Allowed: Violence, harassment, hate speech, self-harm content

When disabled (normal mode):

  • ✅ Blocked: All inappropriate content categories

This mode is useful for gaming communities, mature discussion servers, or communities with specific content policies that allow violence but prohibit sexual material.

Development

Running Tests

pytest
pytest -v                           # Verbose output
pytest tests/test_automod.py        # Specific file
pytest -k "test_scam"               # Filter by name

Code Quality

ruff check src tests                # Linting
ruff format src tests               # Formatting
mypy src                            # Type checking

License

MIT License - see LICENSE file for details.

Roadmap

  • AI-powered content moderation (Claude/OpenAI integration)
  • NSFW image detection
  • Verification/captcha system
  • Rate limiting
  • Voice channel moderation
  • Web dashboard
Reference in New Issue View Git Blame Copy Permalink