GuardDen/README.md

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

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 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)

Commands

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 (Admin only)

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

Banned Words

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

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.

Automod

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

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
│   │   ├── 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
│       ├── ratelimit.py    # Rate limiting
│       └── verification.py # Verification challenges
├── tests/                  # Test suite
├── migrations/             # Database migrations
├── dashboard/              # Web dashboard (FastAPI + React)
├── docker-compose.yml      # Docker deployment
└── pyproject.toml          # Dependencies

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