A comprehensive, open-source self-hosted Discord bot for managing school communities. Features a secure student verification system, modern React-based admin dashboard with real-time updates, advanced analytics, warning management, ticket system, and multi-language support—all containerized with Docker and backed by MongoDB.
Repository: GitHub - MoritzKlasen/OpenSDB
- Overview
- Core Features
- Architecture
- Prerequisites
- Quick Start
- Configuration Guide
- Slash Commands Reference
- Admin Dashboard
- Anti-Scam Detection System
- Ticket System
- Localization
- Developing Locally
- Logging and Monitoring
- Troubleshooting
- Security Considerations
- Contributing
OpenSDB is designed specifically for school Discord servers to:
- Verify student identities and assign them appropriate roles
- Monitor server behavior with a banned words filter and warning system
- Manage administrative tasks through a modern React-based web dashboard with real-time updates
- Support multi-language environments (English, German, Spanish, French, Italian, Turkish, Chinese built-in)
- Create support and verification workflows via ticket systems with automatic channel management
- Track and report user activity, verification metrics, and warning trends through interactive analytics
- Bulk manage users with CSV import/export for batch operations and data migration
The entire system runs in Docker containers for easy deployment and scaling, with Nginx reverse proxy providing SSL/TLS termination and WebSocket support.
- Student Verification – Verify users with their first and last name, automatically assigning verification numbers and roles
- Unverification – Remove verification status and associated roles when needed
- User Comments – Add contextual notes to verified students (e.g., accommodations, issues)
- Deanonymization – View student's real name and recent warnings (admin/team only)
- Prohibited Word Filter – Automatically detect banned words and notify admins
- Warning System – Issue, track, and delete warnings per student
- Admin Notifications – Get real-time alerts in a dedicated admin channel with quick action buttons
- Comment Prompts – Add notes directly from ban notifications
- Anti-Scam Detection – Dual-engine scam detection (rule-based + AI) with multilingual keyword matching, link analysis, behavioral anomaly detection, image scanning, auto-delete, and auto-timeout
- WebSocket Integration – Live dashboard updates without page refreshes
- Multi-user Synchronization – Changes made by one admin appear instantly on all other connected sessions
- Instant User List Updates – New verifications appear immediately in admin panel
- Live Analytics – Real-time user growth and warning metrics
- Ticket System – Students can create support tickets or verification requests
- Auto-role Assignment – Assign roles to new members or upon verification
- Team Role Management – Designate team members with elevated permissions
- Role Customization – Configure separate roles for teams, verified users, and new members
- Multi-language Support – 7 built-in languages (English, German, Spanish, French, Italian, Turkish, Chinese) with per-server language settings
- Localized Message Updates – Language changes automatically update all bot messages deployed in tracking system
- CSV Import/Export – Bulk import student data or export verified users with warnings for analysis and backup
- Metrics API – Track verification rates and warning trends with JSON/CSV endpoints for Grafana integration
- Message Tracking – Bot tracks and manages message updates for automatic localization across all languages
- Real-time Admin Dashboard – Modern React frontend with WebSocket support for live user and warning updates
- Interactive Analytics – Charts for user growth trends and warning activity patterns
- Secure Admin UI – JWT-authenticated web dashboard with HTTPS/SSL support and CORS protection
- AI-Powered Scam Detection – Multi-provider AI support (OpenAI, Ollama, OpenRouter, Anthropic) with vision model routing for image analysis
┌──────────────────────────────────────────────────────┐
│ Nginx Reverse Proxy │
│ (SSL/TLS, WebSocket Support) │
└─────────────────────┬────────────────────────────────┘
│
┌─────────────┴──────────────┐
│ │
┌───────▼────────┐ ┌────────▼──────────┐
│ Discord Bot │ │ Admin Web App │
│ (Node.js + │ │ (Node.js + │
│ discord.js) │ │ Express) │
│ │ │ │
│ • Processes │ │ • React Frontend │
│ commands │ │ (Vite build) │
│ • Monitors │ │ • Real-time WS │
│ messages │ │ • User Management │
│ • Manages │ │ • Analytics │
│ roles & warn │ │ • CSV Import/Exp │
│ │ │ │
│ Memory: 256M │ │ Memory: 128M │
│ CPU: 0.50 │ │ CPU: 0.25 │
└────────┬───────┘ └────────┬──────────┘
│ │
└──────────────┬───────────┘
│
┌────▼─────┐
│ MongoDB │
│ (mongo:7) │
│ │
│ Database │
│ Port:27017│
│ (internal)│
└───────────┘
| Component | Technology | Version | Purpose |
|---|---|---|---|
| Bot Runtime | Node.js | 20-slim | Discord bot execution |
| Web UI Runtime | Node.js | 20-alpine | Admin dashboard backend |
| Discord Library | discord.js | 14.25+ | Discord bot interactions |
| Web Framework | Express.js | 5.2+ | REST API and admin UI server |
| Frontend Framework | React | 18+ | Modern UI components |
| Frontend Build | Vite | 5.0+ | Fast, optimized builds |
| Styling | Tailwind CSS | 3.0+ | Utility-first CSS |
| Charts | Recharts | 2.0+ | Interactive data visualization |
| Real-time | WebSocket | 8.14+ | Live dashboard updates |
| Database | MongoDB | 7 | User and settings storage |
| Reverse Proxy | Nginx | alpine | SSL/TLS termination, load balancing |
| Authentication | JWT + bcrypt | node packages | Secure auth tokens and password hashing |
| Language Locales | JSON | en, de, es, fr, it, tr, zh | Multi-language support |
- Git – For cloning the repository
- Docker & Docker Compose – Install Docker Desktop or Docker + Compose
- Discord Bot Token – Create application at Discord Developer Portal
- Server ID – Your Discord guild ID (enable Developer Mode, right-click server > Copy Server ID)
- OpenSSL – For generating self-signed HTTPS certificates (macOS/Linux: usually pre-installed)
- Node.js – Only if developing locally without Docker; use the version required by the project's
package.json/enginessetting and supported dependencies
- Minimum: 512MB RAM, 1 CPU core
- Recommended: 1GB RAM, 2 CPU cores
- Disk: 1GB free (including MongoDB data growth)
git clone https://github.com/MoritzKlasen/OpenSDB.git
cd OpenSDBCreate .env in the project root with your configuration:
Option A: Copy the example file (recommended)
cp .env.example .envThen edit .env with your values. Alternatively, create it manually:
# Discord Configuration (obtain from Developer Portal)
DISCORD_TOKEN=your-bot-token-here
CLIENT_ID=your-application-id-here
ALLOWED_GUILD_ID=your-server-id-here
# Database
DB_URI=mongodb://mongo:27017/botdb
# Admin UI Credentials
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-strong-password-here
JWT_SECRET=your-random-secret-here
INTERNAL_SECRET=botInternalSecret123
# Server Configuration
ADMIN_UI_PORT=8001
NODE_ENV=production
# Optional: Metrics API Authentication
METRICS_BASIC_USER=grafana
METRICS_BASIC_PASS=changeMe!
# Optional: Email/CORS settings
CORS_ORIGINS=https://yourdomain.comNote:
CORS_ORIGINSmust be an explicit list of allowed origins — wildcard*is not permitted when credentials are enabled.
Option B: Command line (Mac/Linux)
cp .env.example .env
# Then edit with your preferred editor:
nano .env
⚠️ Security Warning: Never commit.envto version control. It's already in.gitignore.
# Build and start all services in the background
docker compose up --build -d
# Verify services are running
docker compose psAll services will start automatically: Discord bot, admin dashboard, MongoDB database, and Nginx reverse proxy.
Local development (Docker Compose):
https://localhost/login
Note: Browser may show SSL warning (self-signed certificate). This is normal for local development. Click "Advanced" → "Proceed".
Remote server:
http://YOUR-SERVER-IP/login (first time setup)
https://YOUR-SERVER-IP/login (after SSL setup)
Login with:
- Username: value of
ADMIN_USERNAMEfrom.env - Password: value of
ADMIN_PASSWORDfrom.env
Wait 10-15 seconds for all services to initialize, then check:
# View bot startup logs
docker compose logs bot --tail 20
# Verify all services are running
docker compose psYou should see all 4 services (bot, web, nginx, mongo) in the Up status. Discord slash commands will automatically register when the bot connects to your server for the first time.
| Variable | Purpose | Required | Example |
|---|---|---|---|
DISCORD_TOKEN |
Bot authentication token from Developer Portal | ✅ | ABCDEFGHIJKLMNOPQRSTUVWXYZ.ZYXWU... |
CLIENT_ID |
Discord application ID | ✅ | 12345678998765432131 |
ALLOWED_GUILD_ID |
Restrict bot to one Discord server | ✅ | 12345678998765432131 |
DB_URI |
MongoDB connection string | ✅ | mongodb://mongo:27017/botdb |
ADMIN_USERNAME |
Dashboard login username | ✅ | admin |
ADMIN_PASSWORD |
Dashboard login password (16+ chars recommended) | ✅ | MyS3curePass123! |
ADMIN_PASSWORD_HASH |
Pre-hashed bcrypt password (alternative to plaintext) | Optional | $2b$10$... |
JWT_SECRET |
JWT signing secret (random 32+ chars) | ✅ | Generate with command below |
INTERNAL_SECRET |
Shared secret between bot and admin (random) | ✅ | botInternalSecret123 |
NODE_ENV |
Environment mode | Optional | production |
ADMIN_UI_PORT |
Dashboard port inside container | Optional | 8001 |
CORS_ORIGINS |
Allowed CORS origins (comma-separated, no wildcards) | Optional | https://yourdomain.com |
METRICS_BASIC_USER |
Metrics API basic auth username | ✅ Required | grafana |
METRICS_BASIC_PASS |
Metrics API basic auth password | ✅ Required | changeMe! |
SERVER_TIMEZONE |
Default timezone for analytics/metrics | Optional | UTC |
ADMIN_SERVER_URL |
URL the bot uses to notify the admin server (needed outside Docker) | Optional | http://web:8001 |
For production deployments, generate strong random secrets:
On Mac/Linux:
# Generate JWT_SECRET and INTERNAL_SECRET
openssl rand -base64 32 # Run twice, use output for each secretOn Windows (PowerShell):
[Convert]::ToBase64String((1..32 | ForEach-Object { [byte](Get-Random -Max 256) }))
# Run twice for both secrets- Go to Discord Developer Portal
- Click "New Application" and name it
- Go to "Bot" tab → Click "Add Bot"
- Under "TOKEN" → Click "Copy" and paste into
DISCORD_TOKENin.env - Go to "OAuth2" tab → Click "URL Generator"
- Check scope:
bot - Check permissions:
Administrator - Copy the generated URL
- Check scope:
- Open the URL in browser to invite bot to your server
- In Discord, enable Developer Mode (Settings → Advanced → Developer Mode)
- Right-click your server name → "Copy Server ID" → paste into
ALLOWED_GUILD_ID
For HTTPS support on production servers:
cd nginx/certs
# Generate self-signed certificate (valid 1 year)
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout opensdb.key -out opensdb.crt \
-config ../openssl.cnf
cd ../..
# Rebuild containers to apply new certificates
docker compose down
docker compose up --build -dNote: Self-signed certificates work for testing but show browser warnings. For production, purchase proper certificates from a Certificate Authority.
The bot uses Discord's slash commands for all interactions. Commands are admin-restricted unless otherwise noted.
Verify a student and assign them a verification number and role.
- Permissions: Server Owner, Team Role
- Result: Student receives verified role, verification number assigned
- Database: Stores name, Discord tag, ID, and verification date
Remove verification status and associated roles from a student.
- Permissions: Server Owner, Team Role
- Result: All non-managed roles removed, on-join role restored, database record deleted
- Note: This removes all roles from the user, including any manually assigned ones unrelated to verification.
Issue a warning to a verified student.
- Permissions: Server Owner, Team Role
- Requirements: User must be verified
- Notifications: Sends DM to user notifying them
- Database: Stores reason, issuer, timestamp
Add or update contextual notes about a student.
- Permissions: Server Owner, Team Role
- Requirements: User must be verified
- Use Cases: Behavioral notes, accommodations, special circumstances
Display a verified user's real name and recent warnings (privileged view).
- Permissions: Everyone can view basic info; Server Owner/Team see full details (comments + warnings)
- Requires: User must be verified
- Shows: Name, Discord tag, last 3 warnings with issuer and date
Add a word to the banned words filter.
- Permissions: Server Owner, Team Role
- Effect: Future messages containing this word trigger admin notifications
Remove a word from the banned words filter.
- Permissions: Server Owner, Team Role
Configure roles for different user statuses.
- Permissions: Server Owner, Administrator, Team Role
- Options:
teamrole: Users with this role can manage botverifiedrole: Role given to verified studentsonjoinrole: Role auto-assigned to new members (removed upon verification)
- Note: At least one role required
Set the channel where banned word alerts are sent.
- Permissions: Server Owner, Administrator, Team Role
- Alerts Include: User mention, channel, message preview, quick action buttons
Display the current server language setting.
- Permissions: Everyone
Change the server's language (affects all bot responses and messages instantly).
- Permissions: Administrator, Server Owner, Team Role
- Options:
en(English),de(German),es(Spanish),fr(French),it(Italian),tr(Turkish),zh(Chinese Simplified) - Effect: Updates all localized messages in real-time
Create a ticket panel with a button for students to open support or verification requests.
- Type:
supportorverify - Category: Category where new tickets will be created
- Overrides: Optional custom title, description, button text
- Features:
- Auto-creates private channels per user
- Team members automatically get access
- Closed tickets remain visible to team only
- Messages are language-tracked for automatic translation
Enable or disable the anti-scam detection system for the server.
- Permissions: Administrator, Server Owner, Team Role
Set the detection engine.
- Options:
default(rule-based) orai(AI-powered with fallback to default)
Set detection sensitivity.
- Options:
low(score ≥60),medium(score ≥40),high(score ≥20)
Set the channel where scam detection alerts are posted.
Toggle automatic deletion of detected scam messages.
Toggle automatic timeout for users posting scam content.
- Duration: 1–40320 minutes (default: 60)
Exempt a user from scam detection.
Whitelist a domain from link analysis.
Configure a single AI provider for scam analysis.
- Providers:
openai,ollama,openrouter,anthropic
Configure separate text and vision AI models for enhanced detection (e.g., text analysis with one model, image analysis with another).
- Options:
text-provider,text-model,text-baseurl,vision-provider,vision-model,vision-baseurl, plus optional API keys and timeouts
Test the configured AI provider connection and verify it's working.
Show detection statistics.
- Periods:
24h,7d,30d,all
Display the current anti-scam configuration, detection mode, sensitivity, AI health status, and whitelist entries.
The admin dashboard is a modern, production-ready React-based web interface built with Vite that provides secure, real-time access to user management and analytics. Access it via the Nginx reverse proxy at /login.
- Real-time Updates – WebSocket integration for live user and warning data without page refresh
- Modern UI – Built with React 18 and Tailwind CSS for a responsive, intuitive interface
- Fast Performance – Optimized with Vite for instant page loads and smooth interactions
- Secure Access – JWT-based authentication with automatic 1-hour session expiry
- Secure Login: Username and password authentication with JWT tokens
- Session Management: 1-hour token expiry with automatic logout
- HTTPS Ready: Works with Nginx reverse proxy and SSL certificates
-
Real-time User List – WebSocket-powered list that updates instantly when new users are verified
-
Live Search – Debounced search by Discord tag, ID, first name, or last name with instant results
-
Visual Warning Badges – Quick overview of warning counts for each user
-
Click to View Details – Select any user to display full profile information
-
User Detail Panel:
- User profile information (Discord tag, ID, real name, verification date)
- Comments Section: View and edit user comments with save/cancel
- Warning History: Structured warning cards showing:
- Reason for warning
- Issued by (admin/moderator name)
- Exact timestamp of warning
- Delete Warnings: Remove specific warnings with confirmation modal
- Real-time Sync – Changes broadcast to all connected admin sessions
-
Export CSV: Download all verified users with warnings as JSON array
- Columns:
verificationNumber,discordTag,discordId,firstName,lastName,comment,warnings,verifiedAt - Excel-compatible with UTF-8 BOM
- Columns:
-
Import CSV: Bulk upload and upsert user data
- Maximum file size: 5MB, CSV files only
- Validates required columns (
discordId) and Discord ID format - Matches by
discordIdfor updates - Preserves existing verification dates if not specified
- User Growth Chart – Interactive line chart showing cumulative user registration over time (default: last 90 days)
- Warning Activity Chart – Bar chart displaying warnings issued by day to identify moderation trends
- Summary Metrics:
- Total registered users
- New users added this month
- Total warnings issued this month
- Real-time metric updates via WebSocket
- Date Range Selection – Customizable time windows for focused analysis
The admin dashboard is built with modern, professional-grade tools:
| Component | Technology | Purpose |
|---|---|---|
| Frontend | React 18 | Component-based UI framework |
| Styling | Tailwind CSS | Utility-first CSS framework |
| Charts | Recharts | Interactive data visualization |
| HTTP Client | Axios | API communication with credentials support |
| Build Tool | Vite | Fast frontend development and production builds |
| Routing | React Router v6 | Client-side navigation |
| Endpoint | Method | Auth | Purpose |
|---|---|---|---|
/api/login |
POST | None | Authenticate with username/password |
/api/verified-users |
GET | JWT | Fetch all verified users |
/api/remove-warning/:discordId/:index |
DELETE | JWT | Delete specific warning by index |
/api/export-users |
GET | JWT | Download CSV of all users |
/api/import-users |
POST | JWT | Upload and import CSV file |
/api/dashboard/users-growth |
GET | JWT | User registration metrics (JSON) |
/api/dashboard/warnings-activity |
GET | JWT | Warning activity metrics (JSON) |
/api/dashboard/alerts-activity |
GET | JWT | Scam detection alerts activity over time |
/api/analytics/warnings-per-day |
GET | JWT | Warnings per day analytics |
/api/settings/server |
GET | JWT | Fetch complete server settings (roles, channels, language, anti-scam config) |
/api/settings/server |
PUT | JWT | Update server settings (sanitized response) |
/api/settings/banned-words |
GET | JWT | Fetch all banned words as array |
/api/settings/banned-words |
POST | JWT | Add new banned word |
/api/settings/banned-words/:word |
DELETE | JWT | Remove banned word from filter |
/api/monitoring/health |
GET | None | Application health status and uptime |
/api/monitoring/security-events |
GET | JWT | Security audit events (query: ?hours=24) |
/api/monitoring/errors |
GET | JWT | Error logs from past N hours (query: ?hours=24) |
/api/metrics/users-per-day.json |
GET | BasicAuth | User registration metrics (Grafana) |
/api/internal/notify-change |
POST | HMAC | Internal bot→admin notification |
/logout |
GET | Any | Clear session and logout |
WebSocket /ws |
WS | JWT | Real-time updates (user changes, warnings, verifications) |
- Login: Access
/loginand authenticate with admin credentials - View Users: Browse verified users in the left panel with real-time search
- Select User: Click a user to view their full profile and complete history
- Manage Warnings: View warning cards and delete as needed (confirmation required)
- Edit Comments: Add contextual notes (accommodations, issues, follow-ups) with instant save
- Analytics: Check user growth trends and moderation activity on dedicated analytics page
- Import/Export: Manage bulk data operations for backup or data migration
- Real-time Sync: Multiple admin sessions stay synchronized via WebSocket; changes appear instantly
OpenSDB includes a comprehensive dual-engine scam detection system that monitors messages in real-time for phishing attempts, spam, and malicious content.
The built-in detection engine uses multiple heuristics scored by weighted risk:
- Suspicious Domain Detection – Identifies phishing TLDs, known scam domains, and URL shorteners
- Punycode/IDN Homograph Attack Detection – Catches visually similar domains designed to deceive
- Multilingual Keyword Matching – High-risk, medium-risk, and single-word categories loaded from locale files
- Content Hashing & Deduplication – MD5-based detection of duplicate/spam messages across channels
- Image Hash Deduplication – Identifies repeated image attachments
- Fuzzy String Comparison – Levenshtein distance matching (>0.8 similarity threshold) to catch slight message variations
- Behavioral Anomaly Detection – Flags new accounts, first messages with links, activity spikes, and cross-channel posting
- Excessive Capitalization & Special Character Detection
Optional AI-powered analysis with multi-provider support:
- Supported Providers: OpenAI, Ollama (self-hosted), OpenRouter, Anthropic/Claude, plus generic fallback
- Multi-Model Routing – Automatically uses text model for text messages and vision model for images
- Vision Model Support – Analyzes images from Discord CDN (QR codes, fake promotions, etc.)
- Structured Classification –
likely scam,suspicious, orlikely safewith confidence scoring (0–100) - Automatic Fallback – Falls back to the default engine if AI is unavailable or fails
- Health Check System – Monitors provider availability
- Custom Provider Registration – Extensible provider registry for additional AI services
For advanced use cases, configure separate models for text and image analysis:
Single Model Setup (uses same model for all content):
/antiscam ai-configure provider:ollama model:qwen2.5:7b baseurl:http://host.docker.internal:11434Ollama on the Docker host: inside the bot container
localhostis the container itself. Usehttp://host.docker.internal:11434(mapped indocker-compose.yml) and make sure Ollama listens on all interfaces (OLLAMA_HOST=0.0.0.0). Ollama needs no API key. Tested withqwen2.5:7b(text) andqwen2.5vl:7b(vision).
Multi-Model Setup (optimized for different content types):
# Configure separate text and vision models
/antiscam ai-configure-multimodel \
text-provider:ollama \
text-model:llama3 \
text-baseurl:http://localhost:11434 \
vision-provider:openai \
vision-model:gpt-4o \
vision-baseurl:https://api.openai.com/v1 \
vision-apikey:sk-your-key-hereBenefits:
- Cost Optimization – Use cheaper models for text, premium models for vision
- Performance Tuning – Specialized models for each content type
- Reliability – Mix self-hosted and cloud providers
- Automatic Routing – Bot automatically selects appropriate model based on message content
Both engines produce a combined risk score (0–100) from weighted components:
- Spam Score – Duplicate/repetition indicators
- Pattern Score – Keyword and text pattern matches
- Link Score – Suspicious URLs and domains
- Anomaly Score – Behavioral signals
| Risk Level | Score Range | Color |
|---|---|---|
| LOW | 0–39 | Green |
| MEDIUM | 40–59 | Yellow |
| HIGH | 60–79 | Orange |
| CRITICAL | 80–100 | Red |
- Admin Alerts – Rich embeds posted to the configured alert channel with spam count, detection mode, risk level, reasons, extracted links, and AI analysis details
- Alert Action Buttons – View Message, Delete All, Timeout 1h, Timeout 24h, Dismiss
- Auto-Delete – Automatically removes detected scam messages (configurable)
- Auto-Timeout – Temporarily mutes users posting scam content (configurable duration: 1–40320 minutes)
- Spam Staging – Groups identical messages by user and content hash; alerts after threshold (3 duplicates, or 1 for previously-flagged content)
- Detection Caching – 5-minute TTL cache prevents redundant analysis of the same content
Every detection event is logged to the ScamDetectionEvent collection with full context:
- Message content, channel, user, and guild identifiers
- Detection mode used and whether fallback was triggered
- AI metadata (provider, model, classification, confidence, reason)
- Risk score, risk level, detection reasons, extracted links/domains
- Action taken (none/flagged/deleted/timedout) and alert status
User behavioral data is tracked in the UserActivity collection for anomaly detection.
# Enable anti-scam with default detection
/antiscam enable
/antiscam alert-channel #scam-alerts
/antiscam sensitivity medium
# Optional: Enable AI mode with Ollama (self-hosted)
/antiscam mode ai
/antiscam ai-configure provider:ollama model:qwen2.5:7b baseurl:http://host.docker.internal:11434
/antiscam ai-test
# Optional: Enable auto-actions
/antiscam auto-delete enabled:True
/antiscam auto-timeout enabled:True duration:60The anti-scam system has many configurable thresholds and behaviors accessible via the /api/settings/server endpoint or stored in the ServerSettings database model:
| Setting | Description | Default | Configured Via |
|---|---|---|---|
enabled |
Enable/disable scam detection | false |
/antiscam enable/disable |
mode |
Detection engine (default or ai) |
default |
/antiscam mode |
sensitivity |
How strictly the rule-based engine scores (low/medium/high) | medium |
/antiscam sensitivity |
alertChannelId |
Where alerts are posted | null |
/antiscam alert-channel |
autoDelete |
Auto-delete detected scam messages | false |
/antiscam auto-delete |
autoTimeout |
Auto-timeout users posting scams | false |
/antiscam auto-timeout |
autoTimeoutDuration |
Timeout duration in minutes (1-40320) | 60 |
/antiscam auto-timeout |
minRiskScoreForAlert |
Minimum score to trigger alert | 45 |
Admin dashboard (Anti-Scam → Advanced) |
minRiskScoreForAutoAction |
Minimum score for auto-delete/timeout | 80 |
Admin dashboard (Anti-Scam → Advanced) |
duplicateMessageThreshold |
Spam threshold (duplicate messages) | 3 |
Admin dashboard (Anti-Scam → Advanced) |
duplicateTimeWindow |
Time window for spam detection (minutes) | 2 |
Admin dashboard (Anti-Scam → Advanced) |
accountAgeRequirement |
Flag new accounts (days) | 7 |
Admin dashboard (Anti-Scam → Advanced) |
firstMessageSuspicion |
Flag first messages with links | true |
Admin dashboard (Anti-Scam → Advanced) |
trustedUserIds |
User IDs exempt from detection | [] |
/antiscam whitelist-user |
trustedDomains |
Whitelisted domains | [] |
/antiscam whitelist-domain |
AI-Specific Settings:
| Setting | Description | Default | Configured Via |
|---|---|---|---|
aiSettings.enabled |
Enable AI analysis | false |
/antiscam mode ai |
aiSettings.provider |
AI provider name | null |
/antiscam ai-configure |
aiSettings.model |
Primary model identifier | null |
/antiscam ai-configure |
aiSettings.baseUrl |
API endpoint URL | null |
/antiscam ai-configure |
aiSettings.apiKey |
Authentication key | null |
/antiscam ai-configure |
aiSettings.timeout |
Request timeout (ms) | 30000 |
/antiscam ai-configure |
aiSettings.textModel.* |
Separate text analysis model config | Inherits from main | /antiscam ai-configure-multimodel |
aiSettings.visionModel.* |
Separate vision analysis model config | Inherits from main | /antiscam ai-configure-multimodel |
aiSettings.notifyAdminsOnFallback |
Alert when AI fails | true |
Database only |
aiSettings.healthCheckEnabled |
Monitor AI provider health | true |
Database only |
aiSettings.healthCheckInterval |
Health check frequency (ms) | 3600000 |
Database only |
AI health monitoring:
- The bot checks the configured AI model(s) every
healthCheckInterval(default 1 h) and on every AI detection;/antiscam ai-testalso records its result. - When the provider becomes unreachable (or recovers), one message is posted to the alert channel – not one per fallback. Disable with
notifyAdminsOnFallback: false. /antiscam statusshows the current status and the time of the last check.
Thresholds and sensitivity:
- An alert is sent when the risk score reaches
minRiskScoreForAlert; auto-delete/auto-timeout (if enabled) trigger atminRiskScoreForAutoAction. sensitivitychanges how the rule-based engine scores keywords and links (high = more points per match); it does not change the thresholds.- AI verdicts are mapped onto the same 0–100 scale: likely scam 50–100, suspicious 30–60, likely safe 0–20 (scaled by the model's confidence), so a confident scam verdict reaches CRITICAL and the default auto-action threshold of 80.
- Detection reasons in alerts are shown in the server language (rule-based reasons via
scamReasonsin the locale files; AI models are asked to answer in that language). - Links whose domain imitates Discord, Steam, Roblox or Epic Games (including misspellings like
dlscord) are flagged unless they are an official domain of that brand (e.g.discord.gift,steampowered.com). Brands and official domains are listed inimpersonatedBrandsindefaultDetectionEngine.js. - Messages are pre-filtered with English phrases plus the scam phrases of the server language (
scamKeywordsinsrc/locales/<lang>.json), so non-English scams also reach full detection.
Ticket panels allow students to create support requests or verification channels.
- Admin Creates Panel:
/ticketpanel support #support-tickets - Button Appears: Students see a button to "Open Ticket"
- Private Channel Created: Named
support-[username]orverify-[username] - Permissions:
- Student can view and message
- Team role members auto-added
- Others cannot see the channel
- Closing: Student or team clicks "Close Ticket"
- Channel name becomes
🔒-[original-name] - Student loses access (team retains access for records)
- Channel name becomes
Channels store metadata in the topic:
status:open; type:support; opener:123456789
This allows the bot to track ticket state and ownership.
Ticket messages are automatically tracked and updated when server language changes.
OpenSDB supports multiple languages with real-time language switching. Built-in: English, German, Spanish, French, Italian, Turkish, and Chinese (Simplified).
Each server has its own language setting (stored in MongoDB).
- Default: English
- Change Command:
/language set [lang] - Supported Languages:
en– Englishde– Deutsch (German)es– Español (Spanish)fr– Français (French)it– Italiano (Italian)tr– Türkçe (Turkish)zh– 简体中文 (Chinese Simplified)
- Create
/src/locales/[lang].json(e.g.,fr.jsonfor French) - Add language code to
SUPPORTEDset insrc/utils/i18n.js - Add subcommand choices in
/src/commands/setlanguage.js - Restart the bot
{
"language": { "current": "...", "setSuccess": "..." },
"errors": { "noPermission": "..." },
"ticketPanel": {
"support": { "title": "...", "desc": "...", "button": "..." },
"verify": { ... }
},
...
}Use placeholders: {userName}, {reason}, etc.
Recommended for developers only. For normal deployment, use Docker Compose (see Quick Start).
- Node.js 20+ – Download
- MongoDB 7+ – Community Edition or run via Docker
- Git – Download
For fastest local development, run only MongoDB in Docker:
# 1. Clone and install
git clone https://github.com/MoritzKlasen/OpenSDB.git
cd OpenSDB
npm install
cd frontend && npm install && cd ..
# 2. Start only MongoDB in Docker
docker run -d --name opensdb-mongo -p 27017:27017 mongo:7
# 3. Create .env file
# Create a new .env file with:
# DB_URI=mongodb://localhost:27017/botdb
# Plus other required variables (DISCORD_TOKEN, CLIENT_ID, etc.)
# 4. Run services locally (in separate terminals)
# Terminal 1: Bot
node src/index.js
# Terminal 2: Admin UI server
node src/admin-server.js
# Dashboard: http://localhost:8001
# To stop:
# - Press Ctrl+C in both terminals
# - docker stop opensdb-mongo
# - docker rm opensdb-mongoMongoDB connection fails:
# Check if MongoDB container is running
docker ps | grep mongo
# If not, restart it
docker start opensdb-mongoPort already in use:
# Use different port for Bot or MongoDB
DB_URI=mongodb://localhost:27018/botdb # different portOpenSDB/
├── src/
│ ├── index.js # Bot entry point
│ ├── admin-server.js # Web UI server
│ ├── loadCommands.js # Command loader
│ ├── commands/ # Slash command definitions
│ │ ├── antiscam.js # Anti-scam config (15 subcommands)
│ │ ├── verify.js
│ │ ├── warn.js
│ │ ├── ticketpanel.js
│ │ └── ...
│ ├── events/ # Discord event handlers
│ │ ├── handleInteractions.js # Button/modal/command logic
│ │ ├── handleAntiScam.js # Scam detection + alerts
│ │ ├── handleBannedWords.js # Message filtering
│ │ └── guildMemberAdd.js # Auto-role on join
│ ├── database/
│ │ ├── connect.js # MongoDB connection
│ │ └── models/ # Mongoose schemas
│ │ ├── VerifiedUser.js
│ │ ├── ServerSettings.js
│ │ ├── BannedWord.js
│ │ ├── LocalizedMessage.js
│ │ ├── ScamDetectionEvent.js
│ │ └── UserActivity.js
│ ├── utils/
│ │ ├── botNotifier.js # HMAC-signed internal notifications
│ │ ├── envValidator.js # Zod-based env validation
│ │ ├── i18n.js # Translation helper
│ │ ├── localizedSend.js # Send + track messages
│ │ ├── logger.js # Structured JSON logging
│ │ ├── security.js # Helmet, rate limiting, CORS
│ │ ├── ticketPanelRenderer.js
│ │ ├── updateLocalizedMessages.js
│ │ ├── websocket.js # JWT-authenticated WebSocket server
│ │ └── scamDetection/ # Anti-scam engines
│ │ ├── aiDetectionEngine.js # AI provider integration
│ │ ├── defaultDetectionEngine.js # Rule-based heuristics
│ │ └── scamKeywords.js # Multilingual keyword loader
│ └── locales/
│ ├── en.json # English translations
│ ├── de.json # German translations
│ ├── es.json # Spanish translations
│ ├── fr.json # French translations
│ ├── it.json # Italian translations
│ ├── tr.json # Turkish translations
│ └── zh.json # Chinese (Simplified) translations
├── frontend/ # React admin dashboard
│ ├── src/
│ │ ├── App.jsx # Router and layout
│ │ ├── components/ # Reusable UI components
│ │ ├── context/ # Auth context provider
│ │ ├── hooks/ # WebSocket and auto-refresh hooks
│ │ ├── pages/ # Login, Dashboard, Analytics pages
│ │ └── utils/ # API client and logger
│ ├── package.json
│ └── vite.config.js
├── deploy-commands.js # Manual command registration (debugging)
├── docker-compose.yml # Service orchestration
├── Dockerfile.bot # Bot container
├── Dockerfile.web # Web UI container
├── nginx/
│ ├── nginx.conf # Reverse proxy config
│ ├── ssl_params.conf # SSL/TLS settings
│ ├── openssl.cnf # Certificate generation config
│ └── certs/ # (Git-ignored) SSL certificates
├── package.json # Dependencies
├── .env # (Git-ignored) Configuration
├── .env.example # Template with all required variables
└── README.md
- Commands:
/src/commands/*.js– Add new slash commands here - Events:
/src/events/*.js– Modify bot behavior - Scam Detection:
/src/utils/scamDetection/*.js– Customize detection engines and keywords - Locales:
/src/locales/*.json– Add/edit translations (including scam keywords) - Frontend:
/frontend/src/– React dashboard components, pages, and hooks - Database Models:
/src/database/models/*.js– Extend data schema
OpenSDB includes comprehensive logging and monitoring capabilities for tracking application activity, debugging issues, and auditing security events.
The application maintains three types of logs (stored in /tmp/logs inside the container):
- app.log – General application activity, API requests, server events
- security.log – Security audit trail, login attempts, authentication failures
- error.log – Errors and exceptions
All logs are in JSON format for easy parsing and integration with log aggregation services.
Access logs and application health through REST endpoints:
# Health check (no auth required)
GET /api/monitoring/health
# Security events (admin only)
GET /api/monitoring/security-events?hours=24
# Error logs (admin only)
GET /api/monitoring/errors?hours=24On startup, the application validates all required environment variables and checks for weak defaults in production. This prevents accidental deployment with test credentials.
Production requirement: Generate strong secrets using:
openssl rand -base64 32# View logs from running container
docker compose exec web cat /tmp/logs/app.log
docker compose exec web cat /tmp/logs/security.log
# Backup logs before container restart
mkdir -p logs-backup-$(date +%s)
docker compose cp web:/tmp/logs logs-backup-$(date +%s)/-
Verify services are running:
docker compose ps
All 4 services (bot, web, nginx, mongo) should show Status: Up.
-
Check bot permissions:
- In Discord Server Settings → Integrations → OpenSDB
- Ensure the bot has Administrator or at least Manage Roles permission
-
Verify environment variables:
# Check .env file for correct values cat .env | grep DISCORD_TOKEN cat .env | grep CLIENT_ID cat .env | grep ALLOWED_GUILD_ID
-
View bot logs:
docker compose logs bot --tail 50
-
Check web service:
docker compose ps
-
View web server logs:
docker compose logs web --tail 50
-
Test dashboard directly:
- Local:
http://localhost/login - Remote:
http://YOUR-SERVER-IP/login
- Local:
-
Clear browser cache:
- Press Ctrl+Shift+Delete (or Cmd+Shift+Delete on Mac)
- Clear all cookies and cache for the domain
- Copy the TOKEN, not the Application ID
- Generate a new token if the current one was exposed
- Allow 5-10 seconds for changes to take effect
- Clear browser cookies
- Verify
ADMIN_USERNAMEandADMIN_PASSWORDin.env - Restart services:
docker compose restart web
# View MongoDB logs
docker compose logs mongo --tail 20
# Restart MongoDB
docker compose restart mongo# Check which process is using a port
lsof -i :80 # macOS/Linux with lsof installed
ss -tulpn | grep :80 # Linux (modern alternative)
netstat -tulpn | grep :80 # Linux (older systems)
netstat -an | findstr :80 # Windows
# Stop the conflicting process or change ports in docker-compose.yml# Remove old certificates
rm -rf nginx/certs/*
# Generate new certificate
cd nginx/certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout opensdb.key -out opensdb.crt \
-config ../openssl.cnf
cd ../..
# Restart services
docker compose down
docker compose up --build -dRestart all services:
docker compose restartStop all services (to save resources):
docker compose downRestart specific service:
docker compose restart bot # or: web, mongo, nginxView logs from all services:
docker compose logs --tail 20 # Last 20 lines
docker compose logs -f # Follow in real-time (Ctrl+C to exit)View specific service logs:
docker compose logs bot --tail 50 # Bot logs
docker compose logs web --tail 50 # Web dashboard
docker compose logs mongo --tail 50 # Database
docker compose logs nginx --tail 50 # Reverse proxyBackup database:
# Create backup directory
mkdir -p backups
# Export MongoDB data
docker compose exec mongo mongodump --out /tmp/dump
docker compose cp mongo:/tmp/dump ./backups/mongodb-$(date +%s)Restore from backup:
docker compose cp ./backups/mongodb-[timestamp]/dump mongo:/tmp/
docker compose exec mongo mongorestore /tmp/dump- Admin Credentials: Use strong passwords (16+ characters, mixed case, numbers, symbols)
- JWT Secret: Generate with
openssl rand -base64 32 - Never commit
.env: Ensure.gitignoreincludes it - Token Expiration: Admin sessions expire after 1 hour; requires re-login
- HTTPS/SSL: Use self-signed certificates for development, proper CA certificates for production
- Nginx Reverse Proxy: Handles TLS termination with security headers and gzip
- Docker Network: Services communicate over internal bridge network with custom subnet
- Port Exposure: Only expose ports 80/443; keep MongoDB port 27017 internal
- Container Hardening: Read-only filesystems,
cap_drop: ALL,no-new-privileges, tmpfs mounts - HMAC Request Signing: Internal bot→admin API calls use HMAC signatures with replay protection
- Rate Limiting: Login attempts (5/15min), general API requests (100/min)
- Helmet Security Headers: Content Security Policy (per-response nonce), XSS protection, and more
- CSRF Protection: Custom header requirement (
X-Requested-With) on state-changing API requests - WebSocket Security: Origin verification against CORS allow list, ping/pong heartbeat with 30-second stale connection timeout
- Input Validation: Zod schema validation for environment variables; Discord ID format validation, comment length limits (500 chars), request body size limits (1MB JSON, 5MB file uploads), and date range caps (max 730 days) on API inputs
- Database Resilience: MongoDB connection retry with exponential backoff (5 attempts)
- Docker Health Checks: Web service monitored via
/api/monitoring/healthendpoint
- Grant Minimal Permissions: Only grant roles the bot actually needs
- Role Positioning: Bot's highest role must be above roles it assigns/removes
- Channel Permissions: Set explicitly; don't rely on @everyone permissions
- Student Data: Stored in MongoDB; ensure server is secure
- Message Logging: Bot can see all messages in monitored channels
- GDPR Compliance: Implement data deletion on
/unverify(currently implemented) - Comment Visibility: Only team members and owner see comments/warnings
- Case Insensitive: Filters match regardless of capitalization
- Partial Matching: Detects words even within other words (e.g., "bad" in "badly")
- Notification Only: Filter notifies admins; doesn't auto-delete (gives context)
- Update Dependencies:
npm updateweekly/monthly - Backup Database: Regular MongoDB exports
- Monitor Logs: Check logs for errors, warnings
- Review Warnings: Periodically audit issued warnings and comments
- Fork & Clone: Create a GitHub fork and clone locally
- Create Branch:
git checkout -b feature/my-feature - Code Style: Use existing code patterns (consistent formatting)
- Test Locally: Run with
npm install && node src/index.js - Commit:
git commit -m "Add [feature]: description" - Push & PR: Push to fork and create pull request
- 🌍 New Language Support: Add additional locales beyond the 7 built-in languages
- 🤖 AI Providers: Add new scam detection AI provider integrations
- 🎨 UI Improvements: Enhance dashboard design/UX
- 🔧 Bug Fixes: Report and fix issues
- 📖 Documentation: Improve guides and examples
- ✨ New Features: Suggest features via Issues
Use GitHub Issues to report bugs or request features:
- Bug Report: Use template
- Feature Request: Use template
OpenSDB is open source under the ISC License. Modify and use freely for educational purposes.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Made with ❤️ by McScheleba
Last Updated: March 2026