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
- **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](https://discord.com/developers/applications)
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:
   ```bash
   git clone https://git.hiddenden.cafe/Hiddenden/GuardDen.git
   cd guardden
   ```

2. Create your environment file:
   ```bash
   cp .env.example .env
   # Edit .env and add your Discord token
   ```

3. Start with Docker Compose:
   ```bash
   docker compose up -d
   ```
4. Open the dashboard (if configured): `http://localhost:8080`

### Local Development

1. Create a virtual environment:
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

2. Install dependencies:
   ```bash
   pip install -e ".[dev,ai]"
   ```

3. Set up environment variables:
   ```bash
   cp .env.example .env
   # Edit .env with your configuration
   ```

4. Start PostgreSQL (or use Docker):
   ```bash
   docker compose up db -d
   ```

5. Run the bot:
   ```bash
   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)
- 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 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:
   ```bash
   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

## Development

### Running Tests

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

### Code Quality

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

## License

MIT License - see LICENSE file for details.

## Roadmap

- [x] AI-powered content moderation (Claude/OpenAI integration)
- [x] NSFW image detection
- [x] Verification/captcha system
- [x] Rate limiting
- [ ] Voice channel moderation
- [x] Web dashboard