A lightweight, cost-conscious Discord moderation bot focused on automated protection against spam and NSFW content. Built for self-hosting with minimal resource usage and predictable AI costs.

Overview

GuardDen is a minimal Discord bot designed for small to medium servers (1-2 guilds) that need automated moderation without the complexity of full-featured moderation systems. It focuses on two core areas:

Spam Detection - Automatic rate limiting, duplicate detection, and mass mention protection
NSFW Content Filtering - AI-powered image analysis with aggressive cost controls

What GuardDen is NOT:

Not a full moderation suite (no manual mod commands, logging, or strike systems)
Not a verification/captcha system
Not a chat moderation bot (no text analysis, banned words, or scam detection)

Target Users:

Small community servers that need automated spam + NSFW protection
Budget-conscious server owners (~$5-25/month AI costs)
Self-hosters who want a simple, maintainable bot

Features

Feature	Description	Cost
Spam Detection	Rate limiting, duplicate messages, mass mentions	Free
NSFW Image Detection	AI-powered analysis of images/GIFs using Claude or GPT	~$5-25/month
User Blocklist	Block ALL media from specific users instantly	Free
NSFW Domain Blocking	Instant blocking of known NSFW video domains	Free
Cost Controls	Rate limits, deduplication, file size limits	Built-in
Single Config File	One YAML file for all settings	Easy
Owner Commands	Status, reload, ping	Free

Spam Detection

Automatically detects and deletes spam messages based on:

Message Rate Limiting: Max 5 messages per 5 seconds (configurable)
Duplicate Detection: Flags repeated identical messages
Mass Mentions: Limits @mentions per message and per time window
Actions: Deletes message, no notifications to user

NSFW Image Detection

AI-powered analysis of images and GIFs with strict cost controls:

Supported Providers: Anthropic Claude, OpenAI GPT
Content Types: Image attachments, Discord GIF embeds (optional)
NSFW Categories: Suggestive, Partial Nudity, Nudity, Explicit
Filtering Mode: NSFW-only by default (only blocks sexual content)
Cost Controls:
- 25 AI checks/hour/guild (default)
- 5 AI checks/hour/user (default)
- Image deduplication (tracks 1000 recent messages)
- File size limit (skip > 3MB)
- Max images per message (2 by default)
Actions: Deletes message, no notifications to user

User Blocklist

Instantly delete ALL media from specific users:

Blocks: Images, GIFs, embeds, URLs
No AI Cost: Instant deletion without analysis
Use Case: Known problematic users, spam accounts

NSFW Domain Blocking

Pre-configured list of known NSFW video domains:

Blocks: pornhub.com, xvideos.com, xnxx.com, etc.
No AI Cost: Pattern matching only
Instant: Deletes message immediately

Quick Start

Prerequisites

Requirement	Version	Purpose
Python	3.11+	Bot runtime
PostgreSQL	15+	Database
Discord Bot Token	-	Bot authentication
AI API Key	(Optional)	Claude or OpenAI for NSFW detection

1. Discord Bot Setup

Create Application
- Go to Discord Developer Portal
- Click New Application → Name it (e.g., "GuardDen")
- Go to Bot tab → Add Bot
Get Bot Token
- Click Reset Token → Copy the token
- Save as GUARDDEN_DISCORD_TOKEN in .env
Enable Intents
- Enable Message Content Intent (required for reading messages)
Generate Invite URL
- Go to OAuth2 → URL Generator
- Select scopes: bot
- Select permissions:
  - Moderate Members (timeout)
  - View Channels
  - Send Messages
  - Manage Messages
  - Read Message History
- Or use permission integer: 275415089216
- Copy generated URL and invite to your server

2. Installation

Option A: Docker (Recommended)

# Clone repository
git clone https://git.hiddenden.cafe/Hiddenden/GuardDen.git
cd GuardDen

# Create configuration files
cp .env.example .env
cp config.example.yml config.yml

# Edit .env - Add your Discord token
nano .env

# Edit config.yml - Configure settings
nano config.yml

# Start with Docker Compose
docker compose up -d

# View logs
docker logs guardden-bot -f

Option B: Local Development

# Clone repository
git clone https://git.hiddenden.cafe/Hiddenden/GuardDen.git
cd GuardDen

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev,ai]"

# Create configuration files
cp .env.example .env
cp config.example.yml config.yml

# Edit configuration
nano .env
nano config.yml

# Start PostgreSQL (or use Docker)
docker compose up db -d

# Run database migrations
alembic upgrade head

# Start bot
python -m guardden

Configuration

Environment Variables (`.env`)

Variable	Required	Description	Default
`GUARDDEN_DISCORD_TOKEN`	✅	Discord bot token	-
`GUARDDEN_DATABASE_URL`	No	PostgreSQL connection URL	`postgresql://guardden:guardden@localhost:5432/guardden`
`GUARDDEN_LOG_LEVEL`	No	Logging level (DEBUG/INFO/WARNING/ERROR)	`INFO`
`GUARDDEN_AI_PROVIDER`	No	AI provider (`anthropic`/`openai`/`none`)	`none`
`GUARDDEN_ANTHROPIC_API_KEY`	No*	Anthropic API key	-
`GUARDDEN_OPENAI_API_KEY`	No*	OpenAI API key	-

*Required if AI_PROVIDER is set to anthropic or openai

Bot Configuration (`config.yml`)

# Bot Settings
bot:
  prefix: "!"
  owner_ids:
    - 123456789012345678  # Your Discord user ID (for owner commands)

# Spam Detection
automod:
  enabled: true
  anti_spam_enabled: true
  message_rate_limit: 5           # Max messages per window
  message_rate_window: 5          # Window in seconds
  duplicate_threshold: 3          # Duplicate messages to trigger
  mention_limit: 5                # Max mentions per message
  mention_rate_limit: 10          # Max mentions per window
  mention_rate_window: 60         # Mention window in seconds

# AI Moderation (NSFW Detection)
ai_moderation:
  enabled: true
  sensitivity: 80                  # 0-100 (higher = stricter)
  nsfw_only_filtering: true        # Only filter sexual content
  
  # Cost Controls
  max_checks_per_hour_per_guild: 25  # Conservative limit
  max_checks_per_user_per_hour: 5    # Prevent abuse
  max_images_per_message: 2          # Analyze max 2 images
  max_image_size_mb: 3               # Skip large files
  
  # Feature Toggles
  check_embed_images: true           # Check Discord GIFs
  check_video_thumbnails: false      # Skip video thumbnails
  url_image_check_enabled: false     # Skip URL downloads

# User Blocklist (instant deletion)
blocked_user_ids:
  - 123456789012345678  # Discord user ID to block

# NSFW Domain Blocklist (instant blocking)
nsfw_video_domains:
  - pornhub.com
  - xvideos.com
  - xnxx.com
  - redtube.com
  - youporn.com

Configuration Options Explained

Spam Detection:

message_rate_limit: How many messages allowed in time window
duplicate_threshold: How many identical messages trigger spam detection
mention_limit: Max @mentions allowed per message

AI Moderation:

sensitivity: Detection strictness (80 = balanced, 100 = very strict, 50 = lenient)
nsfw_only_filtering: true = only block sexual content (default), false = block all inappropriate content
max_checks_per_hour_per_guild: Hard limit on AI API calls per guild (cost control)
max_checks_per_user_per_hour: Per-user limit to prevent spam/abuse

User Blocklist:

Add Discord user IDs to instantly delete ALL their media
No AI cost - instant pattern matching
Useful for repeat offenders or spam bots

Cost Estimation:

Small server (< 100 users): ~$5-10/month
Medium server (100-500 users): ~$15-25/month
Large server (500+ users): Increase rate limits or disable embed checking

Owner Commands

Command	Description
`!status`	Show bot status (uptime, guilds, latency, AI provider)
`!reload`	Reload all cogs (apply code changes without restart)
`!ping`	Check bot latency

Note: All configuration is done via config.yml. There are no in-Discord configuration commands.

How It Works

Detection Flow

Message Received
    ↓
[1] User Blocklist Check (instant)
    ↓ (if not blocked)
[2] NSFW Domain Check (instant)
    ↓ (if no NSFW domain)
[3] Spam Detection (free)
    ↓ (if not spam)
[4] Has Images/Embeds?
    ↓ (if yes)
[5] AI Rate Limit Check
    ↓ (if under limit)
[6] Image Deduplication
    ↓ (if not analyzed recently)
[7] AI Analysis (cost)
    ↓
[8] Action: Delete if violation

Action Behavior

When a violation is detected:

✅ Message deleted immediately
✅ Action logged to console/log file
❌ No DM sent to user (silent)
❌ No timeout applied (delete only)
❌ No moderation log in Discord

Cost Controls

Multiple layers to keep AI costs predictable:

User Blocklist - Skip AI entirely for known bad actors
Domain Blocklist - Skip AI for known NSFW domains
Rate Limiting - Hard caps per guild and per user
Deduplication - Don't re-analyze same message
File Size Limits - Skip very large files
Max Images - Limit images analyzed per message
Optional Features - Disable embed checking to save costs

Development

Project Structure

guardden/
├── src/guardden/
│   ├── bot.py                  # Main bot class
│   ├── config.py               # Settings management
│   ├── cogs/                   # Discord command modules
│   │   ├── automod.py          # Spam detection
│   │   ├── ai_moderation.py    # NSFW image detection
│   │   └── owner.py            # Owner commands
│   ├── models/                 # Database models
│   │   └── guild.py            # Guild settings
│   ├── services/               # Business logic
│   │   ├── ai/                 # AI provider implementations
│   │   ├── automod.py          # Spam detection logic
│   │   ├── config_loader.py    # YAML config loading
│   │   ├── ai_rate_limiter.py  # Cost control
│   │   └── database.py         # DB connections
│   └── __main__.py             # Entry point
├── config.yml                  # Bot configuration (not in git)
├── config.example.yml          # Configuration template
├── .env                        # Environment variables (not in git)
├── .env.example                # Environment template
├── tests/                      # Test suite
├── migrations/                 # Database migrations
├── docker-compose.yml          # Docker deployment
└── pyproject.toml              # Dependencies

Running Tests

# Run all tests
pytest

# Run specific tests
pytest tests/test_automod.py

# Run with coverage
pytest --cov=src/guardden --cov-report=html

Code Quality

# Linting
ruff check src tests

# Formatting
ruff format src tests

# Type checking
mypy src

Database Migrations

# Apply migrations
alembic upgrade head

# Create new migration
alembic revision --autogenerate -m "description"

# Rollback one migration
alembic downgrade -1

Troubleshooting

Bot won't start

Error: Config file not found: config.yml

Solution: Copy config.example.yml to config.yml and edit settings

Error: Discord token cannot be empty

Solution: Add GUARDDEN_DISCORD_TOKEN to .env file

Error: Cannot import name 'ModerationResult'

Solution: Pull latest changes and rebuild: docker compose up -d --build

Bot doesn't respond to commands

Check:

Bot is online in Discord
Bot has correct permissions (Manage Messages, View Channels)
Your user ID is in owner_ids in config.yml
Check logs: docker logs guardden-bot -f

AI not working